Transform Tools

Coordinate transformation and image warping utilities.

Module Reference

Tools for transforming and manipulating ITK transforms.

This module provides the TransformTools class with utilities for working with ITK transforms, including transforming images and contours, generating deformation fields, interpolating between transforms, and correcting spatial folding artifacts.

The tools support various transform operations needed for medical image analysis, particularly in the context of 4D cardiac imaging where transforms are used to track anatomical motion over time.

class physiotwin4d.transform_tools.TransformTools(log_level=20)[source]

Utilities for transforming and manipulating ITK transforms.

This class provides a comprehensive set of tools for working with ITK transforms in medical image analysis. It supports transforming various data types (images, contours), generating visualization aids, and performing advanced operations like transform interpolation and spatial folding correction.

The class is particularly useful for 4D cardiac imaging workflows where transforms are used to track anatomical motion over time, requiring operations like transform chaining, interpolation, and quality control.

Key capabilities: - Transform PyVista contours and ITK images - Generate deformation fields from transforms - Interpolate between transforms temporally - Smooth transforms to reduce noise - Combine transforms with spatial masks - Detect and correct spatial folding - Generate visualization grids

Example

>>> transform_tools = TransformTools()
>>> # Transform a contour mesh
>>> transformed_contour = transform_tools.transform_pvcontour(
...     contour, transform, with_deformation_magnitude=True
... )
>>> # Generate deformation field
>>> field = transform_tools.generate_field(transform, reference_image)
__init__(log_level=20)[source]

Initialize the TransformTools class.

Parameters:

log_level (int | str) – Logging level (default: logging.INFO)

combine_displacement_field_transforms(tfm1, tfm2, reference_image, tfm1_weight=1.0, tfm2_weight=1.0, mode='compose', tfm1_blur_sigma=0.0, tfm2_blur_sigma=0.0)[source]

Compose two displacement field transforms.

In add mode, returns a single displacement field transform with weighted summed vectors. In compose mode, returns a composite transform containing both weighted displacement field transforms.

compose follows ITK’s CompositeTransform convention, where the last-added transform is applied first: the result evaluates tfm1(tfm2(x)), so tfm2 is the stage that runs first.

Return type:

Transform

convert_transform_to_displacement_field(tfm, reference_image, np_component_type=<class 'numpy.float64'>, use_reference_image_as_mask=False)[source]

Generate a dense deformation field from an ITK transform.

Converts any ITK transform into a dense displacement field that explicitly stores the displacement vector at each voxel. This is useful for visualization, analysis, and storage of transforms.

Parameters:

  • tfm (itk.Transform) – Input transform to convert. Can be any ITK transform type (Affine, BSpline, DisplacementField, etc.)

  • reference_image (itk.image) – Defines the spatial grid for the output deformation field (spacing, size, origin, direction)

  • use_reference_image_as_mask (bool) – If True, applies the reference image as a mask to zero out displacement vectors outside the image domain

Returns:

Vector image where each voxel contains a displacement

vector [dx, dy, dz] in physical coordinates

Return type:

itk.image

Example

>>> # Generate deformation field for visualization
>>> field = transform_tools.generate_field(registration_transform,
    reference_ct)
>>> # Use as mask to limit field to anatomical regions
>>> masked_field = transform_tools.generate_field(
...     transform, reference_ct, use_reference_image_as_mask=True
... )
convert_transform_to_displacement_field_transform(tfm, reference_image)[source]

Convert an ITK transform to a displacement field transform.

Return type:

DisplacementFieldTransform

invert_displacement_field_transform(tfm, max_iterations=20, max_error_tolerance=0.05, mean_error_tolerance=0.0005)[source]

Invert a displacement field transform.

Uses SimpleITK’s fixed-point iterative inversion on the input field’s own grid. The defaults are tighter than SimpleITK’s own (10 iterations, 0.1 mm max error) because the fields produced here are not smooth everywhere and converge slowly near their support boundary.

Parameters:

  • tfm (Transform) – Displacement field transform to invert.

  • max_iterations (int) – Fixed-point iterations per voxel.

  • max_error_tolerance (float) – Convergence threshold on the maximum error, in the field’s units.

  • mean_error_tolerance (float) – Convergence threshold on the mean error.

