imfusion.processing#

Submodule containing routines for data processing.

class imfusion.processing.Axis(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Axis used for flip and rotation operations.

X = 0#

Y = 1#

Z = 2#

class imfusion.processing.DevicePolicy(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Execution device policy. Determines whether processing prefers GPU execution or forces CPU execution.

FORCE_CPU = 1#

PREFER_GPU = 0#

class imfusion.processing.InversionRangeMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Inversion range mode. Determines which min/max values are used as inversion bounds.

IMAGE_DATA_RANGE = 0#

TYPE_VALUE_RANGE = 1#

class imfusion.processing.Mode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Execution mode. Determines whether processing modifies and returns the input image or returns a newly created output image.

CREATE_NEW = 1#

IN_PLACE = 0#

class imfusion.processing.PointDistanceResult(self: PointDistanceResult, mean_distance: SupportsFloat | SupportsIndex, median_distance: SupportsFloat | SupportsIndex, standard_deviation: SupportsFloat | SupportsIndex, min_distance: SupportsFloat | SupportsIndex, max_distance: SupportsFloat | SupportsIndex, distances: Annotated[numpy.typing.ArrayLike, numpy.float64, '[m, 1]'])#

Bases: pybind11_object

property distances#

Type:: Annotated[numpy.typing.NDArray[numpy.float64], ”[m, 1]”]

property max_distance#

Type:: float

property mean_distance#

Type:: float

property median_distance#

Type:: float

property min_distance#

Type:: float

property standard_deviation#

Type:: float

class imfusion.processing.Rotation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Rotation angle in degrees.

NEG_180 = -180#

NEG_270 = -270#

NEG_90 = -90#

POS_180 = 180#

POS_270 = 270#

POS_90 = 90#

class imfusion.processing.ThresholdMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Threshold mode.

INSIDE = 0#

OUTSIDE = 1#

imfusion.processing.apply_threshold(image: TImageBound, lower_threshold: SupportsFloat | SupportsIndex, upper_threshold: SupportsFloat | SupportsIndex, threshold_mode: ThresholdMode = ThresholdMode.INSIDE, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Create a binary image by thresholding the input intensities.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage. For SharedImageSet, all images must have the same dimensions.
lower_threshold – Lower threshold bound.
upper_threshold – Upper threshold bound.
threshold_mode – Whether to keep values inside or outside the threshold range.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Thresholded image.

Compute point-wise distances between: 1. source mesh vertices and target mesh surface, 2. source point cloud and target mesh surface, 3. source mesh vertices and target point cloud vertices, 4. source point cloud and the target point cloud

Parameters:

target – Target data, defining the locations to estimate the distance to.
source – Source data, defining the locations to estimate the distance from.
signed_distance – Whether to compute signed distances (applicable to meshes only). Defaults to False.
range_of_interest – Optional range of distances to consider (min, max) in percentage (integer-valued). Distances outside of this range will be set to NaN. Statistics are computed only over non-NaN distances. Defaults to None.

Returns:

A PointDistanceResult object containing the computed statistics and distances.

imfusion.processing.convert_dtype(image: TImageBound, image_type: DType) → TImageBound#

Convert the input image to the requested pixel type.

Note

This algorithm does not modify the input image but creates a new processed image.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
image_type – Requested output pixel type or numpy dtype.

Returns:

Image converted to the requested pixel type.

imfusion.processing.convert_to_grayscale(image: TImageBound, ignore_alpha_channel: bool = False, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Convert a multi-channel image to grayscale by averaging channels.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage. For SharedImageSet, all images must have the same spatial dimension.
ignore_alpha_channel – If true, ignore the alpha channel during grayscale conversion.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image converted to grayscale.

imfusion.processing.crop(image: TImageBound, lower: Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], upper: Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], mode: Mode = Mode.CREATE_NEW) → TImageBound#

Crop the input image in pixel coordinates.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage. For SharedImageSet, all images must have the same spatial dimension.
lower – Inclusive lower crop corner in pixel coordinates.
upper – Inclusive upper crop corner in pixel coordinates.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Cropped image.

imfusion.processing.flip(image: TImageBound, axis: Axis, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Flip the input image along the requested axis.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage. For SharedImageSet, all images must have the same dimensions.
axis – Axis to flip the image along.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image flipped along the requested axis.

imfusion.processing.invert(image: TImageBound, inversion_range_mode: InversionRangeMode = InversionRangeMode.IMAGE_DATA_RANGE, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Invert the input image intensities.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage. For SharedImageSet, all images must have the same dimensions.
inversion_range_mode – Choose whether inversion uses the image data range or the pixel type range.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image with inverted intensities.

imfusion.processing.pad(image: TImageBound, pad_lower_left_front: Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], pad_upper_right_back: Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], padding_mode: PaddingMode, legacy_mirror_padding: bool = False) → TImageBound#

imfusion.processing.pad(image: TImageBound, pad_size_x: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex], pad_size_y: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex], pad_size_z: tuple[SupportsInt | SupportsIndex, SupportsInt | SupportsIndex], padding_mode: PaddingMode, legacy_mirror_padding: bool = False) → TImageBound

