Image Tools

Image I/O, preprocessing, and manipulation utilities.

Module Reference

Image Tools for PhysioTwin4D

This module provides utilities for converting between different medical image formats and performing image processing operations.

class physiotwin4d.image_tools.ImageTools(log_level=20)[source]

Utilities for medical image format conversions and processing.

This class provides methods for converting between ITK (Insight Toolkit) and SimpleITK image formats while preserving all metadata (origin, spacing, direction, pixel type). Supports both scalar and vector (multi-component) images.

Example

>>> tools = ImageTools()
>>> # Convert ITK to SimpleITK
>>> sitk_image = tools.convert_itk_image_to_sitk(itk_image)
>>> # Convert back to ITK
>>> itk_image_back = tools.convert_sitk_image_to_itk(sitk_image)

__init__(log_level=20)[source]

Initialize ImageTools.

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

imreadVD3(filename)[source]

Read an ITK vector image with double precision vectors.

ITK’s imread is not wrapped for itk.Image[itk.Vector[itk.D,3],3], so this method reads as itk.Image[itk.Vector[itk.F,3],3] and converts to double precision.

Parameters:: filename (str) – Path to the image file to read
Returns:: Vector image with double precision
Return type:: itk.Image[itk.Vector[itk.D,3],3]

Example

>>> displacement_field = ImageTools().imreadVD3('deformation.mha')

imwriteVD3(image, filename, compression=True)[source]

Write an ITK vector image with double precision vectors.

ITK’s imwrite is not wrapped for itk.Image[itk.Vector[itk.D,3],3], so this method converts to itk.Image[itk.Vector[itk.F,3],3] and writes.

Parameters:

image (itk.Image[itk.Vector[itk.D,3],3]) – Vector image to write
filename (str) – Path to the output file
compression (bool) – Whether to use compression (default: True)

Return type:

None

Example

>>> ImageTools().imwriteVD3(displacement_field, 'deformation.mha')

convert_itk_image_to_sitk(itk_image)[source]

Convert an ITK image to a SimpleITK image.

This method converts an ITK (Insight Toolkit) image to SimpleITK format while preserving all metadata including origin, spacing, direction, and pixel type. Works with both scalar and vector (multi-component) images.

Parameters:: itk_image (Image) – Input ITK image (can be scalar or vector image)
Return type:: Image
Returns:: SimpleITK image with identical data and metadata

Example

>>> tools = ImageTools()
>>> itk_image = itk.imread('image.nii.gz')
>>> sitk_image = tools.convert_itk_image_to_sitk(itk_image)

convert_sitk_image_to_itk(sitk_image)[source]

Convert a SimpleITK image to an ITK image.

This method converts a SimpleITK image to ITK (Insight Toolkit) format while preserving all metadata including origin, spacing, direction, and pixel type. Works with both scalar and vector (multi-component) images.

Parameters:: sitk_image (Image) – Input SimpleITK image (can be scalar or vector image)
Return type:: Image
Returns:: ITK image with identical data and metadata

Example

>>> tools = ImageTools()
>>> sitk_image = sitk.ReadImage('image.nii.gz')
>>> itk_image = tools.convert_sitk_image_to_itk(sitk_image)

convert_array_to_image_of_vectors(arr_data, reference_image, ptype=itk.D)[source]

Convert a numpy array to an ITK image of vector type.

This method is needed because itk in python does not support creating images of vectors with itk.D precision. Luckily array_view_from_image does support itk.D precision vectors.

Return type:: Any

make_isotropic_image(image)[source]

Resample a 3-D image to isotropic spacing using the finest voxel pitch.

Parameters:: image (Image) – 3-D ITK image to resample.
Return type:: Image
Returns:: Resampled image with uniform spacing equal to the smallest input spacing.
Raises:: ValueError – If image is not 3-D.

binary_dilate_image(image, radius, foreground_value=1, background_value=0)[source]

Binary-dilate image with a ball structuring element.

Parameters:

image (Image) – Binary (or label) image to dilate.
radius (int) – Radius, in voxels, of the ball structuring element.
foreground_value (int) – Pixel value treated as foreground (default: 1).
background_value (int) – Pixel value written for background voxels (default: 0).

Return type:

Image

Returns:

Dilated image with the same pixel type as image.

binary_erode_image(image, radius, foreground_value=1, background_value=0)[source]

Binary-erode image with a ball structuring element.

Parameters:

image (Image) – Binary (or label) image to erode.
radius (int) – Radius, in voxels, of the ball structuring element.
foreground_value (int) – Pixel value treated as foreground (default: 1).
background_value (int) – Pixel value written for eroded-away voxels (default: 0).

Return type:

Image

Returns:

Eroded image with the same pixel type as image.

keep_largest_connected_component(image, foreground_value=1, fully_connected=False)[source]

Keep only the largest connected component of a binary image.

Parameters:

image (Image) – Binary (non-zero = foreground) image.
foreground_value (int) – Value written for the retained component’s voxels (default: 1).
fully_connected (bool) – Whether diagonally-adjacent voxels are considered connected (default: False, i.e. face connectivity only).

Return type:

Image

Returns:

Binary image, same pixel type as image, containing only the largest connected component with value foreground_value (background is 0).

flip_image(in_image, in_mask=None, flip_x=False, flip_y=False, flip_z=False, flip_and_make_identity=False)[source]

Flip the image and mask.

Only axis-aligned flips are supported. If flip_and_make_identity is True, the image and mask are first flipped along any axes whose corresponding diagonal entries in the direction matrix are negative (assuming the direction matrix encodes only axis-aligned flips), then any additional requested flips are performed, and finally the direction matrix is set to the identity matrix. This is useful when combining ITK images with VTK objects (that often do not support a direction matrix).

Parameters:

in_image (Image) – The input image to flip
in_mask (Optional[Image]) – The input mask to flip
flip_x (bool) – Flip the image and mask along the x-axis
flip_y (bool) – Flip the image and mask along the y-axis
flip_z (bool) – Flip the image and mask along the z-axis
flip_and_make_identity (bool) – Flip the image and mask and make the direction matrix identity.

Return type:

Union[Image, tuple[Image, Image]]

Navigation

Utility Modules | Transform Tools | Contour Tools