Return type:

Transform

Returns:

The inverted displacement field transform.

invert_transform(tfm, reference_image)[source]

Invert any transform, analytically when the type supports it.

Prefers ITK’s analytic inverse (available for translation, rigid, affine and composites of them) and falls back to rasterizing a displacement field over reference_image and inverting that numerically.

The analytic inverse is preferred because the fallback is only defined on reference_image’s grid: outside it the field is zero, so the inverse silently degrades to the identity there.

Parameters:

  • tfm (itk.Transform) – Transform to invert.

  • reference_image (itk.Image) – Grid used by the displacement-field fallback.

Returns:

The inverse transform.

Return type:

itk.Transform

transform_pvcontour(contour, tfm, with_deformation_magnitude=False)[source]

Transform PyVista contour meshes using an ITK transform.

Applies an ITK transform to all points in a PyVista PolyData mesh, useful for deforming anatomical contours according to computed registration transforms. Optionally computes deformation magnitude at each point.

Parameters:

  • contour (pv.PolyData) – The input contour mesh to transform

  • tfm (itk.Transform) – ITK transform to apply. Can be a single transform or a list/array containing one transform

  • with_deformation_magnitude (bool) – If True, adds a “DeformationMagnitude” point data array containing the Euclidean distance each point moved

Returns:

The transformed contour mesh with updated point

coordinates and optionally deformation magnitude data

Return type:

pv.PolyData

Example

>>> # Transform cardiac contour with deformation tracking
>>> transformed_heart = transform_tools.transform_pvcontour(
...     heart_contour, cardiac_transform, with_deformation_magnitude=True
... )
>>> # Access deformation magnitudes
>>> deformation = transformed_heart['DeformationMagnitude']
transform_dataset(mesh, tfm, with_deformation_magnitude=False)[source]

Transform a PyVista dataset while preserving mesh topology and data arrays.

Applies an ITK point transform to every point in the input dataset and returns a deep copy with the original cells, cell data, and point data preserved. This is appropriate for non-contour datasets such as UnstructuredGrid inputs where casting to PolyData would lose topology.

Return type:

DataSet

transform_image(img, tfm, reference_image, interpolation_method='linear', background_value=0.0)[source]

Transform an ITK image using a specified transform and interpolation.

Resamples an image according to a geometric transform, using the reference image to define the output grid properties. Different interpolation methods are available depending on data type and quality requirements.

Parameters:

  • img (itk.image) – The input image to transform

  • tfm (itk.Transform) – The ITK transform to apply

  • reference_image (itk.image) – Defines output spacing, size, origin, and direction for the transformed image

  • tfm_type (str) – Interpolation method. Options: - “linear”: Linear interpolation (default, good for CT/MR) - “nearest”: Nearest neighbor (preserves discrete values) - “sinc”: Sinc interpolation (highest quality, slower)

  • background_value (float) – Value written where the reference grid samples outside the input image. Default 0.0, which is right for labelmaps and masks; intensity images need the value that means “no tissue” in their own units – for CT that is -1000 HU (air), not 0 HU (water).

Returns:

The transformed image resampled to reference grid

Return type:

itk.image

Raises:

ValueError – If tfm_type is not one of the supported options

Example

>>> # Transform CT image with linear interpolation
>>> warped_ct = transform_tools.transform_image(
...     ct_image, deformation_transform, reference_ct
... )
>>> # Transform label map preserving discrete values
>>> warped_labels = transform_tools.transform_image(
...     labelmap, transform, reference, interpolation_method='nearest'
... )
convert_vtk_matrix_to_itk_transform(vtk_mat)[source]

Convert a VTK matrix to an ITK transform.

Converts a VTK matrix object into an equivalent ITK transform. This is useful for interoperability between VTK-based processing (e.g., mesh manipulation) and ITK-based image processing and registration.

Parameters:

vtk_mat (itk.vtkMatrix) – The input VTK transform to convert

Returns:

The equivalent ITK transform

Return type:

itk.Transform

Example