Function overload documentation:

Pad the input image by lower-left-front and upper-right-back extents.

Note

This algorithm does not modify the input image but creates a new processed image.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
pad_lower_left_front – Padding added before the image along x, y, and z.
pad_upper_right_back – Padding added after the image along x, y, and z.
padding_mode – Padding mode used to fill the padded region.
legacy_mirror_padding – Use the legacy mirror-padding behavior.

Returns:

Image padded to the requested extent.

Pad the input image by explicit per-axis lower and upper extents.

Note

This algorithm does not modify the input image but creates a new processed image.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
pad_size_x – Padding added before and after the image along the x-axis.
pad_size_y – Padding added before and after the image along the y-axis.
pad_size_z – Padding added before and after the image along the z-axis.
padding_mode – Padding mode used to fill the padded region.
legacy_mirror_padding – Use the legacy mirror-padding behavior.

Returns:

Image padded to the requested extent.

imfusion.processing.resample_by_binning(image: TImageBound, binning: SupportsInt | SupportsIndex | Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], mode: Mode = Mode.CREATE_NEW) → TImageBound#

Resample the input image by combining adjacent input pixels into larger output bins.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
binning – Binning factor applied to the input image. A factor of 2 downsamples by grouping 2x2 (or 2x2x2) neighboring input pixels/voxels into one output sample, reducing the output resolution. Accepts either a single value for all axes or a per-axis triplet.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image resampled with the requested binning factor.

