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.

resample_image_by_scale(image, scale, interpolate=True)[source]

Resample a 3-D image to scale times its voxel count per axis.

The physical extent is preserved: spacing is rescaled to compensate for the new voxel count, and the origin shifts by half the spacing change so the resampled voxel centers stay inside the original extent.

Parameters:

image (Image) – 3-D ITK image to resample.
scale (float) – Per-axis voxel-count multiplier. Values below 1.0 coarsen, values above 1.0 upsample.
interpolate (bool) – Use linear interpolation. False selects nearest neighbor, which is what labelmaps need.

Return type:

Image

Returns:

Resampled image, covering the same physical extent as image.

Raises:

ValueError – If image is not 3-D, or scale is not positive.

pad_image(image, pad_portion=None, pad_voxels=None, background_value=0.0)[source]

Pad image on every side with a constant-valued margin.

The margin is given either as a portion of each axis’ physical extent (pad_portion) or directly in voxels (pad_voxels); exactly one of the two must be supplied. Either accepts a scalar, applied to every axis, or one value per image dimension. Both pad the lower and the upper end of every axis, so pad_voxels=10 grows all six faces of a 3-D image by ten voxels. Spacing and direction are untouched.

The origin and size are updated together so the original voxels keep their physical positions: the padded image’s index (0, 0, 0) sits one margin below the input’s, and the input data occupies the interior. (itk.ConstantPadImageFilter alone reports the margin as a negative start index instead, which most file formats drop on write — shifting the data. The region-of-interest pass here folds that index back into the origin.)

Parameters:

image (Image) – ITK image to pad.
pad_portion (Union[float, list[float], tuple[float, ...], ndarray[tuple[Any, ...], dtype[Any]], None]) – Portion of an axis’ physical extent (size * spacing) to add at both ends, as a scalar for every axis or one value per dimension: 0.1 grows an axis spanning 200 mm by 20 mm per side. Rounded up to whole voxels. Mutually exclusive with pad_voxels.
pad_voxels (Union[int, list[int], tuple[int, ...], ndarray[tuple[Any, ...], dtype[Any]], None]) – Margin in voxels, as a scalar for every axis or one value per dimension, applied at both ends of each axis. Mutually exclusive with pad_portion.
background_value (float) – Pixel value written into the new margin (default: 0.0).

Return type:

Image

Returns:

Padded image with the same pixel type, spacing and direction.

Raises:

ValueError – If neither or both of pad_portion and pad_voxels are given, if either is negative, or if a sequence does not have one entry per image dimension.

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