>>> # Convert VTK transform from mesh processing
>>> itk_transform = transform_tools.get_itk_transform_from_vtk_transform
    vtk_transform)
smooth_transform(tfm, sigma, reference_image)[source]

Smooth a transform using Gaussian filtering to reduce noise.

Applies Gaussian smoothing to the displacement field representation of a transform to reduce noise and create more regularized deformations. This is useful for improving transform quality and reducing artifacts.

Parameters:

  • tfm (itk.Transform) – Input transform to smooth

  • sigma (float) – Standard deviation of Gaussian smoothing kernel in physical units (millimeters). Larger values create more smoothing

  • reference_image (itk.image) – Defines spatial grid for field generation and smoothing

Returns:

DisplacementFieldTransform with smoothed

deformation field

Return type:

itk.Transform

Example

>>> # Smooth noisy registration transform
>>> smooth_transform = transform_tools.smooth_transform(
...     noisy_transform, sigma=2.0, reference_ct
... )
>>> # Light smoothing for artifact reduction
>>> refined_transform = transform_tools.smooth_transform(
...     transform, sigma=0.5, reference_image
... )
smooth_deformation_field_transform(field, sigma, weight_image=None, normal_image=None, interior_mask=None, exterior_sigma=None)[source]

Spread a sparsely sampled deformation field into a continuous one.

field is treated as a weighted set of displacement samples rather than as an image: the weighted samples and their weights are each Gaussian-smoothed by sigma (physical millimeters) and then divided, which is a Gaussian-weighted average of the nearby samples. A thin surface shell therefore becomes a continuous deformation that keeps the displacement magnitude the samples carried, instead of being diluted by the empty voxels a plain blur would average in. Far from every sample the smoothed weight vanishes and the field decays to zero.

That spread is otherwise isotropic, and carries the whole displacement vector outward. Giving normal_image and interior_mask splits each sample into the component along the surface normal, which expansion and contraction live in, and the tangential remainder, which sliding lives in, and spreads only the normal component outside the mask. Tissue beyond an organ is then pushed and pulled by it without being dragged along it, which is how a slip interface such as the pleura or the pericardium behaves. Inside the mask the full vector is spread, so the organ’s own contents still follow its surface. exterior_sigma sets how far that outward push and pull carries, independently of the sigma filling the organ itself. exterior_normal_scale sets how much of that normal component the surrounding tissue actually receives.

Parameters:

  • field (itk.Image) – Input vector deformation field, sampled where weight_image is non-zero.

  • sigma (float) – Standard deviation of the Gaussian smoothing kernel in physical units (millimeters).

  • weight_image (Optional[itk.Image]) – Per-voxel sample weight, such as the vertex count WorkflowInferMovement.create_deformation_field() returns. Omit to weight every voxel holding a non-zero displacement equally, which cannot tell an empty voxel from a genuinely zero-displacement one.

  • normal_image (Optional[itk.Image]) – Per-voxel unit surface normal on field’s grid, as WorkflowInferMovement.create_deformation_field() returns alongside the field. Samples whose normal is zero are spread whole, having no direction to project onto.

  • interior_mask (Optional[itk.Image]) – Scalar image on field’s grid, 1 where the full displacement should be spread and 0 where only its normal component should be. Soften its edge to set the width of the band the tangential motion dies out over; a binary mask makes the boundary a discontinuity.

  • exterior_sigma (Optional[float]) – Smoothing sigma (millimeters) for the normal component spread outside interior_mask, in place of sigma. This is how far the organ reaches into the tissue around it: a smaller value confines its push and pull to a narrower shell without weakening the displacement at the surface, and without touching the spread inside the mask. Defaults to sigma. Ignored when no mask is given.

Returns:

Smoothed field transform.

Return type:

itk.DisplacementFieldTransform

Raises:

ValueError – If only one of normal_image and interior_mask is given, if either does not lie on field’s grid, or if the field holds no non-zero samples to spread.

combine_transforms_with_masks(transform1, transform2, mask1, mask2, reference_image, max_iter=10, jacobian_threshold=0.1)[source]

Combine two transforms using spatial masks with folding correction.