imfusion.processing.resample_to_descriptor(image: TImageBound, descriptor: ImageDescriptorWorld | Sequence[ImageDescriptorWorld], reduction_mode: ReductionMode = ReductionMode.AVERAGE, interpolation_mode: InterpolationMode = InterpolationMode.LINEAR, keep_zero_values: bool = False, device_policy: DevicePolicy = DevicePolicy.PREFER_GPU, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Resample the input image to the requested descriptor geometry. The output takes its dimensions, spacing, and pose matrix from the target descriptor, while keeping the input pixel type as well as shift and scale.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
descriptor – Target output geometry. Accepts a single ImageDescriptorWorld or a list of descriptors. A single descriptor is applied to all input frames. Otherwise, the descriptor list must match the input frame count.
reduction_mode – Reduction mode used when multiple input pixels or voxels contribute to a single output pixel or voxel. Lookup uses the closest input sample as-is. Minimum, Maximum, and Average instead combine neighboring input samples.
interpolation_mode – Interpolation mode used to sample the input image at fractional coordinates. Linear interpolates between nearby input pixels or voxels. Nearest uses the closest input pixel or voxel instead.
keep_zero_values – If true, input pixels or voxels with zero value remain zero after resampling.
device_policy – Device selection policy. Use imfusion.processing.DevicePolicy.PREFER_GPU to prefer GPU execution when available. If no suitable GPU is available or the current configuration is unsupported on GPU, the algorithm may still fall back to CPU internally. Use imfusion.processing.DevicePolicy.FORCE_CPU to force CPU execution.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image resampled to the requested output descriptor geometry.

imfusion.processing.resample_to_dimension(image: TImageBound, target_dimension: Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], reduction_mode: ReductionMode = ReductionMode.AVERAGE, interpolation_mode: InterpolationMode = InterpolationMode.LINEAR, keep_zero_values: bool = False, device_policy: DevicePolicy = DevicePolicy.PREFER_GPU, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Resample the input image to the requested output dimensions.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
target_dimension – Target output dimensions in pixels.
reduction_mode – Reduction mode used when multiple input pixels or voxels contribute to a single output pixel or voxel. Lookup uses the closest input sample as-is. Minimum, Maximum, and Average instead combine neighboring input samples.
interpolation_mode – Interpolation mode used to sample the input image at fractional coordinates. Linear interpolates between nearby input pixels or voxels. Nearest uses the closest input pixel or voxel instead.
keep_zero_values – If true, input pixels or voxels with zero value remain zero after resampling.
device_policy – Device selection policy. Use imfusion.processing.DevicePolicy.PREFER_GPU to prefer GPU execution when available. If no suitable GPU is available or the current configuration is unsupported on GPU, the algorithm may still fall back to CPU internally. Use imfusion.processing.DevicePolicy.FORCE_CPU to force CPU execution.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image resampled to the target dimensions.

imfusion.processing.resample_to_percent(image: TImageBound, percent: SupportsInt | SupportsIndex | Annotated[numpy.typing.ArrayLike, numpy.int32, '[3, 1]'], reduction_mode: ReductionMode = ReductionMode.AVERAGE, interpolation_mode: InterpolationMode = InterpolationMode.LINEAR, keep_zero_values: bool = False, preserve_extent: bool = False, device_policy: DevicePolicy = DevicePolicy.PREFER_GPU, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Resample the input image to a target size relative to the input dimensions.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
percent – Target output size in percent of the input dimensions. Accepts one value for all axes or a per-axis triplet.
reduction_mode – Reduction mode used when multiple input pixels or voxels contribute to a single output pixel or voxel. Lookup uses the closest input sample as-is. Minimum, Maximum, and Average instead combine neighboring input samples.
interpolation_mode – Interpolation mode used to sample the input image at fractional coordinates. Linear interpolates between nearby input pixels or voxels. Nearest uses the closest input pixel or voxel instead.
keep_zero_values – If true, input pixels or voxels with zero value remain zero after resampling.
preserve_extent – Adjust the target spacing such that the output preserves the physical extent of the input image.
device_policy – Device selection policy. Use imfusion.processing.DevicePolicy.PREFER_GPU to prefer GPU execution when available. If no suitable GPU is available or the current configuration is unsupported on GPU, the algorithm may still fall back to CPU internally. Use imfusion.processing.DevicePolicy.FORCE_CPU to force CPU execution.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image resampled to the requested relative size given in percent.

imfusion.processing.resample_to_ref_image(image: TImageBound, reference_image: SharedImage | SharedImageSet, reduction_mode: ReductionMode = ReductionMode.AVERAGE, interpolation_mode: InterpolationMode = InterpolationMode.LINEAR, keep_zero_values: bool = False, device_policy: DevicePolicy = DevicePolicy.PREFER_GPU, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Resample the input image to the geometry of a reference image. The output takes its dimensions, spacing, and pose matrix from the reference image, while keeping the input pixel type as well as shift and scale.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
reference_image – Reference image geometry. Accepts SharedImage or SharedImageSet. A single reference frame is applied to all input frames. Otherwise, the reference set must match the input frame count.
reduction_mode – Reduction mode used when multiple input pixels or voxels contribute to a single output pixel or voxel. Lookup uses the closest input sample as-is. Minimum, Maximum, and Average instead combine neighboring input samples.
interpolation_mode – Interpolation mode used to sample the input image at fractional coordinates. Linear interpolates between nearby input pixels or voxels. Nearest uses the closest input pixel or voxel instead.
keep_zero_values – If true, input pixels or voxels with zero value remain zero after resampling.
device_policy – Device selection policy. Use imfusion.processing.DevicePolicy.PREFER_GPU to prefer GPU execution when available. If no suitable GPU is available or the current configuration is unsupported on GPU, the algorithm may still fall back to CPU internally. Use imfusion.processing.DevicePolicy.FORCE_CPU to force CPU execution.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image resampled to the reference image geometry.

imfusion.processing.resample_to_spacing(image: TImageBound, target_spacing: Annotated[numpy.typing.ArrayLike, numpy.float64, '[3, 1]'], reduction_mode: ReductionMode = ReductionMode.AVERAGE, interpolation_mode: InterpolationMode = InterpolationMode.LINEAR, keep_zero_values: bool = False, preserve_extent: bool = False, device_policy: DevicePolicy = DevicePolicy.PREFER_GPU, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Resample the input image to the requested output spacing.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage and non-empty SharedImageSet.
target_spacing – Target output spacing in world units.
reduction_mode – Reduction mode used when multiple input pixels or voxels contribute to a single output pixel or voxel. Lookup uses the closest input sample as-is. Minimum, Maximum, and Average instead combine neighboring input samples.
interpolation_mode – Interpolation mode used to sample the input image at fractional coordinates. Linear interpolates between nearby input pixels or voxels. Nearest uses the closest input pixel or voxel instead.
keep_zero_values – If true, input pixels or voxels with zero value remain zero after resampling.
preserve_extent – Adjust the target spacing such that the output preserves the physical extent of the input image.
device_policy – Device selection policy. Use imfusion.processing.DevicePolicy.PREFER_GPU to prefer GPU execution when available. If no suitable GPU is available or the current configuration is unsupported on GPU, the algorithm may still fall back to CPU internally. Use imfusion.processing.DevicePolicy.FORCE_CPU to force CPU execution.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image resampled to the target spacing.

imfusion.processing.rotate(image: TImageBound, axis: Axis, angle: Rotation, mode: Mode = Mode.CREATE_NEW) → TImageBound#

Rotate the input image around the requested axis by a multiple of 90 degrees.

Note

Whether this algorithm operates in place on the input image or creates a new processed image depends on the selected mode parameter.

Parameters:

image – Input image. Accepts any SharedImage. For SharedImageSet, all images must have the same dimensions.
axis – Axis to rotate the image around.
angle – Rotation angle.
mode – Execution mode. Use imfusion.processing.Mode.IN_PLACE to modify and return the input image, or imfusion.processing.Mode.CREATE_NEW to return a new processed image.

Returns:

Image rotated around the requested axis.