Test Tools

Baseline vs. result image comparison utilities used by the PhysioMotion4D pytest suite.

Module Reference

Test utilities for comparing images in pytest.

Provides TestTools for baseline vs results comparison with configurable tolerances. All image I/O uses ITK with .mha (compressed); 3D images are passed as itk.Image at the API level.

physiomotion4d.test_tools.set_create_baseline_if_missing(value)

Set whether to create baseline files when missing (used by pytest conftest).

Return type:

None

class physiomotion4d.test_tools.TestTools(class_name, results_dir=None, baselines_dir=None, *, log_level=20)

Bases: PhysioMotion4DBase

Utilities for pytest image comparison: baseline directory, result directory, and comparison with configurable tolerances. Inherits from PhysioMotion4DBase for logging. All image I/O uses ITK with compression where supported.

__init__(class_name, results_dir=None, baselines_dir=None, *, log_level=20)

Initialize test helpers.

Parameters:

• class_name (str) – Identifier used for the default results/baselines subdirectory and the logger name. Callers that supply results_dir or baselines_dir explicitly are responsible for including class_name in the path if they want a per-test subdirectory.

• results_dir (Optional[Path]) – Exact directory for written result artifacts. Used as-is. Defaults to <repo>/tests/results/<class_name> when None.

• baselines_dir (Optional[Path]) – Exact directory for baseline artifacts. Used as-is. Defaults to <repo>/tests/baselines/<class_name> when None.

• log_level (int) – Logging level.

static running_as_test()

True when the script is run as a test (e.g. by pytest experiment tests).

Use this to choose fast/small parameters (fewer iterations, fewer files, etc.) so test runs complete in reasonable time. When False, use full parameters for interactive or production runs.

Return type:

bool

Returns:

True if PHYSIOMOTION_RUNNING_AS_TEST is set to a truthy value (1, true, yes, case-insensitive); False otherwise.

image_pass_fail_and_pixels_above_tolerance()

Return (pass, value) for number of pixels above tolerance from the most recent compare_result_to_baseline_image call. pass is True if value <= max_pixels_above_tol that was used in that call.

Return type:

tuple[bool, int]

image_pass_fail_and_total_absolute_error()

Return (pass, value) for total absolute error from the most recent compare_result_to_baseline_image call. pass is True if value <= total_absolute_error_tol that was used in that call.

Return type:

tuple[bool, float]

image_difference()

Return the difference image (itk.Image) from the most recent compare_result_to_baseline_image call.

Return type:

Any

transform_pass_fail_and_number_of_values_above_tolerance()

Return (pass, value) for number of values above tolerance from the most recent compare_result_to_baseline_transform call. pass is True if value <= max_number_of_values_above_tol that was used in that call.

Return type:

tuple[bool, int]

transform_pass_fail_and_total_absolute_error()

Return (pass, value) for total absolute error from the most recent compare_result_to_baseline_transform call. pass is True if value <= total_absolute_error_tol that was used in that call.

Return type:

tuple[bool, float]

transform_difference()

Return the difference transform (itk.Transform) from the most recent compare_result_to_baseline_transform call.

Return type:

Any

write_result_image(image, filename)

Write the image to the configured result artifact directory.

Return type:

None

write_result_transform(transform, filename)

Write the transform to the configured result artifact directory.

Return type:

None

compare_result_to_baseline_transform(filename, *, per_value_absolute_error_tol=0.0, max_number_of_values_above_tol=0, total_absolute_error_tol=0.0)

Compare the transform to the baseline transform.

Return type:

bool

compare_result_to_baseline_image(filename, *, per_pixel_absolute_error_tol=0.0, max_number_of_pixels_above_tol=0, total_absolute_error_tol=0.0)

Load a 3D result image and a 3D baseline image (.mha), compare the full volumes voxel-by-voxel, save the difference image with “_diff” in the name on failure, and log pass/fail.

If the baseline file does not exist and –create-baselines was given, the 3D result is copied as the new baseline.

Returns True if comparison passed (pixels and total absolute error within tolerance).

Parameters:

• filename (str) – File name (relative to class results/baselines dirs).

• per_pixel_absolute_error_tol (float) – Per-voxel absolute error threshold.

• max_number_of_pixels_above_tol (int) – Max allowed voxels exceeding threshold.

• total_absolute_error_tol (float) – Max allowed sum of absolute differences.

Return type:

bool

save_screenshot_mesh(mesh, filename, *, camera_position='iso', window_size=(800, 600), color='pink', opacity=0.9)

Render a PyVista mesh off-screen and save a PNG.

Saves to the configured result artifact directory. On Linux headless environments, calls pv.start_xvfb() before rendering (no-op when a display is present).

Parameters:

• mesh (Any) – PyVista PolyData or compatible mesh object.

• filename (str) – Output PNG filename, relative to the result artifact dir.

• camera_position (Literal['xy', 'xz', 'yz', 'yx', 'zx', 'zy', 'iso']) – PyVista camera preset, e.g. 'iso', 'xy', 'xz'.

• window_size (tuple[int, int]) – Off-screen render size (width, height) in pixels.

• color (str) – Mesh color string accepted by PyVista.

• opacity (float) – Mesh opacity in [0, 1].

Return type:

Path

Returns:

Absolute Path to the saved PNG.

save_screenshot_openusd(usd_file, filename, *, prim_path='/World', time_code=None)

Render USD mesh geometry off-screen and save a PNG.

The scene is loaded through USDTools.load_usd_as_vtk() into a PyVista mesh, rendered with a fixed isometric camera and fixed 800 x 600 window, and centered automatically by PyVista.

Parameters:

• usd_file (str | Path) – USD file to render.

• filename (str) – Output PNG filename, relative to the result artifact dir.

• prim_path (str) – USD prim path to render. Defaults to /World.

• time_code (Optional[float]) – Optional animation time code. None renders default values and falls back to the first authored mesh point sample.

Return type:

Path

Returns:

Absolute path to the saved PNG.

save_screenshot_image_slice(image, filename, *, axis=0, slice_fraction=0.5, colormap='gray', vmin=None, vmax=None, overlay_mask=None, overlay_alpha=0.4)

Extract one slice from an ITK image and save a PNG via matplotlib.

The numpy array from itk.array_view_from_image has shape (Z, Y, X) (ITK stores X fastest; numpy reverses the axis order). Axis indices: - axis=0: axial (constant-Z plane) - axis=1: coronal (constant-Y plane) - axis=2: sagittal (constant-X plane)

Saves to the configured result artifact directory.

Parameters:

• image (Any) – 3-D itk.Image in RAS world space, axes X Y Z.

• filename (str) – Output PNG filename, relative to the result artifact dir.

• axis (int) – Numpy axis along which to slice (0=axial, 1=coronal, 2=sagittal).

• slice_fraction (float) – Fractional position along axis in [0, 1].

• colormap (str) – Matplotlib colormap name for the base image.

• vmin (Optional[float]) – Lower clamp for display; None means data minimum.

• vmax (Optional[float]) – Upper clamp for display; None means data maximum.

• overlay_mask (Optional[Any]) – Optional binary ITK mask rendered as a semi-transparent overlay. Must have the same spatial extent as image.

• overlay_alpha (float) – Opacity of the mask overlay in [0, 1].

Return type:

Path

Returns:

Absolute Path to the saved PNG.

Navigation

NRRD Conversion | Utility Modules | Data Downloads