Merges two transforms by weighting their displacement fields according to provided masks, then iteratively corrects any spatial folding (negative Jacobian determinant) that may result from the combination.

This is useful for combining transforms computed for different anatomical regions (e.g., separate heart and lung registration) into a single coherent transform.

Parameters:

  • transform1 (itk.Transform) – First transform to combine

  • transform2 (itk.Transform) – Second transform to combine

  • mask1 (itk.Image) – Float mask defining spatial influence of transform1 (0.0 = no influence, 1.0 = full influence)

  • mask2 (itk.Image) – Float mask defining spatial influence of transform2

  • reference_image (itk.Image) – Defines output grid properties

  • max_iter (int) – Maximum iterations for folding correction

  • jacobian_threshold (float) – Jacobian determinant threshold below which folding is detected and corrected

Returns:

DisplacementFieldTransform with combined and

corrected transformation

Return type:

itk.Transform

Example

>>> # Combine heart and lung transforms
>>> combined_transform = transform_tools.combine_transforms_with_masks(
...     heart_transform, lung_transform, heart_mask, lung_mask, reference_ct
... )
compute_jacobian_determinant_from_field(field)[source]

Compute Jacobian determinant of a displacement field.

Calculates the Jacobian determinant at each voxel of a displacement field, which indicates local volume change. Values less than 0 indicate spatial folding, values between 0-1 indicate compression, and values greater than 1 indicate expansion.

Parameters:

field (itk.Image) – Vector displacement field image

Returns:

Scalar image containing Jacobian determinant values

Return type:

itk.Image

Example

>>> jacobian = transform_tools.compute_jacobian_determinant_from_field(
        deformation_field
    )
detect_folding_in_field(jacobian_det, threshold=0.1)[source]

Detect spatial folding in a transform.

Checks for spatial folding by examining the minimum Jacobian determinant value. Folding occurs when the Jacobian determinant becomes negative or very small, indicating non-invertible regions.

Parameters:

  • jacobian_det (itk.Image) – Jacobian determinant image

  • threshold (float) – Threshold below which folding is detected

Returns:

True if folding is detected, False otherwise

Return type:

bool

Example

>>> if transform_tools.detect_folding_in_field(jacobian, 0.1):
...     print('Spatial folding detected - transform needs correction')
reduce_folding_in_field(field, jacobian_det, reduction_factor=0.8, threshold=0.1)[source]

Reduce folding by scaling displacement field in problematic regions.

Corrects spatial folding by reducing the magnitude of displacement vectors in regions where the Jacobian determinant is below the threshold. This is a simple but effective approach to maintaining transform invertibility.

Parameters:

  • field (itk.Image) – Input displacement field to correct

  • jacobian_det (itk.Image) – Jacobian determinant image

  • reduction_factor (float) – Factor to multiply displacements in folding regions (0.8 = 20% reduction)

  • threshold (float) – Jacobian threshold for identifying folding

Returns:

Corrected displacement field with reduced folding

Return type:

itk.Image

Example

>>> corrected_field = transform_tools.reduce_folding_in_field(
...     folded_field, jacobian, reduction_factor=0.7
... )
generate_grid_image(reference_image, grid_size=60, line_width=3)[source]

Generate a grid image.

Return type:

image

convert_field_to_grid_visualization(tfm, reference_image, grid_size=60, line_width=3)[source]

Generate a visual deformation grid for transform visualization.

Creates a regular grid pattern in the reference image space, then applies the transform to visualize the deformation. The resulting warped grid shows how the transform deforms space and can reveal areas of compression, expansion, or folding.

Parameters:

  • tfm (itk.Transform) – Transform to visualize

  • reference_image (itk.image) – Defines spatial domain and grid properties

  • grid_size (int) – Number of grid lines in each dimension

Returns:

Binary image containing the transformed grid pattern

Return type:

itk.image

Example

>>> # Create deformation visualization grid
>>> grid = transform_tools.generate_visual_grid_from_field(
...     cardiac_transform, reference_ct, grid_size=20
... )
>>> # Overlay on original image for visualization

Navigation

Image Tools | Utility Modules | Contour Tools