Reference

imfusion

imfusion - ImFusion SDK for Medical Imaging

This module provides Python bindings for the C++ ImFusion libraries.

exception imfusion.FileNotFoundError: Bases: FileNotFoundError

exception imfusion.IOError: Bases: OSError

exception imfusion.IncompatibleError: Bases: ValueError

exception imfusion.MissingLicenseError: Bases: RuntimeError

class imfusion.Algorithm

Bases: Configurable

Algorithm base type returned by imfusion.algorithm.create. Use imfusion.algorithm.register to define Python algorithms.

class Action

Bases: pybind11_object

property id

property is_hidden

property name

__call__(self: Algorithm) → list: Delegates to: compute()

compute(self: Algorithm) → list

output(self: Algorithm) → None

output_annotations(self: Algorithm) → list[Annotation]

run_action(self: Algorithm, id: str) → Status

Run one of the registered actions.

Parameters:: id (str) – Identifier of the action to run.

property actions: List of registered actions.

property id

property input

property name

property status

class imfusion.Annotation

Bases: pybind11_object

class AnnotationType(self: AnnotationType, value: int)

Bases: pybind11_object

Members:

BOX

CIRCLE

LINE

POINT

POLY_LINE

RECTANGLE

BOX = <AnnotationType.BOX: 0>

CIRCLE = <AnnotationType.CIRCLE: 1>

LINE = <AnnotationType.LINE: 2>

POINT = <AnnotationType.POINT: 3>

POLY_LINE = <AnnotationType.POLY_LINE: 4>

RECTANGLE = <AnnotationType.RECTANGLE: 5>

property name

property value

on_editing_finished(self: Annotation, callback: Callable) → SignalConnection

Register a callback which is called when the annotation has been fully defined by the user.

The callback must not require any arguments.

>>> a = imfusion.app.annotation_model.create_annotation(imfusion.Annotation.LINE)
>>> def callback():
...     print("All points are defined")
>>> a.on_editing_finished(callback)
>>> a.start_editing()

on_points_changed(self: Annotation, callback: Callable) → SignalConnection

Register a callback which is called when any of the points have changed their position.

The callback must not require any arguments.

>>> a = imfusion.app.annotation_model.create_annotation(imfusion.Annotation.LINE)
>>> def callback():
...     print("Points changed")
>>> a.on_points_changed(callback)
>>> a.start_editing()

start_editing(self: Annotation) → None

Start interactive placement of the annotation.

This can currently only be called once.

BOX = <AnnotationType.BOX: 0>

CIRCLE = <AnnotationType.CIRCLE: 1>

LINE = <AnnotationType.LINE: 2>

POINT = <AnnotationType.POINT: 3>

POLY_LINE = <AnnotationType.POLY_LINE: 4>

RECTANGLE = <AnnotationType.RECTANGLE: 5>

property color: Color of the annotation as a normalized RGB tuple.

property editable: Whether the annotation can be manipulated by the user.

property label_text: The text of the label of the annotation.

property label_visible: Whether the label of the annotation needs to be drawn or not.

property line_width: The line width used to draw the annotation.

property max_points

The maximum amount of points this annotation supports.

A -1 indicates that this annotation supports any number of points.

property name: The name of the annotation.

property points

The points which define the annotation in world coordinates.

It is possible to not immediately set all the points that the specific annotation requires: in this case the annotation is required to be manually completed using the mouse in the ImFusionSuite. It is not supported to partially set the points of multiple annotations at once: please complete the current partially-defined annotation before setting the points of another annotation.

Besides, it is not possible to set more points than the specific annotation requires.

property type

Return the type of this annotation.

Raises if the annotation is no longer valid or if the annotation is not supported in Python.

property visible: Whether the annotation needs to be drawn or not.

class imfusion.AnnotationModel

Bases: pybind11_object

create_annotation(self: AnnotationModel, arg0: AnnotationType) → Annotation

property annotations

class imfusion.ApplicationController

Bases: pybind11_object

A ApplicationController instance serves as the center of the ImFusionSDK.

It provides an OpenGL context, a DataModel, executes algorithms and more. While multiple instances are possible, in general there is only one instance.

add_algorithm(self: ApplicationController, id: str, data: list = [], properties: Properties = None) → object

Add the algorithm with the given name to the application.

The algorithm will only be created if it is compatible with the given data. The optional Properties object will be used to configure the algorithm. Returns the created algorithm or None if no compatible algorithm could be found.

>>> app.add_algorithm("Create Synthetic Data", [])  
<imfusion.BaseAlgorithm object at ...>

close_all(self: ApplicationController) → None: Delete all algorithms and datasets. Make sure to not reference any deleted objects after calling this!

execute_algorithm(self: ApplicationController, id: str, data: list = [], properties: Properties = None) → list

Execute the algorithm with the given name and returns its output.

The algorithm will only be executed if it is compatible with the given data. The optional Properties object will be used to configure the algorithm before executing it. Any data created by the algorithm is added to the DataModel before being returned.

load_workspace(self: ApplicationController, path: str, **kwargs) → bool: Loads a workspace file and returns True if the loading was successful. Placeholders can be specified as keyword arguments, for example: >>> app.load_workspace(“path/to/workspace.iws”, sweep=sweep, case=case)

open(self: ApplicationController, path: str) → list: Tries to open the given filepath as data. If successful the data is added to DataModel and returned. Otherwise raises a FileNotFoundError.

remove_algorithm(self: ApplicationController, algorithm: Algorithm) → None: Remove and deletes the given algorithm from the application. Don’t reference the given algorithm afterwards!

save_workspace(self: ApplicationController, path: str) → bool: Saves current workspace to a iws file

select_data(self: ApplicationController, arg0: Data) → None

select_data(self: ApplicationController, arg0: DataList) → None

select_data(self: ApplicationController, arg0: list) → None

Function overload documentation:

select_data(self: ApplicationController, arg0: Data) → None

select_data(self: ApplicationController, arg0: DataList) → None

select_data(self: ApplicationController, arg0: list) → None

update(self: ApplicationController) → None

update_display(self: ApplicationController) → None

property algorithms: Return a list of all open algorithms.

property annotation_model

property data_model

property display

property selected_data

class imfusion.BoundImageDescriptor

Bases: pybind11_object

Immutable version of ImageDescriptor bound to an image.

Struct describing the essential properties of an image.

The ImFusion framework distinguishes two main image pixel value domains, which are indicated by the shift and scale parameters of this image descriptor:

Original pixel value domain: Pixel values are the same as in their original source (e.g. when loaded from a file). Same as the storage pixel value domain if the image’s scale is 1 and the shift is 0

Storage pixel value domain: Pixel values as they are stored in a MemImage. The user may decide to apply such a rescaling in order to better use the available limits of the underlying type.

The following conversion rules apply:

OV = (SV / scale) - shift

SV = (OV + shift) * scale

clone(self: BoundImageDescriptor) → ImageDescriptor: Return a mutable copy as ImageDescriptor.

coord(self: BoundImageDescriptor, index: int) → ndarray[numpy.int32[4, 1]]: Return the pixel/voxel coordinate (x,y,z,c) for a given index

has_index(self: BoundImageDescriptor, x: int, y: int, z: int = 0, c: int = 0) → bool: Return true if the pixel at (x,y,z) exists, false otherwise

image_to_pixel(self: BoundImageDescriptor, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert 3D image coordinates to pixel/voxel position

index(self: BoundImageDescriptor, x: int, y: int, z: int = 0, c: int = 0) → int: Return a linear memory index for a pixel or voxel

is_compatible(self: BoundImageDescriptor, other: ImageDescriptor, ignore_type: bool = False, ignore_3D: bool = False, ignore_channels: bool = False, ignore_spacing: bool = True) → bool: Convenience function to perform partial comparison of two image descriptors. Two descriptors are compatible if their width and height, and optionally number of slices, number of channels and type are the same

is_valid(self: BoundImageDescriptor) → bool: Return if the descriptor is valid (a size of one is allowed)

original_to_storage(self: BoundImageDescriptor, value: float) → float: Apply the image’s shift and scale in order to convert a value from original pixel value domain to storage pixel value domain

pixel_to_image(self: BoundImageDescriptor, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel/voxel position to image coordinates

storage_to_original(self: BoundImageDescriptor, value: float) → float: Apply the image’s shift and scale in order to convert a value from storage pixel value domain to original pixel value domain

property byte_size: Return the size of the image in bytes

property channels

property configuration: Serialize an image descriptor to Properties

property dimension

property dimensions

property extent

property height

property image_to_pixel_matrix: Return a 4x4 matrix to transform from image space to pixel space

property image_to_texture_matrix: Return a 4x4 matrix to transform from image space to texture space

property is_metric

property pixel_to_image_matrix: Return a 4x4 matrix to transform from pixel space to image space

property pixel_type

property scale

property shift

property size: Return the size (number of elements) of the image

property slices

property spacing

Physical extent of each voxel in [mm] stored as a namedtuple. Spacing for a specific dimension can be accessed via x, y, and z attributes.

Returns:: Named tuple with x, y, and z attributes.
Return type:: (collections.namedtuple)

property texture_to_image_matrix: Return a 4x4 matrix to transform from texture space to image space

property type_size: Return the nominal size in bytes of the current component type, zero if unknown

property width

class imfusion.BoundImageDescriptorWorld

Bases: pybind11_object

Immutable version of ImageDescriptorWorld bound to an image.

Convenience struct extending an ImageDescriptor to also include a matrix describing the image orientation in world coordinates.

This struct can be useful for describing the geometrical properties of an image without need to hold the (heavy) image content. As such it can be used for representing reference geometries (see ImageResamplingAlgorithm), or for one-line creation of a new SharedImage.

clone(self: BoundImageDescriptorWorld) → ImageDescriptorWorld: Return a mutable copy as ImageDescriptorWorld.

image_to_pixel(self: BoundImageDescriptorWorld, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert 3D image coordinates to pixel/voxel position

is_spatially_compatible(self: BoundImageDescriptorWorld, other: ImageDescriptorWorld) → bool: Convenience function to compare two image world descriptors (for instance to know whether a resampling is necessary). Two descriptors are compatible if their dimensions, matrix and spacing are identical.

pixel_to_image(self: BoundImageDescriptorWorld, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel/voxel position to image coordinates

pixel_to_world(self: BoundImageDescriptorWorld, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel/voxel position to world coordinates

world_to_pixel(self: BoundImageDescriptorWorld, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert 3D world coordinates to pixel/voxel position

property descriptor

property image_to_pixel_matrix: Return a 4x4 matrix to transform from image space to pixel space

property image_to_texture_matrix: Return a 4x4 matrix to transform from image space to texture space

property matrix_from_world: Return the matrix transforming world coordinates to image coordinates

property matrix_to_world: Return the matrix transforming image coordinates to world coordinates

property pixel_to_image_matrix: Return a 4x4 matrix to transform from pixel space to image space

property pixel_to_world_matrix: Return a 4x4 matrix to transform from pixel space to world space

property texture_to_image_matrix: Return a 4x4 matrix to transform from texture space to image space

property texture_to_world_matrix: Return a 4x4 matrix to transform from texture space to world space

property world_to_pixel_matrix: Return a 4x4 matrix to transform from world space to pixel space

property world_to_texture_matrix: Return a 4x4 matrix to transform from world space to texture space

class imfusion.Configurable

Bases: pybind11_object

configuration(self: Configurable) → Properties

configure(self: Configurable, properties: Properties) → None

configure_defaults(self: Configurable) → None

class imfusion.ConsoleController(self: ConsoleController, name: str = 'ImFusion Python SDK')

Bases: ApplicationController

ApplicationController without a UI interface.

This class is not available in the embedded Python interpreter in the ImFusionSuite.

class imfusion.CroppingMask(self: CroppingMask, dimensions: ndarray[numpy.int32[3, 1]])

Bases: Mask

Simple axis-aligned cropping mask with optional roundness.

class RoundDims(self: RoundDims, value: int)

Bases: pybind11_object

Members:

XY

YZ

XZ

XYZ

XY = <RoundDims.XY: 0>

XYZ = <RoundDims.XYZ: 3>

XZ = <RoundDims.XZ: 2>

YZ = <RoundDims.YZ: 1>

property name

property value

XY = <RoundDims.XY: 0>

XYZ = <RoundDims.XYZ: 3>

XZ = <RoundDims.XZ: 2>

YZ = <RoundDims.YZ: 1>

property border: Number of pixels cropped away

property inverted: Whether the mask is inverted

property roundness: Roundness in percent (100 means an ellipse, 0 a rectangle)

property roundness_dims: Which dimensions the roundness parameter should be applied

class imfusion.Data

Bases: pybind11_object

class Kind(self: Kind, value: int)

Bases: pybind11_object

Members:

UNKNOWN

IMAGE

VOLUME

IMAGE_SET

VOLUME_SET

IMAGE_STREAM

VOLUME_STREAM

POINT_SET

SURFACE

TRACKING_STREAM

TRACKING_DATA

STEREOIMAGESET

IMAGE = <Kind.IMAGE: 1>

IMAGE_SET = <Kind.IMAGE_SET: 3>

IMAGE_STREAM = <Kind.IMAGE_STREAM: 5>

POINT_SET = <Kind.POINT_SET: 7>

STEREOIMAGESET = <Kind.STEREOIMAGESET: 14>

SURFACE = <Kind.SURFACE: 8>

TRACKING_DATA = <Kind.TRACKING_DATA: 10>

TRACKING_STREAM = <Kind.TRACKING_STREAM: 9>

UNKNOWN = <Kind.UNKNOWN: 0>

VOLUME = <Kind.VOLUME: 2>

VOLUME_SET = <Kind.VOLUME_SET: 4>

VOLUME_STREAM = <Kind.VOLUME_STREAM: 6>

property name

property value

class Modality(self: Modality, value: int)

Bases: pybind11_object

Members:

NA

XRAY

CT

MRI

ULTRASOUND

VIDEO

NM

OCT

LABEL

CT = <Modality.CT: 2>

LABEL = <Modality.LABEL: 8>

MRI = <Modality.MRI: 3>

NA = <Modality.NA: 0>

NM = <Modality.NM: 6>

OCT = <Modality.OCT: 7>

ULTRASOUND = <Modality.ULTRASOUND: 4>

VIDEO = <Modality.VIDEO: 5>

XRAY = <Modality.XRAY: 1>

property name

property value

matrix_from_world(self: Data) → ndarray[numpy.float64[4, 4]]

matrix_to_world(self: Data) → ndarray[numpy.float64[4, 4]]

set_matrix_from_world(self: Data, arg0: ndarray[numpy.float64[4, 4]]) → None

set_matrix_to_world(self: Data, arg0: ndarray[numpy.float64[4, 4]]) → None

property components

property kind

property name

class imfusion.DataComponent(self: DataComponent)

Bases: pybind11_object

Data components provide a way to generically attach custom information to Data.

Data and StreamData are the two main classes that hold a list of data components, allowing custom information (for example optional data or configuration settings) to be attached to instances of these classes. Data components are meant to be used for information that is bound to a specific Data instance and that can not be represented by the usual ImFusion data types.

Data components should implement the Configurable methods, in order to support generic (de)serialization.

Note

Data components are supposed to act as generic storage for custom information. When subclassing DataComponent, you should not implement any heavy evaluation logic since this is the domain of Algorithms or other classes accessing the DataComponents.

Example

class MyComponent(imfusion.DataComponent, accessor_name="my_component"):
        def __init__(self, a=""):
                imfusion.DataComponent.__init__(self)
                self.a = a

        @property
        def a(self):
                return self._a

        @a.setter
        def a(self, value):
                if value and not isinstance(value, str):
                        raise TypeError("`a` must be of type `str`")
                self._a = value

        def configure(self, properties: imfusion.Properties) -> None:
                self.a = str(properties["a"])

        def configuration(self) -> imfusion.Properties:
                return imfusion.Properties({"a": self.a})

        def __eq__(self, other: "MyComponent") -> bool:
                return self.a == other.a

configuration(self: DataComponent) → Properties

configure(self: DataComponent, properties: Properties) → None

property id: Returns a unique string identifier for this type of data component

class imfusion.DataComponentBase

Bases: Configurable

property id: Returns the unique string identifier of this component class.

class imfusion.DataComponentList

Bases: pybind11_object

A list of DataComponent. The list contains properties for specific DataComponent types. Each DataComponent type can only occur once.

__getitem__(self: DataComponentList, index: int) → object

__getitem__(self: DataComponentList, indices: list[int]) → list[object]

__getitem__(self: DataComponentList, slice: slice) → list[object]

__getitem__(self: DataComponentList, id: str) → object

Function overload documentation:

__getitem__(self: DataComponentList, index: int) → object

__getitem__(self: DataComponentList, indices: list[int]) → list[object]

__getitem__(self: DataComponentList, slice: slice) → list[object]

__getitem__(self: DataComponentList, id: str) → object

add(self: DataComponentList, component: DataComponent) → object

add(self: DataComponentList, arg0: ImageInfoDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: DisplayOptions2d) → DataComponentBase

add(self: DataComponentList, arg0: DisplayOptions3d) → DataComponentBase

add(self: DataComponentList, arg0: TransformationStashDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: DataSourceComponent) → DataComponentBase

add(self: DataComponentList, arg0: LabelDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: DatasetLicenseComponent) → DataComponentBase

add(self: DataComponentList, arg0: RealWorldMappingDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: ASCDisplayOptions) → DataComponentBase

add(self: DataComponentList, arg0: GeneralEquipmentModuleDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: SourceInfoComponent) → DataComponentBase

add(self: DataComponentList, arg0: ReferencedInstancesComponent) → DataComponentBase

add(self: DataComponentList, arg0: RTStructureDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: FrameGeometryMetadata) → DataComponentBase

add(self: DataComponentList, arg0: UltrasoundMetadata) → DataComponentBase

add(self: DataComponentList, arg0: TargetTag) → DataComponentBase

add(self: DataComponentList, arg0: ProcessingRecordComponent) → DataComponentBase

add(self: DataComponentList, arg0: ReferenceImageDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: PatchesFromImageDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: InversionComponent) → DataComponentBase

add(self: DataComponentList, arg0: PulseEchoEvent) → DataComponentBase

add(self: DataComponentList, arg0: FrameAcquisition) → DataComponentBase

add(self: DataComponentList, arg0: Transducer) → DataComponentBase

add(self: DataComponentList, arg0: ChannelDataLayout) → DataComponentBase

add(self: DataComponentList, arg0: BeamformingRois) → DataComponentBase

add(self: DataComponentList, arg0: CameraCalibrationDataComponent) → DataComponentBase

add(self: DataComponentList, arg0: StereoCalibrationDataComponent) → DataComponentBase

Function overload documentation:

add(self: DataComponentList, component: DataComponent) → object: Adds the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: ImageInfoDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: DisplayOptions2d) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: DisplayOptions3d) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: TransformationStashDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: DataSourceComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: LabelDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: DatasetLicenseComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: RealWorldMappingDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: ASCDisplayOptions) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: GeneralEquipmentModuleDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: SourceInfoComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: ReferencedInstancesComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: RTStructureDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: FrameGeometryMetadata) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: UltrasoundMetadata) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: TargetTag) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: ProcessingRecordComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: ReferenceImageDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: PatchesFromImageDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: InversionComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: PulseEchoEvent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: FrameAcquisition) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: Transducer) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: ChannelDataLayout) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: BeamformingRois) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: CameraCalibrationDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

add(self: DataComponentList, arg0: StereoCalibrationDataComponent) → DataComponentBase: Adds a copy of the component to the component list and returns a reference to the copy.

property asc_display_options

property beamforming_rois

property camera_calibration

property channel_data_layout

property data_source

property dataset_license

property display_options_2d

property display_options_3d

property frame_acquisition

property frame_geometry_metadata

property general_equipment_module

property image_info

property inversion

property label

property patches_from_image

property processing_record

property pulse_echo_event

property real_world_mapping

property reference_image

property referenced_instances

property rt_structure

property source_info

property stereo_calibration

property target_tag

property transducer

property transformation_stash

property ultrasound_metadata

class imfusion.DataGroup

Bases: Data

children_recursive(self: DataGroup) → DataList

property __iter__

property children

property proxy_child

class imfusion.DataList(*args, **kwargs)

Bases: pybind11_object

List of Data. Is implicitly converted from and to regular Python lists.

Deprecated since version 2.15: Use a regular list instead.

Function overload documentation:

__init__(self: DataList) → None

__init__(self: DataList, list: list) → None

__getitem__(self: DataList, index: int) → Data

__getitem__(self: DataList, indices: list[int]) → list[Data]

__getitem__(self: DataList, slice: slice) → list[Data]

Function overload documentation:

__getitem__(self: DataList, index: int) → Data

__getitem__(self: DataList, indices: list[int]) → list[Data]

__getitem__(self: DataList, slice: slice) → list[Data]

__iter__(self: DataList) → Iterator[Data]

add(self: DataList, arg0: Data) → None

append(self: DataList, arg0: Data) → None

get_images(self: DataList, kind: Kind = Kind.UNKNOWN, modality: Modality = Modality.NA) → list

class imfusion.DataModel

Bases: pybind11_object

The DataModel instance holds all datasets of an ApplicationController.

__getitem__(self: DataModel, index: int) → Data

__getitem__(self: DataModel, indices: list[int]) → list[Data]

__getitem__(self: DataModel, slice: slice) → list[Data]

Function overload documentation:

__getitem__(self: DataModel, index: int) → Data

__getitem__(self: DataModel, indices: list[int]) → list[Data]

__getitem__(self: DataModel, slice: slice) → list[Data]

add(self: DataModel, data: Data, name: str = '') → Data

add(self: DataModel, data_list: list[Data]) → list

Function overload documentation:

add(self: DataModel, data: Data, name: str = '') → Data: Add data to the model. The data will be copied and a reference to the copy is returned. If the data cannot be added, a ValueError is raised.

add(self: DataModel, data_list: list[Data]) → list: Add multiple pieces of data to the model. The data will be copied and a reference to the copy is returned. If the data cannot be added, a ValueError is raised.

clear(self: DataModel) → None: Remove all data from the model

contains(self: DataModel, data: Data) → bool

create_group(self: DataModel, arg0: DataList) → DataGroup: Groups a list of Data in the model. Only Data that is already part of the model can be grouped.

get(self: DataModel, name: str) → Data

get_common_parent(self: DataModel, data_list: DataList) → DataGroup: Return the most common parent of all given Data

get_parent(self: DataModel, data: Data) → DataGroup: Return the parent DataGroup of the given Data or None if it is not part of the model. For top-level data this function will return get_root_node().

index(self: DataModel, data: Data) → int: Return index of data. The index is depth-first for all groups.

remove(self: DataModel, data: Data) → None: Remove and delete data from the model. Afterwards data must not be reference anymore!

property root_node: Return the parent DataGroup of the given Data or None if it does not have a parent

property size: Return the total amount of data in the model

class imfusion.DataSourceComponent

Bases: DataComponentBase

class DataSourceInfo(self: DataSourceInfo, arg0: str, arg1: str, arg2: Properties, arg3: int, arg4: list[DataSourceInfo])

Bases: Configurable

update(self: DataSourceInfo, arg0: DataSourceInfo) → None

property filename

property history

property index_in_file

property io_algorithm_config

property io_algorithm_name

property filenames

property sources

class imfusion.DatasetLicenseComponent(*args, **kwargs)

Bases: DataComponentBase

Function overload documentation:

__init__(self: DatasetLicenseComponent) → None

__init__(self: DatasetLicenseComponent, infos: list[DatasetInfo]) → None

class DatasetInfo(*args, **kwargs)

Bases: pybind11_object

Function overload documentation:

__init__(self: DatasetInfo) → None

__init__(self: DatasetInfo, name: str, authors: str, website: str, license: str, attribution_required: bool, commercial_use_allowed: bool) → None

property attribution_required

property authors

property commercial_use_allowed

property license

property name

property website

infos(self: DatasetLicenseComponent) → list[DatasetInfo]

class imfusion.Deformation

Bases: pybind11_object

configuration(self: Deformation) → Properties

configure(self: Deformation, properties: Properties) → None

displace_point(self: Deformation, at: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

displace_points(self: Deformation, at: list[ndarray[numpy.float64[3, 1]]]) → list[ndarray[numpy.float64[3, 1]]]

displacement(self: Deformation, at: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

displacement(self: Deformation, at: ndarray[numpy.float64[2, 1]]) → ndarray[numpy.float64[3, 1]]

displacement(self: Deformation, at: list[ndarray[numpy.float64[3, 1]]]) → list[ndarray[numpy.float64[3, 1]]]

Function overload documentation:

displacement(self: Deformation, at: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

displacement(self: Deformation, at: ndarray[numpy.float64[2, 1]]) → ndarray[numpy.float64[3, 1]]

displacement(self: Deformation, at: list[ndarray[numpy.float64[3, 1]]]) → list[ndarray[numpy.float64[3, 1]]]

class imfusion.Display

Bases: pybind11_object

maximize_view(self: Display, view: View) → None

unmaximize_view(self: Display) → None

views(self: Display) → list

views2d(self: Display) → list

views3d(self: Display) → list

views_slice(self: Display) → list

property focus_view

property layout_mode

class imfusion.DisplayOptions2d(self: DisplayOptions2d, arg0: Data)

Bases: DataComponentBase

property gamma

property invert

property level

property window

class imfusion.DisplayOptions3d(self: DisplayOptions3d, arg0: Data)

Bases: DataComponentBase

property alpha

property invert

property level

property window

class imfusion.ExplicitIntensityMask(self: ExplicitIntensityMask, ref_image: SharedImage, mask_image: SharedImage)

Bases: Mask

Combination of an ExplicitMask and an IntensityMask.

property border_clamp: If true, set sampler wrapping mode to CLAMP_TO_BORDER (default). If false, set to CLAMP_TO_EDGE.

property border_color: Border color (normalized for integer images)

property intensity_range: Range of allowed pixel values

class imfusion.ExplicitMask(*args, **kwargs)

Bases: Mask

Mask holding an individual mask value for every pixel.

Function overload documentation:

__init__(self: ExplicitMask, width: int, height: int, slices: int, initial: int = 0) → None

__init__(self: ExplicitMask, dimensions: ndarray[numpy.int32[3, 1]], initial: int = 0) → None

__init__(self: ExplicitMask, mask_image: MemImage) → None

mask_image(self: ExplicitMask) → SharedImage: Returns a copy of the mask image held by the mask.

class imfusion.FrameworkInfo

Bases: pybind11_object

Provides general information about the framework.

property framework_version

property license

property opengl

property plugins

class imfusion.FreeFormDeformation

Bases: Deformation

configuration(self: FreeFormDeformation) → Properties

configure(self: FreeFormDeformation, arg0: Properties) → None

control_points(self: FreeFormDeformation) → list[ndarray[numpy.float64[3, 1]]]: Get current control point locations (including displacement)

property displacements: Displacement in mm of all control points

property grid_spacing: Spacing of the control point grid

property grid_transformation: Transformation matrix of the control point grid

property subdivisions: Subdivisions of the control point grid

class imfusion.GlPlatformInfo

Bases: pybind11_object

Provides information about the underlying OpenGL driver.

property extensions

property renderer

property vendor

property version

class imfusion.ImageDescriptor(*args, **kwargs)

Bases: pybind11_object

Struct describing the essential properties of an image.

The ImFusion framework distinguishes two main image pixel value domains, which are indicated by the shift and scale parameters of this image descriptor:

Original pixel value domain: Pixel values are the same as in their original source (e.g. when loaded from a file). Same as the storage pixel value domain if the image’s scale is 1 and the shift is 0

Storage pixel value domain: Pixel values as they are stored in a MemImage. The user may decide to apply such a rescaling in order to better use the available limits of the underlying type.

The following conversion rules apply:

OV = (SV / scale) - shift

SV = (OV + shift) * scale

Function overload documentation:

__init__(self: ImageDescriptor) → None

__init__(self: ImageDescriptor, type: PixelType, dimensions: ndarray[numpy.int32[3, 1]], channels: int = 1) → None

__init__(self: ImageDescriptor, type: PixelType, width: int, height: int, slices: int = 1, channels: int = 1) → None

__init__(self: ImageDescriptor, bound_image_descriptor: BoundImageDescriptor) → None

clone(self: ImageDescriptor) → ImageDescriptor: Return a mutable copy of this descriptor.

configure(self: ImageDescriptor, properties: Properties) → None: Deserialize an image descriptor from Properties

coord(self: ImageDescriptor, index: int) → ndarray[numpy.int32[4, 1]]: Return the pixel/voxel coordinate (x,y,z,c) for a given index

has_index(self: ImageDescriptor, x: int, y: int, z: int = 0, c: int = 0) → bool: Return true if the pixel at (x,y,z) exists, false otherwise

image_to_pixel(self: ImageDescriptor, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert 3D image coordinates to pixel/voxel position

index(self: ImageDescriptor, x: int, y: int, z: int = 0, c: int = 0) → int: Return a linear memory index for a pixel or voxel

is_compatible(self: ImageDescriptor, other: ImageDescriptor, ignore_type: bool = False, ignore_3D: bool = False, ignore_channels: bool = False, ignore_spacing: bool = True) → bool: Convenience function to perform partial comparison of two image descriptors. Two descriptors are compatible if their width and height, and optionally number of slices, number of channels and type are the same

is_valid(self: ImageDescriptor) → bool: Return if the descriptor is valid (a size of one is allowed)

original_to_storage(self: ImageDescriptor, value: float) → float: Apply the image’s shift and scale in order to convert a value from original pixel value domain to storage pixel value domain

pixel_to_image(self: ImageDescriptor, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel/voxel position to image coordinates

set_dimensions(self: ImageDescriptor, dimensions: ndarray[numpy.int32[3, 1]], channels: int = 0) → None: Convenience function for specifying the image dimensions and channels at once. If channels is 0, the number of channels will remain unchanged

set_spacing(self: ImageDescriptor, spacing: ndarray[numpy.float64[3, 1]], is_metric: bool) → None: Convenience function for specifying spacing and metric flag at the same time

storage_to_original(self: ImageDescriptor, value: float) → float: Apply the image’s shift and scale in order to convert a value from storage pixel value domain to original pixel value domain

property byte_size: Return the size of the image in bytes

property channels

property configuration: Serialize an image descriptor to Properties

property dimension

property dimensions

property extent

property height

property image_to_pixel_matrix: Return a 4x4 matrix to transform from image space to pixel space

property image_to_texture_matrix: Return a 4x4 matrix to transform from image space to texture space

property is_metric

property pixel_to_image_matrix: Return a 4x4 matrix to transform from pixel space to image space

property pixel_type

property scale

property shift

property size: Return the size (number of elements) of the image

property slices

property spacing

Physical extent of each voxel in [mm] stored as a namedtuple. Spacing for a specific dimension can be accessed via x, y, and z attributes.

When setting the spacing, it is always assumed that the given spacing is metric. If you want to specify a non-metric spacing, use desc.set_spacing(new_spacing, is_metric=False).

Returns:: Named tuple with x, y, and z attributes.
Return type:: (collections.namedtuple)

property texture_to_image_matrix: Return a 4x4 matrix to transform from texture space to image space

property type_size: Return the nominal size in bytes of the current component type, zero if unknown

property width

class imfusion.ImageDescriptorWorld(*args, **kwargs)

Bases: pybind11_object

Convenience struct extending an ImageDescriptor to also include a matrix describing the image orientation in world coordinates.

This struct can be useful for describing the geometrical properties of an image without need to hold the (heavy) image content. As such it can be used for representing reference geometries (see ImageResamplingAlgorithm), or for one-line creation of a new SharedImage.

Function overload documentation:

__init__(self: ImageDescriptorWorld, descriptor: ImageDescriptor, matrix_to_world: ndarray[numpy.float64[4, 4]]) → None

__init__(self: ImageDescriptorWorld, shared_image: SharedImage) → None

__init__(self: ImageDescriptorWorld, bound_image_descriptor_world: BoundImageDescriptorWorld) → None

clone(self: ImageDescriptorWorld) → ImageDescriptorWorld: Returns a copy of this world descriptor.

image_to_pixel(self: ImageDescriptorWorld, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert 3D image coordinates to pixel/voxel position

is_spatially_compatible(self: ImageDescriptorWorld, other: ImageDescriptorWorld) → bool: Convenience function to compare two image world descriptors (for instance to know whether a resampling is necessary). Two descriptors are compatible if their dimensions, matrix and spacing are identical.

pixel_to_image(self: ImageDescriptorWorld, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel/voxel position to image coordinates

pixel_to_world(self: ImageDescriptorWorld, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel/voxel position to world coordinates

world_to_pixel(self: ImageDescriptorWorld, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert 3D world coordinates to pixel/voxel position

property descriptor

property image_to_pixel_matrix: Return a 4x4 matrix to transform from image space to pixel space

property image_to_texture_matrix: Return a 4x4 matrix to transform from image space to texture space

property matrix_from_world

property matrix_to_world

property pixel_to_image_matrix: Return a 4x4 matrix to transform from pixel space to image space

property pixel_to_world_matrix: Return a 4x4 matrix to transform from pixel space to world space

property texture_to_image_matrix: Return a 4x4 matrix to transform from texture space to image space

property texture_to_world_matrix: Return a 4x4 matrix to transform from texture space to world space

property world_to_pixel_matrix: Return a 4x4 matrix to transform from world space to pixel space

property world_to_texture_matrix: Return a 4x4 matrix to transform from world space to texture space

class imfusion.ImageInfoDataComponent(self: ImageInfoDataComponent)

Bases: DataComponentBase

DataComponent storing general information on the image origin.

Modeled after the DICOM patient-study-series hierarchy, it stores information on the patient, study and series the data set belongs to.

class AnatomicalOrientationType(self: AnatomicalOrientationType, value: int)

Bases: pybind11_object

The anatomical orientation type used in Instances generated by this equipment.

Members:

UNKNOWN

BIPED

QUADRUPED

BIPED = <AnatomicalOrientationType.BIPED: 1>

QUADRUPED = <AnatomicalOrientationType.QUADRUPED: 2>

UNKNOWN = <AnatomicalOrientationType.UNKNOWN: 0>

property name

property value

class Laterality(self: Laterality, value: int)

Bases: pybind11_object

Laterality of (paired) body part examined

Members:

UNKNOWN

LEFT

RIGHT

LEFT = <Laterality.LEFT: 1>

RIGHT = <Laterality.RIGHT: 2>

UNKNOWN = <Laterality.UNKNOWN: 0>

property name

property value

class PatientSex(self: PatientSex, value: int)

Bases: pybind11_object

Gender of the patient

Members:

UNKNOWN

MALE

FEMALE

OTHER

FEMALE = <PatientSex.FEMALE: 2>

MALE = <PatientSex.MALE: 1>

OTHER = <PatientSex.OTHER: 3>

UNKNOWN = <PatientSex.UNKNOWN: 0>

property name

property value

property frame_of_reference_uid: Uniquely identifies the Frame of Reference for a Series. Multiple Series within a Study may share a Frame of Reference UID.

property laterality: Laterality of (paired) body part examined

property modality: DICOM modality string specifying the method used to create this series

property orientation_type: DICOM Anatomical Orientation Type

property patient_birth_date: Patient date of birth in yyyyMMdd format

property patient_comment: Additional information about the Patient

property patient_id: DICOM Patient ID

property patient_name: Patient name

property patient_position: Specifies position of the Patient relative to the imaging equipment.

property patient_sex: Patient sex

property photometric_interpretation: Specifies the intended interpretation of the pixel data (e.g. RGB, HSV, …).

property responsible_person: Name of person with medical or welfare decision making authority for the Patient.

property series_date: Series date in yyyyMMdd format

property series_description: Series description

property series_instance_uid: Unique identifier of the Series

property series_number: DICOM Series number. The value of this attribute should be unique for all Series in a Study created on the same equipment.

property series_time: Series time in HHmmss format

property series_time_exact: Series time in microseconds. 0 if the original series time was empty.

property study_date: Study date in yyyyMMdd format

property study_description: Study description

property study_id: DICOM Study ID

property study_instance_uid: Unique identifier for the Study

property study_time: Study time in HHmmss format, optionally with time zone offset &ZZXX

property study_time_exact: Study time in microseconds. 0 if the original study time was empty.

property study_timezone: Study time zone abbreviation

class imfusion.ImageResamplingAlgorithm(*args, **kwargs)

Bases: Algorithm

Algorithm for resampling an image to a target dimension or resolution, optionally with respect to another image.

If a reference image is not provided the size of the output can be either explicitly specified, or implicitly determined by setting a target spacing, binning or relative size w.r.t. the input (in percentage). Only one of these strategies can be active at a time, as specified by the resamplingMode field. The value of the other target fields will be ignored. The algorithm offers convenience methods to jointly update the value of a target field and change the resampling mode accordingly.

In case you provide a reference image it will its pixel grid (dimensions, spacing, pose matrix) for the output. However, the pixel type as well as shift/scale will remain the same as in the input image.

The algorithm supports Linear and Nearest interpolation modes. In the Linear case (default), when accessing the input image at a fractional coordinate, the obtained value will be computed by linearly interpolating between the closest pixels/voxels. In the Nearest case, the value of the closest pixel/voxel will be used instead.

Furthermore, multiple reduction modes are also supported. In contrast to the interpolation mode, which affects how the value of the input image at a given (potentially fractional) coordinate is extracted, this determines what happens when multiple input pixels/voxels contribute to the value of a single output pixel/voxel. In Nearest mode, the value of the closest input pixel/voxel is used as-is. Alternatively, the Minimum, Maximum or Average value of the neighboring pixel/voxels can be used.

By default, the image will be modified in-place; a new one can be created instead by changing the value of the createNewImage parameter.

By default, the resulting image will have an altered physical extent, since the original extent may not be divisible by the target spacing. The algorithm can modify the target spacing to exactly maintain the physical extent, by toggling the preserveExtent parameter.

If the keepZeroValues parameter is set to true, the input pixels/voxels having zero value will not be modified by the resampling process.

Function overload documentation:

__init__(self: ImageResamplingAlgorithm, input_images: SharedImageSet, reference_images: SharedImageSet = None) → None

__init__(self: ImageResamplingAlgorithm, input_images: SharedImageSet, reference_world_descriptors: list[ImageDescriptorWorld]) → None

class ResamplingMode(self: ResamplingMode, value: int)

Bases: pybind11_object

Members:

TARGET_DIM

TARGET_PERCENT

TARGET_SPACING

TARGET_BINNING

TARGET_BINNING = <ResamplingMode.TARGET_BINNING: 3>

TARGET_DIM = <ResamplingMode.TARGET_DIM: 0>

TARGET_PERCENT = <ResamplingMode.TARGET_PERCENT: 1>

TARGET_SPACING = <ResamplingMode.TARGET_SPACING: 2>

property name

property value

resampling_needed(self: ImageResamplingAlgorithm, frame: int = -1) → bool: Return whether resampling is needed or the specified settings result in the same image size and spacing

set_input(self: ImageResamplingAlgorithm, new_input_images: SharedImageSet, new_reference_images: SharedImageSet, reconfigure_from_new_data: bool) → None

set_input(self: ImageResamplingAlgorithm, new_input_images: SharedImageSet, new_reference_world_descriptors: list[ImageDescriptorWorld], reconfigure_from_new_data: bool) → None

Function overload documentation:

set_input(self: ImageResamplingAlgorithm, new_input_images: SharedImageSet, new_reference_images: SharedImageSet, reconfigure_from_new_data: bool) → None: Replaces the input of the algorithm. If reconfigureFromNewData is true, the algorithm reconfigures itself based on meta data of the new input

set_input(self: ImageResamplingAlgorithm, new_input_images: SharedImageSet, new_reference_world_descriptors: list[ImageDescriptorWorld], reconfigure_from_new_data: bool) → None: Replaces the input of the algorithm. If reconfigureFromNewData is true, the algorithm reconfigures itself based on meta data of the new input

set_target_min_spacing(self: ImageResamplingAlgorithm, min_spacing: float) → bool

set_target_min_spacing(self: ImageResamplingAlgorithm, min_spacing: ndarray[numpy.float64[3, 1]]) → bool

Function overload documentation:

set_target_min_spacing(self: ImageResamplingAlgorithm, min_spacing: float) → bool

Set the target spacing with the spacing of the input image, replacing the value in each dimension with the maximum between the original and the provided value.

Parameters:: min_spacing – the minimum value that the target spacing should have in each direction
Returns:: True if the final target spacing is different than the input image spacing

set_target_min_spacing(self: ImageResamplingAlgorithm, min_spacing: ndarray[numpy.float64[3, 1]]) → bool

Set the target spacing with the spacing of the input image, replacing the value in each dimension with the maximum between the original and the provided value.

Parameters:: min_spacing – the minimum value that the target spacing should have in each direction
Returns:: True if the final target spacing is different than the input image spacing

TARGET_BINNING = <ResamplingMode.TARGET_BINNING: 3>

TARGET_DIM = <ResamplingMode.TARGET_DIM: 0>

TARGET_PERCENT = <ResamplingMode.TARGET_PERCENT: 1>

TARGET_SPACING = <ResamplingMode.TARGET_SPACING: 2>

property clone_deformation: Whether to clone deformation from original image before attaching to result

property create_new_image: Whether to compute the result in-place or in a newly allocated image

property force_cpu: Whether to force the computation on the CPU

property interpolation_mode: Mode for image interpolation

property keep_zero_values: Whether to update the target spacing to keep exactly the physical dimensions of the input image

property preserve_extent: Whether to update the target spacing to keep exactly the physical dimensions of the input image

property reduction_mode: Mode for image reduction (e.g. downsampling, resampling, binning)

property resampling_mode: How the output image size should be obtained (explicit dimensions, percentage relative to the input image, …)

property target_binning: How many pixels from the input image should be combined into an output pixel

property target_dimensions: Target dimensions for the new image

property target_percent: Target dimensions for the new image, relatively to the input one

property target_spacing: Target spacing for the new image

property verbose: Whether to enable advanced logging

class imfusion.ImageView2D: Bases: View

class imfusion.ImageView3D: Bases: View

class imfusion.IntensityMask(*args, **kwargs)

Bases: Mask

Masks pixels with a specific value or values outside a specific range.

Function overload documentation:

__init__(self: IntensityMask, type: PixelType, value: float = 0.0) → None

__init__(self: IntensityMask, image: MemImage, value: float = 0.0) → None

property masked_value: Specific value that should be masked

property masked_value_range: Half-open range [min, max) of allowed pixel values

property type

property use_range: Whether the mask should operate in range mode (true) or single-value mode (false)

class imfusion.InterpolationMode(self: InterpolationMode, value: int)

Bases: pybind11_object

Members:

NEAREST

LINEAR

LINEAR = <InterpolationMode.LINEAR: 1>

NEAREST = <InterpolationMode.NEAREST: 0>

property name

property value

class imfusion.InversionComponent

Bases: DataComponentBase

Data component for storing the information needed to invert an operation.

class InversionInfo

Bases: pybind11_object

Struct for storing the information needed to invert an operation.

property context_properties

property identifier

property operation_name

property operation_properties

get_all_inversion_infos(self: InversionComponent, arg0: str) → list[InversionInfo]

get_inversion_info(self: InversionComponent, arg0: str) → InversionInfo

class imfusion.LabelDataComponent(self: LabelDataComponent, label_map: SharedImageSet = None)

Bases: pybind11_object

Stores metadata for a label map, supporting up to 255 labels.

Creates a LabelDataComponent. If a label map of type uint8 is provided, detects labels in the label map.

class LabelConfig(self: LabelConfig, name: str = '', color: ndarray[numpy.float64[4, 1]] = array([0., 0., 0., 0.]), is_visible2d: bool = True, is_visible3d: bool = True)

Bases: pybind11_object

Encapsulates metadata for a label value in a label map.

Constructor for LabelConfig.

Parameters:

name – Name of the label.
color – RGBA color used for rendering the label.
is_visible2d – Visibility flag for 2D/MPR views.
is_visible3d – Visibility flag for 3D views.

property color: RGBA color used for rendering the label. Values should be in the range [0, 1].

property is_visible2d: Visibility flag for 2D/MPR views.

property is_visible3d: Visibility flag for 3D views.

property name: Name of the label.

property segmentation_algorithm_name: Name of the algorithm used to generate the segmentation.

property segmentation_algorithm_type: Type of algorithm used to generate the segmentation.

property snomed_category_code_meaning: Human-readable meaning of the category code.

property snomed_category_code_value: SNOMED CT code for the category this label represents.

property snomed_type_code_meaning: Human-readable meaning of the type code.

property snomed_type_code_value: SNOMED CT code for the type this label represents.

class SegmentationAlgorithmType(self: SegmentationAlgorithmType, value: int)

Bases: pybind11_object

Members:

UNKNOWN

AUTOMATIC

SEMI_AUTOMATIC

MANUAL

AUTOMATIC = <SegmentationAlgorithmType.AUTOMATIC: 1>

MANUAL = <SegmentationAlgorithmType.MANUAL: 3>

SEMI_AUTOMATIC = <SegmentationAlgorithmType.SEMI_AUTOMATIC: 2>

UNKNOWN = <SegmentationAlgorithmType.UNKNOWN: 0>

property name

property value

detect_labels(self: LabelDataComponent, image: SharedImageSet) → None: Detects labels present in an image of type uint8 and creates configurations for non-existing labels using default configurations.

has_label(self: LabelDataComponent, pixel_value: int) → bool: Checks if a label configuration exists for a pixel value.

label_config(self: LabelDataComponent, pixel_value: int) → LabelConfig | None: Gets label configuration for a pixel value.

label_configs(self: LabelDataComponent) → dict[int, LabelConfig]: Returns known label configurations.

remove_label(self: LabelDataComponent, pixel_value: int) → None: Removes label configuration for a pixel value.

remove_unused_labels(self: LabelDataComponent, image: SharedImageSet) → None: Removes configurations for non-existing labels in an image.

set_default_label_config(self: LabelDataComponent, pixel_value: int) → None: Sets default label configuration for a pixel value.

set_label_config(self: LabelDataComponent, pixel_value: int, config: LabelConfig) → None: Sets label configuration for a pixel value.

set_label_configs(self: LabelDataComponent, configs: dict[int, LabelConfig]) → None: Sets known label configurations from a dictionary mapping pixel values to LabelConfig objects.

AUTOMATIC = <SegmentationAlgorithmType.AUTOMATIC: 1>

MANUAL = <SegmentationAlgorithmType.MANUAL: 3>

SEMI_AUTOMATIC = <SegmentationAlgorithmType.SEMI_AUTOMATIC: 2>

UNKNOWN = <SegmentationAlgorithmType.UNKNOWN: 0>

class imfusion.LayoutMode(self: LayoutMode, value: int)

Bases: pybind11_object

Members:

LAYOUT_ROWS

LAYOUT_FOCUS_PLUS_STACK

LAYOUT_FOCUS_PLUS_ROWS

LAYOUT_SIDE_BY_SIDE

LAYOUT_CUSTOM

LAYOUT_CUSTOM = <LayoutMode.LAYOUT_CUSTOM: 100>

LAYOUT_FOCUS_PLUS_ROWS = <LayoutMode.LAYOUT_FOCUS_PLUS_ROWS: 2>

LAYOUT_FOCUS_PLUS_STACK = <LayoutMode.LAYOUT_FOCUS_PLUS_STACK: 1>

LAYOUT_ROWS = <LayoutMode.LAYOUT_ROWS: 0>

LAYOUT_SIDE_BY_SIDE = <LayoutMode.LAYOUT_SIDE_BY_SIDE: 3>

property name

property value

class imfusion.LicenseInfo

Bases: pybind11_object

Provides information about the currently used license.

property expiration_date: Date until the license is valid in ISO format or None if the license won’t expire.

property key

class imfusion.Mask

Bases: pybind11_object

Base interface for implementing polymorphic image masks.

class CreateOption(self: CreateOption, value: int)

Bases: pybind11_object

Enumeration of available behavior for Mask::create_explicit_mask().

Members:

DEEP_COPY

SHALLOW_COPY_IF_POSSIBLE

DEEP_COPY = <CreateOption.DEEP_COPY: 0>

SHALLOW_COPY_IF_POSSIBLE = <CreateOption.SHALLOW_COPY_IF_POSSIBLE: 1>

property name

property value

create_explicit_mask(self: Mask, image: SharedImage, create_option: CreateOption = CreateOption.DEEP_COPY) → MemImage: Creates an explicit mask representation of this mask for a given image.

is_compatible(self: Mask, arg0: SharedImage) → bool: Returns True if the mask can be used with the given image or False otherwise.

mask_value(self: Mask, coord: ndarray[numpy.int32[3, 1]], color: ndarray[numpy.float32[4, 1]]) → int

mask_value(self: Mask, coord: ndarray[numpy.int32[3, 1]], value: float) → int

Function overload documentation:

mask_value(self: Mask, coord: ndarray[numpy.int32[3, 1]], color: ndarray[numpy.float32[4, 1]]) → int: Returns 0 if the given pixel is outside the mask (i.e. invisible/to be ignored) or a non-zero value if it is inside the mask (i.e. visible/to be considered).

mask_value(self: Mask, coord: ndarray[numpy.int32[3, 1]], value: float) → int: Returns 0 if the given pixel is outside the mask (i.e. invisible/to be ignored) or a non-zero value if it is inside the mask (i.e. visible/to be considered).

DEEP_COPY = <CreateOption.DEEP_COPY: 0>

SHALLOW_COPY_IF_POSSIBLE = <CreateOption.SHALLOW_COPY_IF_POSSIBLE: 1>

property requires_pixel_value: Returns True if the mask_value() rely on the pixel value. If this method returns False, the mask_value() method can be safely used with only the coordinate.

class imfusion.MemImage(*args, **kwargs)

Bases: pybind11_object

A MemImage instance represents an image which resides in main memory.

The MemImage class supports the Buffer Protocol. This means that the underlying buffer can be wrapped in e.g. numpy without a copy:

>>> mem = imfusion.MemImage(imfusion.PixelType.BYTE, 10, 10)
>>> arr = np.array(mem, copy=False)
>>> arr.fill(0)
>>> np.sum(arr)
0

Be aware that most numpy operation create a copy of the data and don’t affect the original data:

>>> np.sum(np.add(arr, 1))
100

>>> np.sum(arr)
0

To update the buffer of a MemImage, use np.copyto:

>>> np.copyto(arr, np.add(arr, 1))
>>> np.sum(arr)
100

Alternatively use the out argument of certain numpy functions:

>>> np.add(arr, 1, out=arr)
array(...)

>>> np.sum(arr)
200

Function overload documentation:

__init__(self: MemImage, type: PixelType, width: int, height: int, slices: int = 1, channels: int = 1) → None

__init__(self: MemImage, desc: ImageDescriptor) → None: Factory method to instantiate a MemImage from an ImageDescriptor. note This method does not initialize the underlying buffer

__init__(self: MemImage, array: ndarray[numpy.int8], greyscale: bool = False) → None

Create a MemImage from a numpy.array.

The array must be contiguous and must have between 2 and 4 dimensions. The dimensions are interpreted as (slices, height, width, channels). Missing dimensions are set to one. The color dimension must always be present even for greyscale image in which case it would be 1.

Use the optional greyscale argument to specify that the color dimensions is missing and the buffer should be interpreted as greyscale.

The actual array data is copied into the MemImage.

__init__(self: MemImage, array: ndarray[numpy.uint8], greyscale: bool = False) → None

__init__(self: MemImage, array: ndarray[numpy.int16], greyscale: bool = False) → None

__init__(self: MemImage, array: ndarray[numpy.uint16], greyscale: bool = False) → None

__init__(self: MemImage, array: ndarray[numpy.int32], greyscale: bool = False) → None

__init__(self: MemImage, array: ndarray[numpy.uint32], greyscale: bool = False) → None

__init__(self: MemImage, array: ndarray[numpy.float32], greyscale: bool = False) → None

__init__(self: MemImage, array: ndarray[numpy.float64], greyscale: bool = False) → None

apply_shift_and_scale(arr): Return a copy of the array with storage values converted to original values. The dtype of the returned array is always DOUBLE.

astype(self: MemImage, image_type: object) → MemImage

Create a copy of the current MemImage instance with the requested Image format.

This function accepts either: - an Image type (e.g. imfusion.Image.UINT); - most of the numpy’s dtypes (e.g. np.uint); - python’s float or int types.

If the requested Image format already matches the Image format of the current instance, then a clone of the current instance is returned.

clone(self: MemImage) → MemImage

convert_to_gray(self: MemImage) → MemImage

create_float(self: object, normalize: bool = True, calc_min_max: bool = True, apply_scale_shift: bool = False) → object

crop(self: MemImage, width: int, height: int, slices: int = -1, ox: int = -1, oy: int = -1, oz: int = -1) → MemImage

downsample(self: MemImage, dx: int, dy: int, dz: int = 1, zero_mask: bool = False, reduction_mode: ReductionMode = ReductionMode.AVERAGE) → MemImage

flip(self: MemImage, dim: int) → MemImage

image_to_pixel(self: MemImage, world: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D image coordinate to a pixel position.

invert(self: MemImage, use_image_range: bool) → MemImage

numpy()

Convenience method for converting a MemImage or a SharedImage into a newly created numpy array with scale and shift already applied.

Shift and scale may determine a complex change of pixel type prior the conversion into numpy array:

as a first rule, even if the type of shift and scale is float, they will still be considered as integers if they are representing integers (e.g. a shift of 2.000 will be treated as 2);
if shift and scale are such that the pixel values range (determined by the pixel_type) would not be fitting into the pixel_type, e.g. a negative pixel value but the type is unsigned, then the pixel_type will be promoted into a signed type if possible, otherwise into a single precision floating point type;
if shift and scale are such that the pixel values range (determined by the pixel_type) would be fitting into a demoted pixel_type, e.g. the type is signed but the range of pixel values is unsigned, then the pixel_type will be demoted;
if shift and scale do not certainly determine that all the possible pixel values (in the range determined by the pixel_type) would become integers, then the pixel_type will be promoted into a single precision floating point type.
in any case, the returned numpy array will be returned with type up to 32-bit integers. If the integer type would require more bits, then the resulting pixel_type will be DOUBLE.

Parameters:: self – instance of a MemImage or of a SharedImage
Returns:: numpy.ndarray

pad(self: MemImage, pad_lower_left_front: ndarray[numpy.int32[3, 1]], pad_upper_right_back: ndarray[numpy.int32[3, 1]], padding_mode: PaddingMode, legacy_mirror_padding: bool = True) → MemImage

pad(self: MemImage, pad_size_x: tuple[int, int], pad_size_y: tuple[int, int], pad_size_z: tuple[int, int], padding_mode: PaddingMode, legacy_mirror_padding: bool = True) → MemImage

Function overload documentation:

pad(self: MemImage, pad_lower_left_front: ndarray[numpy.int32[3, 1]], pad_upper_right_back: ndarray[numpy.int32[3, 1]], padding_mode: PaddingMode, legacy_mirror_padding: bool = True) → MemImage

pad(self: MemImage, pad_size_x: tuple[int, int], pad_size_y: tuple[int, int], pad_size_z: tuple[int, int], padding_mode: PaddingMode, legacy_mirror_padding: bool = True) → MemImage

pixel_to_image(self: MemImage, pixel: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]: Convert a 3D pixel position to an image coordinate.

range_threshold(self: MemImage, inside_range: bool, lower_value: float, upper_value: float, use_original: bool = True, replace_with: float = 0) → MemImage

resample(self: imfusion.MemImage, spacing_adjustment: imfusion.SpacingMode, spacing: numpy.ndarray[numpy.float64[3, 1]], zero_mask: bool = False, reduction_mode: imfusion.ReductionMode = <ReductionMode.AVERAGE: 1>, interpolation_mode: imfusion.InterpolationMode = <InterpolationMode.LINEAR: 1>, allowed_dimension_change: bool = False) → MemImage

resample(self: imfusion.MemImage, dimensions: numpy.ndarray[numpy.int32[3, 1]], zero_mask: bool = False, reduction_mode: imfusion.ReductionMode = <ReductionMode.AVERAGE: 1>, interpolation_mode: imfusion.InterpolationMode = <InterpolationMode.LINEAR: 1>) → MemImage

Function overload documentation:

resample(self: imfusion.MemImage, spacing_adjustment: imfusion.SpacingMode, spacing: numpy.ndarray[numpy.float64[3, 1]], zero_mask: bool = False, reduction_mode: imfusion.ReductionMode = <ReductionMode.AVERAGE: 1>, interpolation_mode: imfusion.InterpolationMode = <InterpolationMode.LINEAR: 1>, allowed_dimension_change: bool = False) → MemImage

resample(self: imfusion.MemImage, dimensions: numpy.ndarray[numpy.int32[3, 1]], zero_mask: bool = False, reduction_mode: imfusion.ReductionMode = <ReductionMode.AVERAGE: 1>, interpolation_mode: imfusion.InterpolationMode = <InterpolationMode.LINEAR: 1>) → MemImage

resize(self: MemImage, width: int, height: int, slices: int, channels: int = 1) → MemImage

rotate(self: MemImage, angle: int = 90, flip_dim: int = -1, axis: int = 2) → MemImage

rotate(self: MemImage, rot: ndarray[numpy.float64[3, 3]], tolerance: float = 0.0) → MemImage

Function overload documentation:

rotate(self: MemImage, angle: int = 90, flip_dim: int = -1, axis: int = 2) → MemImage

rotate(self: MemImage, rot: ndarray[numpy.float64[3, 3]], tolerance: float = 0.0) → MemImage

threshold(self: MemImage, value: float, below: bool, apply_shift_scale: bool = True, merge_channels: bool = False, replace_with: float = 0) → MemImage

static zeros(desc: ImageDescriptor) → MemImage: Factory method to create a zero-initialized image

property channels

property dimension

property dimensions

property extent

property height

property image_to_pixel_matrix

property metric

property ndim

property pixel_to_image_matrix

property scale

property shape

Return a numpy compatible shape descripting the dimensions of this image.

The returned tuple has 4 entries: slices, height, width, channels

property shift

property slices

property spacing

property type

property width

class imfusion.Mesh(*args, **kwargs)

Bases: Data

Function overload documentation:

__init__(self: Mesh, mesh: Mesh) → None

__init__(self: Mesh, name: str = '') → None

class Primitive(self: Primitive, value: int)

Bases: pybind11_object

Enumeration of supported mesh primitives.

Members:

SPHERE

CYLINDER

PYRAMID

CUBE

ICOSAHEDRON_SPHERE

CONE

GRID

CONE = <Primitive.CONE: 5>

CUBE = <Primitive.CUBE: 3>

CYLINDER = <Primitive.CYLINDER: 1>

GRID = <Primitive.GRID: 6>

ICOSAHEDRON_SPHERE = <Primitive.ICOSAHEDRON_SPHERE: 4>

PYRAMID = <Primitive.PYRAMID: 2>

SPHERE = <Primitive.SPHERE: 0>

property name

property value

add_face(self: Mesh, index: ndarray[numpy.int32[3, 1]], force: bool) → int

add_vertex(self: Mesh, position: ndarray[numpy.float64[3, 1]]) → int

static create(shape: Primitive) → Mesh

Create a mesh primitive.

Args:
shape: The shape of the primitive to create.

face_normal(self: Mesh, index: int) → ndarray[numpy.float64[3, 1]]

face_vertices(self: Mesh, index: int) → ndarray[numpy.int32[3, 1]]

halfedge_color(self: Mesh, vertex_index: int, face_index: int) → ndarray[numpy.float32[4, 1]]

halfedge_normal(self: Mesh, vertex_index: int, face_index: int) → ndarray[numpy.float64[3, 1]]

halfedge_vertices(self: Mesh, vertex_index: int, face_index: int) → ndarray[numpy.int32[2, 1]]

is_closed(self: Mesh) → bool

is_manifold(self: Mesh) → bool

is_self_intersecting(self: Mesh) → bool

is_vertex_manifold(self: Mesh, index: int) → bool

is_watertight(self: Mesh, check_self_intersection: bool) → bool

remove_face(self: Mesh, index: int, remove_isolated_vertices: bool) → bool

remove_faces(self: Mesh, indices: list[int], remove_isolated_vertices: bool) → None

remove_halfedge_colors(self: Mesh) → None

remove_halfedge_normals(self: Mesh) → None

remove_vertex_colors(self: Mesh) → None

remove_vertex_normals(self: Mesh) → None

remove_vertices(self: Mesh, indices: list[int], remove_isolated_vertices: bool) → None

set_halfedge_color(self: Mesh, vertex_index: int, face_index: int, color: ndarray[numpy.float32[4, 1]]) → None

set_halfedge_color(self: Mesh, vertex_index: int, face_index: int, color: ndarray[numpy.float32[3, 1]], alpha: float) → None

Function overload documentation:

set_halfedge_color(self: Mesh, vertex_index: int, face_index: int, color: ndarray[numpy.float32[4, 1]]) → None

set_halfedge_color(self: Mesh, vertex_index: int, face_index: int, color: ndarray[numpy.float32[3, 1]], alpha: float) → None

set_halfedge_normal(self: Mesh, vertex_index: int, face_index: int, normal: ndarray[numpy.float64[3, 1]]) → None

set_vertex(self: Mesh, index: int, vertex: ndarray[numpy.float64[3, 1]]) → None

set_vertex_color(self: Mesh, index: int, color: ndarray[numpy.float32[4, 1]]) → None

set_vertex_color(self: Mesh, index: int, color: ndarray[numpy.float32[3, 1]], alpha: float) → None

Function overload documentation:

set_vertex_color(self: Mesh, index: int, color: ndarray[numpy.float32[4, 1]]) → None

set_vertex_color(self: Mesh, index: int, color: ndarray[numpy.float32[3, 1]], alpha: float) → None

set_vertex_normal(self: Mesh, index: int, normal: ndarray[numpy.float64[3, 1]]) → None

vertex(self: Mesh, index: int) → ndarray[numpy.float64[3, 1]]

vertex_color(self: Mesh, index: int) → ndarray[numpy.float32[4, 1]]

vertex_normal(self: Mesh, index: int) → ndarray[numpy.float64[3, 1]]

property center

property extent

property filename

property has_halfedge_colors

property has_halfedge_normals

property has_vertex_colors

property has_vertex_normals

property number_of_faces

property number_of_vertices

class imfusion.Optimizer

Bases: pybind11_object

Object for non-linear optimization.

The current bindings are work in progress and therefore limited. They are so far mostly meant to be used for changing an existing optimizer rather than creating one from scratch.

class Mode(self: Mode, value: int)

Bases: pybind11_object

Mode of operation when execute is called.

Members:

OPT : Standard optimization.

STUDY : Randomized study.

PLOT : Evaluate for 1D or 2D plot generation.

EVALUATE : Single evaluation.

EVALUATE = <Mode.EVALUATE: 3>

OPT = <Mode.OPT: 0>

PLOT = <Mode.PLOT: 2>

STUDY = <Mode.STUDY: 1>

property name

property value

__call__(self: Optimizer, x: list[float]) → list[float]: Delegates to: execute()

abort(self: Optimizer) → None: Request to abort the optimization.

configuration(self: Optimizer) → Properties: Returns the configuration of the object.

configure(self: Optimizer, arg0: Properties) → None: Configures the object.

execute(self: Optimizer, x: list[float]) → list[float]: Execute the optimization given a vector of initial parameters of full dimensionality.

set_bounds(self: Optimizer, bounds: float) → None

set_bounds(self: Optimizer, lower_bounds: float, upper_bounds: float) → None

set_bounds(self: Optimizer, bounds: list[float]) → None

set_bounds(self: Optimizer, lower_bounds: list[float], upper_bounds: list[float]) → None

set_bounds(self: Optimizer, bounds: list[tuple[float, float]]) → None

Function overload documentation:

set_bounds(self: Optimizer, bounds: float) → None: Set the same symmetric bounds in all parameters. A value of zero disables the bounds.

set_bounds(self: Optimizer, lower_bounds: float, upper_bounds: float) → None: Set the same lower and upper bounds for all parameters.

set_bounds(self: Optimizer, bounds: list[float]) → None: Set individual symmetric bounds.

set_bounds(self: Optimizer, lower_bounds: list[float], upper_bounds: list[float]) → None: Set individual lower and upper bounds.

set_bounds(self: Optimizer, bounds: list[tuple[float, float]]) → None: Set individual lower and upper bounds as a list of pairs.

set_logging_level(self: Optimizer, file_level: int | None = None, console_level: int | None = None) → None: Set level of detail for logging to text file and the console. 0 = none (default), 1 = init/result, 2 = every evaluation, 3 = only final result after study.

property abort_eval: Abort after a certain number of cost function evaluations.

property abort_fun_tol: Abort if change in cost function value is becomes too small.

property abort_fun_val: Abort if this function value is reached.

property abort_par_tol: Abort if change in parameter values becomes too small.

property abort_time: Abort after a certain elapsed number of seconds.

property aborted: Whether the optimizer was aborted.

property best_val: Return best cost function value.

property dimension: Total number of parameters. The selection gets cleared when the dimension value is modified.

property first_val: Return cost function value of first evaluation.

property minimizing: Whether the optimizer has a loss function (that it should minimize) or an objective function (that it should maximize).

property mode: Mode of operation when execute is called.

property num_eval: Return number of cost function evaluations computed so far.

property param_names: Names of the parameters.

property selection: Selected parameters.

property type: Type of optimizer (see doc/header).

class imfusion.PaddingMode(*args, **kwargs)

Bases: pybind11_object

Members:

CLAMP

MIRROR

ZERO

Function overload documentation:

__init__(self: PaddingMode, value: int) → None

__init__(self: PaddingMode, arg0: str) → None

CLAMP = <PaddingMode.CLAMP: 2>

MIRROR = <PaddingMode.MIRROR: 1>

ZERO = <PaddingMode.ZERO: 0>

property name

property value

class imfusion.ParametricDeformation

Bases: Deformation

set_parameters(self: ParametricDeformation, parameters: list[float]) → None

class imfusion.PatchInfo

Bases: pybind11_object

Struct for storing the descriptor of the image a patch was extracted from and the region of interest in the original image.

property original_image_descriptor

property roi

class imfusion.PatchesFromImageDataComponent

Bases: DataComponentBase

Data component for keeping track of the original location of a patch in the original image. This is set for instance by the SplitIntoPatchesOperation when extracting patches from the input image.

add(self: PatchesFromImageDataComponent, arg0: PatchInfo) → None

property patch_infos

class imfusion.PixelType(self: PixelType, value: int)

Bases: pybind11_object

Members:

BYTE

UBYTE

SHORT

USHORT

INT

UINT

FLOAT

DOUBLE

HFLOAT

BYTE = <PixelType.BYTE: 5120>

DOUBLE = <PixelType.DOUBLE: 5130>

FLOAT = <PixelType.FLOAT: 5126>

HFLOAT = <PixelType.HFLOAT: 5131>

INT = <PixelType.INT: 5124>

SHORT = <PixelType.SHORT: 5122>

UBYTE = <PixelType.UBYTE: 5121>

UINT = <PixelType.UINT: 5125>

USHORT = <PixelType.USHORT: 5123>

property name

property value

class imfusion.PluginInfo

Bases: pybind11_object

Provides information about a framework plugin.

property name

property path

property version

class imfusion.PointCloud(self: PointCloud, points: list[ndarray[numpy.float64[3, 1]]] = [], *, normals: list[ndarray[numpy.float64[3, 1]]] = [], colors: list[ndarray[numpy.float64[3, 1]]] = [])

Bases: Data

Data structure representing a point cloud in 3d space. Each point can have an associated color and normal vector.

Constructs a point cloud with the specified points, normals and colors. If the number of colors / normals does not match the number of points, they will be ignored with a warning.

Parameters:

points – Vertices of the point cloud.
normals – Normals of the point cloud. If the length does not match points, normals will be dropped with a warning.
colors – Colors (RGB) of the point cloud. If the length does not match points, colors will be dropped with a warning.

clone(self: PointCloud) → PointCloud: Create a new point cloud by deep copying an all data from this instance.

transform_point_cloud(self: PointCloud, transformation: ndarray[numpy.float64[4, 4]]) → None

property colors

property has_normals

property is_dense

property normals

property points

property weights

class imfusion.PointCorrespondences(self: PointCorrespondences, first: PointsOnData, second: PointsOnData)

Bases: pybind11_object

Class that handles point correspondences. Points at corresponding indices on the two PointsOnData instances are considered correspondences. When creating PointCorrespondences(first, second) names of points in first and second are made uniform giving precedence to names in first. Logic for matching points based on their names should be implemented outside of this class. The class supports both full-set and subset-based rigid fitting, allowing users to select specific point correspondences for the transformation calculation. The class supports estimation of a fitting error for any correspondence using complementary correspondences, which can assist with the identification of inconsistent correspondences.

class PointCorrespondenceIterator

Bases: pybind11_object

Iterator for PointCorrespondences

__next__(self: PointCorrespondenceIterator) → object

class Reduction(self: Reduction, value: int)

Bases: pybind11_object

Reduction type used during distance evaluation

Members:

MEAN : Mean reduction

MEDIAN : Median reduction

MAX : Max reduction

MIN : Min reduction

MAX = <Reduction.MAX: 2>

MEAN = <Reduction.MEAN: 0>

MEDIAN = <Reduction.MEDIAN: 1>

MIN = <Reduction.MIN: 3>

property name

property value

__getitem__(self: PointCorrespondences, index: int) → tuple: Get a point correspondences pair (in world coordinates) by index

__iter__(self: PointCorrespondences) → PointCorrespondenceIterator: Iterate over all point correspondences in world coordinates

clear(self: PointCorrespondences) → None: Remove all correspondences.

compute_pairwise_distances(self: PointCorrespondences, reduction: Reduction = Reduction.MEAN, weights: list[float] = None) → float: Compute the distance between pairs of correspondences. Parameters: reduction (PointCorrespondences.Reduction): The reduction method to use (MEAN, MEDIAN, MIN, MAX). weights (list of float): Optional weights for each correspondence. If provided, the individual errors are multiplied with these weights before reduction.

fit_rigid(self: PointCorrespondences, subset_indices: list[int] | None = None) → object: Fit a rigid transformation that aligns the selected correspondences. :param subset_indices: Optional list of indices to use for fitting. If not provided, all selected correspondences are used.

is_selected(self: PointCorrespondences, index: int) → bool: Check if a correspondence is selected.

name(self: PointCorrespondences, index: int) → str: Return the name of a correspondence.

set_name(self: PointCorrespondences, index: int, name: str) → None: Set the name of a correspondence at index ‘index’.

set_selected(self: PointCorrespondences, index: int, selected: bool) → None: Set whether a correspondence is selected.

property point_handler: The PointsOnData handlers.

class imfusion.PointsOnData

Bases: pybind11_object

Base interface for points linked to Data.

clear(self: PointsOnData) → None: Remove all the points

empty(self: PointsOnData) → bool: Check if the list of points is empty

find(self: PointsOnData, name: str, start: int = 0) → int: Get the first index of a point with the given name, starting from index start. Return -1 if not found

numpy(self: PointsOnData) → ndarray[numpy.float64]: Convert all points to a numpy array

property selected_points: Return the selected points in world coordinates

class imfusion.PointsOnImage(self: PointsOnImage, image: SharedImageSet)

Bases: PointsOnData

Class that hold a list of points on a volume or image. Points are automatically updated when the matrix or deformation changes.

Create a PointsOnImage object for the given SharedImageSet.

__getitem__(self: PointsOnImage, index: int) → PyPointsOnImagePoint

__getitem__(self: PointsOnImage, indices: list[int]) → list[PyPointsOnImagePoint]

__getitem__(self: PointsOnImage, slice: slice) → list[PyPointsOnImagePoint]

__getitem__(self: PointsOnImage, name: str) → PyPointsOnImagePoint

Function overload documentation:

__getitem__(self: PointsOnImage, index: int) → PyPointsOnImagePoint

__getitem__(self: PointsOnImage, indices: list[int]) → list[PyPointsOnImagePoint]

__getitem__(self: PointsOnImage, slice: slice) → list[PyPointsOnImagePoint]

__getitem__(self: PointsOnImage, name: str) → PyPointsOnImagePoint: Get a point in world coordinates by name.

__iter__(self: PointsOnImage) → PyPointsIterator: Iterate over all points in world coordinates

__setitem__(self: PointsOnImage, arg0: int, arg1: ndarray[numpy.float64[3, 1]]) → None: Set a point in world coordinates

add_image_point(self: PointsOnImage, point: ndarray[numpy.float64[3, 1]], frame: int) → None: Add a new point in image coordinates for a given frame.

add_world_point(self: PointsOnImage, point: ndarray[numpy.float64[3, 1]], find_closest_frame: bool = True) → None: Add a new point in world coordinates. If find_closest_frame is true, assigns to closest frame.

image_point(self: PointsOnImage, index: int) → tuple[ndarray[numpy.float64[3, 1]], int]: Return the point in image coordinates, paired with its associated frame.

property all_points: Return the points in world coordinates.

property image_points: Return the points in image coordinates, paired with their associated frame.

property selected_image_points: Return only the selected points in image coordinates, paired with their associated frame.

class imfusion.Properties(*args, **kwargs)

Bases: pybind11_object

Properties objects store arbitrary key-value pairs as strings in a hierarchical fashion. Properties are extensively used within the ImFusion frameworks for purposes such as:

Saving and loading the state of an application to and from files.
Configuring the View instances of the UI.
Configuring the Algorithm instances.

The bindings provide two interfaces: a C++-like one based on param() and set_param(), and a more Pythonic interface using the [] operator. Both interfaces are equivalent and interchangeable.

Parameters can be set with the set_param() method, e.g.:

>>> p = imfusion.Properties()
>>> p.set_param('Spam', 5)

The parameter type will be set depending on the type of the Python value similar to C++. To retrieve a parameter, a value of the desired return type must be passed:

>>> spam = 0
>>> p.param('Spam', spam)
5

If the parameter doesn’t exists, the value of the second argument is returned:

>>> foo = 8
>>> p.param('Foo', foo)
8

The Properties object also exposes all its parameters as items, e.g. to add a new parameter just add a new key:

>>> p = imfusion.Properties()
>>> p['spam'] = 5

When using the dictionary-like syntax with the basic types (bool, int, float, str and list), the returned values are typed accordingly:

>>> type(p['spam'])
<class 'int'>

However, for matrix and vector types, the param() method needs to be used, which receives an extra variable of the same type that has to be returned:

>>> import numpy as np
>>> np_array = np.ones(3)
>>> p['foo'] = np_array
>>> p.param('foo', np_array)
array([1., 1., 1.])

In fact, the dictionary-like syntax would just return it as a string instead:

>>> p['foo']
'1 1 1 '

Additionally, the attributes of parameters are available through the param_attributes() method:

>>> p.set_param_attributes('spam', 'max: 10')
>>> p.param_attributes('spam')
[('max', '10')]

A Properties object can be obtained from a dict:

>>> p = imfusion.Properties({'spam': 5, 'eggs': True, 'sub/0': { 'eggs': False }})
>>> p['eggs']
True
>>> p['sub/0']['eggs']
False

There are two possible, but slightly different, ways to convert a Properties instance into a dict. The first method is by dict casting, which returns a dict made by nested Properties. The second method is by calling the asdict() method, which returns a dict expanding also the nested Properties instances:

>>> dict(p)
{'spam': 5, 'eggs': True, 'sub/0': <Properties object at ...>}
>>> p.asdict()
{'spam': 5, 'eggs': True, 'sub/0': {'eggs': False}}

When a parameter needs to take values among a set of possible choices, the parameter can be assigned to an EnumStringParam:

>>> p["choice"] = imfusion.Properties.EnumStringParam(value="choice2", admitted_values={"choice1", "choice2"})
>>> p["choice"]
Properties.EnumStringParam(value="choice2", admitted_values={...})

Please refer to EnumStringParam for more information.

Function overload documentation:

__init__(self: Properties, name: str = '') → None

__init__(self: Properties, dictionary: dict) → None

class EnumStringParam(self: EnumStringParam, *, value: str, admitted_values: set[str])

Bases: pybind11_object

Parameter that can assume a certain value among a set of str possibilities.

A first way to instantiate this class, is to provide the value and the set of admitted values:

>>> p = imfusion.Properties()
>>> p["choice"] = imfusion.Properties.EnumStringParam(value="choice2", admitted_values={"choice1", "choice2"})
>>> p["choice"]
Properties.EnumStringParam(value="choice2", admitted_values={...})

If EnumStringParam is assigned to a value that is not in the set of possible choices, then a ValueError is raised:

>>> p["choice"] = imfusion.Properties.EnumStringParam(value="choice3", admitted_values={"choice1", "choice2"})
Traceback (most recent call last):
        ...
ValueError: EnumStringParam was assigned to 'choice3' but it is not in the set of admitted values: ...

An EnumStringParam instance can be constructed from a Enum member by using the from_enum() method, in which case the EnumStringParam instance gets its value from the given Enum member, and gets its admitted_values from the set of Enum members:

>>> import enum
>>> class Choices(enum.Enum):
...    CHOICE_1: str = "choice1"
...    CHOICE_2: str = "choice2"
...
>>> p["choice"] = imfusion.Properties.EnumStringParam.from_enum(Choices.CHOICE_2)
>>> p["choice"]
Properties.EnumStringParam(value="CHOICE_2", admitted_values={...})

An EnumStringParam instance that corresponds 1-to-1 to an Enum can be converted into the Enum member that corresponds to its current value:

>>> p["choice"].to_enum(Choices)
<Choices.CHOICE_2: 'choice2'>

In the example above, the Enum members were used to populated the admitted_values. However, it is also possible to populate the admitted_values from the Enum values:

>>> p["choice"] = imfusion.Properties.EnumStringParam.from_enum(Choices.CHOICE_2, take_enum_values=True)
>>> p["choice"]
Properties.EnumStringParam(value="choice2", admitted_values={...})
>>> p["choice"].to_enum(Choices)
<Choices.CHOICE_2: 'choice2'>

Parameters:

value – a choice among the set of admitted_values.
admitted_values – set of str defining the available values.

classmethod from_enum()

(cls: object, enum_member: object, take_enum_values: bool = False) -> imfusion.Properties.EnumStringParam

Construct an EnumStringParam automatically out of the provided instance of an enumeration class.

Parameters:

enum_member – a member of an enumeration class. The current value will be assigned to this argument, while the admitted_values will be automatically constructed from the members of the enumeration class.
take_enum_values – is False, then the enumeration members are taken as values. If True, then the enumeration values are taken as values: please note that in this case all the enumeration values must be unique and of str type.

to_enum(self: EnumStringParam, enum_type: object) → object

Casts into the corresponding member of the enum_type type. It raises when this is not possible.

Parameters:: enum_type – the enumeration class into which to cast the current value. Please note that this enumeration class must be compatible, which means it must correspond to the set of admitted_values.

property admitted_values: The current set of admitted values.

property value: The current value that is assumed among the current set of admitted values.

__getitem__(self: Properties, arg0: str) → object

__iter__(self: object) → Iterator

__setitem__(self: Properties, name: str, value: bool) → None

__setitem__(self: Properties, name: str, value: int) → None

__setitem__(self: Properties, name: str, value: float) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]]) → None

__setitem__(self: Properties, name: str, value: str) → None

__setitem__(self: Properties, name: str, value: PathLike) → None

__setitem__(self: Properties, name: str, value: list[str]) → None

__setitem__(self: Properties, name: str, value: list[PathLike]) → None

__setitem__(self: Properties, name: str, value: list[bool]) → None

__setitem__(self: Properties, name: str, value: list[int]) → None

__setitem__(self: Properties, name: str, value: list[float]) → None

__setitem__(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]]) → None

__setitem__(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]]) → None

__setitem__(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]]) → None

__setitem__(self: Properties, name: str, value: EnumStringParam) → None

__setitem__(self: Properties, name: str, value: object) → None

Function overload documentation:

__setitem__(self: Properties, name: str, value: bool) → None

__setitem__(self: Properties, name: str, value: int) → None

__setitem__(self: Properties, name: str, value: float) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]]) → None

__setitem__(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]]) → None

__setitem__(self: Properties, name: str, value: str) → None

__setitem__(self: Properties, name: str, value: PathLike) → None

__setitem__(self: Properties, name: str, value: list[str]) → None

__setitem__(self: Properties, name: str, value: list[PathLike]) → None

__setitem__(self: Properties, name: str, value: list[bool]) → None

__setitem__(self: Properties, name: str, value: list[int]) → None

__setitem__(self: Properties, name: str, value: list[float]) → None

__setitem__(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]]) → None

__setitem__(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]]) → None

__setitem__(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]]) → None

__setitem__(self: Properties, name: str, value: EnumStringParam) → None

__setitem__(self: Properties, name: str, value: object) → None

add_sub_properties(self: Properties, name: str) → Properties

asdict(self: Properties) → dict

Return the Properties as a dict.

The dictionary values have the correct type when they are basic (bool, int, float, str and list), all other param types are returned with a str type. Subproperties are turned into nested dicts.

clear(self: Properties) → None

copy_from(self: Properties, arg0: Properties) → None

get(self: Properties, key: str, default_value: object = None) → object

get_name(self: Properties) → str

items(self: Properties) → list

keys(self: Properties) → list

static load_from_json(path: str) → Properties

static load_from_xml(path: str) → Properties

param(self: Properties, name: str, value: bool) → bool

param(self: Properties, name: str, value: int) → int

param(self: Properties, name: str, value: float) → float

param(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]]) → ndarray[numpy.float64[3, 3]]

param(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]]) → ndarray[numpy.float64[4, 4]]

param(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]]) → ndarray[numpy.float64[3, 4]]

param(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]]) → ndarray[numpy.float32[3, 3]]

param(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]]) → ndarray[numpy.float32[4, 4]]

param(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]]) → ndarray[numpy.float64[2, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]]) → ndarray[numpy.float64[4, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]]) → ndarray[numpy.float64[5, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]]) → ndarray[numpy.float32[2, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]]) → ndarray[numpy.float32[3, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]]) → ndarray[numpy.float32[4, 1]]

param(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]]) → ndarray[numpy.int32[2, 1]]

param(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]]) → ndarray[numpy.int32[3, 1]]

param(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]]) → ndarray[numpy.int32[4, 1]]

param(self: Properties, name: str, value: str) → str

param(self: Properties, name: str, value: PathLike) → PathLike

param(self: Properties, name: str, value: list[str]) → list[str]

param(self: Properties, name: str, value: list[PathLike]) → list[PathLike]

param(self: Properties, name: str, value: list[bool]) → list[bool]

param(self: Properties, name: str, value: list[int]) → list[int]

param(self: Properties, name: str, value: list[float]) → list[float]

param(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]]) → list[ndarray[numpy.float64[2, 1]]]

param(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]]) → list[ndarray[numpy.float64[3, 1]]]

param(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]]) → list[ndarray[numpy.float64[4, 1]]]

param(self: Properties, name: str, value: EnumStringParam) → EnumStringParam

Function overload documentation:

param(self: Properties, name: str, value: bool) → bool

param(self: Properties, name: str, value: int) → int

param(self: Properties, name: str, value: float) → float

param(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]]) → ndarray[numpy.float64[3, 3]]

param(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]]) → ndarray[numpy.float64[4, 4]]

param(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]]) → ndarray[numpy.float64[3, 4]]

param(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]]) → ndarray[numpy.float32[3, 3]]

param(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]]) → ndarray[numpy.float32[4, 4]]

param(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]]) → ndarray[numpy.float64[2, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]]) → ndarray[numpy.float64[4, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]]) → ndarray[numpy.float64[5, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]]) → ndarray[numpy.float32[2, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]]) → ndarray[numpy.float32[3, 1]]

param(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]]) → ndarray[numpy.float32[4, 1]]

param(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]]) → ndarray[numpy.int32[2, 1]]

param(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]]) → ndarray[numpy.int32[3, 1]]

param(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]]) → ndarray[numpy.int32[4, 1]]

param(self: Properties, name: str, value: str) → str

param(self: Properties, name: str, value: PathLike) → PathLike

param(self: Properties, name: str, value: list[str]) → list[str]

param(self: Properties, name: str, value: list[PathLike]) → list[PathLike]

param(self: Properties, name: str, value: list[bool]) → list[bool]

param(self: Properties, name: str, value: list[int]) → list[int]

param(self: Properties, name: str, value: list[float]) → list[float]

param(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]]) → list[ndarray[numpy.float64[2, 1]]]

param(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]]) → list[ndarray[numpy.float64[3, 1]]]

param(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]]) → list[ndarray[numpy.float64[4, 1]]]

param(self: Properties, name: str, value: EnumStringParam) → EnumStringParam

param_attributes(self: Properties, name: str) → list[tuple[str, str]]

params(self: Properties) → list[str]

Return a list of all param names.

Params inside sub-properties will be prefixed with the name of the sub-properties (e.g. ‘sub/var’). If with_sub_params is false, only the top-level params are returned.

remove_param(self: Properties, name: str) → bool

save_to_json(self: Properties, path: str) → None

save_to_xml(self: Properties, path: str) → None

set_name(self: Properties, name: str) → None

set_param(self: Properties, name: str, value: bool) → None

set_param(self: Properties, name: str, value: bool, default: bool) → None

set_param(self: Properties, name: str, value: int) → None

set_param(self: Properties, name: str, value: int, default: int) → None

set_param(self: Properties, name: str, value: float) → None

set_param(self: Properties, name: str, value: float, default: float) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]], default: ndarray[numpy.float64[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]], default: ndarray[numpy.float64[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]], default: ndarray[numpy.float64[3, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]], default: ndarray[numpy.float32[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]], default: ndarray[numpy.float32[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]], default: ndarray[numpy.float64[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]], default: ndarray[numpy.float64[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]], default: ndarray[numpy.float64[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]], default: ndarray[numpy.float64[5, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]], default: ndarray[numpy.float32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]], default: ndarray[numpy.float32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]], default: ndarray[numpy.float32[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]], default: ndarray[numpy.int32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]], default: ndarray[numpy.int32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]], default: ndarray[numpy.int32[4, 1]]) → None

set_param(self: Properties, name: str, value: str) → None

set_param(self: Properties, name: str, value: str, default: str) → None

set_param(self: Properties, name: str, value: PathLike) → None

set_param(self: Properties, name: str, value: PathLike, default: PathLike) → None

set_param(self: Properties, name: str, value: list[str]) → None

set_param(self: Properties, name: str, value: list[str], default: list[str]) → None

set_param(self: Properties, name: str, value: list[PathLike]) → None

set_param(self: Properties, name: str, value: list[PathLike], default: list[PathLike]) → None

set_param(self: Properties, name: str, value: list[bool]) → None

set_param(self: Properties, name: str, value: list[bool], default: list[bool]) → None

set_param(self: Properties, name: str, value: list[int]) → None

set_param(self: Properties, name: str, value: list[int], default: list[int]) → None

set_param(self: Properties, name: str, value: list[float]) → None

set_param(self: Properties, name: str, value: list[float], default: list[float]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]], default: list[ndarray[numpy.float64[2, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]], default: list[ndarray[numpy.float64[3, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]], default: list[ndarray[numpy.float64[4, 1]]]) → None

set_param(self: Properties, name: str, value: EnumStringParam) → None

set_param(self: Properties, name: str, value: EnumStringParam, default: EnumStringParam) → None

Function overload documentation:

set_param(self: Properties, name: str, value: bool) → None

set_param(self: Properties, name: str, value: bool, default: bool) → None

set_param(self: Properties, name: str, value: int) → None

set_param(self: Properties, name: str, value: int, default: int) → None

set_param(self: Properties, name: str, value: float) → None

set_param(self: Properties, name: str, value: float, default: float) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 3]], default: ndarray[numpy.float64[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 4]], default: ndarray[numpy.float64[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 4]], default: ndarray[numpy.float64[3, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 3]], default: ndarray[numpy.float32[3, 3]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 4]], default: ndarray[numpy.float32[4, 4]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[2, 1]], default: ndarray[numpy.float64[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[3, 1]], default: ndarray[numpy.float64[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[4, 1]], default: ndarray[numpy.float64[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float64[5, 1]], default: ndarray[numpy.float64[5, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[2, 1]], default: ndarray[numpy.float32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[3, 1]], default: ndarray[numpy.float32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.float32[4, 1]], default: ndarray[numpy.float32[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[2, 1]], default: ndarray[numpy.int32[2, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[3, 1]], default: ndarray[numpy.int32[3, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]]) → None

set_param(self: Properties, name: str, value: ndarray[numpy.int32[4, 1]], default: ndarray[numpy.int32[4, 1]]) → None

set_param(self: Properties, name: str, value: str) → None

set_param(self: Properties, name: str, value: str, default: str) → None

set_param(self: Properties, name: str, value: PathLike) → None

set_param(self: Properties, name: str, value: PathLike, default: PathLike) → None

set_param(self: Properties, name: str, value: list[str]) → None

set_param(self: Properties, name: str, value: list[str], default: list[str]) → None

set_param(self: Properties, name: str, value: list[PathLike]) → None

set_param(self: Properties, name: str, value: list[PathLike], default: list[PathLike]) → None

set_param(self: Properties, name: str, value: list[bool]) → None

set_param(self: Properties, name: str, value: list[bool], default: list[bool]) → None

set_param(self: Properties, name: str, value: list[int]) → None

set_param(self: Properties, name: str, value: list[int], default: list[int]) → None

set_param(self: Properties, name: str, value: list[float]) → None

set_param(self: Properties, name: str, value: list[float], default: list[float]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[2, 1]]], default: list[ndarray[numpy.float64[2, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[3, 1]]], default: list[ndarray[numpy.float64[3, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]]) → None

set_param(self: Properties, name: str, value: list[ndarray[numpy.float64[4, 1]]], default: list[ndarray[numpy.float64[4, 1]]]) → None

set_param(self: Properties, name: str, value: EnumStringParam) → None

set_param(self: Properties, name: str, value: EnumStringParam, default: EnumStringParam) → None

set_param_attributes(self: Properties, name: str, attributes: str) → None

sub_properties(self: Properties, name: str, create_if_doesnt_exist: bool = False) → Properties

sub_properties(self: Properties) → list[Properties]

Function overload documentation:

sub_properties(self: Properties, name: str, create_if_doesnt_exist: bool = False) → Properties

sub_properties(self: Properties) → list[Properties]

sub_properties_all(self: Properties, name: str) → list

values(self: Properties) → list

class imfusion.PyPointsIterator

Bases: pybind11_object

__iter__(self: PyPointsIterator) → PyPointsIterator

__next__(self: PyPointsIterator) → PyPointsOnImagePoint

class imfusion.PyPointsOnImagePoint

Bases: pybind11_object

property image_frame: Gets/sets the image frame of a point.

property image_position: Gets/sets the image position of a point.

property name: Gets/sets the name of a point.

property selected: Gets/sets whether a point is selected. By default all points are selected.

property world_position: Gets/sets the world position of a point.

class imfusion.RealWorldMappingDataComponent(self: RealWorldMappingDataComponent)

Bases: DataComponentBase

class Mapping(self: Mapping)

Bases: pybind11_object

original_to_real_world(self: Mapping, value: float) → float

storage_to_real_world(self: Mapping, image_descriptor: ImageDescriptor, value: float) → float

property intercept

property slope

property type

property unit

class MappingType(self: MappingType, value: int)

Bases: pybind11_object

Members:

REAL_WORLD_VALUES

STANDARDIZED_UPTAKE_VALUES

REAL_WORLD_VALUES = <MappingType.REAL_WORLD_VALUES: 0>

STANDARDIZED_UPTAKE_VALUES = <MappingType.STANDARDIZED_UPTAKE_VALUES: 1>

property name

property value

REAL_WORLD_VALUES = <MappingType.REAL_WORLD_VALUES: 0>

STANDARDIZED_UPTAKE_VALUES = <MappingType.STANDARDIZED_UPTAKE_VALUES: 1>

property mappings

property units

class imfusion.ReductionMode(self: ReductionMode, value: int)

Bases: pybind11_object

Members:

LOOKUP

AVERAGE

MINIMUM

MAXIMUM

AVERAGE = <ReductionMode.AVERAGE: 1>

LOOKUP = <ReductionMode.LOOKUP: 0>

MAXIMUM = <ReductionMode.MAXIMUM: 3>

MINIMUM = <ReductionMode.MINIMUM: 2>

property name

property value

class imfusion.ReferenceImageDataComponent

Bases: DataComponentBase

Data component used to store a reference image. The reference image is used to keep track of the input of a processing pipeline or a machine learning model, and can be used to set the correct image descriptor for the output of the pipeline.

property reference

class imfusion.RegionOfInterest(self: RegionOfInterest, offset: ndarray[numpy.int32[3, 1]], size: ndarray[numpy.int32[3, 1]])

Bases: pybind11_object

Class representing a rectangular region of interest (ROI) in an image.

The ROI is defined by an offset (starting position) and a size (dimensions).

Parameters:

offset – Starting position of the ROI as a 3D vector (x, y, z) in voxel coordinates
size – Size of the ROI as a 3D vector (width, height, depth) in voxels

property offset: Starting position of the ROI in voxel coordinates

property size: Size of the ROI in voxels

class imfusion.Selection(*args, **kwargs)

Bases: Configurable

Utility class for describing a selection of elements out of a set. Conceptually, a Selection pairs a list of bools describing selected items with the index of a “focus” item and provides syntactic sugar on top. For instance, the set of selected items could define which ones to show in general while the focus item is additionally highlighted. The class is fully separate from the item set of which it describes the selection. This means for instance that it cannot know the actual number of items in the set and the user/parent class must manually make sure that they match. Also, a Selection only manages indices and offers no way of accessing the underlying elements. In order to iterate over all selected indices, you can do for instance the following:

>>> for index in range(selection.start, selection.stop):
...     if selection[index]:
...             pass

The same effect can also be achieved in a much more terse fashion:

>>> for selected_index in selection.selected_indices:
...     pass

For convenience, the selection can also be converted to a slice object (if the selection has a regular spacing, see below):

>>> selected_subset = container[selection.to_slice()]

Sometimes it can be more convenient to “thin out” a selection by only selecting every N-th element. To this end, the Selection constructor takes the arguments start, stop and step. Setting step to N will only select every N-th element, mimicking the signature of range, slice, etc.

Function overload documentation:

__init__(self: Selection) → None

__init__(self: Selection, stop: int) → None

__init__(self: Selection, start: int, stop: int, step: int = 1) → None

__init__(self: Selection, indices: list[int]) → None

class NonePolicy(self: NonePolicy, value: int)

Bases: pybind11_object

Members:

EMPTY

FOCUS

ALL

ALL = <NonePolicy.ALL: 2>

EMPTY = <NonePolicy.EMPTY: 0>

FOCUS = <NonePolicy.FOCUS: 1>

property name

property value

__getitem__(self: Selection, index: int) → bool

__iter__(self: Selection) → object

__setitem__(self: Selection, index: int, selected: bool) → None

clamp(self: Selection, last_selected_index: int) → None

is_selected(self: Selection, index: int, none_policy: NonePolicy) → bool

select_only(self: Selection, index: int) → None

select_up_to(self: Selection, stop: int) → None

set_first_last_skip(self: Selection, arg0: int, arg1: int, arg2: int) → None

to_slice(self: Selection) → slice

ALL = <NonePolicy.ALL: 2>

EMPTY = <NonePolicy.EMPTY: 0>

FOCUS = <NonePolicy.FOCUS: 1>

property first_selected

property focus

property has_regular_skip

property is_none

property last_selected

property range

property selected_indices

property size

property skip

property start

property step

property stop

class imfusion.SharedImage(*args, **kwargs)

Bases: pybind11_object

A SharedImage instance represents an image that resides in different memory locations, i.e. in CPU memory or GPU memory.

A SharedImage can be directly converted from and to a numpy array:

>>> img = imfusion.SharedImage(np.ones([10, 10, 1], dtype='uint8'))
>>> arr = np.array(img)

See MemImage for details.

Function overload documentation:

__init__(self: SharedImage, mem_image: MemImage) → None

__init__(self: SharedImage, desc: ImageDescriptor) → None

__init__(self: SharedImage, desc: ImageDescriptorWorld) → None

__init__(self: SharedImage, type: PixelType, width: int, height: int, slices: int = 1, channels: int = 1) → None

__init__(self: SharedImage, array: ndarray[numpy.int8], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.uint8], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.int16], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.uint16], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.int32], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.uint32], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.float32], greyscale: bool = False) → None

__init__(self: SharedImage, array: ndarray[numpy.float64], greyscale: bool = False) → None

all(self: SharedImage) → bool: Returns True if all pixels / voxels is non-zero

any(self: SharedImage) → bool: Returns True if at least one pixel / voxel is non-zero

apply_shift_and_scale(arr): Return a copy of the array with storage values converted to original values. The dtype of the returned array is always DOUBLE.

argmax(self: SharedImage) → list[ndarray[numpy.int32[4, 1]]]

Return a list of the indices of maximum values, channel-wise. The indices are represented as (x, y, z, image index).

Returns:: List of indices (x, y, z, image index) returned as a list of numpy arrays.

argmin(self: SharedImage) → list[ndarray[numpy.int32[4, 1]]]

Return a list of the indices of minimum values, channel-wise. The indices are represented as (x, y, z, image index).

Returns:: List of indices (x, y, z, image index) returned as a list of numpy arrays.

assign_array(arr, casting='same_kind')

Copies the contents of arr to the SharedImage. Automatically calls setDirtyMem.

The casting parameters behaves like numpy.copyto.

astype(self: SharedImage, pixelType: object) → SharedImage

Create a copy of the current SharedImage instance with the requested Image format.

This function accepts either: - a PixelType (e.g. imfusion.PixelType.UInt); - most of the numpy’s dtypes (e.g. np.uint); - python’s float or int types.

If the requested PixelType already matches the PixelType of the provided SharedImage, then a clone of the current instance is returned.

channel_swizzle(self: SharedImage, indices: list[int]) → SharedImage

Reorders the channels of an image based on the input indices, e.g. indices[0] will correspond to the first channel of the output image.

Parameters:: indices – List of channel indices to swizzle the channels of the input.
Returns:: SharedImage instance with reordered channels.

clone(self: SharedImage) → SharedImage

dimension(self: SharedImage) → int

exclusive_mem(self: SharedImage) → None: Clear representations that are not CPU memory

image_to_world(self: SharedImage, image_coordinates: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

max(self: SharedImage) → ndarray[numpy.float64[m, 1]]

Return the list of the maximum elements of images, channel-wise.

Returns:: Channel-wise values returned as a numpy array.

mean(self: SharedImage) → ndarray[numpy.float64[m, 1]]

Return a list of channel-wise average of image elements.

Returns:: Channel-wise values returned as a numpy array.

mem(self: SharedImage) → MemImage

min(self: SharedImage) → ndarray[numpy.float64[m, 1]]

Return the list of the minimum elements of images, channel-wise.

Returns:: Channel-wise values returned as a numpy array.

norm(self: SharedImage, order: int | float | str = 2) → ndarray[numpy.float64[m, 1]]

Returns the norm of an image instance, channel-wise.

Parameters:: order – Order of the norm. Use a number (e.g., 1 or 2) or ‘inf’. The default is the L2 norm.
Returns:: Norm values per channel returned as a numpy array.

numpy()

Convenience method for converting a MemImage or a SharedImage into a newly created numpy array with scale and shift already applied.

Shift and scale may determine a complex change of pixel type prior the conversion into numpy array:

as a first rule, even if the type of shift and scale is float, they will still be considered as integers if they are representing integers (e.g. a shift of 2.000 will be treated as 2);
if shift and scale are such that the pixel values range (determined by the pixel_type) would not be fitting into the pixel_type, e.g. a negative pixel value but the type is unsigned, then the pixel_type will be promoted into a signed type if possible, otherwise into a single precision floating point type;
if shift and scale are such that the pixel values range (determined by the pixel_type) would be fitting into a demoted pixel_type, e.g. the type is signed but the range of pixel values is unsigned, then the pixel_type will be demoted;
if shift and scale do not certainly determine that all the possible pixel values (in the range determined by the pixel_type) would become integers, then the pixel_type will be promoted into a single precision floating point type.
in any case, the returned numpy array will be returned with type up to 32-bit integers. If the integer type would require more bits, then the resulting pixel_type will be DOUBLE.

Parameters:: self – instance of a MemImage or of a SharedImage
Returns:: numpy.ndarray

pixel_to_world(self: SharedImage, pixel_coordinates: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

prepare(self: SharedImage, shift_only: bool = False) → None

Prepare the image:: Integral types are converted to unsigned representation if applicable, double-precision will be converted to single-precision float. Furthermore, if shift_only is False it will rescale the present intensity range to [0..1] for floating point types or to the entire available value range for integral types.

prod(self: SharedImage) → ndarray[numpy.float64[m, 1]]

Return a list of channel-wise production of image elements.

Returns:: Channel-wise values returned as a numpy array.

set_dirty_mem(self: SharedImage) → None

sum(self: SharedImage) → ndarray[numpy.float64[m, 1]]

Return a list of channel-wise sum of image elements.

Returns:: Channel-wise values returned as a numpy array.

sync(self: SharedImage) → None

torch(device: device = None, dtype: dtype = None, same_as: Tensor = None) → Tensor

Convert SharedImageSet or a SharedImage to a torch.Tensor.

Parameters:

self (DataElement | SharedImageSet | SharedImage) – Instance of SharedImageSet or SharedImage (this function bound as a method to SharedImageSet and SharedImage)
device (device) – Target device for the new torch.Tensor
dtype (dtype) – Type of the new torch.Tensor
same_as (Tensor) – Template tensor whose device and dtype configuration should be matched. device and dtype are still applied afterwards.

Returns:

New torch.Tensor

Return type:

Tensor

world_to_image(self: SharedImage, world_coordinates: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

world_to_pixel(self: SharedImage, world_coordinates: ndarray[numpy.float64[3, 1]]) → ndarray[numpy.float64[3, 1]]

property channels

property deformation

property descriptor: Read-only descriptor view of this image.

property descriptor_world: Read-only world descriptor view of this image.

property extent

property height

property image_to_world_matrix

property kind

property mask

property metric

property modality

property ndim

property pixel_to_world_matrix

property scale

property shape

Numpy compatible shape describing the dimensions of this image, stored as a namedtuple.

Returns:: Named tuple with slices, height, width, and channels attributes.
Return type:: (collections.namedtuple)

property shift

property slices

property spacing

Physical extent of each voxel in [mm] stored as a namedtuple. Spacing for a specific dimension can be accessed via x, y, and z attributes.

Returns:: Named tuple with x, y, and z attributes.
Return type:: (collections.namedtuple)

property width

property world_to_image_matrix

property world_to_pixel_matrix

class imfusion.SharedImageSet(*args, **kwargs)

Bases: Data

Set of images independent of their storage location.

This class is the main high-level container for image data consisting of one or multiple images or volumes, and should be used both in algorithms and visualization classes. Both a single focus and multiple selection is featured, as well as providing transformation matrices for each image.

The focus image of a SharedImageSet can be directly converted from and to a numpy array:

>>> img = imfusion.SharedImageSet(np.ones([1, 10, 10, 10, 1], dtype='uint8'))
>>> arr = np.array(img)

See MemImage for details.

Function overload documentation:

__init__(self: SharedImageSet) → None: Creates an empty SharedImageSet.

__init__(self: SharedImageSet, mem_image: MemImage) → None

__init__(self: SharedImageSet, shared_image: SharedImage) → None

__init__(self: SharedImageSet, array: ndarray[numpy.int8], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.uint8], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.int16], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.uint16], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.int32], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.uint32], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.float32], greyscale: bool = False) → None

__init__(self: SharedImageSet, array: ndarray[numpy.float64], greyscale: bool = False) → None

__getitem__(self: SharedImageSet, index: int) → SharedImage

__iter__(self: SharedImageSet) → Iterator[SharedImage]

add(self: SharedImageSet, shared_image: SharedImage) → None

add(self: SharedImageSet, mem_image: MemImage) → None

Function overload documentation:

add(self: SharedImageSet, shared_image: SharedImage) → None

add(self: SharedImageSet, mem_image: MemImage) → None

all(self: SharedImageSet) → bool: Returns True if all pixels / voxels is non-zero

any(self: SharedImageSet) → bool: Returns True if at least one pixel / voxel is non-zero

apply_shift_and_scale(arr)

Return a copy of the array with storage values converted to original values.

Parameters:

self – instance of a SharedImageSet which provides shift and scale
arr – array to be converted from storage values into original values

Returns:

numpy.ndarray

argmax(self: SharedImageSet) → list[ndarray[numpy.int32[4, 1]]]

Return a list of the indices of maximum values, channel-wise. The indices are represented as (x, y, z, image index).

Returns:: List of indices (x, y, z, image index) returned as a list of numpy arrays.

argmin(self: SharedImageSet) → list[ndarray[numpy.int32[4, 1]]]

Return a list of the indices of minimum values, channel-wise. The indices are represented as (x, y, z, image index).

Returns:: List of indices (x, y, z, image index) returned as a list of numpy arrays.

assign_array(arr): Copies the contents of arr to the MemImage. Automatically calls setDirtyMem.

astype(self: SharedImageSet, pixel_type: object) → SharedImageSet

Returns a new SharedImageSet formed by new SharedImage instances obtained by converting the original ones into the requested PixelType.

This function accepts either: - a PixelType (e.g. imfusion.PixelType.UInt); - most of the numpy’s dtypes (e.g. np.uint); - python’s float or int types.

If the requested type already matches the input type, the returned SharedImageSet will contain clones of the original images.

channel_swizzle(self: SharedImageSet, indices: list[int]) → SharedImageSet

Reorders the channels of an image based on the input indices, e.g. indices[0] will correspond to the first channel of the output image.

Parameters:: indices – List of channel indices to swizzle the channels of the input.
Returns:: SharedImageSet instance with reordered channels.

clear(self: SharedImageSet) → None

clone(self: SharedImageSet, with_data: bool = True) → SharedImageSet

deformation(self: SharedImageSet, which: int = -1) → Deformation

descriptor(self: SharedImageSet, which: int = -1) → BoundImageDescriptor: Return a read-only descriptor view for a specific or selected image.

elementwise_components(self: SharedImageSet, which: int = -1) → DataComponentList

static from_images(path: str) → SharedImageSet

static from_images(path: list[str]) → SharedImageSet

Function overload documentation:

from_images(path: str) → SharedImageSet

Load different images as a single SharedImageSet.

Currently supported image formats are: [bmp, pgm, png, ppm, jpg, jpeg, tif, tiff, jp2].

Parameters:: folder_path – The directory where all images are located to be loaded as a SharedImageSet.
Raises:: IOError if the file cannot be opened or if the extensions is not supported. –

from_images(path: list[str]) → SharedImageSet

Load different images as a single SharedImageSet.

Currently supported image formats are: [bmp, pgm, png, ppm, jpg, jpeg, tif, tiff, jp2].

Parameters:: file_paths – paths to image files to be loaded as a SharedImageSet.
Raises:: IOError if the file cannot be opened or if the extensions is not supported. –

classmethod from_torch(tensor: Tensor, get_metadata_from: SharedImageSet | None = None) → SharedImageSet

Create a SharedImageSet from a torch Tensor. If you want to copy metadata from an existing SharedImageSet you can pass it as the get_metadata_from argument. If you are using this, make sure that the size of the tensor’s batch dimension and the number of images in the SIS are equal. If get_metadata_from is provided, properties will be copied from the SIS and world_to_image_matrix, spacing and modality from the contained SharedImages.

Parameters:

cls – Instance of type i.e. SharedImageSet (this function is bound as a classmethod to SharedImageSet)
tensor (Tensor) – Instance of torch.Tensor
get_metadata_from (SharedImageSet | None) – Instance of SharedImageSet from which metadata should be copied.

Returns:

New instance of SharedImageSet

Return type:

SharedImageSet

get(self: SharedImageSet, which: int = -1) → SharedImage

mask(self: SharedImageSet, which: int = -1) → Mask

matrix(self: SharedImageSet, which: int = -1) → ndarray[numpy.float64[4, 4]]

matrix_from_world(self: SharedImageSet, which: int) → ndarray[numpy.float64[4, 4]]

matrix_to_world(self: SharedImageSet, which: int) → ndarray[numpy.float64[4, 4]]

max(self: SharedImageSet) → ndarray[numpy.float64[m, 1]]

Return the list of the maximum elements of images, channel-wise.

Returns:: Channel-wise values returned as a numpy array.

mean(self: SharedImageSet) → ndarray[numpy.float64[m, 1]]

Return a list of channel-wise average of image elements.

Returns:: Channel-wise values returned as a numpy array.

mem(self: SharedImageSet, which: int = -1) → MemImage

min(self: SharedImageSet) → ndarray[numpy.float64[m, 1]]

Return the list of the minimum elements of images, channel-wise.

Returns:: Channel-wise values returned as a numpy array.

norm(self: SharedImageSet, order: int | float | str = 2) → ndarray[numpy.float64[m, 1]]

Returns the norm of an image instance, channel-wise.

Parameters:: order – Order of the norm. Use a number (e.g., 1 or 2) or ‘inf’. The default is the L2 norm.
Returns:: Norm values per channel returned as a numpy array.

numpy()

Convenience method for reading a SharedImageSet as original values, with shift and scale already applied.

Parameters:: self – instance of a SharedImageSet
Returns:: numpy.ndarray

prod(self: SharedImageSet) → ndarray[numpy.float64[m, 1]]

Return a list of channel-wise production of image elements.

Returns:: Channel-wise values returned as a numpy array.

remove(self: SharedImageSet, shared_image: SharedImage) → None: Removes and deletes the SharedImage from the set.

selected_images(self: SharedImageSet, arg0: NonePolicy) → list[SharedImage]

set_deformation(self: SharedImageSet, deformation: Deformation, which: int = -1) → None

set_dirty_mem(self: SharedImageSet) → None

set_mask(self: SharedImageSet, mask: Mask, which: int = -1) → None

set_matrix(self: SharedImageSet, matrix: ndarray[numpy.float64[4, 4]], which: int = -1, update_all: bool = False) → None

set_matrix_from_world(self: SharedImageSet, matrix: ndarray[numpy.float64[4, 4]], which: int, update_all: bool = False) → None

set_matrix_to_world(self: SharedImageSet, matrix: ndarray[numpy.float64[4, 4]], which: int, update_all: bool = False) → None

set_timestamp(self: SharedImageSet, time: float, which: int = -1) → None

sum(self: SharedImageSet) → ndarray[numpy.float64[m, 1]]

Return a list of channel-wise sum of image elements.

Returns:: Channel-wise values returned as a numpy array.

timestamp(self: SharedImageSet, which: int = -1) → float

torch(device: device = None, dtype: dtype = None, same_as: Tensor = None) → Tensor

Convert SharedImageSet or a SharedImage to a torch.Tensor.

Parameters:

self (DataElement | SharedImageSet | SharedImage) – Instance of SharedImageSet or SharedImage (this function bound as a method to SharedImageSet and SharedImage)
device (device) – Target device for the new torch.Tensor
dtype (dtype) – Type of the new torch.Tensor
same_as (Tensor) – Template tensor whose device and dtype configuration should be matched. device and dtype are still applied afterwards.

Returns:

New torch.Tensor

Return type:

Tensor

property all_same_descriptor

property all_timestamped

property focus

property modality

property properties

property selection

property shape

Return a numpy compatible shape descripting the dimensions of this image.

The returned tuple has 5 entries: #frames, slices, height, width, channels

property size

class imfusion.SignalConnection

Bases: pybind11_object

disconnect(self: SignalConnection) → bool

property is_active

property is_blocked

property is_connected

class imfusion.SkippingMask(self: SkippingMask, shape: ndarray[numpy.int32[3, 1]], skip: ndarray[numpy.int32[3, 1]])

Bases: Mask

Basic mask where only every N-th pixel is considered inside.

property skip: Step size in pixels for the mask

class imfusion.SpacingMode(self: SpacingMode, value: int)

Bases: pybind11_object

Members:

EXACT

ADJUST

ADJUST = <SpacingMode.ADJUST: 1>

EXACT = <SpacingMode.EXACT: 0>

property name

property value

class imfusion.TrackedSharedImageSet(self: TrackedSharedImageSet)

Bases: SharedImageSet

add_tracking(self: TrackedSharedImageSet, tracking_sequence: TrackingSequence) → None

clear_trackings(self: TrackedSharedImageSet) → None

remove_tracking(self: TrackedSharedImageSet, num: int = -1) → TrackingSequence

tracking(self: TrackedSharedImageSet, num: int = -1) → TrackingSequence

property height

property num_tracking

property tracking_used

property trackings

property use_timestamps

property width

class imfusion.TrackerID(*args, **kwargs)

Bases: pybind11_object

Function overload documentation:

__init__(self: TrackerID) → None

__init__(self: TrackerID, id: str = '', model_number: str = '', name: str = '') → None

empty(self: TrackerID) → bool

from_string(self: str) → TrackerID

to_model_name_string(self: TrackerID, arg0: bool) → str

to_string(self: TrackerID, arg0: bool) → str

property id

property model_number

property name

class imfusion.TrackingSequence(self: TrackingSequence, name: str = '')

Bases: Data

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]]) → None

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]], timestamp: float) → None

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]], timestamp: float, quality: float) → None

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]], timestamp: float, quality: float, flags: int) → None

Function overload documentation:

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]]) → None

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]], timestamp: float) → None

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]], timestamp: float, quality: float) → None

add(self: TrackingSequence, mat: ndarray[numpy.float64[4, 4]], timestamp: float, quality: float, flags: int) → None

clear(self: TrackingSequence) → None

flags(self: TrackingSequence, num: int = -1) → int

matrix(self: TrackingSequence, num: int) → ndarray[numpy.float64[4, 4]]

matrix(self: TrackingSequence, time: float) → ndarray[numpy.float64[4, 4]]

Function overload documentation:

matrix(self: TrackingSequence, num: int) → ndarray[numpy.float64[4, 4]]

matrix(self: TrackingSequence, time: float) → ndarray[numpy.float64[4, 4]]

quality(self: TrackingSequence, num: int) → float

quality(self: TrackingSequence, time: float, check_distance: bool = True, ignore_relative: bool = False) → float

Function overload documentation:

quality(self: TrackingSequence, num: int) → float

quality(self: TrackingSequence, time: float, check_distance: bool = True, ignore_relative: bool = False) → float

raw_matrix(self: TrackingSequence, num: int) → ndarray[numpy.float64[4, 4]]

remove(self: TrackingSequence, pos: int, count: int = 1) → None

set_raw_matrix(self: TrackingSequence, idx: int, value: ndarray[numpy.float64[4, 4]]) → None

set_timestamp(self: TrackingSequence, idx: int, value: float) → None

shift_timestamps(self: TrackingSequence, shift: float) → None

timestamp(self: TrackingSequence, num: int = -1) → float

property calibration

property center

property filename

property filter_mode

property filter_size

property has_timestamps

property instrument_id

property instrument_model

property instrument_name

property invert

property median_time_step

property registration

property relative_to_first

property relative_tracking

property size

property temporal_offset

property tracker_id

class imfusion.TransformationStashDataComponent(self: TransformationStashDataComponent)

Bases: DataComponentBase

property original

property transformations

class imfusion.View

Bases: pybind11_object

reset(self: View) → None

property visible

class imfusion.VisualizerHandle

Bases: pybind11_object

The handle to a visualizer. It allows to close a specific visualizer when needed. Example:

>>> visualizer_handle = imfusion.show(data_list, title="MyData")
>>> assert visualizer_handle.title() == "MyData"
>>> ...  
>>> visualizer_handle.close()

close(self: VisualizerHandle) → None: Close the visualizer associated to this handle.

title(self: VisualizerHandle) → str: Get the title of the visualizer associated to this handle.

class imfusion.VitalsDataComponent

Bases: DataComponentBase

DataComponent for storing a collection of time dependent vital signs like ECG, heart rate or pulse oximeter measurements.

class VitalsKind(self: VitalsKind, value: int)

Bases: pybind11_object

Members:

ECG

PULSE_OXIMETER

HEARTH_RATE

OTHER

ECG = <VitalsKind.ECG: 0>

HEARTH_RATE = <VitalsKind.HEARTH_RATE: 2>

OTHER = <VitalsKind.OTHER: 3>

PULSE_OXIMETER = <VitalsKind.PULSE_OXIMETER: 1>

property name

property value

class VitalsTimeSeries

Bases: pybind11_object

property signal

property timestamps

__getitem__(self: VitalsDataComponent, kind: VitalsKind) → list[VitalsTimeSeries]

ECG = <VitalsKind.ECG: 0>

HEARTH_RATE = <VitalsKind.HEARTH_RATE: 2>

OTHER = <VitalsKind.OTHER: 3>

PULSE_OXIMETER = <VitalsKind.PULSE_OXIMETER: 1>

property kinds

imfusion.algorithm_properties(id: str, data: list) → object: Returns the default properties of the given algorithm. This is useful to figure out what properties are supported by an algorithm.

Deprecated since version 0.12.0: Use imfusion.algorithm.get_properties() instead.

imfusion.auto_window(image: SharedImageSet, change2d: bool = True, change3d: bool = True, lower_limit: float = 0.0, upper_limit: float = 0.0) → None

Update window/level of input image to show the entire intensity range of the image.

Parameters:

image (SharedImageSet) – Image to change the windowing for.
change2d (bool) – Flag whether update the DisplayOptions2d attached to a img.
change3d (bool) – Flag whether update the DisplayOptions3d attached to a img.
lower_limit (double) – Ratio of lower values removed by the auto windowing.
upper_limit (double) – Ratio of upper values removed by the auto windowing.

imfusion.available_algorithms(sub_string: str = '', case_sensitive: bool = False) → object

Return a list of all available algorithm ids.

Optionally, a substring can be given to filter the list (case-insensitive by default).

Deprecated since version 0.12.0: Use imfusion.algorithm.list_available() instead.

imfusion.available_data_components() → list[str]: Returns the Unique IDs of all DataComponents registered in DataComponentFactory.

imfusion.close_viewers() → None: Close all the visualizers that were opened with show().

imfusion.create_algorithm(id: str, data: list = [], properties: Properties = None) → object

Create the algorithm with the given id without executing it.

The algorithm will only be created if it is compatible with the given data. The optional Properties object will be used to configure the algorithm.

Deprecated since version 0.12.0: Use imfusion.algorithm.create() instead.

imfusion.create_data_component(id: str, properties: Properties = None) → object

Instantiates a DataComponent specified by the given ID.

Parameters:

id – Unique ID of the DataComponent to create.
properties – Optional Properties object. If not None, it will used to configure the newly created DataComponent.

imfusion.documentation_url() → str: Returns the URL to the ImFusion Python SDK documentation.

imfusion.execute_algorithm(id: str, data: list = [], properties: Properties = None) → object

Execute the algorithm with the given id and return its output.

The algorithm will only be executed if it is compatible with the given data. The optional Properties object will be used to configure the algorithm before executing it.

Deprecated since version 0.12.0: Use imfusion.algorithm.execute() instead.

imfusion.gpu_info() → str | None: Return string with information about GPU to check if hardware support for OpenGL is available.

imfusion.has_gl_context() → bool

imfusion.info(*, show_license_key: bool = False) → FrameworkInfo: Provides general information about the framework.

imfusion.init(pluginFolders: list = [], initOpenGL: bool = True) → None

imfusion.is_compatible_imfusion_plugin(arg0: str | PathLike) → bool

imfusion.list_viewers() → list[VisualizerHandle]: Return a list of visualization handles that were created with show(). Please note that this method may return viewers that have been closed without VisualizerHandle.close() or close_viewers().

imfusion.load(path: str | PathLike) → object: Deprecation alias for imfusion.io.load().

imfusion.load_plugin(path: str | PathLike) → str: Load a single ImFusionLib plugin from the given file. WARNING: This might execute arbitary code. Only use with trusted files!

imfusion.load_plugins(folder: str | PathLike) → None: Loads all ImFusionLib plugins from the given folder. WARNING: This might execute arbitary code. Only use with trusted folders!

imfusion.log_debug(message: str) → None

imfusion.log_error(message: str) → None

imfusion.log_info(message: str) → None

imfusion.log_level() → int: Returns the level of the logging in the ImFusionSDK (Trace = 0, Debug = 1, Info = 2, Warning = 3, Error = 4, Fatal = 5, Quiet = 6)

imfusion.log_trace(message: str) → None

imfusion.log_warn(message: str) → None

imfusion.open_in_suite(data: list[Data]) → None: Starts the ImFusion Suite with the input data list. The ImFusionSuite executable must be in your PATH.

imfusion.opencv_build_version() → str: OpenCV version the ImFusion build was linked against (e.g. “4.12.0”).

imfusion.save(object: object, path: str | PathLike) → object

imfusion.save(image: SharedImageSet, path: str | PathLike, **kwargs) → object

Function overload documentation:

imfusion.save(object: object, path: str | PathLike) → object: Deprecation alias for imfusion.io.save().

imfusion.save(image: SharedImageSet, path: str | PathLike, **kwargs) → object: Deprecation alias for imfusion.io.save().

imfusion.set_log_level(level: int) → None

Sets the level of the logging in the ImFusionSDK (Trace = 0, Debug = 1, Info = 2, Warning = 3, Error = 4, Fatal = 5, Quiet = 6).

The initial log level is 3 (Warning), but can be set explicitly with the IMFUSION_LOG_LEVEL environment variable.

Note

After calling transfer_logging_to_python() this function has no effect.

Launch a visualizer displaying the given Data (e.g. a SharedImageSet), or DataList or the content of the requested file.

Parameters:

data_or_file – Input data or path to the file to be displayed. When providing a path, please note that only .imf files are supported at this point.
title – Optional window title.
block – Option to control whether to block or not the python interpreter while the visualizer is running. In case of None, the visualizer automatically becomes non-blocking when the Python interpreter is in interactive mode.

Returns:

A VisualizerHandle for the opened visualizer.

imfusion.transfer_logging_to_python() → None

Transfers the control of logging from ImFusionLib to the “ImFusion” logger, which can obtained through the python’s logging module with logging.getLogger("ImFusion").

After calling transfer_logging_to_python, the configuration of the logger will be possible exclusively through the Python’s logging module interface, e.g. using logging.getLogger("ImFusion").setLevel. Besides, all the imfusion logs that happen after calling this function but before importing the logging module will not be captured.

Note

Please note that this redirection cannot be cancelled and that any subsequent calls to this functions will have no effect.

Warning

Due to the GIL, log messages from internal threads won’t be forwarded to the logger.

imfusion.processing

Submodule containing routines for data processing.

class imfusion.processing.PointDistanceResult(self: PointDistanceResult, mean_distance: float, median_distance: float, standard_deviation: float, min_distance: float, max_distance: float, distances: ndarray[numpy.float64[m, 1]])

Bases: pybind11_object

property distances

property max_distance

property mean_distance

property median_distance

property min_distance

property standard_deviation

imfusion.processing.compute_point_distance(target: Mesh | PointCloud, source: Mesh | PointCloud, signed_distance: bool = False, range_of_interest: tuple[int, int] | None = None) → PointDistanceResult

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.io

IO

imfusion.io.load(path: str | PathLike) → list

Load the content of a file or folder as a list of Data.

The list can contain instances of any class deriving from Data, i.e. SharedImage, Mesh, PointCloud, etc…

Parameters:: path – can be path to a file containing a supported file formats, or a folder containing Dicom data, if the imfusion package was built with Dicom support.

Note

An IOError is raised if the file cannot be opened or a ValueError if the filetype is not supported. Some filetypes (like workspaces) cannot be opened by this function, but must be opened with imfusion.ApplicationController.open().

For PointCloud files in .pcd format: PCD files store colors as integers in the range [0, 255], however, the returned PointCloud will have colors converted to floating-point values in the range [0.0, 1.0].

Example

>>> imfusion.io.load('ct_image.png')  
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(USHORT width: 512 height: 512 spacing: 0.661813x0.661813x1 mm)])]  
>>> imfusion.io.load('multi_label_segmentation.nii.gz')  
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(UBYTE width: 128 height: 128 slices: 128 channels: 3 spacing: 1x1x1 mm)])]  
>>> imfusion.io.load('us_sweep.dcm')  
[imfusion.SharedImageSet(size: 20, [  
        imfusion.SharedImage(UBYTE width: 164 height: 552 spacing: 0.228659x0.0724638x1 mm),  
        imfusion.SharedImage(UBYTE width: 164 height: 552 spacing: 0.228659x0.0724638x1 mm),  
        ...  
        imfusion.SharedImage(UBYTE width: 164 height: 552 spacing: 0.228659x0.0724638x1 mm)  
>>> imfusion.io.load('path_to_folder_containing_multiple_dcm_datasets')  
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(FLOAT width: 400 height: 400 slices: 300 spacing: 2.03642x2.03642x3 mm)])]  

imfusion.io.save(shared_image_set: SharedImageSet, path: str | PathLike, **kwargs) → None

imfusion.io.save(mesh: Mesh, file_path: str | PathLike) → None

imfusion.io.save(point_cloud: PointCloud, file_path: str | PathLike) → None

imfusion.io.save(data: Data, file_path: str | PathLike) → None

imfusion.io.save(data_list: list[Data], file_path: str | PathLike) → None

Function overload documentation:

imfusion.io.save(shared_image_set: SharedImageSet, path: str | PathLike, **kwargs) → None

Save a SharedImageSet to the specified file or folder path. The path extension is used to determine which file format to save to. If a folder path is provided instead, then images are saved in the directory as separate png files. Currently supported file formats are:

ImFusion File, extension imf

NIfTI File, extensions [nii, nii.gz]

Folder path

Parameters:

shared_image_set – Instance of SharedImageSet.
path – Path to output file or folder. The path extension is used to determine the file format.

Keyword Arguments:

keep_ras_coordinates (bool) – NIfTI only. Whether to keep to the keep RAS (Right, Anterior, Superior) coordinate system.
compression_level (int) – Folder only. Compression level of the output png files. Valid values range from 0-9 (0 - no compression, 9 - “maximal” compression).

Raises:

RuntimeError if path extension is not supported. Currently supported extensions are ['imf', 'nii', 'nii.gz'], or no extension (save to folder). –

Example

>>> image_set = imfusion.SharedImageSet(np.ones((1,8,8,1)))
>>> imfusion.io.save(image_set, tmp_path / 'file.imf')  # saves an ImFusion file
>>> imfusion.io.save(image_set, tmp_path / 'file.nii.gz', keep_ras_coordinates=True)  # saves a NIfTI file

imfusion.io.save(mesh: Mesh, file_path: str | PathLike) → None

Save a imfusion.Mesh to the specified file path. The path extension is used to determine which file format to save to. Currently supported file formats are:

ImFusion File, extension imf

Polygon File Format or the Stanford Triangle Format, extension ply

STL file format used for 3D printing and computer-aided design (CAD), extension stl

Object File Format, extension off

OBJ file format developed by Wavefront , extension obj

Virtual Reality Modeling Language file format, extension wrl

Standard Starlink NDF (SUN/33) file format, extension surf

Raster GIS file format developed by Esri, extension grid

3D Manufacturing Format , extension 3mf

Parameters:

mesh – Instance of imfusion.Mesh.
file_path – Path to output file. The path extension is used to determine the file format.

Raises:

RuntimeError if file_path extension is not supported. Currently supported extensions are ['ply', 'stl', 'off', 'obj', 'wrl', 'surf', 'grid', '3mf']. –

Example

>>> mesh = imfusion.Mesh.create(imfusion.Mesh.Primitive.SPHERE)
>>> imfusion.io.save(mesh, tmp_path / 'mesh.imf')

imfusion.io.save(point_cloud: PointCloud, file_path: str | PathLike) → None

Save a imfusion.PointCloud to the specified file path. The path extension is used to determine which file format to save to. Currently supported file formats are:

ImFusion File, extension imf

Point Cloud Data used inside Point Cloud Library (PCL), extension pcd

OBJ file format developed by Wavefront , extension obj

Polygon File Format or the Stanford Triangle Format, extension ply

For .pcd and .imf files, colors are stored as integers in the range [0, 255], even if the PointCloud has colors in the floating-point range [0.0, 1.0]. When saving to these formats, all color values must be in the range [0.0, 1.0], otherwise a ValueError will be raised.

Parameters:

point_cloud – Instance of imfusion.PointCloud.
file_path – Path to output file. The path extension is used to determine the file format.

Raises:

RuntimeError – If file_path extension is not supported. Supported extensions are imf, pcd, obj, ply, txt, xyz.
ValueError – If saving to .pcd or .imf format and any color value is outside the range 0.0 to 1.0.

Example

>>> pc = imfusion.PointCloud([(0,0,0), (1,1,1), (-1,-1,-1)])
>>> imfusion.io.save(pc, tmp_path / 'point_cloud.pcd')

imfusion.io.save(data: Data, file_path: str | PathLike) → None

Save a Data instance to the specified file path as an ImFusion file.

Parameters:

data – Any instance of class deriving from Data can be saved with this method; examples are SharedImageSet, Mesh, and PointCloud.
file_path – Path to ImFusion file. The data is saved in a single file. File path must end with .imf.

Note

Raises a RuntimeError on failure or if file_path doesn’t end with .imf extension.

Example

>>> mesh = imfusion.Mesh.create(imfusion.Mesh.Primitive.SPHERE)
>>> imfusion.io.save(mesh, tmp_path / 'mesh.imf')

imfusion.io.save(data_list: list[Data], file_path: str | PathLike) → None

Save a list of data to the specified file path as an ImFusion file.

Parameters:

data_list – List of Data. Any class deriving from Data can be saved with this method. Examples of Data are SharedImageSet, Mesh, PointCloud, etc.
file_path – Path to ImFusion file. The entire list of Data is saved in a single file. File path must end with .imf.

Note

Raises a RuntimeError on failure or if file_path doesn’t end with .imf extension.

Example

>>> image_set = imfusion.SharedImageSet(np.ones((1,8,8,1)))
>>> mesh = imfusion.Mesh.create(imfusion.Mesh.Primitive.SPHERE)
>>> point_cloud = imfusion.PointCloud([(0,0,0), (1,1,1), (-1,-1,-1)])
>>> another_image_set = imfusion.SharedImageSet(np.ones((1,8,8,1)))
>>> imfusion.io.save([image_set, mesh, point_cloud, another_image_set], tmp_path / 'file.imf')

imfusion.typing

Typing module for the imfusion base module.

Most parts of the ImFusion Python SDK provide PEP 484-style type annotations. This module adds extra types and protocols for type hints and improved type safety.

class imfusion.typing.Spacing(x: float, y: float, z: float)

Physical extent of each voxel.

Parameters:

x (float) – Physical extent in x-direction (in [mm] unless is_metric=false).
y (float) – Physical extent in y-direction (in [mm] unless is_metric=false).
z (float) – Physical extent in z-direction (in [mm] unless is_metric=false).

Create new instance of Spacing(x, y, z)

x: float: Alias for field number 0

y: float: Alias for field number 1

z: float: Alias for field number 2

imfusion.algorithm

imfusion.algorithm submodule.

Provides functionalities to register Python classes as algorithms so that they can be executed within the ImFusionSuite.

exception imfusion.algorithm.AlgorithmExecutionError: Bases: RuntimeError

class imfusion.algorithm.Algorithm

Bases: Configurable

Algorithm base type returned by imfusion.algorithm.create. Use imfusion.algorithm.register to define Python algorithms.

class Action

Bases: pybind11_object

property id

property is_hidden

property name

__call__(self: Algorithm) → list: Delegates to: compute()

compute(self: Algorithm) → list

output(self: Algorithm) → None

output_annotations(self: Algorithm) → list[Annotation]

run_action(self: Algorithm, id: str) → Status

Run one of the registered actions.

Parameters:: id (str) – Identifier of the action to run.

property actions: List of registered actions.

property id

property input

property name

property status

class imfusion.algorithm.Input(self: Input, expected_type: type[TDataBound], *, validator: Callable[[TDataBound], bool] | None = None, is_optional: bool = False)

Bases: typing.Generic[typing.TDataBound]

Data descriptor to define Input data for customized algorithms that are registered in the ImFusionSuite.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     imageset = imfusion.algorithm.Input(imfusion.SharedImageSet,
...                                         validator = lambda sis: sis.descriptor().dimension == 3)
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         imagset: imfusion.SharedImageSet = self.imageset

check_value(self: Input, value: TDataBound) → None

property is_optional

class imfusion.algorithm.ParamBool(self: ParamBool, name: str, *, default: bool)

Bases: pybind11_object

Data descriptor ParamBool for customizing registered algorithms.

This parameter appears as a checkbox in the ImFusion Suite user interface.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     my_param_bool = imfusion.algorithm.ParamBool("My Param", default=False)
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default boolean value.

class imfusion.algorithm.ParamChoice(self: ParamChoice, name: str, *, default: TEnumBound)

Bases: typing.Generic[typing.TEnumBound]

Data descriptor ParamChoice for customizing registered algorithms.

This parameter appears as a drop-down selection in the ImFusion Suite user interface.

Example:

>>> from enum import Enum, auto
>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     class Choice(Enum):
...         A = auto()
...
...     my_param_choice = imfusion.algorithm.ParamChoice("My Choice", default=Choice.A)
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default enum choice value.

class imfusion.algorithm.ParamColor(self: ParamColor, name: str, *, default: Color, dialog_type: DialogType = DialogType.NORMAL)

Bases: pybind11_object

Data descriptor ParamColor for customizing registered algorithms.

This parameter appears as a color picker dialog in the ImFusion Suite user interface.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     my_param_color = imfusion.algorithm.ParamColor("My Param", default=imfusion.algorithm.ParamColor.Color(255, 0, 0))
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default color value.
dialog_type – Color dialog mode shown in the user interface.

class Color(r: int, g: int, b: int, a: int = 255)

Bases: object

RGBA (red, green, blue, alpha / opacity) color with integer components in [0, 255].

All channels accept integer values only and are validated whenever they are assigned.

Parameters:

r (int) –
g (int) –
b (int) –
a (int) –

classmethod from_float(r: float, g: float, b: float, a: float = 1.0) → Color

Create color from floats in [].

Parameters:

r (float) –
g (float) –
b (float) –
a (float) –

Return type:

Color

classmethod from_hex(hex_color: str) → Color

Create color from hex string (#RRGGBB or #RRGGBBAA).

Parameters:: hex_color (str) –
Return type:: Color

to_float() → tuple[float, float, float, float]

Return RGBA values normalized to [0.0, 1.0].

Return type:: tuple[float, float, float, float]

to_hex(include_alpha: bool = False) → str

Return hex representation.

Parameters:: include_alpha (bool) –
Return type:: str

property a: int: Alpha channel in [0, 255].

property b: int: Blue channel in [0, 255].

property g: int: Green channel in [0, 255].

property r: int: Red channel in [0, 255].

class DialogType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Dialog type

Members:

NORMAL Standard dialog.

REDUCED Reduced dialog layout.

IN_PLACE In-place dialog layout.

IN_PLACE = 'in-place'

NORMAL = 'normal'

REDUCED = 'reduced'

class imfusion.algorithm.ParamDouble(self: ParamDouble, name: str, *, default: float, with_slider: bool = False, min: float | None = None, max: float | None = None, step: float | None = None, decimals: int | None = None, unit: str | None = None)

Bases: pybind11_object

Data descriptor ParamDouble for customizing registered algorithms.

This parameter appears as a floating-point input with optional slider in the ImFusion Suite user interface.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     my_param_double = imfusion.algorithm.ParamDouble("My Param", default=0.0)
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default floating-point value.
with_slider – Whether to show a slider in the user interface.
min – Optional minimum value.
max – Optional maximum value.
step – Optional increment step.
decimals – Optional number of decimals shown in the user interface.
unit – Optional unit text shown next to the value.

class imfusion.algorithm.ParamInt(self: ParamInt, name: str, *, default: int, with_slider: bool = False, min: int | None = None, max: int | None = None, step: int | None = None, unit: str | None = None)

Bases: pybind11_object

Data descriptor ParamInt for customizing registered algorithms.

This parameter appears as an integer input with optional slider in the ImFusion Suite user interface.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     my_param_int = imfusion.algorithm.ParamInt("My Param", default=0)
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default integer value.
with_slider – Whether to show a slider in the user interface.
min – Optional minimum value.
max – Optional maximum value.
step – Optional increment step.
unit – Optional unit text shown next to the value.

class imfusion.algorithm.ParamPath(self: ParamPath, name: str, *, default: str | PathLike, path_type: PathType = PathType.OPEN_FILE, caption: str | None = None, filters: list[FileFilter] = [])

Bases: pybind11_object

Data descriptor ParamPath for customizing registered algorithms.

This parameter appears as a file or directory picker dialog in the ImFusion Suite user interface.

Example:

>>> from pathlib import Path
>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     my_param_path = imfusion.algorithm.ParamPath("My Param", default=Path("/tmp/input.ext"))
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default path value.
path_type – Type of file dialog shown in the user interface.
caption – Optional dialog caption.
filters – Optional list of file filters shown in the dialog.

class FileFilter(name: str, extensions: str | Sequence[str])

Bases: object

File dialog filter specifying a display name (name) and file extension (extenstion)

Parameters:

name (str) –
extensions (str | Sequence[str]) –

property extensions: tuple[str, ...]: Tuple of file extensions (letters only, e.g. (‘txt’,..)).

property name: str: Display name of the filter.

class PathType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Path type

Members:

OPEN_DIRECTORY Select a directory.

OPEN_FILE Open an existing file.

SAVE_FILE Select a file to save.

OPEN_DIRECTORY = 'OpenDirectory'

OPEN_FILE = 'OpenFile'

SAVE_FILE = 'OpenFile'

class imfusion.algorithm.ParamString(self: ParamString, name: str, *, default: str, textBox: bool = False, password_mode: PasswordMode = PasswordMode.DISABLED)

Bases: pybind11_object

Data descriptor ParamString for customizing registered algorithms.

This parameter appears as a text input field in the ImFusion Suite user interface.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
... class MyAlgorithm:
...     my_param_string = imfusion.algorithm.ParamString("My Param", default="My String")
...
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

Parameters:

name – Display name shown in the ImFusion Suite user interface.
default – Default string value.
textBox – Whether to show a multi-line text box in the user interface.
password_mode – Display mode used for password-like input.

class PasswordMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Password mode

Members:

DISABLED Characters are always shown.

HIDDEN Characters are always hidden.

MASKED Characters are masked.

MASKED_IF_NO_EDIT Characters are only shown on edit and masked otherwise.

DISABLED = 'Normal'

HIDDEN = 'NoEcho'

MASKED = 'Password'

MASKED_IF_NO_EDIT = 'PasswordEchoOnEdit'

class imfusion.algorithm.Status(self: Status, value: int)

Bases: pybind11_object

Members:

UNKNOWN

SUCCESS

ERROR

INVALID_INPUT

INCOMPLETE_INPUT

OUT_OF_MEMORY_HOST

OUT_OF_MEMORY_GPU

UNSUPPORTED_GPU

UNKNOWN_ACTION

USER

ERROR = <Status.ERROR: 1>

INCOMPLETE_INPUT = <Status.INCOMPLETE_INPUT: 3>

INVALID_INPUT = <Status.INVALID_INPUT: 2>

OUT_OF_MEMORY_GPU = <Status.OUT_OF_MEMORY_GPU: 5>

OUT_OF_MEMORY_HOST = <Status.OUT_OF_MEMORY_HOST: 4>

SUCCESS = <Status.SUCCESS: 0>

UNKNOWN = <Status.UNKNOWN: -1>

UNKNOWN_ACTION = <Status.UNKNOWN_ACTION: 7>

UNSUPPORTED_GPU = <Status.UNSUPPORTED_GPU: 6>

USER = <Status.USER: 1000>

property name

property value

imfusion.algorithm.action(display_name: str) → Callable[[Callable[[TAlgorithmBound], None]], Callable[[TAlgorithmBound], None]]

Decorator for defining actions of Python algorithms registered in the ImFusionSuite.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
>>> class MyAlgorithm:
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass
...
...     @imfusion.algorithm.action(display_name="My Action")
...     def my_action(self) -> None:
...         pass

imfusion.algorithm.create(id: str, data: list = [], properties: Properties = None) → object

Create the algorithm with the given id and but without executing it.

The algorithm will only be created if it is compatible with the given data. The optional Properties object will be used to configure the algorithm.

Parameters:

id – String identifier of the Algorithm to create.
data – List of input data that the Algorithm expects.
properties – Configuration for the Algorithm in the form of a Properties instance.

Example

>>> imfusion.algorithm.create("AlgorithmID", [])  
... <imfusion.BaseAlgorithm object at ...>

imfusion.algorithm.execute(id: str, data: list = [], properties: Properties = None) → list

Execute the algorithm with the given id and returns its output.

The algorithm will only be executed if it is compatible with the given data. The optional Properties object will be used to configure the algorithm before executing it.

imfusion.algorithm.get_properties(id: str, data: list) → Properties: Returns the default properties of the given algorithm. This is useful to figure out what properties are supported by an algorithm.

imfusion.algorithm.list_available(sub_string: str = '', case_sensitive: bool = False) → list[str]

Return a list of all available algorithm ids.

Optionally, a substring can be given to filter the list (case-insensitive by default).

imfusion.algorithm.register(*, display_name: str) → Callable[[type[TAlgorithmBound]], type[TAlgorithmBound]]

Decorator for registering Python algorithms in the ImFusion Suite.

Example:

>>> @imfusion.algorithm.register(display_name="My Algorithm")
>>> class MyAlgorithm:
...     def __call__(self) -> list[imfusion.Data] | tuple[imfusion.Data] | imfusion.Data | None:
...         pass

imfusion.algorithm.register_deprecated_id(deprecated_id: str, canonical_id: str) → None

Register a legacy algorithm ID that redirects to a current one with a deprecation warning.

Both IDs must be fully qualified, e.g. "PYTHON.OldAlgorithm" → "PYTHON.NewAlgorithm". A deprecation warning is emitted in the log whenever the legacy ID is used to look up or instantiate an algorithm.

imfusion.algorithm.typing

Typing module for the imfusion.algorithm module.

Most parts of the ImFusion Python SDK provide PEP 484-style type annotations. This module adds extra types and protocols for type hints and improved type safety.

class imfusion.algorithm.typing.Algorithm

Bases: Protocol

Runtime-checkable, generic protocol that defines the requirements for a user-defined algorithm that can be registered in the ImFusionSuite.

__call__() → list[Data] | tuple[Data] | Data | None

Call self as a function.

Return type:: list[Data] | tuple[Data] | Data | None

imfusion.algorithm.typing.TAlgorithmBound = ~TAlgorithmBound: typing.TypeVar[TAlgorithmBound, bound = Algorithm]

imfusion.algorithm.typing.TDataBound = ~TDataBound: typing.TypeVar[TDataBound, bound = Data]

imfusion.algorithm.typing.TEnumBound = ~TEnumBound: typing.TypeVar[TEnumBound, bound = Enum]

imfusion.anatomy

ImFusion Anatomy Plugin Python Bindings

Core Functionality Areas

Anatomical Data Structures:

AnatomicalStructure: Individual anatomical structure with keypoints, planes, meshes, and images
AnatomicalStructureCollection: Container for multiple anatomical structures
GenericASC: Generic anatomical structure collection implementation

Registration and Processing:

ASCRegistration: Registration between anatomical structure collections
GenerateLinearShapeModel: Generate linear shape models from anatomical structure collections

Example Usage

Basic anatomical structure access:

>>> import imfusion.anatomy as anatomy
>>> import imfusion

>>> # Load anatomical structure collection
>>> asc = imfusion.open("anatomical_structures.imf")

>>> # Access individual anatomical structures
>>> num_structures = asc.num_anatomical_structures()
>>> print(f"Found {num_structures} anatomical structures")

>>> # Get structure by identifier
>>> liver = asc.anatomical_structure("liver")
>>> print(f"Liver identifier: {liver.identifier}")

>>> # Access keypoints using new interface
>>> keypoints = liver.keypoints2
>>> print(f"Available keypoints: {keypoints.keys()}")
>>> tip_point = keypoints["tip"]

>>> # Access meshes
>>> meshes = liver.meshes
>>> if "surface" in meshes:
...     surface_mesh = meshes["surface"]

Working with transformations:

>>> # Get transformation matrices
>>> world_to_local = liver.matrix_from_world
>>> local_to_world = liver.matrix_to_world

>>> # Transform keypoints to world coordinates
>>> world_tip = local_to_world @ tip_point

Registration example:

>>> # Load two anatomical structure collections
>>> fixed_asc = imfusion.open("template.imf")
>>> moving_asc = imfusion.open("patient.imf")

>>> # Create registration algorithm
>>> registration = anatomy.ASCRegistration(fixed_asc, moving_asc)
>>> registration.registration_method = anatomy.ASCRegistration.RegistrationMethod.PointsAndPlanes

>>> # Compute registration
>>> registration.compute()

Creating anatomical structures from label maps:

>>> # Load label image
>>> label_image = imfusion.open("segmentation.nii")

>>> # Define label mappings
>>> label_mapping = {1: "liver", 2: "kidney", 3: "spleen"}

>>> # Create generic ASC from label map
>>> asc = anatomy.generic_asc_from_label_map(label_image, label_mapping)

>>> # Access created structures
>>> liver = asc.anatomical_structure("liver")

Shape model generation:

>>> # Load mean shape template
>>> mean_shape = imfusion.open("mean_template.imf")

>>> # Create shape model generator
>>> shape_model_gen = anatomy.GenerateLinearShapeModel(mean_shape)

>>> # Configure input directory with training data
>>> shape_model_gen.p_inputDirectory = "/path/to/training/data"

>>> # Generate shape model
>>> results = shape_model_gen()
>>> shape_model = results["shape_model"]
>>> updated_mean = results.get("mean")

For detailed documentation of specific classes and functions, use Python’s built-in help() function or access the docstrings directly.

Note: This module requires the ImFusion Anatomy plugin to be properly installed.

exception imfusion.anatomy.AnatomicalStructureInvalidException: Bases: Exception

class imfusion.anatomy.ASCDisplayOptions(self: ASCDisplayOptions)

Bases: DataComponentBase

DataComponent to store AnatomicalStructureCollection-specific rendering options.

add_style_sheet(self: ASCDisplayOptions, arg0: StyleSheet, arg1: str | None) → None

get_or_append_style_sheet(self: ASCDisplayOptions, arg0: str, arg1: str | None) → StyleSheet

remove_style_sheets_by_name(self: ASCDisplayOptions, arg0: str) → None

class imfusion.anatomy.ASCRegistration(self: ASCRegistration, fixed: AnatomicalStructureCollection, moving: AnatomicalStructureCollection)

Bases: Algorithm

Registration between AnatomicalStructureCollectionObjects

class RegistrationMethod(self: RegistrationMethod, value: int)

Bases: pybind11_object

Members:

DeformableMeshRegistration

RigidImages

PointsAndPlanes

PointsRigidScaling

DeformableMeshRegistration = <RegistrationMethod.DeformableMeshRegistration: 2>

PointsAndPlanes = <RegistrationMethod.PointsAndPlanes: 1>

PointsRigidScaling = <RegistrationMethod.PointsRigidScaling: 4>

RigidImages = <RegistrationMethod.RigidImages: 3>

property name

property value

property registration_method: Registration method

class imfusion.anatomy.AnatomicalStructure

Bases: pybind11_object

get_keypoint(self: AnatomicalStructure, arg0: str) → ndarray[numpy.float64[3, 1]]

remove_keypoint(self: AnatomicalStructure, arg0: str) → None: Remove a keypoint, raises KeyError if it does not exist

set_keypoint(self: AnatomicalStructure, arg0: str, arg1: ndarray[numpy.float64[3, 1]]) → None: Set or overwrite an existing keypoint

property graphs: Key value access to graphs. Assignable from dict.

property identifier: Returns the identifier of the anatomical structure.

property images: Key value access to images. Assignable from dict.

property is_2d: Returns true if the anatomical structure is 2D, false if it is 3D.

property keypoints: Dictionary getter (of a copy of) and setter access for all keypoints. Use get_keypoint and set_keypoint for access to individual keypoints.

property keypoints2: Key value access to keypoints. Assignable from dict.

property matrix_from_world: Access to 4x4 matrix representing transformation from world coordinate space to the local coordinate space of this structure.

property matrix_to_world: Access to 4x4 matrix representing transformation from local coordinate space of this structure to the world coordinate space.

property meshes: Key value access to meshes. Assignable from dict.

property planes: Key value access to planes. Assignable from dict.

property pointclouds: Key value access to pointclouds. Assignable from dict.

property valid: Indicate whether the object is still valid, if invalid, member access raises an AnatomicalStructureInvalidException

class imfusion.anatomy.AnatomicalStructureCollection

Bases: Data

AnatomicalStructureCollection provides an interface for managing collections of AnatomicalStructure objects.

add(self: AnatomicalStructureCollection, structure: AnatomicalStructure) → None: Add a clone of the structure to the collection. Raises ValueError if the collection does not accept this structure type.

anatomical_structure(self: AnatomicalStructureCollection, index: int) → AnatomicalStructure

anatomical_structure(self: AnatomicalStructureCollection, identifier: str) → AnatomicalStructure

Function overload documentation:

anatomical_structure(self: AnatomicalStructureCollection, index: int) → AnatomicalStructure: Returns the anatomical structure at the given index

anatomical_structure(self: AnatomicalStructureCollection, identifier: str) → AnatomicalStructure: Returns the anatomical structure with the given identifier

anatomical_structure_identifiers(self: AnatomicalStructureCollection) → list[str]: Returns a list of the names of all anatomical structures in the collection

clone(self: AnatomicalStructureCollection) → AnatomicalStructureCollection

num_anatomical_structures(self: AnatomicalStructureCollection) → int: Returns the number of anatomical structures in the collection

pop(self: AnatomicalStructureCollection, index_or_identifier: int | str) → AnatomicalStructure: Remove and return a structure from an ASC. You can pass an index or a string identifier.

class imfusion.anatomy.GenerateLinearShapeModel(self: GenerateLinearShapeModel, mean_shape: AnatomicalStructureCollection)

Bases: Algorithm

Generate a linear shape model from a set of AnatomicalStructureCollections. Input data are the mean shape and a set of .imf files with AnatomicalStructureCollections located in the input directory. The mean shape defines the anatomical structures of interest and can optionally be updated iteratively in batches before the linear shape model is computed.

Parameters:: mean_shape – AnatomicalStructureCollection that defines the registration target and structures of interest.

class imfusion.anatomy.GenericASC(self: GenericASC)

Bases: AnatomicalStructureCollection, Data

GenericASC holds the data associated with a generic anatomical structure collection.

clone(self: GenericASC) → GenericASC

class imfusion.anatomy.GenericAnatomicalStructure(*args, **kwargs)

Bases: AnatomicalStructure

Generic anatomical structure implementation.

Function overload documentation:

__init__(self: GenericAnatomicalStructure) → None

__init__(self: GenericAnatomicalStructure, arg0: str) → None

property identifier

class imfusion.anatomy.KeyValueDataWrapperGraph

Bases: pybind11_object

KeyValueDataWrapper encapsulates a key-value store KeyValueStore holding data of type T with specific type handling. It provides a Python-friendly interface to access and manipulate data stored in a KeyValueStore using string-based keys. The KeyValueDataWrapper ensures that the data is still valid when accessed and raises an AnatomicalStructureInvalidException if the data is no longer valid. Data are copied or cloned to ensure that the data is still valid when the python object is used, except for shared_ptr value types indicated by the mutable_return_values attribute.

Parameters:

data_store (KeyValueStore) – A reference to the KeyValueStore that holds the actual data.
anatomical_structure (AnatomicalStructureWrapper) – A reference to an anatomical structure, providing context.
identifier (str) – A unique identifier for this data wrapper instance, used for logging or tracking.

__getitem__(self: KeyValueDataWrapperGraph, arg0: str) → Graph

__iter__(self: KeyValueDataWrapperGraph) → Iterator

__setitem__(self: KeyValueDataWrapperGraph, arg0: str, arg1: Graph) → None

asdict(self: KeyValueDataWrapperGraph) → dict[str, Graph]: Convert the key-value store into a dictionary.

from_dict(self: KeyValueDataWrapperGraph, dict_in: dict, clear: bool = True) → None: Set the key-value store from a dictionary.

keys(self: KeyValueDataWrapperGraph) → list[str]: Get a list of all keys.

update(self: KeyValueDataWrapperGraph, dict_in: dict) → None: Update the key-value store from a dictionary.

values(self: KeyValueDataWrapperGraph) → list[Graph]: Get a list of all values.

property attributes: Attributes of KeyValueDataWrapper’s elements.

property mutable_return_values: Indicate whether the KeyValueDataWrapper returns mutable values.

property valid: Indicate whether the anatomical structure object is still valid.

class imfusion.anatomy.KeyValueDataWrapperMesh

Bases: pybind11_object

KeyValueDataWrapper encapsulates a key-value store KeyValueStore holding data of type T with specific type handling. It provides a Python-friendly interface to access and manipulate data stored in a KeyValueStore using string-based keys. The KeyValueDataWrapper ensures that the data is still valid when accessed and raises an AnatomicalStructureInvalidException if the data is no longer valid. Data are copied or cloned to ensure that the data is still valid when the python object is used, except for shared_ptr value types indicated by the mutable_return_values attribute.

Parameters:

data_store (KeyValueStore) – A reference to the KeyValueStore that holds the actual data.
anatomical_structure (AnatomicalStructureWrapper) – A reference to an anatomical structure, providing context.
identifier (str) – A unique identifier for this data wrapper instance, used for logging or tracking.

__getitem__(self: KeyValueDataWrapperMesh, arg0: str) → Mesh

__iter__(self: KeyValueDataWrapperMesh) → Iterator

__setitem__(self: KeyValueDataWrapperMesh, arg0: str, arg1: Mesh) → None

asdict(self: KeyValueDataWrapperMesh) → dict[str, Mesh]: Convert the key-value store into a dictionary.

from_dict(self: KeyValueDataWrapperMesh, dict_in: dict, clear: bool = True) → None: Set the key-value store from a dictionary.

keys(self: KeyValueDataWrapperMesh) → list[str]: Get a list of all keys.

update(self: KeyValueDataWrapperMesh, dict_in: dict) → None: Update the key-value store from a dictionary.

values(self: KeyValueDataWrapperMesh) → list[Mesh]: Get a list of all values.

property attributes: Attributes of KeyValueDataWrapper’s elements.

property mutable_return_values: Indicate whether the KeyValueDataWrapper returns mutable values.

property valid: Indicate whether the anatomical structure object is still valid.

class imfusion.anatomy.KeyValueDataWrapperPointCloud

Bases: pybind11_object

KeyValueDataWrapper encapsulates a key-value store KeyValueStore holding data of type T with specific type handling. It provides a Python-friendly interface to access and manipulate data stored in a KeyValueStore using string-based keys. The KeyValueDataWrapper ensures that the data is still valid when accessed and raises an AnatomicalStructureInvalidException if the data is no longer valid. Data are copied or cloned to ensure that the data is still valid when the python object is used, except for shared_ptr value types indicated by the mutable_return_values attribute.

Parameters:

data_store (KeyValueStore) – A reference to the KeyValueStore that holds the actual data.
anatomical_structure (AnatomicalStructureWrapper) – A reference to an anatomical structure, providing context.
identifier (str) – A unique identifier for this data wrapper instance, used for logging or tracking.

__getitem__(self: KeyValueDataWrapperPointCloud, arg0: str) → PointCloud

__iter__(self: KeyValueDataWrapperPointCloud) → Iterator

__setitem__(self: KeyValueDataWrapperPointCloud, arg0: str, arg1: PointCloud) → None

asdict(self: KeyValueDataWrapperPointCloud) → dict[str, PointCloud]: Convert the key-value store into a dictionary.

from_dict(self: KeyValueDataWrapperPointCloud, dict_in: dict, clear: bool = True) → None: Set the key-value store from a dictionary.

keys(self: KeyValueDataWrapperPointCloud) → list[str]: Get a list of all keys.

update(self: KeyValueDataWrapperPointCloud, dict_in: dict) → None: Update the key-value store from a dictionary.

values(self: KeyValueDataWrapperPointCloud) → list[PointCloud]: Get a list of all values.

property attributes: Attributes of KeyValueDataWrapper’s elements.

property mutable_return_values: Indicate whether the KeyValueDataWrapper returns mutable values.

property valid: Indicate whether the anatomical structure object is still valid.

class imfusion.anatomy.KeyValueDataWrapperSharedImageSet

Bases: pybind11_object

KeyValueDataWrapper encapsulates a key-value store KeyValueStore holding data of type T with specific type handling. It provides a Python-friendly interface to access and manipulate data stored in a KeyValueStore using string-based keys. The KeyValueDataWrapper ensures that the data is still valid when accessed and raises an AnatomicalStructureInvalidException if the data is no longer valid. Data are copied or cloned to ensure that the data is still valid when the python object is used, except for shared_ptr value types indicated by the mutable_return_values attribute.

Parameters:

data_store (KeyValueStore) – A reference to the KeyValueStore that holds the actual data.
anatomical_structure (AnatomicalStructureWrapper) – A reference to an anatomical structure, providing context.
identifier (str) – A unique identifier for this data wrapper instance, used for logging or tracking.

__getitem__(self: KeyValueDataWrapperSharedImageSet, arg0: str) → SharedImageSet

__iter__(self: KeyValueDataWrapperSharedImageSet) → Iterator

__setitem__(self: KeyValueDataWrapperSharedImageSet, arg0: str, arg1: SharedImageSet) → None

asdict(self: KeyValueDataWrapperSharedImageSet) → dict[str, SharedImageSet]: Convert the key-value store into a dictionary.

from_dict(self: KeyValueDataWrapperSharedImageSet, dict_in: dict, clear: bool = True) → None: Set the key-value store from a dictionary.

keys(self: KeyValueDataWrapperSharedImageSet) → list[str]: Get a list of all keys.

update(self: KeyValueDataWrapperSharedImageSet, dict_in: dict) → None: Update the key-value store from a dictionary.

values(self: KeyValueDataWrapperSharedImageSet) → list[SharedImageSet]: Get a list of all values.

property attributes: Attributes of KeyValueDataWrapper’s elements.

property mutable_return_values: Indicate whether the KeyValueDataWrapper returns mutable values.

property valid: Indicate whether the anatomical structure object is still valid.

class imfusion.anatomy.KeyValueDataWrapperVec3

Bases: pybind11_object

KeyValueDataWrapper encapsulates a key-value store KeyValueStore holding data of type T with specific type handling. It provides a Python-friendly interface to access and manipulate data stored in a KeyValueStore using string-based keys. The KeyValueDataWrapper ensures that the data is still valid when accessed and raises an AnatomicalStructureInvalidException if the data is no longer valid. Data are copied or cloned to ensure that the data is still valid when the python object is used, except for shared_ptr value types indicated by the mutable_return_values attribute.

Parameters:

data_store (KeyValueStore) – A reference to the KeyValueStore that holds the actual data.
anatomical_structure (AnatomicalStructureWrapper) – A reference to an anatomical structure, providing context.
identifier (str) – A unique identifier for this data wrapper instance, used for logging or tracking.

__getitem__(self: KeyValueDataWrapperVec3, arg0: str) → ndarray[numpy.float64[3, 1]]

__iter__(self: KeyValueDataWrapperVec3) → Iterator

__setitem__(self: KeyValueDataWrapperVec3, arg0: str, arg1: ndarray[numpy.float64[3, 1]]) → None

asdict(self: KeyValueDataWrapperVec3) → dict[str, ndarray[numpy.float64[3, 1]]]: Convert the key-value store into a dictionary.

from_dict(self: KeyValueDataWrapperVec3, dict_in: dict, clear: bool = True) → None: Set the key-value store from a dictionary.

keys(self: KeyValueDataWrapperVec3) → list[str]: Get a list of all keys.

update(self: KeyValueDataWrapperVec3, dict_in: dict) → None: Update the key-value store from a dictionary.

values(self: KeyValueDataWrapperVec3) → list[ndarray[numpy.float64[3, 1]]]: Get a list of all values.

property attributes: Attributes of KeyValueDataWrapper’s elements.

property mutable_return_values: Indicate whether the KeyValueDataWrapper returns mutable values.

property valid: Indicate whether the anatomical structure object is still valid.

class imfusion.anatomy.KeyValueDataWrapperVec4

Bases: pybind11_object

KeyValueDataWrapper encapsulates a key-value store KeyValueStore holding data of type T with specific type handling. It provides a Python-friendly interface to access and manipulate data stored in a KeyValueStore using string-based keys. The KeyValueDataWrapper ensures that the data is still valid when accessed and raises an AnatomicalStructureInvalidException if the data is no longer valid. Data are copied or cloned to ensure that the data is still valid when the python object is used, except for shared_ptr value types indicated by the mutable_return_values attribute.

Parameters:

data_store (KeyValueStore) – A reference to the KeyValueStore that holds the actual data.
anatomical_structure (AnatomicalStructureWrapper) – A reference to an anatomical structure, providing context.
identifier (str) – A unique identifier for this data wrapper instance, used for logging or tracking.

__getitem__(self: KeyValueDataWrapperVec4, arg0: str) → ndarray[numpy.float64[4, 1]]

__iter__(self: KeyValueDataWrapperVec4) → Iterator

__setitem__(self: KeyValueDataWrapperVec4, arg0: str, arg1: ndarray[numpy.float64[4, 1]]) → None

asdict(self: KeyValueDataWrapperVec4) → dict[str, ndarray[numpy.float64[4, 1]]]: Convert the key-value store into a dictionary.

from_dict(self: KeyValueDataWrapperVec4, dict_in: dict, clear: bool = True) → None: Set the key-value store from a dictionary.

keys(self: KeyValueDataWrapperVec4) → list[str]: Get a list of all keys.

update(self: KeyValueDataWrapperVec4, dict_in: dict) → None: Update the key-value store from a dictionary.

values(self: KeyValueDataWrapperVec4) → list[ndarray[numpy.float64[4, 1]]]: Get a list of all values.

property attributes: Attributes of KeyValueDataWrapper’s elements.

property mutable_return_values: Indicate whether the KeyValueDataWrapper returns mutable values.

property valid: Indicate whether the anatomical structure object is still valid.

class imfusion.anatomy.Selector(self: Selector, arg0: SelectorElem | list[SelectorElem])

Bases: pybind11_object

Selector is a class combining with logical OR multiple SelectorElem objects.

static parse(arg0: str) → Selector | None

class imfusion.anatomy.SelectorElem

Bases: pybind11_object

SelectorElem is a class for querying objects.

static parse(arg0: str) → SelectorElem | None

class imfusion.anatomy.StyleProperty(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Known style “property-names”

ALLOW_OBJECT_ATTRIBUTES_OVERRIDE = 'allow_object_attributes_override'

ALPHA = 'alpha'

ALPHA_CIRCLE_VISUALIZATION = 'alpha_circle_visualization'

ALPHA_CROSS_SECTION = 'alpha_cross_section'

ALPHA_LINE = 'alpha_line'

ALPHA_OUTLINE = 'alpha_outline'

ALPHA_POINT = 'alpha_point'

ALPHA_SURFACE = 'alpha_surface'

ALPHA_WIREFRAME = 'alpha_wireframe'

AMBIENT_SURFACE = 'ambient_surface'

AS_CROSSHAIR = 'as_crosshair'

CIRCLE_VISUALIZATION_FEATURE_NAME = 'circle_visualization_feature_name'

COLOR = 'color'

COLORMAP = 'colormap'

COLOR_CIRCLE_VISUALIZATION = 'color_circle_visualization'

COLOR_CROSS_SECTION = 'color_cross_section'

COLOR_LINE = 'color_line'

COLOR_OUTLINE = 'color_outline'

COLOR_POINT = 'color_point'

COLOR_SURFACE = 'color_surface'

COLOR_WIREFRAME = 'color_wireframe'

DIFFUSE_SURFACE = 'diffuse_surface'

DRAW_DIRECTION_ON_LINES = 'draw_direction_on_lines'

LABEL_PIXEL_OFFSET = 'label_pixel_offset'

LINE_BLENDING_EDGE_FEATURE_NAME = 'line_blending_edge_feature_name'

LINE_BLENDING_NODE_FEATURE_NAME = 'line_blending_node_feature_name'

LINE_WIDTH = 'line_width'

MATERIAL_MODE = 'material_mode'

ONLY_DRAW_NONTRIVIAL_NODES = 'only_draw_nontrivial_nodes'

OUTLINE_WIDTH = 'outline_width'

PLANE_NORMAL_LENGTH = 'plane_normal_length'

POINT_SIZE = 'point_size'

SHININESS_SURFACE = 'shininess_surface'

SHOW_LABEL_TEXT = 'show_label_text'

SHOW_LABEL_TEXT_DEBUG = 'show_label_text_debug'

SHOW_NODE_LABELS = 'show_node_labels'

SHOW_ONLY_PLANE_NORMALS = 'show_only_plane_normals'

SMOOTH_SPLINE = 'smooth_spline'

SPECULAR_SURFACE = 'specular_surface'

TUBE_END_T = 'tube_end_t'

TUBE_THICKNESS = 'tube_thickness'

VISIBILITY = 'visibility'

VISIBILITY_CIRCLE_VISUALIZATION = 'visibility_circle_visualization'

VISIBILITY_CROSS_SECTION = 'visibility_cross_section'

VISIBILITY_LINE = 'visibility_line'

VISIBILITY_OUTLINE = 'visibility_outline'

VISIBILITY_POINT = 'visibility_point'

VISIBILITY_SURFACE = 'visibility_surface'

VISIBILITY_WIREFRAME = 'visibility_wireframe'

class imfusion.anatomy.StyleSheet(self: StyleSheet, name: str)

Bases: pybind11_object

Class for managing a logically grouped set of style rules.

Constructor that creates a single (empty) Style sheet.

append_or_modify(self: StyleSheet, arg0: Selector | None | str, arg1: Callable) → bool: The declaration of a style rule identified by the selector is appended (if non-existent) or modified using the given callback.

property enabled: True if the style sheet is enabled in the styling cascade.

property name: The name identifying the style sheet.

imfusion.anatomy.generic_asc_from_label_map(arg0: SharedImageSet, arg1: dict[int, str]) → GenericASC

imfusion.spine

ImFusion Spine Plugin Python Bindings

Core Functionality Areas

Spine Data Structures:

SpineData: Container for complete spine with multiple vertebrae
OrientedVertebra: Individual vertebra representation with keypoints, planes, and splines

Spine Algorithms:

SpineBaseAlgorithm: Main algorithm for CT spine localization, classification, and segmentation
SpineLocalization2DAlgorithm: 2D X-ray vertebra detection and localization
SpinePolyRigidDeformation: Poly-rigid registration and deformation calculations given an existing SpineData

Example Usage

Basic spine analysis workflow:

>>> import imfusion.spine as spine
>>> import imfusion

>>> # Load CT image
>>> ct_image = imfusion.open("spine_ct.nii")

>>> # Create spine analysis algorithm
>>> alg = spine.SpineBaseAlgorithm(ct_image)

>>> # Set spine bounds automatically
>>> alg.set_bounds()

>>> # Localize and classify vertebrae
>>> status = alg.localize()

>>> # Get spine data with all vertebrae
>>> spine_data = alg.take_spine_data()
>>> print(f"Found {spine_data.num_vertebrae()} vertebrae")

>>> # Access individual vertebrae
>>> l1_vertebra = spine_data.vertebra("L1")
>>> position = l1_vertebra.calculate_position()

>>> # Segment specific vertebra
>>> l1_segmentation = alg.segment("L1")

2D X-ray analysis:

>>> # Load X-ray image
>>> xray = imfusion.open("spine_xray.dcm")

>>> # Create 2D localization algorithm
>>> alg_2d = spine.SpineLocalization2DAlgorithm(xray)

>>> # Run detection
>>> alg_2d.compute()

Poly-rigid deformation example:

>>> # Load CT volume and spine data
>>> ct_volume = imfusion.open("spine_ct.nii")
>>> spine_data = imfusion.open("spine_data.imf")  # :class:`~imfusion.anatomy.AnatomicalStructureCollection`

>>> # Create poly-rigid deformation algorithm
>>> deform_alg = spine.SpinePolyRigidDeformation(ct_volume, spine_data)

>>> # Configure deformation parameters
>>> deform_alg.chamfer_distance = True
>>> deform_alg.mode = spine.PolyRigidDeformationMode.BACKWARD
>>> deform_alg.inversion_steps = 50

>>> # Compute the deformation
>>> deform_alg.compute()

For detailed documentation of specific classes and functions, use Python’s built-in help() function or access the docstrings directly.

Note: This module requires the ImFusion Spine plugin to be properly installed.

class imfusion.spine.OrientedVertebra

Bases: AnatomicalStructure

Individual vertebra with spatial orientation and anatomical features.

Represents a single vertebra in 3D space with complete anatomical information including keypoints, orientation planes, splines, and associated imaging data. Each vertebra has a unique name (e.g., “L1”, “T12”) and can be classified by type (cervical, thoracic, lumbar).

The vertebra maintains keypoints for anatomical landmarks (body center, pedicles, etc.), orientation information derived from these landmarks, and can store associated segmentation masks and other imaging data.

Example

>>> vertebra = spine_data.vertebra("L1")
>>> position = vertebra.calculate_position()
>>> orientation = vertebra.orientation
>>> print(f"L1 at position: {position}")

calculate_position(self: OrientedVertebra) → ndarray[numpy.float64[3, 1]]: Sets and returns the position of the vertebra using the body center and the left and right pedicle centers if available, otherwise set it to the body center or return NaN if none are available.

clone(self: OrientedVertebra) → OrientedVertebra

Create a deep copy of the vertebra.

Returns:: Independent copy of this vertebra with all properties
Return type:: OrientedVertebra

name(self: OrientedVertebra) → str

Get the name of the vertebra.

Returns:: Vertebra name (e.g., “L1”, “T12”, “C7”)
Return type:: str

property orientation: Returns the 3x3 rotation matrix of the orientation of the vertebra using the body center and the left and right pedicle centers if available, otherwise returns an identity transformation.

property pinned_type_id: The pinned type id of the vertebra

property type_id: The type id of the vertebra

property type_probability: The type class probabilities of the vertebra

class imfusion.spine.PolyRigidDeformationMode(self: PolyRigidDeformationMode, value: int)

Bases: pybind11_object

Mode for poly-rigid deformation computation.

Defines how the deformation is computed and applied: - BACKWARD: Compute deformation based on forward model, then invert it - FORWARD: Compute deformation based on backwards model directly - ONLYRIGID: Only deform rigid sections, implicitly masks nonrigid sections

Members:

BACKWARD : Compute forward model then invert (default)

FORWARD : Compute backwards model directly

ONLYRIGID : Only deform rigid sections

BACKWARD = <PolyRigidDeformationMode.BACKWARD: 0>

FORWARD = <PolyRigidDeformationMode.FORWARD: 1>

ONLYRIGID = <PolyRigidDeformationMode.ONLYRIGID: 2>

property name

property value

class imfusion.spine.SpineBaseAlgorithm(self: SpineBaseAlgorithm, source: SharedImageSet, label: SharedImageSet = None)

Bases: Algorithm

Comprehensive spine analysis algorithm for CT images.

Main algorithm for spine localization, classification, and segmentation in CT volumes. Provides a complete pipeline for detecting vertebrae, classifying their types (cervical, thoracic, lumbar), and segmenting individual anatomical structures including vertebrae, sacrum, and ilium.

The algorithm works with calibrated CT images and uses machine learning models for accurate spine analysis. It maintains a collection of detected vertebrae that can be accessed, modified, and segmented individually.

Typical workflow:

Initialize with CT image
Set spine bounds (automatic or manual)
Localize vertebrae
Segment individual structures
Extract spine data for further analysis

Example

>>> ct = imfusion.open("spine_ct.nii")[0]
>>> alg = spine.SpineBaseAlgorithm(ct)
>>> alg.set_bounds()
>>> alg.localize()
>>> l1_seg = alg.segment("L1")
>>> spine_data = alg.take_spine_data()

Initialize the spine analysis algorithm.

Parameters:

source – Input CT image set for spine analysis
label – Optional label image set for guided analysis (default: None)

available_model_names(self: SpineBaseAlgorithm) → list[str]

Get list of all available model names.

Returns:: Names of all registered models
Return type:: List[str]

current_model_name(self: SpineBaseAlgorithm) → str

Get the name of the currently active model.

Returns:: Name of the current model
Return type:: str

localize(self: SpineBaseAlgorithm) → Status

Perform complete vertebra localization and classification.

Clears any existing vertebrae, then localizes all vertebrae in the CT image and classifies them by type (cervical, thoracic, lumbar). This is the main processing method that should be called after setting bounds.

Returns:

Success if localization and classification succeeded,: otherwise an error status indicating what failed

Return type:

Algorithm.Status

Note

Call set_bounds() before this method for best results.

reset(self: SpineBaseAlgorithm, arg0: SharedImageSet, arg1: SharedImageSet, arg2: list[ndarray[numpy.float64[3, 1]]], arg3: list[ndarray[numpy.float64[3, 1]]], arg4: list[ndarray[numpy.float64[3, 1]]], arg5: bool) → None

Reset the algorithm with new data and parameters.

Parameters:

source – New source image set
label – New label image set (can be None)
bounds_min – Minimum bounds for spine region
bounds_max – Maximum bounds for spine region
bounds_center – Center point for spine region
clear_vertebrae – Whether to clear existing vertebrae (default: True)

segment(self: SpineBaseAlgorithm, index: int) → SharedImageSet

segment(self: SpineBaseAlgorithm, name: str) → SharedImageSet

Function overload documentation:

segment(self: SpineBaseAlgorithm, index: int) → SharedImageSet

Segment a specific vertebra by index.

Args:
index: Zero-based index of the vertebra to segment

Returns:
SharedImageSet: Segmentation mask for the specified vertebra

Raises:
IndexError: If index is out of range

segment(self: SpineBaseAlgorithm, name: str) → SharedImageSet

Segment a specific vertebra by name.

Args:
name: Name of the vertebra to segment (e.g., “L1”, “T12”)

Returns:
SharedImageSet: Segmentation mask for the specified vertebra

Raises:
KeyError: If no vertebra with the given name is found

segmentAll(self: object) → object

segmentIlium(self: object) → object

segmentSacrum(self: object) → object

segment_all_vertebrae(self: SpineBaseAlgorithm) → Status

Segment all detected vertebrae.

Returns:: Combined segmentation mask containing all vertebrae
Return type:: SharedImageSet

segment_discs(self: SpineBaseAlgorithm) → Status

Segment intervertebral discs.

Returns:: Segmentation mask for all intervertebral discs
Return type:: SharedImageSet

segment_ilium(self: SpineBaseAlgorithm) → bool

Segment the ilium bones.

Returns:: Segmentation mask for both left and right ilium
Return type:: SharedImageSet

segment_pelvis(self: SpineBaseAlgorithm, join_left_and_right_pelvis: bool = False, should_have_sacrum: bool = True) → bool

Segment the pelvis structures.

Parameters:

join_left_and_right_pelvis – Whether to combine left and right pelvis into single mask (default: False)
should_have_sacrum – Whether to include the sacrum as output of the pelvis model

Returns:

Segmentation mask for pelvis structures

Return type:

SharedImageSet

segment_sacrum(self: SpineBaseAlgorithm) → bool

Segment the sacrum.

Returns:: Segmentation mask for the sacrum
Return type:: SharedImageSet

set_bounds(self: SpineBaseAlgorithm) → None: Predicts and sets vertebra column bounds in the input image.

set_model_by_name(self: SpineBaseAlgorithm, arg0: str) → bool

Set the active model by name.

Parameters:: model_name – Name of the model to use for spine analysis

takeSpineData(self: object) → object

take_spine_data(self: SpineBaseAlgorithm) → SpineData

Extract and take ownership of the spine data.

Transfers the complete spine data structure containing all detected vertebrae and their properties to the caller. After calling this method, the algorithm no longer owns the spine data.

Returns:: Complete spine data structure with all detected vertebrae
Return type:: SpineData

class imfusion.spine.SpineData

Bases: AnatomicalStructureCollection

SpineData holds the data associated with a single spine.

add_vertebra(self: SpineData, oriented_vertebra: OrientedVertebra) → None

Add a copy of a vertebra to the spine.

Parameters:: oriented_vertebra – OrientedVertebra object to add (will be cloned)

Note

A deep copy of the vertebra is added to preserve the original.

clone(self: SpineData) → SpineData

Create a deep copy of the spine data.

Returns:: Independent copy with all vertebrae and properties
Return type:: SpineData

get_keypoint(self: SpineData, arg0: str) → ndarray[numpy.float64[3, 1]]

Get a specific keypoint by name.

Parameters:: key – Name of the keypoint to retrieve
Returns:: 3D coordinates of the keypoint
Return type:: vec3
Raises:: KeyError – If the keypoint does not exist

hasSacrum(self: object) → object

has_ilium(self: SpineData) → bool

Check if ilium data is present.

Returns:: True if ilium structures are detected, False otherwise
Return type:: bool

has_sacrum(self: SpineData) → bool

Check if sacrum data is present.

Returns:: True if sacrum structures are detected, False otherwise
Return type:: bool

numVertebrae(self: object) → object

num_vertebrae(self: SpineData) → int

Get the number of vertebrae in the spine.

Returns:: Total number of detected vertebrae
Return type:: int

removeVertebra(self: object, arg0: str) → object

remove_keypoint(self: SpineData, key: str) → None

Remove a keypoint from the spine data.

Parameters:: key – Name of the keypoint to remove
Raises:: KeyError – If the keypoint does not exist

remove_vertebra(self: SpineData, name: str, check_unique: bool = True) → None

remove_vertebra(self: SpineData, index: int) → None

Function overload documentation:

remove_vertebra(self: SpineData, name: str, check_unique: bool = True) → None

Remove a vertebra by name.

Args:
name: Name of the vertebra to remove (e.g., “L1”) check_unique: Whether to verify the name is unique before removal (default: True)

Raises:
KeyError: If no vertebra with the given name exists KeyError: If check_unique is True and multiple vertebrae have the same name

remove_vertebra(self: SpineData, index: int) → None

Remove a vertebra by index.

Args:
index: Zero-based index of the vertebra to remove

Raises:
IndexError: If the index is out of range

set_keypoint(self: SpineData, key: str, value: ndarray[numpy.float64[3, 1]]) → None

Set or overwrite a keypoint.

Parameters:

key – Name of the keypoint to set
value – 3D coordinates for the keypoint

vertebra(self: SpineData, index: int) → OrientedVertebra

vertebra(self: SpineData, name: str, check_unique: bool = True) → OrientedVertebra

Function overload documentation:

vertebra(self: SpineData, index: int) → OrientedVertebra: Direct read-write access to an OrientedVertebra by name or index. Raises IndexError for out of range indices or KeyError if the name does not exist. If the vertebra object becomes invalid (i.e. removed from the spine), member access to the object raises an expection.

vertebra(self: SpineData, name: str, check_unique: bool = True) → OrientedVertebra

Access a vertebra by name.

Args:
name: Name of the vertebra to access (e.g., “L1”) check_unique: Whether to verify the name is unique (default: True)

Returns:
OrientedVertebra: Reference to the vertebra object

Raises:
KeyError: If no vertebra with the given name exists KeyError: If check_unique is True and multiple vertebrae have the same name

Note:
The returned object becomes invalid if the vertebra is removed from the spine.

property keypoints

Dictionary access to all keypoints in the spine data.

Getter returns a copy of all keypoints as a dictionary mapping keypoint names to their 3D coordinates. Setter allows bulk assignment of keypoints from a dictionary. For individual keypoint access, use get_keypoint() and set_keypoint() methods.

Returns:: Dictionary of keypoint names to 3D coordinates
Return type:: Dict[str, vec3]

property vertebrae_names: Returns a list of vertebra names. The order is the same as the order of the vertebrae in the spine when accessed via index.

class imfusion.spine.SpineLocalization2DAlgorithm(self: SpineLocalization2DAlgorithm, image: SharedImageSet)

Bases: Algorithm

2D spine localization algorithm for X-ray images.

Detects and localizes vertebrae, femurs, and clavicles in 2D X-ray images using machine learning models. The algorithm can work with multiple model sets and provides configurable keypoint sensitivity.

The resulting detections are stored in the algorithm’s output as SpineData objects containing OrientedVertebra structures with detected keypoints and anatomical features.

Example

>>> xray = imfusion.open("spine_xray.dcm")[0]
>>> alg = spine.SpineLocalization2DAlgorithm(xray)
>>> alg.add_model("model_v1", "body.pt", "femur.pt", "clavicle.pt", 0.5)
>>> alg.compute()
>>> results = alg.output()

Initialize the 2D spine localization algorithm.

Parameters:: image – Input X-ray image set for spine localization

add_model(self: SpineLocalization2DAlgorithm, arg0: str, arg1: str, arg2: str, arg3: str, arg4: float) → None

Add a machine learning model for spine structure detection.

Registers a new model set with the algorithm and configures it for use in subsequent compute() calls. The model can detect vertebrae, femurs, and clavicles depending on which model paths are provided.

Parameters:

model_name – Unique identifier for the model set
body_detection_path – Path to PyTorch model file for vertebra detection (can be empty)
femur_detection_path – Path to PyTorch model file for femur detection (can be empty)
clavicle_detection_path – Path to PyTorch model file for clavicle detection (can be empty)
keypoint_sensitivity – Sensitivity threshold for keypoint detection (0.0-1.0)

Note

At least one detection path should be provided. Empty paths will skip detection for that anatomical structure.

class imfusion.spine.SpinePolyRigidDeformation(*args, **kwargs)

Bases: Algorithm

Set up a poly-rigid deformation on a volume and one or two AnatomicalStructureCollection objects.

The distance volumes are computed from the vertebrae stored in the source AnatomicalStructureCollection, which are used to define the rigid regions. This algorithm initializes a PolyRigidDeformation on the input CT volume based on the computed distance volumes with as many control points as the number of vertebrae.

If two AnatomicalStructureCollection objects are provided, the first AnatomicalStructureCollection object is registered to the second AnatomicalStructureCollection object and this is used to set the initial parameters of the poly-rigid deformation.

Function overload documentation:

__init__(self: SpinePolyRigidDeformation, image: SharedImageSet, spine_source: AnatomicalStructureCollection) → None

Constructor with a single volume and AnatomicalStructureCollection.

Args:
image: Input CT volume to set deformation on spine_source: AnatomicalStructureCollection containing vertebrae for rigid regions

__init__(self: SpinePolyRigidDeformation, image: SharedImageSet, spine_source: AnatomicalStructureCollection, spine_destination: AnatomicalStructureCollection) → None

Constructor with volume and source/destination AnatomicalStructureCollections.

Args:
image: Input CT volume to set deformation on spine_source: Source AnatomicalStructureCollection containing vertebrae for rigid regions spine_destination: Optional destination AnatomicalStructureCollection for initial transformations

class imfusion.spine.VertebraType(self: VertebraType, value: int)

Bases: pybind11_object

Enumeration of vertebra types to assign vertebrae to their anatomical region in the spine.

Members:

NONE : No specific vertebra type

CERVICAL : Cervical vertebra (C1-C7)

THORACIC : Thoracic vertebra (T1-T12)

LUMBAR : Lumbar vertebra (L1-L6)

SACRAL : Sacral vertebra (S1-S5)

CERVICAL = <VertebraType.CERVICAL: 1>

LUMBAR = <VertebraType.LUMBAR: 3>

NONE = <VertebraType.NONE: 0>

SACRAL = <VertebraType.SACRAL: 4>

THORACIC = <VertebraType.THORACIC: 2>

property name

property value

imfusion.spine.hasMissingVertebraHeuristic(arg0: object, arg1: SpineData) → object

imfusion.spine.has_missing_vertebra_heuristic(arg0: SpineData) → bool

Heuristic function to detect if vertebrae are missing from a spine.

Parameters:: spine_data – SpineData object to analyze
Returns:: True if missing vertebrae are detected, False otherwise
Return type:: bool

imfusion.spine.vertebra_label_to_string(vertebra_label: int) → str: Converts a vertebra index to a corresponding vertebra ID str. For example 5 is converted to 'C6'.

imfusion.spine.vertebra_string_to_label(vertebra_string: str) → int | None: Converts a vertebra ID str to a corresponding vertebra index. For example 'C6' is converted to 5. When the input argument does not match any vertebra, this function returns None.

imfusion.spine.vertebra_type_offset(vertebra_type: VertebraType) → int: Returns the index offset corresponding to a vertebra type. For example the index offset of THORACIC is 7 because the thoracic vertebrae are listed after the cervical vertebrae.

imfusion.dicom

Submodules containing DICOM related functionalities.

To load a single DICOM file, use imfusion.dicom.load_file() and imfusion.dicom.load_folder() to load all series contained in a folder. Both functions return a list of results. In general, each DICOM series is loaded as one Data. This is not always possible though. For example DICOM slices might not stack up in a way representable by a SharedImageSet.

Besides loading DICOMs from the local filesystem, PACS and DicomWeb are supported as well through the imfusion.dicom.load_url() function.

To load a series from PACS, use an URL with the following format: pacs://<hostname>:<port>/<PACS AE title>?series=<series instance uid>&study=<study instance uid> To receive DICOMs from the PACS, a temporary server will be started on the port defined by imfusion.dicom.set_pacs_client_config().

To load a series from a DicomWeb compatible server, use the DicomWeb endpoint (depends on the server), e.g.: https://<hostname>:<port>/dicom-web/studies/<study instance uid>/series/<series instance uid>. If the server requires authentication, a imfusion.dicom.AuthenticationProvider has to be registered. The authentication scheme depends on the server, but here is an example for HTTP Basic Auth with username and password:

class AuthProvider(imfusion.dicom.AuthorizationProvider):
        def __init__(self):
                imfusion.dicom.AuthorizationProvider.__init__(self)
                self.token = ""

        def authorization(self, url):
                return self.token

        def refresh_authorization(self, url, num_failed_requests):
                if acquire_authorization(url, ""):
                        return True
                else:
                        self.token = ""
                        return False

        def acquire_authorization(self, url, message):
                print("Please provide authorization for accessing", url)
                if (message):
                        print(message)

                try:
                        username = input("Username: ")
                        password = getpass.getpass()
                except KeyboardInterrupt:
                        return False

                self.token = "Basic " + base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("utf=8")
                return True

imfusion.dicom.set_default_authorization_provider(AuthProvider())

imfusion.dicom.load_url("https://example.com/dicom-web/studies/1.2.3.4/series/5.6.7.8")

class imfusion.dicom.AuthorizationProvider(self: AuthorizationProvider)

Bases: pybind11_object

acquire_authorization(self: AuthorizationProvider, url: str, message: str) → bool

Acquire authorization by e.g. asking the user.

This method might get called from another thread. In this case, implementations that require the main thread to show a GUI should just return false. An optional message can be provided (e.g. to display an error from a previous login attempt).

authorization(self: AuthorizationProvider, url: str) → str

Get the Authorization header for the given url.

The url is the complete url for the request that is going to be performed. Implementation should cache the value according to the server URL (see extract_server_url). When an empty string is returned, no Authorization header should be send. This method will be call from multiple threads.

extract_server_url(self: AuthorizationProvider, url: str) → str

Extract the server part of the URL.

E.g. http://example.com:8080/dicomweb/studies becomes http://example.com:8080.

refresh_authorization(self: AuthorizationProvider, url: str, num_failed_requests: int) → bool

Try to refresh the authorization without user interaction.

Implementations should stop retrying after a certain number of failed attemps. This method will be call from multiple threads.

remove_authorization(self: AuthorizationProvider, url: str) → None

Remove any cached authorization for the given server.

This should essentially log out the user and let the user re-authenticate with the next acquireAuthorization call.

class imfusion.dicom.GeneralEquipmentModuleDataComponent(self: GeneralEquipmentModuleDataComponent)

Bases: DataComponentBase

property anatomical_orientation_type

property device_serial_number

property gantry_id

property institution_address

property institution_name

property institutional_departmentname

property manufacturer

property manufacturers_model_name

property software_versions

property spatial_resolution

property station_name

class imfusion.dicom.RTStructureDataComponent(self: RTStructureDataComponent)

Bases: DataComponentBase

DataComponent for PointClouds loaded from a DICOM RTStructureSet.

Provides information about the original structure/grouping of the points. See RTStructureIoAlgorithm for details about how RTStructureSets are loaded.

Warning

Since this component uses fixed indices into the PointCloud’s points structure, it can only be used if the PointCloud remains unchanged!

class Contour

Bases: pybind11_object

Represents a single item in the original ‘Contour Sequence’ (3006,0040).

property length

property start_index

property type

class GeometryType(self: GeometryType, value: int)

Bases: pybind11_object

Defines how the points of a contour should be interpreted.

Members:

POINT

OPEN_PLANAR

CLOSED_PLANAR

OPEN_NONPLANAR

CLOSED_PLANAR = <GeometryType.CLOSED_PLANAR: 2>

OPEN_NONPLANAR = <GeometryType.OPEN_NONPLANAR: 3>

OPEN_PLANAR = <GeometryType.OPEN_PLANAR: 1>

POINT = <GeometryType.POINT: 0>

property name

property value

class ROIGenerationAlgorithm(self: ROIGenerationAlgorithm, value: int)

Bases: pybind11_object

Defines how the RT structure was generated

Members:

UNKNOWN

AUTOMATIC

SEMI_AUTOMATIC

MANUAL

AUTOMATIC = <ROIGenerationAlgorithm.AUTOMATIC: 1>

MANUAL = <ROIGenerationAlgorithm.MANUAL: 3>

SEMI_AUTOMATIC = <ROIGenerationAlgorithm.SEMI_AUTOMATIC: 2>

UNKNOWN = <ROIGenerationAlgorithm.UNKNOWN: 0>

property name

property value

property color

property contours

property generation_algorithm

property referenced_frame_of_reference_UID

class imfusion.dicom.ReferencedInstancesComponent(self: ReferencedInstancesComponent)

Bases: DataComponentBase

DataComponent to store DICOM instances that are referenced by the dataset.

A DICOM dataset can reference a number of other DICOM datasets that are somehow related. The references in this component are determined by the ReferencedSeriesSequence.

is_referencing(self: ReferencedInstancesComponent, arg0: SourceInfoComponent) → bool

is_referencing(self: ReferencedInstancesComponent, arg0: SharedImageSet) → bool

Function overload documentation:

is_referencing(self: ReferencedInstancesComponent, arg0: SourceInfoComponent) → bool: Returns true if the instances of the given SourceInfoComponent are referenced by this component.

The instances and references have to only intersect for this to return true. This way, e.g. a segmentation would be considered referencing a CT if it only overlaps in a view slices.

is_referencing(self: ReferencedInstancesComponent, arg0: SharedImageSet) → bool: Convenient method that calls the above method with SourceInfoComponent of sis.

Only returns true if all elementwise SourceInfoComponents are referenced.

class imfusion.dicom.SourceInfoComponent(self: SourceInfoComponent)

Bases: DataComponentBase

property sop_class_uids

property sop_instance_uids

property source_uris

imfusion.dicom.load_file(file_path: str) → list

Load a single file as DICOM.

Depending on the SOPClassUID of the DICOM file, this can result in:

a 2D or 3D SharedImageSet containing one or multiple frames
a segmentation labelmap (i.e. a 8-bit SharedImageSet with a LabelDataComponent)
a RT Structure Set (i.e. a PointCloud with a RTStructureDataComponent)

For regular images, usually only one result is generated. If not it is usually an indication that the file could not be entirely reconstructed as a volume (e.g. the spacing between slices is not uniform).

For segmentations, multiple labelmaps will be returned if labels overlap (i.e. one pixel has at least 2 labels).

For RT Structure Sets, one PointCloud is returned per structure.

imfusion.dicom.load_folder(folder_path: str, recursive: bool = True, ignore_non_dicom: bool = True) → list

Load all DICOM files from a folder.

Generally this produces one dataset per DICOM series, however, this might not always be the case. Check ImageInfoDataComponent for the actual series UID.

See imfusion.dicom.load_file() for a list of datasets that can be generated.

Parameters:

folder_path (str) – A path to a folder or an URL.
recursive (bool) – Whether subfolders should be scanned recursively for all DICOM files.
ignore_non_dicom (bool) – Whether files without a valid DICOM header should be ignored. This is usually faster and produces less warnings/errors, but technically the DICOM header is optional and might be missing. This is very rare though.

imfusion.dicom.load_url(url: str, recursive: bool = True, ignore_non_dicom: bool = True) → list

Load all DICOM files from a URL.

Generally this produces one dataset per DICOM series, however, this might not always be the case. Check ImageInfoDataComponent for the actual series UID.

The URL support the file://, http(s):// and pacs:// schemes.

To load a series from PACS, use an URL with the following format: pacs://<hostname>:<port>/<PACS AE title>?series=<series instance uid>&study=<study instance uid> To receive DICOMs from the PACS, a temporary server will be started on the port defined by imfusion.dicom.set_pacs_client_config().

Parameters:

url (str) – An URL.
recursive (bool) – Whether subfolders should be scanned recursively for all DICOM files. Only used for file:// URLs.
ignore_non_dicom (bool) – Whether files without a valid DICOM header should be ignored. This is usually faster and produces less warnings/errors, but technically the DICOM header is optional and might be missing. This is very rare though. Only used for file:// URLs.

imfusion.dicom.rtstruct_to_labelmap(rtstruct_set: list[PointCloud], referenced_image: SharedImageSet, combine_label_maps: bool = False) → list[SharedImageSet]

Algorithm to convert a PointCloud with a RTStructureDataComponent datacomponent to a labelmap.

This is currently only supported for CLOSED_PLANAR contours in RTStructureDataComponent. The algorithm requires a reference volume that determines the size of the labelmap. Each contour is expected to be planar on a slice in the reference volume. This algorithm works best when using the volume that is referenced by the original DICOM RTStructureDataSet (see imfusion.RTStructureDataComponent.referenced_frame_of_reference_UID).

Returns one labelmap per input RT Structure.

imfusion.dicom.save_file(image: SharedImageSet, file_path: str, referenced_image: SharedImageSet = None) → None

Save an image as a single DICOM file.

The SOP Class that is used for the export is determined based on the modality of the image. For example, CT images will be exported as ‘Enhanced CT Image Storage’ and LABEL images as ‘Segmentation Storage’.

When exporting volumes, note that older software might not be able to load them. Use imfusion.dicom.save_folder() instead.

Optionally, the generated DICOMs can also reference another DICOM image, which is passed with the referenced_image argument. This referenced_image must have been loaded from DICOM and/or contain a elementwise SourceInfoComponent and a ImageInfoDataComponent contain a valid series instance UID. With such a reference, other software can determine whether different DICOMs are related. This is especially important when exporting segmentations with modality LABEL. The exported segmentations must reference the data that was used to generate the segmentation. If this reference is missing, the exported segmentations cannot be loaded in some software.

When exporting segmentations, only the slices containing non-zero labels will be exported. After re-importing the file, it therefore might have a different number of slices.

For saving RT Structures, see imfusion.dicom.save_rtstruct().

Parameters:

image (SharedImageSet) – The image to export
file_path (str) – File to write the resulting DICOM to. Existing files will be overwritten!
referenced_image (SharedImageSet) – An optional image that the exported image should reference.

Warning

At the moment, only exporting single frame CT and MR volumes is well supported. Since DICOM is an extensive standard, any other kind of image might lead to a non-standard or invalid DICOM.

imfusion.dicom.save_folder(image: SharedImageSet, folder_path: str, referenced_image: SharedImageSet = None) → None

Save an image as a DICOM folder containing potentially multiple files.

The SOP Class that is used for the export is determined based on the modality of the image. For example, CT images will be exported as ‘CT Image Storage’.

Works like imfusion.dicom.save_file() except for using different SOP Class UIDs.

imfusion.dicom.save_rtstruct(labelmap: SharedImageSet, referenced_image: SharedImageSet, file_path: str) → None

imfusion.dicom.save_rtstruct(rtstruct_set: list[PointCloud], referenced_image: SharedImageSet, file_path: str) → None

Function overload documentation:

imfusion.dicom.save_rtstruct(labelmap: SharedImageSet, referenced_image: SharedImageSet, file_path: str) → None: Save a labelmap as a RT Structure Set.

The contours of a label inside the labelmap will be used as a contour in the RT Structure. Each slice of the labelmap generates seperate contours (RT Structure does not support 3D contours).

imfusion.dicom.save_rtstruct(rtstruct_set: list[PointCloud], referenced_image: SharedImageSet, file_path: str) → None: Save a list of PointCloud as a RT Structure Set.

Each PointCloud must provide a RTStructureDataComponent.

imfusion.dicom.set_default_authorization_provider(arg0: AuthorizationProvider) → None

imfusion.dicom.set_pacs_client_config(ae_title: str, port: int) → None

Set the client configuration when connecting to a PACS.

To receive DICOMs from a PACS server, the AE title and port needs to be registered with the PACS as well (vendor specific and not done by this function!).

Warning

The values will be persisted on the system and will be restored when the application is restarted.

imfusion.stream

class imfusion.stream.AlgorithmExecutorStream: Bases: ImageStream

class imfusion.stream.FakeImageStream(*args, **kwargs)

Bases: ImageStream

Synthetic image stream for testing and prototyping.

The stream emits generated 2D/3D images with configurable descriptor, count, spacing, and image representation.

Function overload documentation:

__init__(self: FakeImageStream, width: int = 100, height: int = 100, slices: int = 1, channels: int = 1) → None

Create a fake stream with the given image dimensions.

Parameters:
width: Image width in pixels. height: Image height in pixels. slices: Number of slices (depth). channels: Number of channels.

__init__(self: FakeImageStream, image: MemImage) → None

Create a fake stream initialized from a static memory image.

Parameters:
image: Source image descriptor and data reference.

class EmittedImageRepresentation(self: EmittedImageRepresentation, value: int)

Bases: pybind11_object

Image representations produced by FakeImageStream.

Members:

MEM_IMAGE :
Emit only imfusion.MemImage representation.

GL_IMAGE :
Emit only OpenGL image representation.

MEM_AND_GL_IMAGE :
Emit both imfusion.MemImage and OpenGL image representations.

GL_IMAGE = <EmittedImageRepresentation.GL_IMAGE: 1>

MEM_AND_GL_IMAGE = <EmittedImageRepresentation.MEM_AND_GL_IMAGE: 2>

MEM_IMAGE = <EmittedImageRepresentation.MEM_IMAGE: 0>

property name

property value

GL_IMAGE = <EmittedImageRepresentation.GL_IMAGE: 1>

MEM_AND_GL_IMAGE = <EmittedImageRepresentation.MEM_AND_GL_IMAGE: 2>

MEM_IMAGE = <EmittedImageRepresentation.MEM_IMAGE: 0>

property descriptor: Descriptor used for emitted images.

property emit_vitals_data: Whether synthetic ECG vitals data is emitted.

property emitted_image_representation: Which image representation(s) are emitted.

property fps: Stream frame rate in Hz.

property height: Current image height in pixels.

property num_images: Number of generated images in the internal sequence.

property size: Return stream size.

property spacing: The pixel / voxel spacing for emitted images.

property width: Current image width in pixels.

class imfusion.stream.FakePolyDataStream: Bases: PolyDataStream

class imfusion.stream.FakeTrackingStream: Bases: TrackingStream

class imfusion.stream.ImageOutStream(self: ImageOutStream, output_connection: OutputConnection, name: str): Bases: OutStream

class imfusion.stream.ImageStream

Bases: Stream

property modality

property top_down

class imfusion.stream.OutStream

Bases: Stream

property uuid

class imfusion.stream.OutputConnection

Bases: pybind11_object

close_connection(self: OutputConnection) → None

is_compatible(self: OutputConnection, kind: Kind) → bool

open_connection(self: OutputConnection) → None

send_data(self: OutputConnection, data: Data) → None

property is_connected

class imfusion.stream.PlaybackImageStream: Bases: ImageStream

class imfusion.stream.PlaybackTrackingStream: Bases: TrackingStream

class imfusion.stream.PolyDataOutStream: Bases: OutStream

class imfusion.stream.PolyDataStream: Bases: Stream

class imfusion.stream.SpacingAttachedImageStream: Bases: ImageStream

class imfusion.stream.Stream

Bases: Data

class State(self: State, value: int)

Bases: pybind11_object

Members:

CLOSED

OPENING

OPEN

STARTING

RUNNING

PAUSING

PAUSED

RESUMING

STOPPING

CLOSING

CLOSED = <State.CLOSED: 0>

CLOSING = <State.CLOSING: 9>

OPEN = <State.OPEN: 2>

OPENING = <State.OPENING: 1>

PAUSED = <State.PAUSED: 6>

PAUSING = <State.PAUSING: 5>

RESUMING = <State.RESUMING: 7>

RUNNING = <State.RUNNING: 4>

STARTING = <State.STARTING: 3>

STOPPING = <State.STOPPING: 8>

property name

property value

close(self: Stream) → bool

configuration(self: Stream) → Properties: Returns the configuration of the object.

configure(self: Stream, arg0: Properties) → None: Configures the object.

create_default_stream_controller(self: Stream) → bool

is_state_one_of(self: Stream, states: list[State]) → bool

open(self: Stream) → bool

pause(self: Stream) → bool

reset(self: Stream) → bool

restart(self: Stream) → bool

resume(self: Stream) → bool

start(self: Stream) → bool

stop(self: Stream) → bool

CLOSED = <State.CLOSED: 0>

CLOSING = <State.CLOSING: 9>

OPEN = <State.OPEN: 2>

OPENING = <State.OPENING: 1>

PAUSED = <State.PAUSED: 6>

PAUSING = <State.PAUSING: 5>

RESUMING = <State.RESUMING: 7>

RUNNING = <State.RUNNING: 4>

STARTING = <State.STARTING: 3>

STOPPING = <State.STOPPING: 8>

property current_state

property supports_pausing

property uuid

class imfusion.stream.StreamRecorderAlgorithm(self: StreamRecorderAlgorithm, arg0: list[Stream])

Bases: Algorithm

class CaptureMode(self: CaptureMode, value: int)

Bases: pybind11_object

Members:

CAPTURE_ALL

ON_REQUEST

CAPTURE_ALL = <CaptureMode.CAPTURE_ALL: 0>

ON_REQUEST = <CaptureMode.ON_REQUEST: 1>

property name

property value

class DataCombinationMode(self: DataCombinationMode, value: int)

Bases: pybind11_object

Members:

INDIVIDUAL

ALL

FIRST_TRACKING

ONE_ON_ONE

ALL = <DataCombinationMode.ALL: 1>

FIRST_TRACKING = <DataCombinationMode.FIRST_TRACKING: 2>

INDIVIDUAL = <DataCombinationMode.INDIVIDUAL: 0>

ONE_ON_ONE = <DataCombinationMode.ONE_ON_ONE: 3>

property name

property value

set_capture_next_sample(self: StreamRecorderAlgorithm) → None

start(self: StreamRecorderAlgorithm) → None

stop(self: StreamRecorderAlgorithm) → None

ALL = <DataCombinationMode.ALL: 1>

CAPTURE_ALL = <CaptureMode.CAPTURE_ALL: 0>

FIRST_TRACKING = <DataCombinationMode.FIRST_TRACKING: 2>

INDIVIDUAL = <DataCombinationMode.INDIVIDUAL: 0>

ONE_ON_ONE = <DataCombinationMode.ONE_ON_ONE: 3>

ON_REQUEST = <CaptureMode.ON_REQUEST: 1>

property capture_mode

property compress_save

property data_combination_mode

property image_samples_limit

property image_stream

property is_recording

property limit_reached

property num_recorded_bytes

property num_recorded_frames

property num_recorded_tracking_data

property num_recorders

property number_of_data_to_keep

property number_of_data_to_keep_limit

property passed_time

property patient_name

property record_both_timestamps

property recorded_bytes_limit

property save_as_dicom

property save_path

property save_to_file

property stop_on_image_size_changed

property system_mem_limit

property time_limit

property tracking_quality_threshold

property tracking_samples_limit

property tracking_stream

property use_device_time_for_image_stream

property use_device_time_for_tracking_stream

class imfusion.stream.SynchronousConsumer(self: SynchronousConsumer, stream: Stream)

Bases: pybind11_object

Synchronous consumer for blocking data access to data of a Stream.

Intended to be used as a context manager to automatically connect and disconnect.

Returned values use Data types from the main imfusion package:

Image streams: imfusion.SharedImageSet.
Poly-data streams: (meshes, point_clouds) — two lists of imfusion.Mesh and imfusion.PointCloud.
Tracking streams: List of imfusion.TrackingSequence, one for each tracking instrument. One pose per instrument, in stream order.

Note

This consumer does not guarantee that all samples are received, even when get_next_data is called repeatedly, and it is not targeted for real-time / high-throughput applications.

Parameters:: stream – Stream to subscribe to.

Example

>>> import imfusion
>>> from imfusion import stream
>>> with stream.SynchronousConsumer(image_stream) as cap:
...     while True:
...         try:
...             frame = cap.get_next_data(1) # 1 second timeout
...             if frame is not None:
...                 # frame is e.g. imfusion.SharedImageSet
...                 pass
...         except TimeoutError:
...             continue  # timeout
...         except ValueError:
...             break  # consumer stopped

get_next_data(self: SynchronousConsumer, timeout: float | None = None) → object

Wait for the next stream sample and convert it to SDK data objects.

Parameters:

timeout_seconds – Optional timeout in seconds (fractions of seconds are supported). If omitted, waits indefinitely.

Raises:

TimeoutError – If timeout expires before a sample arrives.
ValueError – If the consumer was stopped (e.g. context exited) or was not connected.
TypeError – If the stream emits a sample type that is not image, tracking, or poly-data.

class imfusion.stream.TrackingOutStream(self: TrackingOutStream, output_connection: OutputConnection, name: str): Bases: OutStream

class imfusion.stream.TrackingStream

Bases: Stream

property main_instrument_index

class imfusion.stream.VideoCameraStream: Bases: ImageStream

imfusion.igtl

class imfusion.igtl.Connection(self: Connection, name: str, hostname: str = 'localhost', port: int = 18944, is_server: bool = True, crc_check: bool = True, reconnect: bool = True)

Bases: Stream, OutputConnection

class ConnectionStatus(self: ConnectionStatus, value: int)

Bases: pybind11_object

Members:

DISCONNECTED

CONNECTED

CONNECTING

WAITING

CONNECTED = <ConnectionStatus.CONNECTED: 1>

CONNECTING = <ConnectionStatus.CONNECTING: 2>

DISCONNECTED = <ConnectionStatus.DISCONNECTED: 0>

WAITING = <ConnectionStatus.WAITING: 3>

property name

property value

add_filter(self: Connection, device_type: str, device_name: str) → None

close_connection(self: Connection) → None

is_compatible(self: Connection, kind: Kind) → bool

open_connection(self: Connection) → None

remove_filter(self: Connection, device_type: str, device_name: str) → None

CONNECTED = <ConnectionStatus.CONNECTED: 1>

CONNECTING = <ConnectionStatus.CONNECTING: 2>

DISCONNECTED = <ConnectionStatus.DISCONNECTED: 0>

WAITING = <ConnectionStatus.WAITING: 3>

property host

property is_connected

property is_server

property port

property status

class imfusion.igtl.Device(self: Device, connection: Connection, name: str, igtl_type: str, compatible_types: list[str] = [])

Bases: pybind11_object

class IoConfiguration(self: IoConfiguration, value: int)

Bases: pybind11_object

Members:

INPUT

OUTPUT

INPUT_OUTPUT

UNKNOWN

INPUT = <IoConfiguration.INPUT: 0>

INPUT_OUTPUT = <IoConfiguration.INPUT_OUTPUT: 2>

OUTPUT = <IoConfiguration.OUTPUT: 1>

UNKNOWN = <IoConfiguration.UNKNOWN: 3>

property name

property value

is_compatible(self: Device, type: str) → bool

reset_connection(self: Device) → None

INPUT = <IoConfiguration.INPUT: 0>

INPUT_OUTPUT = <IoConfiguration.INPUT_OUTPUT: 2>

OUTPUT = <IoConfiguration.OUTPUT: 1>

UNKNOWN = <IoConfiguration.UNKNOWN: 3>

property compatible_types

property device_name

property io_configuration

property is_connected

property type

class imfusion.igtl.IgtlImageOutStream(self: IgtlImageOutStream, output_connection: Connection, name: str): Bases: ImageOutStream, Device

class imfusion.igtl.IgtlImageStream(self: IgtlImageStream, connection: Connection, name: str): Bases: ImageStream, Device

class imfusion.igtl.IgtlPolyDataOutStream: Bases: PolyDataOutStream, Device

class imfusion.igtl.IgtlPolyDataStream: Bases: PolyDataStream, Device

class imfusion.igtl.IgtlTrackingOutStream(self: IgtlTrackingOutStream, connection: Connection, name: str, type: str): Bases: OutStream, Device

class imfusion.igtl.IgtlTrackingStream(self: IgtlTrackingStream, connection: Connection, name: str, type: str): Bases: TrackingStream, Device

class imfusion.igtl.ImageData(self: ImageData, connection: Connection, name: str, clone_data: bool): Bases: SharedImageSet, Device

imfusion.machinelearning

Submodules containing routines for pre- and post-processing data to feed to a ML training framework.

exception imfusion.machinelearning.DataElementException: Bases: Exception

exception imfusion.machinelearning.DataItemException: Bases: Exception

exception imfusion.machinelearning.DataLoaderError: Bases: Exception

exception imfusion.machinelearning.ImageSamplerError: Bases: Exception

exception imfusion.machinelearning.MetricException: Bases: Exception

exception imfusion.machinelearning.OperationError: Bases: Exception

class imfusion.machinelearning.AddCenterBoxOperation(self: AddCenterBoxOperation, box_half_width: int = 0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Add an additional channel to the input image with a binary box at its center. The purpose of that operation is to give a location information to the model.

Parameters:

box_half_width – Half-width of the box in pixels.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AddDegradedLabelAsChannelOperation(self: AddDegradedLabelAsChannelOperation, blob_radius: float = 5.0, invert: bool = False, blob_coordinates: list[ndarray[numpy.float64[3, 1]]] = [], only_positive: bool = False, label_dilation: float = 0.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Operation that adds a guidance channel from the label map information, in order to train an interactive segmentation or segmentation refinement model.

This operation is designed for generating training data (in the context of interactive segmentation) from: - A label map indicating the ground truth, only available at training time - Points (blob coordinates) simulating clicks from the user that will be encoded as blobs in the new guidance channel

The operation creates an additional image channel that encodes both pieces of information: - Spherical blobs are rendered at the specified coordinates with the given radius - The sign (positive/negative) of values in this channel indicates whether the location belongs to the label (label==1) or not

Standard mode (p_invert=false, default) used in interactive scenarios where the user gives the information that one pixel should be inside/outside the output: - Inside blobs: +1.0 where label==1, -1.0 (or 0.0 if p_onlyPositive=true) where label!=1 - Outside blobs: 0.0 everywhere

Inverted mode (p_invert=true) used in refinement scenarios where the user wants to refine a first result at a particular location while freezing all the rest: - Inside blobs: 0.0 (marking the annotation location) - Outside blobs: +1.0 where label==1, -1.0 (or 0.0 if p_onlyPositive=true) where label!=1

A dilation parameter allows to dilate/erode the label map that will be used for determining the sign of the values in the guidance channel. This operation is internal and does not modify the actual label map.

Note

Requires exactly one label map in the input DataItem. Distributes blob coordinates across images for multi-image batches.

Parameters:

blob_radius – Radius of each spherical blob in millimeters. Default: 5.0
invert – Inverts the spatial behavior. False (default): blobs have signed values, background is 0. True: blobs are 0, background has signed values. Default: False
blob_coordinates – Coordinates of blob centers in world coordinates. For batches, automatically distributed across images. Default: []
only_positive – Controls negative value suppression. False (default): use both +1 and -1 values. True: replace negative values with 0, keeping only positive guidance. Default: False
label_dilation – Morphologically dilate (positive values) or erode (negative values) the label map in pixels/voxels before determining signs. Zero (default) uses label as-is. Default: 0.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AddPixelwisePredictionChannelOperation(self: AddPixelwisePredictionChannelOperation, config_path: str = '', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Run an existing pixelwise model and add result to the input image as additional channels. The prediction is automatically resampled to the input image resolution.

Parameters:

config_path – path to the YAML configuration file of the pixelwise model
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AddPositionChannelOperation(self: AddPositionChannelOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Add additional channels with the position of the pixels. Execute the algorithm AddPositionAsChannelAlgorithm internally, and uses the same configuration (parameter names and values).

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AddRandomNoiseOperation(self: AddRandomNoiseOperation, type: str = 'uniform', intensity: float = 0.2, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a pixelwise random noise to the image intensities.: For type == "uniform": noise is drawn in \([-\textnormal{intensity}, \textnormal{intensity}]\).

For type == "gaussian: noise is drawn from a Gaussian with zero mean and standard deviation equal to \(\textnormal{intensity}\).

For type == "gamma": noise is drawn from a Gamma distribution with \(k = \theta = \textnormal{intensity}\) (note that this noise has a mean of 1.0 so it is biased).

For type == "shot": noise is drawn from a Gaussian with zero mean and standard deviation equal to \(\textnormal{intensity} * \sqrt{\textnormal{pixel_value}}\).

Parameters:

type – Distribution of the noise (‘uniform’, ‘gaussian’, ‘gamma’, ‘shot’). Default: ‘uniform’
intensity – Value related to the standard deviation of the generated noise. Default: 0.2
probability – Value in [0.0, 1.0] indicating the probability of this operation to be performed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AdjustShiftScaleOperation(self: AdjustShiftScaleOperation, shift: list[float] = [0.0], scale: list[float] = [1.0], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a shift and scale to each channel of the input image. If shift and scale are vectors with multiple values, then for each channel c, \(\textnormal{output}_c = (\textnormal{input}_c + \textnormal{shift}_c) / \textnormal{scale}_c\). If shift and scale have a single value, then for each channel c, \(\textnormal{output}_c = (\textnormal{input} + \textnormal{shift}_c) / \textnormal{scale}\).

Parameters:

shift – Shift parameters as double (one value per channel, or one single value for all channels). Default: [0.0]
scale – Scaling parameter as double (one value per channel, or one single value for all channels). Default: [1.0]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ApplyTopDownFlagOperation(self: ApplyTopDownFlagOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Flip the input image if it has a topDown flag set to false.

Note

The topDown flag is not accessible from Python

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ApproximateToHigherResolutionOperation(self: ApproximateToHigherResolutionOperation, epsilon: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Replicate the input image of the operation from the original reference image (in ReferenceImageDataComponent) This operation is to be used mainly as post-processing, when a model produces a filtered image at a sub-resolution: it then tries to replicate the output from the original image so that no resolution is lost. It consists in estimating a multiplicative scalar field between the input and the downsampled original image, upsample it and then re-apply it on the original image.

Parameters:

epsilon – Used to avoid division by zero in case the original image has zero values. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ArgMaxOperation(self: ArgMaxOperation, selected_channels: list[int] = [], background_threshold: float | None = None, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Create a label map with the indices corresponding of the input channel with the highest value. The output of this operation is zero indexed, i.e. no matter which channels where selected the output is always in range [0; n - 1] where n is the number of selected channels (+ 1 if background threshold selected).

Parameters:

selected_channels – List of channels to be selected for the argmax. If empty, use all channels (default). Indices are zero indexed, e.g. [0, 1, 2, 3] selects the first 4 channels.
background_threshold – If set, the arg-max operation assumes the background is not explicitly encoded, and is only set when all activations are below background_threshold. The output then encodes 0 as the background. E.g. if the first 4 channels were selected, the possible output values would be [0, 1, 2, 3, 4] with 0 for the background and the rest for the selected channels.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AxisFlipOperation(self: AxisFlipOperation, axes: list[str] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Flip image content along specified set of axes.

Parameters:

axes – List of strings from {‘x’,’y’,’z’} specifying the axes to flip. For 2D images, only ‘x’ and ‘y’ are valid.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.AxisRotationOperation(self: AxisRotationOperation, axes: list[str] = [], angles: list[int] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Rotate image around image axis with axis-specific rotation angles that are signed multiples of 90 degrees.

Parameters:

axes – List of strings from {‘x’,’y’,’z’} specifying the axes to rotate around. For 2D images, only [‘z’] is valid.
angles – List of integers (with same lengths as axis) specifying the rotation angles in degrees. Only +- 0/90/180/270 are valid.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.BakeDeformationOperation(self: BakeDeformationOperation, adjust_size: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Deform an image with its attached Deformation and store the result into the returned output image. This operation will return a clone of the input image if it does not have any deformation attached. The output image will not have an attached Deformation.

Parameters:

adjust_size – whether the size of the output image would be automatically adjusted to fit the deformed content. Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.BakePhotometricInterpretationOperation(self: BakePhotometricInterpretationOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Bake the Photometric Interpretation into the intensities of the image. If the image has a Photometric Interpretation of MONOCHROME1, the intensities will run be inverted using: \(\textnormal{output} = \textnormal{max} - (\textnormal{input} - \textnormal{min})\)

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.BakeTransformationOperation(self: BakeTransformationOperation, padding_mode: PaddingMode = PaddingMode.ZERO, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply the rotation contained in the matrix of the input volume. The internal memory buffer will be re-organized but the image location in world coordinate will not change. The output matrix is guaranteed to have no rotation (but may still have a translation component). Pixels outside the original image extent will be padded according to the padding_mode parameter. Note: If a mask is present, this operation assumes that it is an ExplicitMask and will process it as well.

Parameters:

padding_mode – defines which type of padding is used in [“zero”, “clamp”, “mirror”]. Default: ZERO
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.BlobsFromKeypointsOperation(self: BlobsFromKeypointsOperation, blob_radius: float = 5.0, image_field_name: str = 'data', blobs_field_name: str = 'label', label_map_mode: bool = False, sharp_blobs: bool = False, blob_radius_units: ParamUnit = MM, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Transforms keypoints into an actual image (blob map with the same size of the image). Requires an input image called “data” (can be overwritten with the parameter image_field_name) and some keypoints called “keypoints” (can be overwritten with the parameter apply_to).

Parameters:

blob_radius – Size of the generated blobs in mm. Default: 5.0
image_field_name – Field name of the reference image. Default: “data”
blobs_field_name – Field name of the output blob map. Default: “label”
label_map_mode – Generate ubyte label map instead of multi-channel gaussian blobs. Default: False
sharp_blobs – Specifies whether to sharpen the profiles of the blob function, making its support more compact. Default: False
blob_radius_units – The units to use when interpreting the blob_radius parameter. Default: “mm”
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.BoundingBoxElement(self: BoundingBoxElement, boundingbox_set: BoundingBoxSet)

Bases: DataElement

DataElement for storing and processing bounding box annotations.

BoundingBoxElement wraps a BoundingBoxSet to represent 3D bounding box annotations in ML pipelines. Bounding boxes are commonly used for object detection and region-of-interest specifications.

Initialize a BoundingBoxElement

Parameters:: boundingbox_set – In case the argument is a numpy array, the array shape is expected to be [N, C, B, 2, 3], where N is the batch size, C the number of different keypoint types (channel), B the number of instances of the same box type. Each Box is expected to have dimensions [2, 3]. If the argument is a nested list, the same concept applies also to the size of each level of nesting.

property boxes: Access to the underlying BoundingBoxSet.

class imfusion.machinelearning.BoundingBoxSet(*args, **kwargs)

Bases: Data

Class for managing sets of bounding boxes

The class is meant to be used in parallel with SharedImageSet. For each frame in the set, and for each type of bounding box (i.e. car, airplane, lung, cat), there is a list of boxes that encompass an instance of that type in the reference image. In terms of tensor dimensions, this would be represented as [N, C, B], where N is the batch size, C is the number of channels (i.e. types of boxes), and B is the number of boxes for the same instance type. Each Box has a dimension of [2, 3], consisting of a pair of vec3 for describing center and extent. See the Box class for more information.

Note

The API for this class is experimental and may change soon.

Function overload documentation:

__init__(self: BoundingBoxSet, boxes: list[list[list[Box]]]) → None

Initialize a BoundingBoxSet from a nested vector of Box objects.

Parameters:: boxes – 3D nested vector [N, C, B] of Box objects where N=batch size, C=channels (box types), B=boxes per type

__init__(self: BoundingBoxSet, boxes: list[list[list[tuple[ndarray[numpy.float64[3, 1]], ndarray[numpy.float64[3, 1]]]]]]) → None

Initialize a BoundingBoxSet from nested vectors of (center, extent) pairs.

Parameters:: boxes – 3D nested vector [N, C, B] where each box is a pair of vec3 (center, extent)

__init__(self: BoundingBoxSet, boxes: list[list[list[tuple[list[float], list[float]]]]]) → None

Initialize a BoundingBoxSet from nested lists of ([center], [extent]) pairs.

Parameters:: boxes – 3D nested list where each box is ((center_list, extent_list)) with 3D coordinates

__init__(self: BoundingBoxSet, array: ndarray[numpy.float64]) → None

Initialize a BoundingBoxSet from a numpy array.

Parameters:: array – Numpy array with shape [N, C, B, 2, 3] where N=batch size, C=channels, B=boxes, 2=(center, extent), 3=coordinates

static load(location: str | PathLike) → BoundingBoxSet | None

Load a BoundingBoxSet from an ImFusion file.

Parameters:: location – input path.

save(self: BoundingBoxSet, location: str | PathLike) → None

Save a BoundingBoxSet as an ImFusion file.

Parameters:: location – output path.

property data: The bounding box data stored as a 5D nested vector [N, C, B, 2, 3] where N=batch size, C=channels, B=number of boxes per channel, 2=(center, extent), and 3=coordinates

class imfusion.machinelearning.Box(*args, **kwargs)

Bases: pybind11_object

Bounding Box class for ML tasks. Since bounding boxes are axis aligned by definition, a Box is represented by its center and its extent. This representation allows for easy rotation, augmentation etc.

Function overload documentation:

__init__(self: Box, center: ndarray[numpy.float64[3, 1]], extent: ndarray[numpy.float64[3, 1]]) → None

Initialize a Box with center and extent.

Parameters:

center – 3D vector specifying the center point of the box
extent – 3D vector specifying the size/extent of the box

__init__(self: Box, center_and_extent: tuple[ndarray[numpy.float64[3, 1]], ndarray[numpy.float64[3, 1]]]) → None

Initialize a Box from a tuple of (center, extent).

Parameters:: center_and_extent – Tuple of two 3D vectors (center, extent)

property center: The center point of the bounding box as a 3D vector (x, y, z)

property extent: The extent (size) of the bounding box as a 3D vector (width, height, depth)

class imfusion.machinelearning.CenterROISampler(self: CenterROISampler, roi_size: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: ImageROISampler

Sampler which samples one ROI from the input image and label map with a target size. The ROI is centered on the image center. The arrays will be padded if the target size is larger than the input image.

Parameters:

roi_size – Target size of the ROIs to be extracted as [Width, Height, Slices]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

padding_mode: Padding mode for input images. Default: CLAMP

label_padding_mode: Padding mode for target label maps. Default: CLAMP

class imfusion.machinelearning.ChannelDropoutOperation(self: ChannelDropoutOperation, selected_channels: list[int] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Sets the specified input channels to zero while keeping all other channels unchanged (0-based indexing).

Parameters:

selected_channels – List of channels to be set to zero. If empty, no channels are modified.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ChannelGatherOperation(self: ChannelGatherOperation, value_field: str = 'values', index_field: str = 'indices', output_field: str = 'gathered', *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Gathers per-voxel values from a multi-channel “value” image using channel indices from a separate “index” image.

For every voxel v and index channel k:

output[v, k] = values[v, indices[v, k]]

The index image must be uint8 or uint16 and may have one or more channels. A single-channel index image (e.g. an ArgMax label map) applied to a softmax probability image produces a single-channel confidence map. A K-channel index image yields a K-channel output (independent gathers). Both images must have identical spatial dimensions. Out-of-range indices raise an error. Only CPU execution is supported.

Parameters:

value_field – DataItem field name for the multi-channel value image. Default: ‘values’
index_field – DataItem field name for the integer index image. Default: ‘indices’
output_field – DataItem field name where the gathered output will be stored. Default: ‘gathered’
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.CheckDataOperation(self: CheckDataOperation, num_dimensions: int = 0, num_images: int = 0, num_channels: int = 0, data_type: str = '', dimensions: ndarray[numpy.int32[3, 1]] = array([0, 0, 0], dtype=int32), spacing: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), label_match_input: bool = False, label_type: str = '', label_values: list[int] = [], label_dimensions: ndarray[numpy.int32[3, 1]] = array([0, 0, 0], dtype=int32), label_channels: int = 0, check_rotation_matrix: bool = False, check_deformation: bool = False, check_shift_scale: bool = False, fail_on_error: bool = True, save_path_on_error: str = '', check_label_values_are_subset: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Checks if all input data match a set of expected conditions. If parameters are zero or empty, they are not checked.

Parameters:

num_dimensions – Expected number of dimensions in the input. Set to 0 to skip this check. Default: 0
num_images – Expected number of images in the input. Set to 0 to skip this check. Default: 0
num_channels – Expected number of channels in the input. Set to 0 to skip this check. Default: 0
data_type – Expected datatype of input. Must be one of: [“”, “float”, “uint8”, “int8”, “uint16”, “int16”, “uint32”, “int32”, “double”]. Empty string skips this check. Default: “”
dimensions – Expected spatial dimensions [width, height, depth] of input image. Set all dimensions to 0 to skip checking it. Default: [0,0,0]
spacing – Expected spacing [x, y, z] of input image in mm. Set all components to 0 to skip checking it. Default: [0,0,0]
label_match_input – Whether label dimensions and channel count must match the input image. Default: False
label_type – Expected datatype of labels. Must be one of: [“”, “float”, “uint8”, “int8”, “uint16”, “int16”, “uint32”, “int32”, “double”]. Empty string skips this check. Default: “”
label_values – List of required label values (excluding 0). No other values are allowed. When check_label_values_are_subset is false, all must be present. Empty list skips this check. Default: []
label_dimensions – Expected spatial dimensions [width, height, depth] of label image. Set all dimensions to 0 to skip checking it. Default: [0,0,0]
label_channels – Expected number of channels in the label image. Set to 0 to skip this check. Default: 0
check_rotation_matrix – Whether to verify the input image has no rotation matrix. Default: False
check_deformation – Whether to verify the input image has no deformation. Default: False
check_shift_scale – Whether to verify the input image has identity intensity transformation. Default: False
fail_on_error – Whether to raise an exception on validation failure (True) or just log an error (False). Default: True
save_path_on_error – Path where to save the failing input as an ImFusion file (.imf) when validation fails. Empty string disables saving. Default: “”
check_label_values_are_subset – Whether to check if the label values are a subset of the label values provided with label_values, otherwise check if all values are present in the label image. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ClipOperation(self: ClipOperation, min: float = 0.0, max: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Clip the intensities to a minimum and maximum value: all intensities outside this range will be clipped to the range border.

Parameters:

min – Minimum intensity of the output image. Default: 0.0
max – Maximum intensity of the output image. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ComputingDevice(*args, **kwargs)

Bases: pybind11_object

Enum specifying which computing device (CPU or GPU) should be used for operations.

Values:: FORCE_CPU: Always use CPU for processing GPU_IF_GL_IMAGE: Use GPU only if the input is a GlImage GPU_IF_OPENGL: Use GPU if OpenGL is available FORCE_GPU: Always use GPU for processing

Members:

FORCE_CPU : Always execute on CPU

GPU_IF_GL_IMAGE : Execute on GPU only if input is a GlImage

GPU_IF_OPENGL : Execute on GPU if OpenGL is available

FORCE_GPU : Always execute on GPU

Function overload documentation:

__init__(self: ComputingDevice, value: int) → None

__init__(self: ComputingDevice, arg0: str) → None

FORCE_CPU = <ComputingDevice.FORCE_CPU: 0>

FORCE_GPU = <ComputingDevice.FORCE_GPU: 3>

GPU_IF_GL_IMAGE = <ComputingDevice.GPU_IF_GL_IMAGE: 1>

GPU_IF_OPENGL = <ComputingDevice.GPU_IF_OPENGL: 2>

property name

property value

class imfusion.machinelearning.ConcatenateNeighboringFramesToChannelsOperation(self: ConcatenateNeighboringFramesToChannelsOperation, radius: int = 0, reduction_mode: str = 'none', same_padding: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

This function iterates over each frame, augmenting the channel dimension by appending or adding information from neighboring frames from both sides. For instance, with radius=1 concatenation, an image with dimensions (10, 1, 256, 256, 1) becomes an (10, 1, 256, 256, 3) image, meaning each frame will now include its predecessor (channel 0), itself (channel 1), and its successor (channel 2). For multi-channel inputs, only the first channel is used for concatenation; other channels are appended after these in the output. With reduction_mode, central and augmented frames can be reduced to a single frame to preserve the original number of channels.

Parameters:

radius – Defines the number of neighboring frames added to each side within the channel dimension. Default: 0
reduction_mode – Determines if and how to reduce neighboring frames. Options: “none” (default, concatenates), “average”, “maximum”.
same_padding – Use frame replication (not zero-padding) at sequence edges. Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ConvertSlicesToVolumeOperation(self: ConvertSlicesToVolumeOperation, axis: str = 'z', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Stacks a set of 2D images extracted along a specified axis into an actual 3D volume.

Parameters:

axis – Axis along which to extract slices (must be either ‘x’, ‘y’ or ‘z’)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ConvertToGrayOperation(self: ConvertToGrayOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Convert the input image to a single channel image by averaging all channels.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ConvertVolumeToSlicesOperation(self: ConvertVolumeToSlicesOperation, axis: str = 'z', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Unstacks a 3D volume to a set of 2D images extracted along one of the axes.

Parameters:

axis – Axis along which to extract slices (must be either ‘x’, ‘y’ or ‘z’)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ConvolutionalCRFOperation(self: ConvolutionalCRFOperation, adaptiveness: float = 0.5, smooth_weight: float = 0.1, radius: int = 5, downsampling: int = 2, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Adapt segmentation map or raw output of model to image content.

Parameters:

adaptiveness – Indicates how much the segmentation should be adapted to the image content. Range [0, 1]. Default: 0.5
smooth_weight – Weight of the smoothness kernel. Higher values create a greater penalty for nearby pixels having different labels. Default: 0.1
radius – Radius of the message passing window in pixels. Default: 5
downsampling – Amount of downsampling used in message passing, makes the effective radius of the message passing window larger. Default: 2
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.CopyOperation(self: CopyOperation, source: list[str] = [], target: list[str] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Copies a set of fields of a data item.

Parameters:

source – list of the elements to be copied
target – list of names of the new elements (must match the size of source)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.CropAroundLabelMapOperation(self: CropAroundLabelMapOperation, label_values: list[int] = [1], margin: int = 1, reorder: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Crops the input image and label to the bounds of the specified label value, and sets the label value to 1 and all other values to zero in the resulting label.

Parameters:

label_values – Label values to select. Default: [1]
margin – Margin, in pixels. Default: 1
reorder – Whether label values in result should be mapped to 1,2,3… based on input in label_values. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.CropOperation(self: CropOperation, size: ndarray[numpy.int32[3, 1]] = array([0, 0, 0], dtype=int32), offset: ndarray[numpy.int32[3, 1]] = array([0, 0, 0], dtype=int32), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Crop input images and label maps with a given size and offset.

Parameters:

size – List of integers representing the target dimensions of the image to be cropped. If -1 is specified, the whole dimension will be kept, starting from the corresponding offset.
offset – List of integers representing the position of the lower corner of the cropped image
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.CutOutOperation(self: CutOutOperation, size: list[ndarray[numpy.float64[3, 1]]] = [array([1., 1., 1.])], offset: list[ndarray[numpy.float64[3, 1]]] = [array([0., 0., 0.])], fill_value: list[float] = [0.0], size_units: ParamUnit = MM, offset_units: ParamUnit = VOXEL, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Cut out input images and label maps with a given size, offset and fill values.

Parameters:

size – List of 3-dim vectors representing the target dimensions of the image to be cut out. Default: [1, 1, 1]
offset – List of 3-dim vectors representing the position of the lower corner of the cut out area. Default: [0, 0, 0]
fill_value – List of intensity value (floats) for filling out cutout region. Default: [0.0]
size_units – Units of the size parameter (ParamUnit.MM or “mm”, ParamUnit.FRACTION or “fraction”, ParamUnit.VOXEL or “voxel”). Default: MM
offset_units – Units of the offset parameter (ParamUnit.MM or “mm”, ParamUnit.FRACTION or “fraction”, ParamUnit.VOXEL or “voxel”). Default: VOXEL

Note: ParamUnit can be automatically converted from a string. This means you can directly pass a string like “mm”, “fraction”, or “voxel” to the param_units parameters instead of using the enum values.: device: Specifies whether this Operation should run on CPU or GPU. seed: Specifies seeding for any randomness that might be contained in this operation. error_on_unexpected_behaviour: Specifies whether to throw an exception instead of warning about unexpected behavior. apply_to: Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy) record_identifier: Unused for this operation as it is not invertible

class imfusion.machinelearning.DataElement

Bases: pybind11_object

Base class for elements containing typed data in a DataItem.

DataElement is the fundamental building block for storing heterogeneous data types in machine learning pipelines. Each element wraps a specific data type (images, keypoints, bounding boxes, tensors, etc.) and provides a uniform interface for processing.

DataElements support: - Batch processing with consistent batch sizes - Target tagging for training labels - Cloning and splitting operations - Type-specific content access

class CloneOptions(self: CloneOptions, value: int)

Bases: pybind11_object

Controls which parts of a DataElement are copied during cloning.

Members:

EVERYTHING : Copy everything, including the underlying data (full deep copy).

SHALLOW : For images and vectors, make a shallow copy of the underlying data (the new element shares the pixel/buffer data with the original). Keypoints and bounding boxes are deep copied.

CONTAINER : For keypoints and bounding boxes, only clone the container without the underlying data.

NO_IMAGE_DATA : For images and vectors, only clone the container without the underlying data.

CONTAINER = <CloneOptions.CONTAINER: 2>

EVERYTHING = <CloneOptions.EVERYTHING: 0>

NO_IMAGE_DATA = <CloneOptions.NO_IMAGE_DATA: 3>

SHALLOW = <CloneOptions.SHALLOW: 1>

property name

property value

__iter__() → Iterator

Return an iterator over the contents of this DataElement.

This allows DataElements to be used in for-loops and other iteration contexts.

Returns:: Iterator over the element’s content
Return type:: Iterator

clone(self: imfusion.machinelearning.DataElement, opt: imfusion.machinelearning.DataElement.CloneOptions = <CloneOptions.EVERYTHING: 0>) → DataElement

clone(self: DataElement, with_data: bool) → DataElement

Function overload documentation:

clone(self: imfusion.machinelearning.DataElement, opt: imfusion.machinelearning.DataElement.CloneOptions = <CloneOptions.EVERYTHING: 0>) → DataElement

Create a copy of the element.

Parameters:: opt (CloneOptions) – Controls which parts of the element are copied. Defaults to CloneOptions.EVERYTHING (full deep copy). Use CloneOptions.SHALLOW to obtain a shallow copy where image/vector data is shared with the original (keypoints and bounding boxes are still deep copied).
Returns:: A new DataElement that is a copy of this one.
Return type:: DataElement

clone(self: DataElement, with_data: bool) → DataElement

Create a copy of the element.

Deprecated since version Use: clone(opt=...) with a CloneOptions value instead. with_data=True corresponds to opt=CloneOptions.EVERYTHING and with_data=False corresponds to opt=CloneOptions.CONTAINER.

Parameters:: with_data (bool) – If True, perform a full deep copy. If False, only clone the container without the underlying data.
Returns:: A new DataElement that is a copy of this one.
Return type:: DataElement

numpy(copy=False)

Convert a DataElement to a numpy array.

This method enables numpy array protocol support for DataElement objects, allowing them to be used with numpy.array() and similar functions.

Parameters:

copy – If True, force a copy of the data. Default: False
self (DataElement) –

Returns:

numpy array representation of the DataElement

split(self: DataElement) → list[DataElement]: Split an element into several ones along the batch dimension.

static stack(elements: list[DataElement]) → DataElement: Stack several elements along the batch dimension.

tag_as_target(self: DataElement) → None: Mark this element as being a target.

torch(device: device = None, dtype: dtype = None, same_as: Tensor = None) → Tensor

Convert SharedImageSet or a SharedImage to a torch.Tensor.

Parameters:

self (DataElement | SharedImageSet | SharedImage) – Instance of SharedImageSet or SharedImage (this function bound as a method to SharedImageSet and SharedImage)
device (device) – Target device for the new torch.Tensor
dtype (dtype) – Type of the new torch.Tensor
same_as (Tensor) – Template tensor whose device and dtype configuration should be matched. device and dtype are still applied afterwards.

Returns:

New torch.Tensor

Return type:

Tensor

untag_as_target(self: DataElement) → None: Remove target status from this element.

property batch_size: Returns the batch size of the element.

property components: Returns the list of DataComponents for this element.

property content: Access to the underlying Data.

property dimension: Returns the dimensionality of the underlying data

property is_target: Returns true if this element is marked as a target.

property ndim: Returns the dimensionality of the underlying data

property type: Returns the type of the underlying data

class imfusion.machinelearning.DataItem(self: DataItem, elements: dict[str, DataElement] = {})

Bases: Data

Class managing a dictionary of DataElements. This class is used as the container for applying Operations to a collection of heterogeneous data in a consistent way. This class implements the concept of batch size for the contained elements. As such, a DataItem can be split or stacked along the batch axis like the contained DataElements, but because of that it enforces that all DataElement stored have consistent batch size.

Construct a DataItem with existing Elements if provided.

Parameters:: elements (Dict[str, imfusion.DataElement]) – elements to be inserted into the DataItem, default: {}

class CompressionMode(self: CompressionMode, value: int)

Bases: pybind11_object

Members:

NONE : No compression

RLE : Run-length encoding

ZSTD : ZSTD lossless compression (default)

NONE = <CompressionMode.NONE: 0>

RLE = <CompressionMode.RLE: 1>

ZSTD = <CompressionMode.ZSTD: 65>

property name

property value

__getitem__(self: DataItem, field: str) → DataElement: Get a DataElement by field name. Raises KeyError if field doesn’t exist

__iter__(self: DataItem) → Iterator[tuple[str, DataElement]]: Return an iterator over field names in the DataItem

__setitem__(self: DataItem, field: str, element: DataElement) → None

__setitem__(self: DataItem, field: str, element: ImageElement) → None

__setitem__(self: DataItem, field: str, element: KeypointsElement) → None

__setitem__(self: DataItem, field: str, element: BoundingBoxElement) → None

__setitem__(self: DataItem, field: str, element: VectorElement) → None

__setitem__(self: DataItem, field: str, element: TensorSetElement) → None

__setitem__(self: DataItem, field: str, shared_image_set: SharedImageSet) → None

__setitem__(self: DataItem, field: str, keypoint_set: KeypointSet) → None

__setitem__(self: DataItem, field: str, bboxes: BoundingBoxSet) → None

__setitem__(self: DataItem, field: str, tensorset: TensorSet) → None

Function overload documentation:

__setitem__(self: DataItem, field: str, element: DataElement) → None

Set a DataElement to the DataItem.

Parameters:

field (str) – field name
element (DataElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, element: ImageElement) → None

Set a ImageElement to the DataItem.

Parameters:

field (str) – field name
element (ImageElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, element: KeypointsElement) → None

Set a KeypointsElement to the DataItem.

Parameters:

field (str) – field name
element (KeypointsElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, element: BoundingBoxElement) → None

Set a BoundingBoxElement to the DataItem.

Parameters:

field (str) – field name
element (BoundingBoxElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, element: VectorElement) → None

Set a VectorElement to the DataItem.

Parameters:

field (str) – field name
element (VectorElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, element: TensorSetElement) → None

Set a TensorSetElement to the DataItem.

Parameters:

field (str) – field name
element (TensorSetElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, shared_image_set: SharedImageSet) → None

Set a SharedImageSet to the DataItem.

Parameters:

field (str) – field name
element (SharedImageSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, keypoint_set: KeypointSet) → None

Set a KeypointSet to the DataItem.

Parameters:

field (str) – field name
element (imfusion.KeypointSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, bboxes: BoundingBoxSet) → None

Set a BoundingBoxSet to the DataItem.

Parameters:

field (str) – field name
element (BoundingBoxSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

__setitem__(self: DataItem, field: str, tensorset: TensorSet) → None

Set a Tensor to the DataItem.

Parameters:

field (str) – field name
element (Tensor) – element to be inserted into the DataItem, if the field exists it’s overwritten.

clear(self: DataItem) → None: Clears the data item and leaves it empty.

clone(self: imfusion.machinelearning.DataItem, opt: imfusion.machinelearning.DataElement.CloneOptions = <CloneOptions.EVERYTHING: 0>) → DataItem

clone(self: DataItem, with_data: bool) → DataItem

Function overload documentation:

clone(self: imfusion.machinelearning.DataItem, opt: imfusion.machinelearning.DataElement.CloneOptions = <CloneOptions.EVERYTHING: 0>) → DataItem

Returns a copy of the data item.

Parameters:: opt (CloneOptions) – Controls which parts of the contained elements are copied. Defaults to DataElement.CloneOptions.EVERYTHING (full deep copy). Use DataElement.CloneOptions.SHALLOW to obtain a shallow copy where image and vector data is shared with the original (keypoints and bounding boxes are still deep copied).
Returns:: A new DataItem whose elements have been cloned according to opt.
Return type:: DataItem

clone(self: DataItem, with_data: bool) → DataItem

Returns a copy of the data item.

Deprecated since version Use: clone(opt=...) with a DataElement.CloneOptions value instead. with_data=True corresponds to opt=DataElement.CloneOptions.EVERYTHING and with_data=False corresponds to opt=DataElement.CloneOptions.NO_IMAGE_DATA.

Parameters:: with_data (bool) – If True, perform a full deep copy. If False, image and vector elements are cloned without their underlying data.
Returns:: A new DataItem.
Return type:: DataItem

contains(self: DataItem, field_name: str) → bool

Checks if the data item contains a field with the given name.

Parameters:: field_name – Name of the field to check for
Returns:: True if the field exists, False otherwise
Return type:: bool

static deserialize(data: Buffer) → DataItem

Deserialize DataItem from bytes (plain ImFusionFile format).

Parameters:: data – Serialized DataItem as any buffer-protocol object (bytes, bytearray, memoryview, etc.)
Returns:: Deserialized DataItem
Return type:: DataItem
Raises:: RuntimeError – If deserialization fails

get(self: DataItem, field: str) → DataElement

get(self: DataItem, field: str, default: DataElement) → DataElement

Function overload documentation:

get(self: DataItem, field: str) → DataElement

Returns a reference to an element (raises a KeyError if field is not in item)

Parameters:: field (str) – Name of the field to retrieve.

get(self: DataItem, field: str, default: DataElement) → DataElement

Returns a reference to an element (or the default value if field is not in item)

Parameters:

field (str) – Name of the field to retrieve.
default (DataElement) – default value to return if field is not in DataItem.

get_all(self: DataItem, element_type: ElementType) → set[DataElement]

Returns a set of all elements of the specified type.

This method filters the DataItem to find all DataElements matching the given ElementType.

Parameters:: element_type – The type of elements to retrieve (e.g., ElementType.Image, ElementType.Keypoint)
Returns:: Set of DataElements matching the specified type
Return type:: set

items(self: DataItem) → Iterator[tuple[str, DataElement]]: Returns an iterator over (field_name, DataElement) pairs in the DataItem

keys(self: DataItem) → Iterator[str]: Returns an iterator over all field names in the DataItem

static load(location: str | PathLike) → DataItem

Load data item from ImFusion file.

Parameters:: location – input path.

static merge(items: list[DataItem]) → DataItem

Merge several data items by setting all their fields to the output item

Parameters:: items (List[DataItem]) – List of input items to merge.

Note

Raises an exception is the same field is contained in more than one item.

pop(self: DataItem, field: str) → DataElement

Remove the DataElement associated to the given field and returns it.

Parameters:: field (str) – Name of the field to remove.

save(self: DataItem, location: str | PathLike, compression: CompressionMode = DataItem.CompressionMode.ZSTD, field_compression: dict[str, CompressionMode] = {}) → None

Save a DataItem as ImFusion file.

Parameters:

location – output path.
compression – Default compression mode (default: DataItem.CompressionMode.ZSTD).
field_compression – Optional dict mapping field names to compression modes. Fields not in the dict use the default compression. Example: {“labels”: DataItem.CompressionMode.ZSTD, “image”: DataItem.CompressionMode.NONE}

Note

Compression support is element-type dependent

serialize(self: DataItem, compression: CompressionMode = DataItem.CompressionMode.ZSTD, field_compression: dict[str, CompressionMode] = {}) → bytes

Serialize this DataItem to bytes (plain ImFusionFile format).

Parameters:

compression – Default compression mode (default: DataItem.CompressionMode.ZSTD).
field_compression – Optional dict mapping field names to compression modes. Fields not in the dict use the default compression. Example: {“labels”: DataItem.CompressionMode.ZSTD, “image”: DataItem.CompressionMode.NONE}

Note

Compression support is element-type dependent

Returns:: Serialized DataItem
Return type:: bytes
Raises:: RuntimeError – If serialization fails

set(self: DataItem, field: str, element: DataElement) → None

set(self: DataItem, field: str, element: ImageElement) → None

set(self: DataItem, field: str, element: KeypointsElement) → None

set(self: DataItem, field: str, element: BoundingBoxElement) → None

set(self: DataItem, field: str, element: VectorElement) → None

set(self: DataItem, field: str, element: TensorSetElement) → None

set(self: DataItem, field: str, shared_image_set: SharedImageSet) → None

set(self: DataItem, field: str, keypoint_set: KeypointSet) → None

set(self: DataItem, field: str, bounding_box_set: BoundingBoxSet) → None

set(self: DataItem, field: str, tensorset: TensorSet) → None

Function overload documentation:

set(self: DataItem, field: str, element: DataElement) → None

Set a DataElement to the DataItem.

Parameters:

field (str) – field name
element (DataElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, element: ImageElement) → None

Set a ImageElement to the DataItem.

Parameters:

field (str) – field name
element (ImageElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, element: KeypointsElement) → None

Set a KeypointsElement to the DataItem.

Parameters:

field (str) – field name
element (KeypointsElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, element: BoundingBoxElement) → None

Set a BoundingBoxElement to the DataItem.

Parameters:

field (str) – field name
element (BoundingBoxElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, element: VectorElement) → None

Set a VectorElement to the DataItem.

Parameters:

field (str) – field name
element (VectorElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, element: TensorSetElement) → None

Set a TensorSetElement to the DataItem.

Parameters:

field (str) – field name
element (TensorSetElement) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, shared_image_set: SharedImageSet) → None

Set a SharedImageSet to the DataItem.

Parameters:

field (str) – field name
element (SharedImageSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, keypoint_set: KeypointSet) → None

Set a KeypointSet to the DataItem.

Parameters:

field (str) – field name
element (KeypointSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, bounding_box_set: BoundingBoxSet) → None

Set a BoundingBoxSet to the DataItem.

Parameters:

field (str) – field name
element (BoundingBoxSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

set(self: DataItem, field: str, tensorset: TensorSet) → None

Set a TensorSet to the DataItem.

Parameters:

field (str) – field name
element (TensorSet) – element to be inserted into the DataItem, if the field exists it’s overwritten.

static split(item: DataItem) → list[DataItem]

Split a data item along the batch channels into items, each with batch size 1

Parameters:: item (DataItem) – Item to split.

static stack(items: list[DataItem]) → DataItem

Stack several data items along the batch dimension.

Parameters:: items (List[DataItem]) – List of input items to stack.

update(self: DataItem, other: DataItem, clone: bool = True) → None

Update the contents of self with elements from other

Parameters:

other (DataItem) – DataItem that holds the information that should be added to self.
clone (bool) – Indicates whether other should be cloned before the update. If False other will be invalidated, default=True.

Note

Raises an exception if the batch_size of other does not match self.

values(self: DataItem) → Iterator[DataElement]: Returns an iterator over all DataElements in the DataItem

NONE = <CompressionMode.NONE: 0>

RLE = <CompressionMode.RLE: 1>

ZSTD = <CompressionMode.ZSTD: 65>

property batch_size: Returns the batch size of the fields, zero if no elements are present, or None if there are inconsistencies within them.

property dimension: Returns the dimensionality of the elements, or zero if no elements are present or if there are inconsistencies within them.

property fields: Returns the set of all fields contained in the data item.

property ndim: Returns the dimensionality of the elements, or zero if no elements are present or if there are inconsistencies within them.

class imfusion.machinelearning.DataLoaderSpecs(self: DataLoaderSpecs, name: str, configuration: Properties, phase: Phase, inputs: list[str], output: str)

Bases: pybind11_object

Specification for configuring a data loader in a Dataset pipeline.

This class contains the configuration parameters for a data loader, including its name, properties, execution phase, and input/output field names.

Initialize a DataLoaderSpecs.

Parameters:

name – Name of the data loader
configuration – Properties object containing loader configuration
phase – Execution phase (Training/Validation/Inference/Always)
inputs – List of input field names
output – Output field name

property configuration: Configuration properties for the data loader

property inputs: Input field names

property name: Name of the data loader

property output: Output field name

property phase: Execution phase for the data loader

class imfusion.machinelearning.Dataset(*args, **kwargs)

Bases: pybind11_object

Class for creating an iterable dataset by chaining data loading and transforming operations executed in a lazy fashion. The Dataset implements an iterable interface, which allows to use iter() and next() built-ins as well as range based loops.

Function overload documentation:

__init__(self: Dataset, data_lists: list[tuple[dict[int, str], list[str]]], shuffle: bool = False, verbose: bool = False) → None

Constructs a dataset from lists of filenames.

Parameters:

data_lists (list) – list txt files, each listing the file paths. Complete type: List[Str]
shuffle (bool) – shuffle file order. Default: false
verbose (bool) – enable verbose logging. Default: false

__init__(self: Dataset, read_from: str, reader_properties: Properties, verbose: bool = False) → None

Constructs a dataset by specifying a reader type as a string.

Parameters:

read_from (string) – specifies the type of reader that is created implicitly. Options: “filesystem”.
reader_properties (Properties) – properties used to configure the reader.
verbose (bool) – print debug information when running the data loader. Default: false

__init__(self: Dataset, verbose: bool = False) → None

Constructs an empty dataset.

Parameters:: verbose (bool) – print debug information when running the data loader. Default: false

__iter__(self: Dataset) → Dataset: Return an iterator over the dataset. Automatically resets the dataset to the beginning

__next__(self: Dataset) → DataItem: Get the next DataItem from the dataset. Raises StopIteration when exhausted

static available_decorators() → list[str]: Returns the keys of the register decorator functions

static available_filter_functions() → list[str]: Returns filter function keys to be used in Dataset.filter decorator function

static available_map_functions() → list[str]: Returns map function keys to be used in Dataset.map decorator function

batch(self: Dataset, batch_size: int = 1, pad: bool = False, overlap: int = 0) → Dataset

Batches the next batch_size items in a single one before returning it.

Parameters:

batch_size (int) – batch size.
pad (bool) – last batch gets filled up with the last data item until the batch matches batch_size.
overlap (int) – number of items overlapping in consecutive batches. Must be less than batch_size.

build_pipeline(self: Dataset, property_list: list[DataLoaderSpecs], config_phase: Phase = Phase.ALWAYS) → None

Configures the Dataset decorators to be used based on a list of Properties.

Parameters:

property_list (list) – list of imfusion.Properties or list of dict()
config_phase (Phase) – configuration phase.

cache(self: Dataset, make_exclusive_cpu: bool = True, lazy: bool = True, compression_level: int = 0, shuffle: bool = False) → Dataset: Deprecated - please use ‘memory_cache’ now.

disk_cache(self: Dataset, location: str = '', lazy: bool = True, reload_from_disk: bool = True, compression: str = 'LabelsOnly', shuffle: bool = False) → Dataset

Caches the dataset already loaded in a persistent manner (on a disk location) Raises a DataLoaderError if the dataset is not countable.

Parameters:

location (string) – path to the folder where all the data will be cached.
lazy (bool) – if false, the cache is filled upon construction (otherwise as items are requested).
reload_from_disk (bool) – try to reload the cache from a previous session (reload is the deprecated name of this parameter).
compression (str) – compression strategy. ‘None’ for no compression, ‘LabelsOnly’ to compress only semantic segmentation label maps (using ZSTD), ‘All’ to compress all fields (using ZSTD). Default is ‘LabelsOnly’ (this differs from the deprecated boolean API default, which was no compression).
shuffle (bool) – re-shuffle the cache order every epoch.

filter(self: Dataset, func: Callable[[DataItem], bool]) → Dataset

filter(self: Dataset, func_name: str) → Dataset

Function overload documentation:

filter(self: Dataset, func: Callable[[DataItem], bool]) → Dataset

Filters the dataset according to a user defined function. Note: Filtering makes the dataset uncountable, since the func output is conditional.

Parameters:: func (def func(dict) -> bool) – filtering criterion to be applied to each input item. The input must be of the form dict[str, SharedImageSet]

filter(self: Dataset, func_name: str) → Dataset

Filters the dataset according to a user defined function. Note: Filtering makes the dataset uncountable, since the func output is conditional.

Parameters:: func_name (str) – name of a registered filter function specifying a criterion to be applied to each input item. The input must be of the form dict[str, SharedImageSet]

map(self: Dataset, func: Callable[[DataItem], None], num_parallel_calls: int = 1) → Dataset

map(self: Dataset, func_name: str, num_parallel_calls: int = 1) → Dataset

Function overload documentation:

map(self: Dataset, func: Callable[[DataItem], None], num_parallel_calls: int = 1) → Dataset

Applies a mapping to each item of the dataset. Optionally specify the number num_parallel_calls of asynchronous threads which are used for the mapping.

Parameters:

func (def func(dict) -> dict) – function mapping the input items. The input and output must be of the form dict[str, SharedImageSet]
num_parallel_calls (int) – specify the number num_parallel_calls of asynchronous threads which are used for the mapping. Defaults to 1.

map(self: Dataset, func_name: str, num_parallel_calls: int = 1) → Dataset

Applies a mapping to each item of the dataset. Optionally specify the number num_parallel_calls of asynchronous threads which are used for the mapping.

Parameters:

func_name (str) – name of a registered function, mapping the input items. The input and output must be of the form dict[str, SharedImageSet]
num_parallel_calls (int) – specify the number num_parallel_calls of asynchronous threads which are used for the mapping. Defaults to 1.

memory_cache(self: Dataset, make_exclusive_cpu: bool = True, lazy: bool = True, compression: str = 'None', shuffle: bool = False, num_threads: int = 1, shallow_copy: bool = False) → Dataset

Caches the dataset already loaded. Raises a DataLoaderError if the dataset is not countable. Raises a MemoryError if the system runs out of memory.

Parameters:

make_exclusive_cpu (bool) – keep the data exclusively on CPU.
lazy (bool) – if false, the cache is filled upon construction (otherwise as items are requested).
compression (str) – compression strategy. ‘None’ for no compression, ‘LabelsOnly’ to compress only semantic segmentation label maps (using ZSTD), ‘All’ to compress all fields (using ZSTD).
shuffle (bool) – re-shuffle the cache order every epoch.
num_threads (int) – number of threads to use for copying from the cache.
shallow_copy (bool) – if True, returns items from the cache without deep-copying the underlying data. Avoids the copy overhead but is potentially unsafe: any in-place modification of the returned item will corrupt the cache. Only enable this if you are certain the pipeline will not modify the data. Ignored when compression is enabled. Default: False.

prefetch(self: Dataset, prefetch_size: int, sync_to_gl: bool = True) → Dataset

Prefetches items from the underlying loader in a background thread.

Parameters:

prefetch_size (int) – number of items to prefetch.
sync_to_gl (bool) – synchronize the objects to GL memory after being prefetched.

preprocess(self: imfusion.machinelearning.Dataset, preprocessing_pipeline: list[tuple[str, imfusion.Properties, imfusion.machinelearning.Phase]], exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → Dataset

preprocess(self: Dataset, operations: list[Operation]) → Dataset

Function overload documentation:

preprocess(self: imfusion.machinelearning.Dataset, preprocessing_pipeline: list[tuple[str, imfusion.Properties, imfusion.machinelearning.Phase]], exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → Dataset

Adds a generic preprocessing step to the data pipeline. The processing is performed by the underlying sequence of Operation.

Parameters:

preprocessing_pipeline – List of specifications to construct the underlying OperationsSequence. Each specification must be a tuple consisting of the name of the operation, its Phase, and Properties for configuring it.
exec_phase –
Execution phase for the entire preprocessing pipeline. The execution will run only those operations whose phase (specified in the specs) corresponds to the current exec_phase, with the following exceptions:
1. Operations marked with phase == Phase.Always are always run regardless of the exec_phase.
2. If exec_phase == Phase.Always, all operations in the preprocessing pipeline are run regardless of their individual phase.

preprocess(self: Dataset, operations: list[Operation]) → Dataset

Adds a generic preprocessing step to the data pipeline. The processing is performed by the underlying sequence of Operation.

Parameters:: operations – List of operations that will do the actual processing.

randomize(self: Dataset, buffer_size: int, num_item_repetitions: int = 1, seed: int = -1) → Dataset

Applies iterative replacement shuffling to the dataset. Maintains a fixed-size buffer that provides randomized items through iterative replacement. Initially fills the buffer, then continuously returns random items while replacing them with new items from the source. This avoids the batch filling delays of traditional shuffle approaches.

Parameters:

buffer_size (int) – size of the replacement buffer.
num_item_repetitions (int) – number of times a data item is being sampled. Default 1.
seed (int) – seed for the random selection.

read(self: Dataset, reader_type: str, reader_properties: Properties, verbose: bool = False) → Dataset

Constructs a dataset by specifying a reader type as a string.

Parameters:

reader_type – specifies the type of reader that is created implicitly. Options: “filesystem” (MemoryReader needs to be fixed to work with properties)
reader_properties – properties used to configure the reader.
verbose – print debug information when running the data loader. Default: false

reinit(self: Dataset) → None: Reinit the dataset, clearing state surviving reset() (i.e. data caches).

repeat(self: Dataset, num_epoch_repetitions: int, num_item_repetitions: int = 1) → Dataset

Repeats the dataset num_epoch_repetitions times and each individual item num_item_repetitions times.

Parameters:

num_epoch_repetitions (int) – number of times the underlying dataset epoch is repeated. If num_epoch_repetitions == -1, it repeats the dataset infinitely.
num_item_repetitions (int) – number of times each item is repeated. If num_item_repetitions == -1, it repeats the item infinitely.

reset(self: Dataset) → None: Resets the data loader.

sample(self: Dataset, sampling_pipeline: list[tuple[str, Properties]], *, sampler_selection_seed: int = 1) → Dataset

sample(self: Dataset, samplers: list[ImageROISampler], weights: list[float] | None = None, *, sampler_selection_seed: int = 1) → Dataset

sample(self: Dataset, sampler: ImageROISampler) → Dataset

Function overload documentation:

sample(self: Dataset, sampling_pipeline: list[tuple[str, Properties]], *, sampler_selection_seed: int = 1) → Dataset

Adds a ROI sampling step to the data pipeline. During this step the loaded image is reduced to a region of interest (ROI). The strategy for sampling this regions location is determined by the ImageROISamplers, which is randomly chosen from the underlying sampler set each time this step executes.

Parameters:

sampling_set_config – List of tuples of sampler name and corresponding Properties for configuring it.
sampler_selection_seed – Seed for the random generator of the samplers selection

sample(self: Dataset, samplers: list[ImageROISampler], weights: list[float] | None = None, *, sampler_selection_seed: int = 1) → Dataset

Adds a ROI sampling step to the data pipeline. During this step the loaded image is reduced to a region of interest (ROI). The strategy for sampling this regions location is determined by the ImageROISamplers, which is randomly chosen from the underlying sampler set each time this step executes.

Parameters:

samplers – List of sampler to choose from when sampling.
weights – Probability weights for the samplers specifying the relative probability of choosing each sampler.
sampler_selection_seed (unsigned int) – Seed for the random generator of the samplers selection

sample(self: Dataset, sampler: ImageROISampler) → Dataset

Adds a ROI sampling step to the data pipeline. During this step the loaded image is reduced to a region of interest (ROI). The strategy for sampling this regions location is determined by the ImageROISamplers, which is randomly chosen from the underlying sampler set each time this step executes.

Parameters:: sampler – Sampler to choose from when sampling.

set_random_seed(self: Dataset, seed: int) → None: Seeds the data loading pipeline.

shuffle(self: Dataset, shuffle_buffer: int = -1, seed: int = -1) → Dataset

Shuffles the next how_many items of the dataset. Defaults to -1, i.e. shuffles the entire dataset. If how_many is not specified and the dataset is not countable, it throws a DataLoaderError.

Parameters:

shuffle_buffer (int) – number of consecutive items to shuffle. Defaults to all items of the dataset
seed (int) – seed for the random shuffling.

split(self: Dataset, num_items: int = -1) → Dataset

Splits the content of the SharedImagesSets into SIS containing a single image.

Parameters:: num_items – Keep only the first num_items frames. Default is -1, which keeps all frames.

Note

Calling this method will make the dataset uncountable

property size: Returns the length of the dataset or None if the set is uncountable.

property verbose: Flag indicating whether extra information is logged when fetching data items.

class imfusion.machinelearning.DefaultROISampler(self: DefaultROISampler, dimension_divisor: int = 1, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: ImageROISampler

Sampler which simply returns the image and the label map, after padding of a specified dimension divisor: each spatial dimension of the output arrays will be divisible by dimension_divisor.

Parameters:

dimension_divisor – Divisor of dimensions of the output images
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

padding_mode: Padding mode for input images. Default: CLAMP

label_padding_mode: Padding mode for target label maps. Default: CLAMP

class imfusion.machinelearning.DeformationOperation(self: DeformationOperation, num_subdivisions: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), displacements: list[ndarray[numpy.float32[3, 1]]] = [], padding_mode: PaddingMode = PaddingMode.ZERO, adjust_size: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a deformation to the image using a specified control point grid and specified displacements.

Parameters:

num_subdivisions – list specifying the number of subdivisions for each dimension (the number of control points is subdivisions+1). For 2D images, there must be 0 subdivision in the last component. Default: [1, 1, 1]
displacements – list of 3-dim vectors specifying the displacement (mm) for each control point. Should have length equal to the number of control points. Default: []
padding_mode – defines which type of padding is used in [“zero”, “clamp”, “mirror”]. Default: ZERO
adjust_size – configures whether the resulting image should adjust its size to encompass the deformation. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Note: PaddingMode can be automatically converted from a string. This means you can directly pass a string like “zero”, “clamp”, or “mirror” to the padding_mode parameters instead of using the enum values.

class imfusion.machinelearning.DiceMetric(self: DiceMetric, ignore_background: bool = True)

Bases: Metric

Computes the Dice coefficient for segmentation tasks.

The Dice coefficient measures the overlap between predicted and target segmentation masks.

Constructs a DiceMetric.

Parameters:: ignore_background – If True, ignores the background class (label 0) when computing the Dice coefficient. Default: True

compute_dice(self: DiceMetric, prediction: SharedImageSet, target: SharedImageSet) → list[dict[int, float]]

Computes the Dice coefficient for the given prediction and target segmentations.

The Dice coefficient measures overlap between two segmentation masks, with values ranging from 0 (no overlap) to 1 (perfect overlap).

Parameters:

prediction – The predicted segmentation mask
target – The target/ground truth segmentation mask

Returns:

The Dice coefficient value between 0 and 1

Return type:

float

class imfusion.machinelearning.ElementType(*args, **kwargs)

Bases: pybind11_object

Enum specifying the type of data element in a DataItem.

Values:: IMAGE: Image data (stored as SharedImageSet) KEYPOINT: Keypoint data (stored as KeypointSet) BOUNDING_BOX: Bounding box data (stored as BoundingBoxSet) VECTOR: Vector data (stored as SharedImageSet with 1D data) TENSOR: Tensor data (stored as TensorSet) ANY: Any data

Members:

IMAGE : Image data element (2D or 3D images)

KEYPOINT : Keypoint data element (sets of point coordinates)

BOUNDING_BOX : Bounding box data element (rectangular regions)

VECTOR : Vector data element (1D arrays of values)

TENSOR : Tensor data element (arbitrary-dimensional arrays)

ANY : Any data element

Function overload documentation:

__init__(self: ElementType, value: int) → None

__init__(self: ElementType, arg0: str) → None

ANY = <ElementType.ANY: 5>

BOUNDING_BOX = <ElementType.BOUNDING_BOX: 1>

IMAGE = <ElementType.IMAGE: 0>

KEYPOINT = <ElementType.KEYPOINT: 2>

TENSOR = <ElementType.TENSOR: 4>

VECTOR = <ElementType.VECTOR: 3>

property name

property value

class imfusion.machinelearning.Engine(*args, **kwargs)

Bases: pybind11_object

Generic interface for machine learning models serialized by specific frameworks (e.g. PyTorch, ONNX, etc.).

This class is used by the MachineLearningModel to forward the prediction request to the framework that was used to serialize the model.

See imfusion.machinelearning.engines for examples of Python engine implementations.

Function overload documentation:

__init__(self: Engine, name: str) → None

Initialize a custom Engine subclass.

This constructor is used when creating custom engine implementations in Python.

Parameters:: name – Name identifier for the engine type (e.g., ‘torch’, ‘onnx’)

__init__(self: imfusion.machinelearning.Engine, name: str, properties: imfusion.Properties, language: imfusion.machinelearning.EngineLanguage = <EngineLanguage.ANY: 0>) → None

Create an engine for the selected implementation language.

Parameters:

name – Name identifier for the engine type (e.g., ‘torch’, ‘onnx’)
properties – Collection of params for configuring the Engine.
language – Which implementation language to consider when creating the engine. With EngineLanguage.ANY, all registered engine are considered.

Note

For the torch and onnx engines, the C++ implementation have precendence over the python one.: If you want to only allow the python implementation, set the env variable IMFUSION_PLUGIN_BLACKLIST=Torch;OnnxRuntime, to avoid

the C++ engine to be registered.

__call__(self: Engine, input: DataItem) → DataItem: Delegates to: predict()

static available_engines(language: EngineLanguage = EngineLanguage.ANY) → list[str]

List all registered inference engines for a given implementation language.

Params:: language (EngineLanguage): Cpp, Python, or Any for the union of both.

available_providers(self: Engine) → list[ExecutionProvider]: Returns the execution providers available to the Engine

check_input_fields(self: Engine, input: DataItem) → None: Checks that input fields specified in the model yaml config are present in the input item.

check_output_fields(self: Engine, input: DataItem) → None: Checks the output fields specified in the model yaml config are present in the item returned by predict.

configure(self: Engine, properties: Properties) → None: Configures the Engine.

connect_signals(self: Engine) → None: Connects signals like on_model_file_changed, on_force_cpu_changed.

init(self: Engine, properties: Properties) → None: Initializes the Engine.

is_identical(self: Engine, other: Engine) → bool: Compares this engine instance with another one.

static is_registered(engine_name: str, quiet: bool = True, language: EngineLanguage = EngineLanguage.ANY) → bool

Check if an engine is registered for the selected implementation language.

Params:: quiet (bool): If False, Prints a detailed error message in case no engine is found. Defualt: True language (EngineLanguage): Cpp, Python, or Any for the union of both. Default: Any.

load_model_artifact(self: Engine) → bytes

Loads the model artifact specified in property model_file either from the model file or from a resource repository.

Returns:: The model artifact as a bytes object.
Return type:: bytes
Raises:: RuntimeError – If the model artifact could not be loaded.

on_force_cpu_changed(self: Engine) → None: Signal triggered when p_force_cpu changes.

on_model_file_changed(self: Engine) → None: Signal triggered when p_model_file changes.

predict(self: Engine, input: DataItem) → DataItem: Runs the prediction.

provider(self: Engine) → ExecutionProvider | None: Returns the execution provider currently used by the Engine.

property config: Engine configuration object. Modify properties directly (e.g., config.force_cpu = True). Property changes automatically trigger synchronization with deprecated parameters via signals.

property force_cpu: If set, forces the model to run on CPU.

property input_fields: Names of the model input heads.

property model_file: Path to the yaml model configuration.

property name: The name/type of this engine (e.g., ‘onnx’, ‘torch’, ‘openvino’)

property output_fields: Names of the model output heads.

property output_fields_to_ignore: Model output heads to discard.

property version: Version of the model configuration.

class imfusion.machinelearning.EngineConfiguration

Bases: pybind11_object

Configuration settings for a machine learning engine.

This class contains all the configuration parameters needed to set up and run a machine learning inference engine, including model paths, device settings, and input/output field specifications.

configure(self: EngineConfiguration, properties: Properties) → None: Configures the EngineConfiguration.

to_properties(self: EngineConfiguration) → Properties: Converts the EngineConfiguration to a Properties object.

default_input_name = 'Input'

default_output_name = 'Prediction'

property engine_specific_parameters: Parameter that are specific to the type of Engine.

property force_cpu: If set, forces the model to run on CPU.

property input_fields: Names of the model input heads.

property model_file: Path to the yaml model configuration.

property output_fields: Names of the model output heads.

property output_fields_to_ignore: Model output heads to discard.

property type: Type of Engine, i.e. torch, onnx, openvino…

property version: Version of the model configuration.

class imfusion.machinelearning.EngineLanguage(self: EngineLanguage, value: int)

Bases: pybind11_object

Enum for selecting and filtering engines based on the implementation programming language.

Values:: Any: Engines implemented in any language. Cpp: Engines implemented in C++. Python: Engines implemented in Python.

Members:

ANY : Engines implemented in any language.

CPP : Engines implemented in C++.

PYTHON : Engines implemented in Python.

ANY = <EngineLanguage.ANY: 0>

CPP = <EngineLanguage.CPP: 1>

PYTHON = <EngineLanguage.PYTHON: 2>

property name

property value

class imfusion.machinelearning.EnsureExplicitMaskOperation(self: EnsureExplicitMaskOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Converts the existing mask of all input images into explicit masks. If an image does not have a mask, no mask will be created. Warning: This operation might be computationally extensive since it processes every frame of the SharedImageSet independently.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.EnsureOneToOneMatrixMappingOperation(self: EnsureOneToOneMatrixMappingOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Ensures that it is possible to get/set the matrix of each frame of the input image set independently. This operation is targeted at TrackedSharedImageSets, which might define their matrices via a tracking sequence with timestamps (there is then no one-to-one correspondence between matrices and images, but matrices are looked-up and interpolated via their timestamps). In such cases, the operation creates a new tracking sequence with as many samples as images and turns off the timestamp usage.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ExecutionProvider(self: ExecutionProvider, value: int)

Bases: pybind11_object

Enum specifying the execution provider (backend) for running machine learning models.

Different execution providers offer varying levels of performance and hardware acceleration.

Values:: CPU: CPU execution (available on all platforms) CUDA: NVIDIA CUDA GPU execution CUSTOM: Custom execution provider DIRECTML: DirectML GPU execution (Windows) MPS: Apple Metal Performance Shaders (macOS) OPENVINO: Intel OpenVINO execution

Members:

CPU : CPU execution provider - available on all platforms

CUDA : NVIDIA CUDA GPU execution provider

CUSTOM : Custom execution provider

DIRECTML : DirectML GPU execution provider (Windows)

MPS : Apple Metal Performance Shaders execution provider (macOS)

OPENVINO : Intel OpenVINO execution provider

CPU = <ExecutionProvider.CPU: 0>

CUDA = <ExecutionProvider.CUDA: 2>

CUSTOM = <ExecutionProvider.CUSTOM: 1>

DIRECTML = <ExecutionProvider.DIRECTML: 3>

MPS = <ExecutionProvider.MPS: 5>

OPENVINO = <ExecutionProvider.OPENVINO: 4>

property name

property value

class imfusion.machinelearning.ExtractRandomSubsetOperation(self: ExtractRandomSubsetOperation, subset_size: int = 1, keep_order: bool = False, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Extracts a random subset from a SharedImageSet.

Parameters:

subset_size – Size of the extracted subset of images. Default: 1
keep_order – If true the extracted subset will have the same ordering as the input. Default: False
probability – Probability of applying this Operation. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ExtractSubsetOperation(self: ExtractSubsetOperation, subset: list[int] = [0], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Extracts a subset from a SharedImageSet.

Parameters:

subset – Indices of the selected images.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.FillLabelMapHolesOperation(self: FillLabelMapHolesOperation, label_value: int = 1, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Fill any holes in the label map.

Parameters:

label_value – Id of the label that will be affected by the refinement operations.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ForegroundGuidedLabelUpsamplingOperation(self: ForegroundGuidedLabelUpsamplingOperation, apply_to: list[str] = ['highResSigmoid', 'lowResSoftmax'], output_field: str | None = None, remove_fields: bool = True, apply_sigmoid: bool = True, guidance_weight: float = 1.0, boundary_refinement_max_iter: int = 3, boundary_refinement_smooth: float = 1.0, boundary_refinement_add_only: list[int] = [], *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Generates a high-resolution label map by upsampling a multi-class softmax prediction guided by a high-resolution binary segmentation. This operation combines a high-resolution binary segmentation (e.g., from a sigmoid prediction) with a lower-resolution multi-class one-hot encoded segmentation (e.g., from a softmax prediction) to produce a refined high-resolution multi-class label map. The approach is inspired by pan-sharpening techniques used in remote sensing (https://arxiv.org/abs/1504.04531). The multi-class one hot image should contain the background class as the first channel.

Parameters:

apply_to – List of field names for input images, expected order: [“highResSigmoid”, “lowResSoftmax”]
output_field – Name for the output field. If not specified, overwrites first input field
remove_fields – Remove input fields after processing. Default: True
apply_sigmoid – Use sigmoid intensities to guide foreground/background decision. If False, outputs most likely non-background class (if any, otherwise background) from softmax. Default: True
guidance_weight – Weight of sigmoid vs softmax for foreground decision [0-1]. Lower values can reduce false positives. Ignored if apply_sigmoid=False. Default: 1.0
boundary_refinement_max_iter – Maximum iterations for boundary refinement at output resolution. Higher values may be needed for larger resolution differences. Ideal values depend on the data and boundary_refinement_smooth. Default: 3
boundary_refinement_smooth – Smoothing factor for boundary refinement. Larger values remove smaller label patches. Default: 1.0
boundary_refinement_add_only – Optional list of label values to restrict the refinement to additions only. Default: []
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.GammaCorrectionOperation(self: GammaCorrectionOperation, gamma: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a gamma correction which changes the overall contrast (see https://en.wikipedia.org/wiki/Gamma_correction)

Parameters:

gamma – Power applied to the normalized intensities. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.GenerateRandomKeypointsOperation(self: GenerateRandomKeypointsOperation, num_points: int = 1, num_channels: int = 1, sample_from_label: bool = False, output_field_name: str = 'keypoints', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Generate uniformly distributed random keypoints in the image. Optionally the distribution is restricted to label values that are nonzero, otherwise (or if there are no nonzero label values), then the keypoints are sampled from the entire image extent. There is a fixed (but configurable) number of keypoints per channel, and a fixed (but configurable) number of output channels in the output keypoint element.

Parameters:

num_points – Number of points to generate per channel. Default: 1.
num_channels – Number of channels in the output keypoint set. Default: 1.
sample_from_label – Whether or not points should be drawn from the label if possible. Default: False.
output_field_name – Name of the output keypoints field. Default: “keypoints”.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.HighPassOperation(self: HighPassOperation, half_kernel_size: int = 1, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Smooths the input image with a Gaussian kernel with half_kernel_size, then subtracts the smoothed image from the input, resulting in a reduction of low-frequency components.

Parameters:

half_kernel_size – half kernel size in pixels. Corresponding standard deviation is half_kernel_size / 3.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ImageElement(self: ImageElement, image: SharedImageSet)

Bases: SISBasedElement

DataElement for storing and processing image data.

ImageElement wraps a SharedImageSet to represent image inputs or outputs in ML pipelines. It inherits from SISBasedElement and provides access to the underlying image data through the sis property.

Initialize an ImageElement from a SharedImageSet.

Parameters:: image (SharedImageSet) – image to be converted to a ImageElement

static from_torch(tensor: Tensor) → ImageElement

Create an ImageElement from a torch Tensor.

The tensor’s channel dimension should be at index 1 (NCHW or NCDHW format). This is a convenience wrapper around SharedImageSet.from_torch() that automatically wraps the result in an ImageElement.

Parameters:: tensor (Tensor) – Instance of torch.Tensor to convert
Returns:: New ImageElement containing the converted data
Return type:: ImageElement

class imfusion.machinelearning.ImageMathOperation(self: ImageMathOperation, formula: str = '', meta_data_from: str = '', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Computes a specified formula involving images from the input dataitem. Supported operations between images of same shape or an image and a scalar:

Addition/Substraction (+, -)

Multiplication/Division (*, /)

Parenthesis can be used to specify operation priorities. For instance, if the dataitem contains 3 elements: image, additive_noise, multiplicative_noise, one can compute: noisy_image = image * multiplicative_noise + additive_noise and store the output in the dataitem under the “noisy_image” field.

The different images are expected to have the same shape.

The resulting image is of type float and does not have a matrix or spacing. These will be copied from the “metaDataFrom” element.

Parameters:

formula (string) – Formula to be computed. Variables from the dataitem must be referred to by their dataitem field (see example above).
meta_data_from (string) – Optional ImageElement to get the matrix and spacing information from. If not specified or empty, the output won’t have a matrix or spacing information. Default: ‘’
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ImageMattingOperation(self: ImageMattingOperation, img_size: int = 0, kernel_size: int = 101, epsilon: float = 0.009999999776482582, num_iters: int = 1, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Refine edges of label-map based on the intensities of the input image. This can make coarse predictions smoother or may correct wrong predictions on the boundaries. It applies the method from the paper “Guided Image Filtering” by Kaiming He et al.

Parameters:

img_size – target image dimension. No downsampling if 0.
kernel_size – guided filter kernel size.
epsilon – guided filter epsilon.
num_iters – guided filter number of iterations.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ImageROISampler

Bases: Operation

Base class for ROI samplers

static available_cpp_samplers() → list[str]: Returns the list of registered C++ samplers.

compute_roi(self: ImageROISampler, image: SharedImageSet) → RegionOfInterest | None: Compute ROI on the given image.

extract_roi(self: ImageROISampler, image: SharedImageSet, roi: RegionOfInterest | None) → SharedImageSet: Extract ROIs from an image.

property label_padding_mode: The label padding mode property.

property padding_mode: The image padding mode property.

property requires_label: Bool indicating whether ROI must be computed on the label map.

class imfusion.machinelearning.ImagewiseClassificationMetrics(self: ImagewiseClassificationMetrics, num_classes: int = 2)

Bases: Metric

Computes imagewise classification metrics.

This metric evaluates classification performance on entire images rather than individual pixels, computing confusion matrices and overall classification accuracy.

Constructs an ImagewiseClassificationMetrics.

Parameters:: num_classes – Number of classes in the classification task. Default: 2

class Result

Bases: pybind11_object

Results container for imagewise classification metric computations.

property confusion_matrix: Confusion matrix for the classification results

property prediction: Predicted class label

property target: Target/ground truth class label

compute_results(self: ImagewiseClassificationMetrics, prediction: SharedImageSet, target: SharedImageSet) → list[Result]

Computes classification metrics for the given prediction and target.

Parameters:

prediction – The predicted class labels
target – The target/ground truth class labels

Returns:

Object containing the prediction, target, and confusion matrix

Return type:

Results

class imfusion.machinelearning.InterleaveMode(*args, **kwargs)

Bases: pybind11_object

Enum specifying how to interleave data from multiple datasets.

Values:: ALTERNATE: Alternate between datasets in round-robin fashion PROPORTIONAL: Sample from datasets proportionally to their sizes

Members:

ALTERNATE : Alternate between datasets in round-robin fashion

PROPORTIONAL : Sample from datasets proportionally to their relative sizes

Function overload documentation:

__init__(self: InterleaveMode, value: int) → None

__init__(self: InterleaveMode, arg0: str) → None

ALTERNATE = <InterleaveMode.ALTERNATE: 0>

PROPORTIONAL = <InterleaveMode.PROPORTIONAL: 1>

property name

property value

class imfusion.machinelearning.InverseOperation(self: InverseOperation, target_identifier: str = '', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Operation that inverts a specific operation by using the InversionComponent. This operation provides a way to invert a specific operation by its record identifier. It retrieves the inverse operation specifications from the InversionComponent of the processed elements, creates an appropriate inverse operation, and then after successful processing, removes the inversion information. The process works as follows:

The InverseOperation searches for elements with the InversionComponent matching the target identifier

It creates and configures an operation based on these specifications

It applies this inverse operation to the input

After successful processing, it removes the inversion information from all processed elements. This guarantees LIFO order when operations with the same identifier are applied multiple times.

Note: This inverts only operations that explicitly support inversion and that have recorded themselves with the specified record identifier. Inversions may not be be able to fully recover the input image, e.g. inverting a cropping operation yields a padded image, not the original image.

Usage example:
# Apply a padding operation with a specific record identifier
pad_op = PadOperation((10, 10), (10, 10), (0, 0))
props = Properties({"record_identifier": "my padding"})
pad_op.configure(props)
padded_image = pad_op.process(some_input_image)

# Create an inverse operation to undo the padding,
# using the record_identifier as target identifier for inversion.
inv_op = InverseOperation("my padding")
unpadded_image = inv_op.process(padded_image)
Note: The InverseOperation reuses the created inverse operation when possible, only creating a new one when the type changes, and only reconfiguring when the properties change. If element-specific properties are needed, they should be set by the Operation that is to be inverted in process() via data components and used in process() of the InverseOperation.

Args:
target_identifier: The identifier of the operation to invert. Default: “”

device: Specifies whether this Operation should run on CPU or GPU. seed: Specifies seeding for any randomness that might be contained in this operation. error_on_unexpected_behaviour: Specifies whether to throw an exception instead of warning about unexpected behavior. apply_to: Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy) record_identifier: Unused for this operation as it is not invertible

class imfusion.machinelearning.InvertOperation(self: InvertOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Invert the intensities of the image: \(\textnormal{output} = -\textnormal{input}\).

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.InvertibleOperation(self: InvertibleOperation, name: str, processing_policy: ProcessingPolicy, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Base class for operations that support inversion.

Basic Usage:

Inherit from InvertibleOperation
Implement the inverse_specs() method
Implement the DataElement-specific process methods (process_images(), process_points(), process_boxes()) (or override process(DataItem) and call super().process(item))
Use InverseOperation with the same identifier to create and apply the inverse

Implementation Patterns

Pattern 1: Override process_images() (Recommended)

class PyImageIntensityScalingOperation(ml.InvertibleOperation):

    def __init__(self, scale_factor: float = 2.0):
        ml.InvertibleOperation.__init__(self, "PyImageIntensityScalingOperation", ml.Operation.ProcessingPolicy.EVERYTHING)
        self.scale_factor: float = scale_factor

    def process_images(self, images):
        """ Scale the images by the scale_factor """
        return ml.LinearIntensityMappingOperation(factor=self.scale_factor, bias=0.0).process(images)

    def configure(self, properties: Properties) -> bool:
        """
        Configure this Operation. Since the inverse of this operation is itself with inverted parameter,
        this method is used to set up the inverse operation parameters.
        """
        params = properties.asdict()
        if "scale_factor" in params:
            self.scale_factor = params["scale_factor"]
            properties.remove_param("scale_factor")
        return super().configure(properties)

    def inverse_specs(self):
        """ Return specs for this operation with inverse parameters """
        props = Properties({"scale_factor": (1.0 / self.scale_factor) if self.scale_factor != 0 else np.nan})
        return ml.Operation.Specs("PyImageIntensityScalingOperation", props, ml.Phase.ALWAYS)

Pattern 2: Override process(DataItem) (Advanced)

class PyDataItemIntensityScalingOperation(ml.InvertibleOperation):
    def __init__(self, scale_factor: float = 2.0):
        ml.InvertibleOperation.__init__(self, "PyDataItemIntensityScalingOperation", ml.Operation.ProcessingPolicy.EVERYTHING)
        self.scale_factor: float = scale_factor

    def process(self, input: Union[ml.DataItem, imf.SharedImageSet]) -> Optional[imf.SharedImageSet]:
        """ Record this operation for inversion (in this case, before running the actual transformation),
        and apply the actual transformation.

        Due to overloaded process() method, the input can be either a DataItem or a SharedImageSet.
        In the case of a DataItem, the operation is applied inplace.
        """
        # record the operation for inversion:
        ret = super().process(input)
        # apply the actual transformation:
        if isinstance(input, ml.DataItem):
            assert ret is None, f"DataItem is not expected to be returned, but got {ret}"
            ml.LinearIntensityMappingOperation(
                factor=self.scale_factor).process(input)
        elif isinstance(input, imf.SharedImageSet):
            return ml.LinearIntensityMappingOperation(
                factor=self.scale_factor).process(ret)
        else:
            raise ValueError(f"Invalid input type: {type(input)}")

    def process_images(self, sis: imf.SharedImageSet) -> imf.SharedImageSet:
        """ Pass-through method to define the compatible data element.
        The recording and inversion happen in the InvertibleOperation.process() call.
        """
        return sis

    def inverse_specs(self) -> ml.Operation.Specs:
        """ Return specs for an operation that can perform the inverse
        Note: The inverse operation can be any registered operation, not necessarily this class
        """
        props = Properties({"factor": (1.0 / self.scale_factor) if self.scale_factor != 0 else np.nan, "bias": 0.})
        return ml.Operation.Specs("LinearIntensityMapping", props, ml.Phase.ALWAYS)

Complete Workflow Example

# Create forward operation
forward_op = PyImageIntensityScalingOperation(scale_factor=2.0)
forward_op.record_identifier = "scale_2x" # this is required for inversion information to be stored

# Apply forward transformation
forward_op.process(data_item)

# Create and apply inverse operation
inverse_op = ml.InverseOperation("scale_2x") # inversion information is retrieved from the target record_identifier
inverse_op.process(data_item)  # Undoes the scaling

How It Works Internally

When process() is called, InvertibleOperation records operation details in an InversionComponent
The InversionComponent stores the operation name and configuration needed for inversion
InverseOperation uses this recorded information plus your inverse_specs() to create the inverse
The system supports both Python operations inverting themselves and delegating to other operations
If needed, data-specific inversion information may be attached to the DataElement in the forward operation so it can be used by the specified inverse operation

__call__(self: InvertibleOperation, item: DataItem) → None
__call__(self: InvertibleOperation, images: SharedImageSet, in_place: bool = False) → SharedImageSet
__call__(self: InvertibleOperation, points: KeypointSet, in_place: bool = False) → KeypointSet
__call__(self: InvertibleOperation, boxes: BoundingBoxSet, in_place: bool = False) → BoundingBoxSet: Delegates to: process()

configuration(self: InvertibleOperation) → Properties: Returns the current configuration as a Properties object

configure(self: InvertibleOperation, properties: Properties) → bool: Configures the operation with the given properties

process(self: InvertibleOperation, item: DataItem) → None

process(self: InvertibleOperation, images: SharedImageSet, in_place: bool = False) → SharedImageSet

process(self: InvertibleOperation, points: KeypointSet, in_place: bool = False) → KeypointSet

process(self: InvertibleOperation, boxes: BoundingBoxSet, in_place: bool = False) → BoundingBoxSet

Function overload documentation:

process(self: InvertibleOperation, item: DataItem) → None: Execute the operation on the input DataItem in-place, i.e. the input item will be modified.

process(self: InvertibleOperation, images: SharedImageSet, in_place: bool = False) → SharedImageSet

Execute the operation on the input images and returns its output.

Args:: images (SharedImageSet): the input images. in_place (bool): If False, the input is guaranteed to be unchanged and the function will return a new object. If True, the input will be changed and the function will return it. (Default: False).

process(self: InvertibleOperation, points: KeypointSet, in_place: bool = False) → KeypointSet

Execute the operation on the input keypoints. The output will always be a different set of keypoints, i.e. this function never works in-place.

Args:: points (SharedImageSet): the input points. in_place (bool): if True, the input will be changed and the function will return it. If False, the input is guaranteed to be unchanged and the function will return a new object (Default: False).

process(self: InvertibleOperation, boxes: BoundingBoxSet, in_place: bool = False) → BoundingBoxSet

Execute the operation on the input bounding boxes. The output will always be a different set of bounding boxes, i.e. this function never works in-place.

Args:: boxes (SharedImageSet): the input boxes. in_place (bool): If False, the input is guaranteed to be unchanged and the function will return a new object. If True, the input will be changed and the function will return it. (Default: False).

seed_random_engine(self: InvertibleOperation, seed: int) → None: Seeds the random number generator for this operation

property active_fields: Fields in the data item that this operation will process.

property computing_device: The computing device property.

property does_not_modify_input: Returns True if the operation guarantees not to modify the input data

property error_on_unexpected_behaviour: Treat unexpected behaviour warnings as errors.

property name: The name of the operation

property processing_policy: The processing_policy property. Resetting it overrides the default operation behaviour on label.

property record_identifier: Identifier used to record this operation for inversion. Setting this enables inversion if the operation supports it.

property seed: Random seed for operations with randomness

property supports_inversion: Returns whether this operation supports inversion.

class imfusion.machinelearning.KeepLargestComponentOperation(self: KeepLargestComponentOperation, max_number_components: int = 1, min_component_size: int = -1, max_component_size: int = -1, threshold: float = 0.5, multi_class: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Create a label map with the largest components above the specified threshold. The output label map encodes each component with a different label value (1 for the largest, 2 for the second largest, etc.). Input images may be float or integer, output are unsigned 8-bit integer images (i.e. max 255 components). The operation will automatically set the default processing policy based on its input (if the input contains more than than one image, then only the label maps will be processed).

Parameters:

max_number_components – the maximum number of components to keep. Default: 1
min_component_size – the minimum size of a component to keep. Default: -1, i.e. no minimum
max_component_size – the maximum size of a component to keep Default: -1, i.e. no maximum
threshold – the threshold to use for the binarization. Default: 0.5
multi_class – If true, process each class label separately and preserve class indices in the output. Expects integer label map as input (0=background, 1=class1, etc.)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.KeypointSet(*args, **kwargs)

Bases: Data

Class for managing sets of keypoints

The class is meant to be used in parallel with SharedImageSet. For each frame in the set, and for each type of keypoint (i.e. body, pedicles, etc..), there is a list of points indicating an instance of that type in the reference image. In terms of tensor dimensions, this would be represented as [N, C, K], where N is the batch size, C is the number of channels (i.e. types of keypoints), and K is the number of keypoints for the same instance type. Each Keypoint is a vec3 having a further dimension [3].

Note

This class API is experimental and might change soon.

Function overload documentation:

__init__(self: KeypointSet, points: list[list[list[ndarray[numpy.float64[3, 1]]]]]) → None

Initialize a KeypointSet from a nested vector of vec3 points.

Parameters:: points – 4D nested vector [N, C, K, 3] where N=batch size, C=channels (keypoint types), K=keypoints per type, 3=coordinates

__init__(self: KeypointSet, points: list[list[list[list[float]]]]) → None

Initialize a KeypointSet from a nested list of points.

Parameters:: points – 4D nested list [[[[x,y,z]]]] where each innermost list has 3 coordinates

__init__(self: KeypointSet, array: ndarray[numpy.float64]) → None

Initialize a KeypointSet from a numpy array.

Parameters:: array – Numpy array with shape [N, C, K, 3] where N=batch size, C=channels, K=keypoints per channel, 3=coordinates

static load(location: str | PathLike) → KeypointSet | None

Load a KeypointSet from an ImFusion file.

Parameters:: location – input path.

save(self: KeypointSet, location: str | PathLike) → None

Save a KeypointSet as an ImFusion file.

Parameters:: location – output path.

property data: The keypoint data stored as a 4D nested vector [N, C, K, 3] where N=batch size, C=channels, K=number of keypoints per channel, and 3=coordinates (x,y,z)

class imfusion.machinelearning.KeypointsElement(self: KeypointsElement, keypoint_set: KeypointSet)

Bases: DataElement

DataElement for storing and processing keypoint annotations.

KeypointsElement wraps a KeypointSet to represent 3D keypoint annotations in ML pipelines. Keypoints are commonly used for anatomical landmarks, pose estimation, or other spatial point annotations.

Initialize a KeypointsElement.

Parameters:: keypoint_set – In case the argument is a numpy array, the array shape is expected to be [N, C, K, 3], where N is the batch size, C the number of different keypoint types (channel), K the number of instances of the same point type, which are expected to have dimension 3. If the argument is a nested list, the same concept applies also to the size of each level of nesting.

property keypoints: Access to the underlying KeypointSet.

class imfusion.machinelearning.KeypointsFromBlobsOperation(self: KeypointsFromBlobsOperation, keypoints_field_name: str = 'keypoints', keypoint_extraction_mode: int = 0, blob_intensity_cutoff: float = 0.02, min_cluster_distance: float = 10.0, min_cluster_weight: float = 0.1, max_internal_clusters: int = 1000, run_smoothing: bool = False, smoothing_half_kernel: int = 2, run_intensity_based_refinement: bool = False, apply_to: list[str] = [], *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Extracts keypoints from blob image. Takes ImageElement specified in :code:’apply_to’ as input. If :code:’apply_to’ is not specified and there is only one image in the data item, this image will automatically be selected.

Parameters:

keypoints_field_name – Field name of the output keypoints. Default: “keypoints”
keypoint_extraction_mode – Extraction mode: 0: Max, 1: Mean, 2: Local Max. Default: 0
blob_intensity_cutoff – Minimum blob intensity to be considered in analysis. Default: 0.02
min_cluster_distance – In case of local aggregation methods, minimum distance allowed among clusters. Default: 10.0
min_cluster_weight – In case of local aggregation methods, minimum intensity for cluster to be consider independent. Default: 0.1
max_internal_clusters – In case of local aggregation methods, maximum number of internal clusters to be considered; to avoid excessive numbers that stall the algorithm. If there are more, the lower weighted ones are removed first. Default: 1000
run_smoothing – Runs a Gaussian smoothing with 1 pixel standard deviation to improve stability of local maxima. Default: False
smoothing_half_kernel – Runs a Gaussian smoothing with 1 pixel standard deviation to improve stability of local maxima. Default: 2
run_intensity_based_refinement – Runs blob intensity based refinement of clustered keypoints. Default: False
apply_to – Field containing the blob image. If not specified and if there is only one image in the data item, this image will automatically be selected. Default: []
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.LabelROISampler(self: LabelROISampler, roi_size: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), labels_values: list[int] = [], sample_boundaries_only: bool = False, fallback_to_random: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: ImageROISampler

Sampler which samples ROIs from the input image and label map, such that one particular label appears. For each ROI, one of the labels_values will be selected and the sampler will make sure that the ROI includes this label. If the sample_boundaries_only flag is set to true, regions will at least have two different label values. If the constraints are not feasible, the sampler will either extract a random ROI with the target size or return an empty image, based on the flag fallback_to_random. (The actual purpose of returning an empty image is to actually chain this sampler with a FilterDataLoader, so that images without a valid label are just completely skipped).

Parameters:

roi_size – Target size of the ROIs to be extracted as [Width, Height, Slices]
labels_values – List of integers representing the target labels
sample_boundaries_only – Make sure that the ROI contains a boundary (i.e. at least two different label values)
fallback_to_random – Whether to sample a random ROI or return an empty one when the target label values are not found. Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

padding_mode: Padding mode for input images. Default: CLAMP

label_padding_mode: Padding mode for target label maps. Default: CLAMP

class imfusion.machinelearning.LazyModule(name: str)

Bases: object

Wrapper that delays importing a package until its attributes are accessed. We need this to keep the import time of the ìmfusion package reasonable.

Note

This wrapper is fairly basic and does not support assignments to the modules, i.e. no monkey-patching.

Initialize a LazyModule wrapper.

Parameters:: name (str) – Fully qualified name of the module to load lazily (e.g., ‘torch’, ‘onnxruntime’)

class imfusion.machinelearning.LinearIntensityMappingOperation(*args, **kwargs)

Bases: Operation

Apply a linear shift and scale to the image intensities. \(\textnormal{output}_c = \textnormal{factor}_c \cdot \textnormal{input}_c + \textnormal{bias}_c\)

A single-element list broadcasts to all channels. A multi-element list applies per-channel.

Parameters:

factor – Multiplying factor(s) — list of floats. Default: [1.0]
bias – Additive bias(es) — list of floats. Default: [0.0]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Function overload documentation:

__init__(self: LinearIntensityMappingOperation, factor: list[float] = [1.0], bias: list[float] = [0.0], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

__init__(self: LinearIntensityMappingOperation, factor: float = 1.0, bias: float = 0.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

class imfusion.machinelearning.MRIBiasFieldCorrectionOperation(self: MRIBiasFieldCorrectionOperation, iterations: int = 1, config_path: str = 'GENERIC3D', field_smoothing_half_kernel: int = -1, preserve_mean_intensity: bool = True, output_is_field: bool = False, field_dimensions: ndarray[numpy.int32[3, 1]] = array([0, 0, 0], dtype=int32), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Perform bias field correction using an implicitly trained neural network (see MRIBiasFieldCorrectionAlgorithm for more details and the parameters description).

Parameters:

iterations – For values > 1, the field is iteratively refined. Default: 1
config_path – Path of the machine learning model (use “GENERIC3D” or “GENERIC2D” for the default models). Default: “GENERIC3D”
field_smoothing_half_kernel – For values > 0, additional smoothing with a Gaussian kernel. Default: -1
preserve_mean_intensity – Preserve the mean image intensity in the output. Default: True
output_is_field – Produce the field, not the corrected image. Default: False
field_dimensions – Internal field dimensions (zeroes represent the model default dimensions). Default: [0, 0, 0]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.MRIBiasFieldGenerationOperation(self: MRIBiasFieldGenerationOperation, length_scale_mm: float = 100.0, field_amplitude: float = 0.4, center: ndarray[numpy.float64[3, 1]] = array([0.25, 0.25, 0.25]), distance_scaling: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), invert_field: bool = False, output_is_field: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply or generate a multiplicative intensity modulation field. If the output is a field, it is shifted as close to mean 1 as possible while remaining positive everywhere. If the output is not a field, the image intensity is shifted so that the mean intensity of the input image is preserved.

Parameters:

length_scale_mm – Length scale (in mm) of the Gaussian radial basis function. Default: 100.0
field_amplitude – Total field amplitude (centered around one). I.e. 0.4 for a 40% field. Default: 0.4
center – Relative center of the Gaussian with respect to the image axes. Values from [0..1] for locations inside the image. Default: [0.25, 0.25, 0.25]
distance_scaling – Relative scaling of the x, y, z world coordinates for field anisotropy. Default: [1, 1, 1]
invert_field – Invert the final field: field <- 2 - field. Default: False
output_is_field – Produce the field, not the corrupted image. Note, the additive normalization method depends on this. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.MachineLearningModel(self: imfusion.machinelearning.MachineLearningModel, config_path: Union[str, os.PathLike], default_prediction_output: imfusion.machinelearning.PredictionOutput = <PredictionOutput.UNKNOWN: -1>)

Bases: pybind11_object

Class for creating a MachineLearningModel.

Create a MachineLearningModel. If the resource required by the MachineLearningModel could not be acquired, raises a RuntimeError.

Parameters:

config_path – Path to the configuration file used to create ModelConfiguration object owned by the model.
default_prediction_output – Parameter used to specify the prediction output of a model if this is missing from the config file. The prediction output type must be specified either here or in the configuration file under the key PredictionOutput. If it is specified in both places, the one from the config file is used.

__call__(self: MachineLearningModel, input: DataItem) → DataItem
__call__(self: MachineLearningModel, images: SharedImageSet) → SharedImageSet: Delegates to: predict()

engine(self: MachineLearningModel) → Engine: Returns the underlying engine used by the model. This can be useful for setting CPU/GPU mode, querying whether CUDA is available, etc.

predict(self: MachineLearningModel, input: DataItem) → DataItem

predict(self: MachineLearningModel, images: SharedImageSet) → SharedImageSet

Function overload documentation:

predict(self: MachineLearningModel, input: DataItem) → DataItem

Method to execute a generic multiple input/multiple output model The input and output type of a machine learning model is the DataItem, which allows to give and retrieve an heterogeneous map-type container of the data needed and returned by the model.

Parameters:: input (DataItem) – Input data item containing all data to be used for inference

predict(self: MachineLearningModel, images: SharedImageSet) → SharedImageSet

Convenience method to execute a single-input/single-output image-based model.

Parameters:: images (SharedImageSet) – Input image set to be used for inference

property label_names: Dict of the list of label names for each output. Keys are the engine output names if specified, else “Prediction”.

class imfusion.machinelearning.MakeFloatOperation(self: MakeFloatOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Convert the input image to float with original values (internal shifts and scales are baked in).

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.MarkAsTargetOperation(self: MarkAsTargetOperation, apply_to: list[str] = [], *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Mark elements from the input data item as learning “target” which might affect the behaviour of the subsequent operations that rely on ProcessingPolicy or use other custom target-specific logic.

Parameters:

apply_to – fields to mark as targets (will initialize the underlying apply_to parameter)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.MergeAsChannelsOperation(self: MergeAsChannelsOperation, apply_to: list[str] = [], output_field: str = '', remove_fields: bool = True, *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Merge multiple DataElements into a single one along the channel dimension. Only applicable for ImageElements and VectorElements.

Parameters:

apply_to – fields which should be merged.
output_field – name of the resulting field.
remove_fields – remove fields used for merging from the data item. Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.Metric

Bases: pybind11_object

Base class for computing metrics on machine learning predictions.

Metrics are used to evaluate model performance by comparing predictions to ground truth targets.

__call__(self: Metric, item: DataItem) → list[dict[str, ndarray[numpy.float64[m, n]]]]: Delegates to: compute()

compute(self: Metric, item: DataItem) → list[dict[str, ndarray[numpy.float64[m, n]]]]

Computes the metric on a DataItem containing predictions and targets.

Parameters:: item – DataItem containing the prediction and target data
Returns:: Dictionary with metric results
Return type:: dict

configuration(self: Metric) → Properties

Returns the current configuration of the metric.

Returns:: Current configuration properties
Return type:: Properties

configure(self: Metric, properties: Properties) → None

Configures the metric with the given properties.

Parameters:: properties – Configuration properties for the metric

property data_scheme

Returns the required data scheme for this metric.

The data scheme specifies which fields in the DataItem are required for computing the metric.

class imfusion.machinelearning.ModelConfiguration(self: imfusion.machinelearning.ModelConfiguration, config_path: str, default_prediction_output: imfusion.machinelearning.PredictionOutput = <PredictionOutput.UNKNOWN: -1>)

Bases: pybind11_object

Configuration class for MachineLearningModel parameters.

This class parses YAML configuration files and validates their consistency. It supports versioned configurations to maintain API compatibility.

Version Management: - The p_version parameter tracks the configuration format version at the time the model was created. - When changes to the ModelConfiguration class API are made, VERSION_COUNT is incremented. - Older configurations are automatically upgraded to the latest version. - Use the save() function to convert configurations to the latest version.

Create a ModelConfiguration. If the resource required by the ModelConfiguration could not be acquired, raises a RuntimeError. :param config_path: Path to the YAML configuration file used to create ModelConfiguration object. :param default_prediction_output: type of prediction output, can be [Image, Vector, Keypoints, BoundingBoxes, Tensor]. For legacy configuration (Version < 3) this parameter has to be given programmatically.

compare_with(self: ModelConfiguration, other: ModelConfiguration, ignore_version: bool = False) → bool

Compare this configuration with another ModelConfiguration.

This method performs a deep comparison of all configuration parameters between this instance and the provided configuration.

Parameters:

other (ModelConfiguration) – The configuration to compare against.
ignore_version (bool, optional) – If True, version differences are ignored during comparison. Defaults to False.

Returns:

True if the configurations are identical, False otherwise.

Return type:

bool

save(self: ModelConfiguration, config_path: str) → bool: Save the ModelConfiguration to a file. Note: This can be useful for converting an old configuration to the latest version. :param config_path: Path to the configuration file used to save the ModelConfiguration.

VERSION_COUNT = 8

property version: Version of the model configuration.

class imfusion.machinelearning.ModelType(*args, **kwargs)

Bases: pybind11_object

Enum specifying the type of machine learning model.

Values:: RANDOM_FOREST: Random forest model NEURAL_NETWORK: Neural network model

Members:

RANDOM_FOREST : Random forest-based model

NEURAL_NETWORK : Neural network-based model

Function overload documentation:

__init__(self: ModelType, value: int) → None

__init__(self: ModelType, arg0: str) → None

NEURAL_NETWORK = <ModelType.NEURAL_NETWORK: 1>

RANDOM_FOREST = <ModelType.RANDOM_FOREST: 0>

property name

property value

class imfusion.machinelearning.MorphologicalFilterOperation(self: MorphologicalFilterOperation, mode: str = 'dilation', op_size: int = 1, use_l1_distance: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Runs a morphological operation on the input.

Parameters:

mode – name of the operation in [‘dilation’, ‘erosion’, ‘opening’, ‘closing’]
op_size – size of the structuring element
use_l1_distance – flag to use L1 (absolute) or L2 (squared) distance in the local computations
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.NormalizeMADOperation(self: NormalizeMADOperation, selected_channels: list[int] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Normalize the input image based on robust statistics. The image is shifted so that the median corresponds to 0 and normalized with the median absolute deviation (see https://en.wikipedia.org/wiki/Median_absolute_deviation). The operation is performed channel-wise.

Parameters:

selected_channels – channels selected for MAD normalization. If empty, all channels are normalized (default).
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.NormalizeNormalOperation(self: NormalizeNormalOperation, keep_background: bool = False, background_value: float = 0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Normalize the input image so that it has a zero-mean and a unit-standard deviation. A particular intensity value can be set to be ignored during the computations.

Parameters:

keep_background – Should ignore all intensities with background_value. Default: False
background_value – Intensity value to be potentially ignored. Default: 0.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.NormalizePercentileOperation(self: NormalizePercentileOperation, min_percentile: float = 0.0, max_percentile: float = 1.0, clamp_values: bool = False, ignore_zeros: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Normalize the input image based on its intensity distribution, in particular on a lower and upper percentile. The output image is not guaranteed to be in [0;1] but the lower percentile will be mapped to 0 and the upper one to 1.

Parameters:

min_percentile – Lower percentile in [0;1]. Default: 0.0
max_percentile – Lower percentile in [0;1], Default: 1.0
clamp_values – Intensities are clipped to the new range. Default: False
ignore_zeros – Whether to ignore zeros when computing the percentiles. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.NormalizeUniformOperation(self: NormalizeUniformOperation, min: float = 0.0, max: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Normalize the input image based so their minimum/maximum intensity so that the output image has a [min; max] range. The operation is performed channel-wise.

Parameters:

min – New minimum value of the image after normalization. Default: 0.0
max – New maximum value of the image after normalization. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.OneHotOperation(self: OneHotOperation, num_channels: int = 0, encode_background: bool = True, to_ubyte: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Encode a single channel label image, to a one-hot representation of ‘channels’ channels. If encode_background is off, label ‘0’ will denote the background and doesn’t encode to anything, Label ‘1’ will set the value ‘1’ in the first channel, Label ‘2’ will set the value ‘1’ in the second channels, etc. If encode_background is on, label ‘0’ will be the background and set the value ‘1’ in the first channel, Label ‘1’ will set the value ‘1’ in the second channel, etc. The number of channels must be large enough to contain this encoding.

Parameters:

num_channels – Number of channels in the output. Must be equal or larger to the highest possible label value. Default: 0
encode_background – whether to encode background in first channel. Default: True
to_ubyte – return label as ubyte (=int8) instead of float. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.Operation(self: Operation, name: str, processing_policy: ProcessingPolicy = ProcessingPolicy.EVERYTHING_BUT_LABELS, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: pybind11_object

Base class for data preprocessing and augmentation operations in machine learning pipelines.

Operations are used to transform DataItems in a Dataset pipeline. They can process images, keypoints, bounding boxes, vectors, and tensors. Operations can be chained together to create complex preprocessing pipelines.

To create a custom operation in Python, inherit from this class and implement: - configure(): Configure the operation from Properties - configuration(): Return current configuration as Properties - process(): Process a DataItem (or override type-specific methods like process_images)

See also

InvertibleOperation: For operations that support inversion Dataset: For using operations in data pipelines

Initialize a custom Operation subclass.

This constructor is used when creating custom operation classes in Python.

Parameters:

name – Name identifier for the operation
processing_policy – Policy determining which fields to process (default: EverythingExceptLabels)
device – Computing device (CPU/GPU) for the operation
apply_to – List of field names to process (if empty, uses processing_policy)
seed – Random seed for reproducible behavior
error_on_unexpected_behaviour – If True, raise exceptions instead of warnings

class ProcessingPolicy(*args, **kwargs)

Bases: pybind11_object

Enum specifying which types of data an operation should process.

This controls whether operations process regular data, label/segmentation data, or both.

Values:: EVERYTHING_BUT_LABELS: Process all data except labels/segmentation masks EVERYTHING: Process all data including labels ONLY_LABELS: Process only labels/segmentation masks

Members:

EVERYTHING_BUT_LABELS : Process all data except labels and segmentation masks

EVERYTHING : Process all data including both regular data and labels

ONLY_LABELS : Process only labels and segmentation masks, skip regular data

Function overload documentation:

__init__(self: ProcessingPolicy, value: int) → None

__init__(self: ProcessingPolicy, arg0: str) → None

EVERYTHING = <ProcessingPolicy.EVERYTHING: 1>

EVERYTHING_BUT_LABELS = <ProcessingPolicy.EVERYTHING_BUT_LABELS: 0>

ONLY_LABELS = <ProcessingPolicy.ONLY_LABELS: 2>

property name

property value

class Specs(*args, **kwargs)

Bases: pybind11_object

Specification for constructing and configuring an Operation.

This class contains the necessary information to create an operation instance, including its name, configuration properties, and execution phase.

Function overload documentation:

__init__(self: Specs) → None

Initialize an empty Operation::Specs object.

Creates a specification with default values that can be filled in later.

__init__(self: Specs, name: str, configuration: Properties, when_to_apply: Phase) → None

Initialize an Operation::Specs with full configuration.

Parameters:

name – Name of the operation to instantiate
configuration – Properties object containing operation configuration
when_to_apply – Phase during which the operation should be executed

property name: Name of the operation to instantiate

property prop: Configuration properties for the operation

property when_to_apply: Phase during which this operation should be executed (Training/Validation/Inference/Always)

__call__(self: Operation, item: DataItem) → None
__call__(self: Operation, images: SharedImageSet, in_place: bool = False) → SharedImageSet
__call__(self: Operation, points: KeypointSet, in_place: bool = False) → KeypointSet
__call__(self: Operation, boxes: BoundingBoxSet, in_place: bool = False) → BoundingBoxSet: Delegates to: process()

configuration(self: Operation) → Properties: Returns the current configuration as a Properties object

configure(self: Operation, properties: Properties) → bool: Configures the operation with the given properties

process(self: Operation, item: DataItem) → None

process(self: Operation, images: SharedImageSet, in_place: bool = False) → SharedImageSet

process(self: Operation, points: KeypointSet, in_place: bool = False) → KeypointSet

process(self: Operation, boxes: BoundingBoxSet, in_place: bool = False) → BoundingBoxSet

Function overload documentation:

process(self: Operation, item: DataItem) → None: Execute the operation on the input DataItem in-place, i.e. the input item will be modified.

process(self: Operation, images: SharedImageSet, in_place: bool = False) → SharedImageSet

Execute the operation on the input images and returns its output.

Args:: images (SharedImageSet): the input images. in_place (bool): If False, the input is guaranteed to be unchanged and the function will return a new object. If True, the input will be changed and the function will return it. (Default: False).

process(self: Operation, points: KeypointSet, in_place: bool = False) → KeypointSet

Execute the operation on the input keypoints. The output will always be a different set of keypoints, i.e. this function never works in-place.

Args:: points (SharedImageSet): the input points. in_place (bool): if True, the input will be changed and the function will return it. If False, the input is guaranteed to be unchanged and the function will return a new object (Default: False).

process(self: Operation, boxes: BoundingBoxSet, in_place: bool = False) → BoundingBoxSet

Execute the operation on the input bounding boxes. The output will always be a different set of bounding boxes, i.e. this function never works in-place.

Args:: boxes (SharedImageSet): the input boxes. in_place (bool): If False, the input is guaranteed to be unchanged and the function will return a new object. If True, the input will be changed and the function will return it. (Default: False).

seed_random_engine(self: Operation, seed: int) → None: Seeds the random number generator for this operation

EVERYTHING = <ProcessingPolicy.EVERYTHING: 1>

EVERYTHING_BUT_LABELS = <ProcessingPolicy.EVERYTHING_BUT_LABELS: 0>

ONLY_LABELS = <ProcessingPolicy.ONLY_LABELS: 2>

property active_fields: Fields in the data item that this operation will process.

property computing_device: The computing device property.

property does_not_modify_input: Returns True if the operation guarantees not to modify the input data

property error_on_unexpected_behaviour: Treat unexpected behaviour warnings as errors.

property name: The name of the operation

property processing_policy: The processing_policy property. Resetting it overrides the default operation behaviour on label.

property record_identifier: Identifier used to record this operation for inversion. Setting this enables inversion if the operation supports it.

property seed: Random seed for operations with randomness

property supports_inversion: Returns whether this operation supports inversion.

class imfusion.machinelearning.OperationsSequence(*args, **kwargs)

Bases: pybind11_object

Helper class that executes a list of operations sequentially. This class tries to minimize the number of intermediate copies and should be used for performance reasons.

Function overload documentation:

__init__(self: OperationsSequence) → None: Default constructor that initializes the class with an empty list of operations.

__init__(self: OperationsSequence, pipeline_config: list[tuple[str, Properties, Phase]]) → None

Init the sequential processing with a pipeline of Operations and their relative specs. The operations are executed according to their pipeline order.

Parameters:: pipeline_config – List of specs for the operations to add to the sequence.

__init__(self: OperationsSequence, operations: list[Operation], phases: list[Phase] = []) → None

Init the sequential processing with a pipeline of Operations and their relative specs. The operations are executed according to their pipeline order.

Parameters:

operations – List of operations to be added.
phases – Execution phase of each operation.

__call__(self: imfusion.machinelearning.OperationsSequence, input: imfusion.SharedImageSet, exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>, in_place: bool = True) → SharedImageSet
__call__(self: imfusion.machinelearning.OperationsSequence, input: imfusion.machinelearning.DataItem, exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → bool: Delegates to: process()

add_operation(self: imfusion.machinelearning.OperationsSequence, operation: imfusion.machinelearning.Operation, phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → bool

add_operation(self: imfusion.machinelearning.OperationsSequence, name: str, properties: imfusion.Properties, phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → None

Function overload documentation:

add_operation(self: imfusion.machinelearning.OperationsSequence, operation: imfusion.machinelearning.Operation, phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → bool

Add an operation to the sequential processing. The operations are executed according to the addition order.

Parameters:

operation – operation instance to add to the sequence.
phase – when to execute the added operation. Default: Phase.Always

add_operation(self: imfusion.machinelearning.OperationsSequence, name: str, properties: imfusion.Properties, phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → None

Add an operation to the sequential processing. The operations are executed according to the addition order.

Parameters:

name – name of the operation to add to the sequence. You must use the name used for registering the op in the operation factory. A list of the available ops can be retrieved by available_operations())().
properties – properties to configure the operation.
phase – specifies at which execution phase should the operation be run.

static available_cpp_operations() → list[str]: Returns the list of registered C++ operations available for usage in OperationsSequence.

static available_operations() → list[str]: Returns the list of all registered operations available for usage in OperationsSequence.

static available_py_operations() → list[str]: Returns the list of registered Python operations available for usage in OperationsSequence.

ok(self: OperationsSequence) → bool: Returns whether operation setup was successful.

operation_names(self: OperationsSequence) → list[str]: Returns the operation names added to the sequence.

process(self: imfusion.machinelearning.OperationsSequence, input: imfusion.SharedImageSet, exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>, in_place: bool = True) → SharedImageSet

process(self: imfusion.machinelearning.OperationsSequence, input: imfusion.machinelearning.DataItem, exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → bool

Function overload documentation:

process(self: imfusion.machinelearning.OperationsSequence, input: imfusion.SharedImageSet, exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>, in_place: bool = True) → SharedImageSet

Execute the preprocessing pipeline on the given input images. This function never works in-place.

Parameters:

input – input image
exec_phase –
specifies the execution phase of the preprocessing pipeline. The execution will run only those operations whose phase (specified in the specs) corresponds to the current exec_phase, with the following exceptions:
1. Operations marked with phase == Phase.Always are always run regardless of the exec_phase.
2. If exec_phase == Phase.Always, all operations in the preprocessing pipeline are run regardless of their individual phase.

in_place (bool): If False, the input is guaranteed to be unchanged and the function will return a new object. If True, the input will be changed and the function will return it. (Default: False).

process(self: imfusion.machinelearning.OperationsSequence, input: imfusion.machinelearning.DataItem, exec_phase: imfusion.machinelearning.Phase = <Phase.ALWAYS: 7>) → bool

Execute the preprocessing pipeline on the given input. This function always works in-place, i.e. the input DataItem will be modified.

Parameters:

input – DataItem to be processed
exec_phase –
specifies the execution phase of the preprocessing pipeline. The execution will run only those operations whose phase (specified in the specs) corresponds to the current exec_phase, with the following exceptions:
1. Operations marked with phase == Phase.Always are always run regardless of the exec_phase.
2. If exec_phase == Phase.Always, all operations in the preprocessing pipeline are run regardless of their individual phase.

set_error_on_unexpected_behaviour(self: OperationsSequence, value: bool) → None

Set flag on all operations to control error behavior for unexpected situations.

When enabled, operations will throw exceptions instead of issuing warnings when encountering unexpected behavior (e.g., applying augmentation to labels).

Parameters:: value – If True, throw exceptions on unexpected behavior; if False, issue warnings

property operations: List of all operations in this sequence with their execution phases

class imfusion.machinelearning.OrientedROISampler(self: OrientedROISampler, roi_size: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), roi_spacing: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), num_samples: int = 1, random_rotation_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), random_flipping_probability: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), random_shearing_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), random_scaling_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), random_jitter_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), sample_from_labels_proportion: float = 0.0, avoid_borders: bool = False, align_crop: bool = False, centers: list[ndarray[numpy.float64[3, 1]]] | None = None, random_scaling_logarithmic: bool = False, random_rotation_probability: float = 1.0, random_shearing_probability: float = 1.0, random_scaling_probability: float = 1.0, y_axis_down: bool = False, squeeze: bool = False, random_rotation_distribution: Distribution = Distribution.NORMAL, random_shearing_distribution: Distribution = Distribution.NORMAL, random_jitter_distribution: Distribution = Distribution.NORMAL, equalize_label_classes: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: ImageROISampler

The OrientedROISampler draws num_samples ROIs of size roi_size with spacing roi_spacing per dataset. sample_from_labels_proportion controls the expected fraction of ROI centers drawn from the target instead of uniformly from the full image; the actual number of target-guided samples is binomially distributed around that proportion. Label maps and Keypoints are supported for target-guided sampling. For targets with LABEL, ROI centers are drawn with class-agnostic foreground sampling by default: every non-zero voxel has equal probability regardless of label value, so larger structures dominate the draw. Setting equalize_label_classes to True switches to class-balanced sampling: a present label value is first picked uniformly at random and then a voxel of that class is picked uniformly at random, so small and large structures are centered with equal probability. For target images of any other modality, target values act as relative heatmap weights: zero-valued voxels are never selected, larger values are sampled more often, values do not need to sum to 1, and negative values are not supported. For Keypoint targets, a random keypoint is selected as the ROI center. If no valid target voxels are present, target-guided slots fall back to uniform random sampling. Random augmentations can applied, including rotation, flipping, shearing, scaling and jitter. These augmentations are directly changing the matrix of the sample, thus the samples are not guaranteed to be affine or even in a right-handed coordinate system. The samples retain their matrices, so they can be viewed in their original position. May throw an ImageSamplerError

Parameters:

roi_size – Target size of the ROIs to be extracted as [Width, Height, Slices]
roi_spacing – Target spacing of the ROIs to be extracted in mm
num_samples – Number of samples to draw from one image. Default: 1
random_rotation_range – Per-axis rotation magnitude. For normal distribution: standard deviation in degrees sampled as N(0, range). For uniform distribution: half-range in degrees, sampled uniformly in [-range, +range]. Default: [0, 0, 0]
random_flipping_probability – Vector defining the chance that the corresponding dimension gets flipped. Default: [0, 0, 0]
random_shearing_range – Per-axis shearing magnitude. For normal distribution: standard deviation, sampled as N(0, range). For uniform distribution: half-range, sampled uniformly in [-range, +range]. Default: [0, 0, 0]
random_scaling_range – Vector defining the range of scaling in each dimension. Default: [0, 0, 0]
random_jitter_range – Per-axis jitter added to label-guided sample centers. For normal distribution: standard deviation in mm, sampled as N(0, range). For uniform distribution: half-range in mm, sampled uniformly in [-range, +range]. Default: [0, 0, 0]
sample_from_labels_proportion – Fraction of ROI centers sampled from the target instead of uniformly from the full image. The actual number of target-guided samples is drawn from a binomial distribution. For LABEL targets, the sampling strategy depends on equalize_label_classes: by default centers are sampled uniformly from all non-zero voxels (so larger structures dominate); when equalize_label_classes is True, centers are drawn with class-balanced sampling instead. For other target image modalities, centers are sampled proportionally to target intensity. If no valid target voxels are present, target-guided slots fall back to uniform random sampling. Default: 0.0.
equalize_label_classes – Switch to class-balanced sampling for target-guided centers from a LABEL target. When enabled, a present label value is first picked uniformly at random and then a voxel of that class uniformly at random, so small and large structures are centered with equal probability. The default (class-agnostic foreground sampling, used by sample_from_labels_proportion alone) treats every non-zero voxel equally and lets the largest structures dominate. Has no effect for non-LABEL targets or keypoint targets. Default: False.
avoid_borders – When taking random samples, the samples avoid to see the border if this is turned on. Default: false
align_crop – Align crop to image grid system, before applying augmentations. Default: false
centers – Optional list of centers to sample from. Default: []
random_scaling_logarithmic – Sample the scaling from a distribution that yields uniform scaling factors in 1/x … x with \(x = 1 + \textnormal{random_scaling_range}\) instead of using scalings from \(\max(|1.0 + \mathcal{N}(0, \text{randomScalingRange})|, 0.001)\). Default: False
random_rotation_probability – Probability to apply a random rotation (parametrized by random_rotation_range). Default: 1.f
random_shearing_probability – Probability to apply a random shearing (parametrized by random_shearing_range). Default: 1.f
random_scaling_probability – Probability to apply a random scaling (parametrized by random_scaling_range). Default: 1.f
y_axis_down – Force y-axis direction to point down in world-coordinates, should only be used for certain legacy pipelines. Default: False
squeeze – Squeeze crops to a 2D representation which has their unary dimension in the ‘slices’ dimension; requires that one of the dimensions in roi_size is 1.
random_rotation_distribution – Sampling distribution for random_rotation_range in [“normal”, “uniform”]. Default: “normal”
random_shearing_distribution – Sampling distribution for random_shearing_range in [“normal”, “uniform”]. Default: “normal”
random_jitter_distribution – Sampling distribution for random_jitter_range in [“normal”, “uniform”]. Default: “normal”
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

padding_mode: Padding mode for input images. Default: ZERO

label_padding_mode: Padding mode for target label maps. Default: ZERO

class Distribution(*args, **kwargs)

Bases: pybind11_object

Members:

NORMAL

UNIFORM

Function overload documentation:

__init__(self: Distribution, value: int) → None

__init__(self: Distribution, arg0: str) → None

NORMAL = <Distribution.NORMAL: 0>

UNIFORM = <Distribution.UNIFORM: 1>

property name

property value

class imfusion.machinelearning.PadDimsOperation(self: PadDimsOperation, target_dims: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), padding_mode: PaddingMode = PaddingMode.MIRROR, padding_value: float | None = None, label_padding_mode: PaddingMode | None = None, label_padding_value: int | None = None, allow_dimension_change: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: InvertibleOperation

This operation expands an image by adding padding pixels to any or all sides. The value of the border can be specified by the padding mode:

Clamp: The border pixels are the same as the closest image pixel.

Mirror: The border pixels are the same as the closest image pixel.

Zero: Constant padding with zeros or, if provided, with paddingValue.

For label maps (i.e. modality == Modality.LABEL), a separate padding mode and value can be specified:

If both label padding mode and label padding value are specified, those values are used to pad the label map.

If only the label padding mode is specified, the paddingValue is used to fill the label map (only for zero padding).

If only the label padding value is specified, the paddingMode is used as the label padding mode.

If neither label padding mode nor label padding value are specified, paddingMode and paddingValue are used for label maps as well.

Note: the padding widths are evenly distributed to the left and right of the input image.: If the difference delta between the target dimensions and the input dimensions is odd, the padding is distributed as delta / 2 to the left and delta / 2 + 1 to the right.

Note: PaddingMode can be automatically converted from a string. This means you can directly pass a string like “zero”, “clamp”, or “mirror” to the padding_mode parameters instead of using the enum values.

Parameters:

target_dims – Target dimensions [width, height, depth] for the padded image. Default: [1, 1, 1]
padding_mode – Mode for padding in [“zero”, “clamp”, “mirror”]. Default: MIRROR
padding_value – Value to use for padding when using Zero mode (optional). Default: None
label_padding_mode – Mode for padding label maps in [“zero”, “clamp”, “mirror”], optional. Default: None
label_padding_value – Value to use for padding label maps when using Zero mode (optional). Default: None
allow_dimension_change – Allow padding dimensions equal to 1, which can change image dimension (e.g. 2D to 3D). Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Identifier of this operation to retrieve inversion parameters from the record

class imfusion.machinelearning.PadDimsToNextMultipleOperation(self: PadDimsToNextMultipleOperation, dimension_divisor: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), padding_mode: PaddingMode = PaddingMode.MIRROR, padding_value: float | None = None, label_padding_mode: PaddingMode | None = None, label_padding_value: int | None = None, allow_dimension_change: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: InvertibleOperation

Pads each dimension of the input image to the next multiple of the specified divisor. For example, if an image has dimensions (100, 150, 200) and dimension_divisor is (32, 16, 64), the output will have dimensions (128, 160, 256). This operation is useful for ensuring that the input dimensions are compatible with a ML model (e.g. a CNN or UNet) that expects specific dimensions. The value of the border can be specified by the padding mode:

Clamp: The border pixels are the same as the closest image pixel.

Mirror: The border pixels are the same as the closest image pixel.

Zero: Constant padding with zeros or, if provided, with paddingValue.

For label maps (i.e. modality == Modality.LABEL), a separate padding mode and value can be specified:

If both label padding mode and label padding value are specified, those values are used to pad the label map.

If only the label padding mode is specified, the paddingValue is used to fill the label map (only for zero padding).

If only the label padding value is specified, the paddingMode is used as the label padding mode.

If neither label padding mode nor label padding value are specified, paddingMode and paddingValue are used for label maps as well.

Note: the padding widths are evenly distributed to the left and right of the input image.: If the difference delta between the target dimensions and the input dimensions is odd, the padding is distributed as delta / 2 to the left and delta / 2 + 1 to the right.

Note: PaddingMode can be automatically converted from a string. This means you can directly pass a string like “zero”, “clamp”, or “mirror” to the padding_mode parameters instead of using the enum values.

Parameters:

dimension_divisor – The divisor for each dimension of the input image. Default: [1, 1, 1]
padding_mode – Mode for padding in [“zero”, “clamp”, “mirror”]. Default: MIRROR
padding_value – Value to use for padding when using Zero mode (optional). Default: None
label_padding_mode – Mode for padding label maps in [“zero”, “clamp”, “mirror”], optional. Default: None
label_padding_value – Value to use for padding label maps when using “zero” mode (optional). Default: None
allow_dimension_change – Allow padding dimensions equal to 1, which can change image dimension (e.g. 2D to 3D). Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Identifier of this operation to retrieve inversion parameters from the record

class imfusion.machinelearning.PadOperation(self: PadOperation, pad_size_x: ndarray[numpy.int32[2, 1]] = array([0, 0], dtype=int32), pad_size_y: ndarray[numpy.int32[2, 1]] = array([0, 0], dtype=int32), pad_size_z: ndarray[numpy.int32[2, 1]] = array([0, 0], dtype=int32), padding_mode: PaddingMode = PaddingMode.MIRROR, padding_value: float | None = None, label_padding_mode: PaddingMode | None = None, label_padding_value: int | None = None, allow_dimension_change: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: InvertibleOperation

Pad an image to a specific padding size in each dimension. This operation expands an image by adding padding pixels to any or all sides. The value of the border can be specified by the padding mode:

Clamp: The border pixels are the same as the closest image pixel.

Mirror: The border pixels are the same as the closest image pixel.

Zero: Constant padding with zeros or, if provided, with paddingValue.

For label maps (i.e. modality == Modality.LABEL), a separate padding mode and value can be specified:

If both label padding mode and label padding value are specified, those values are used to pad the label map.

If only the label padding mode is specified, the paddingValue is used to fill the label map (only for zero padding).

If only the label padding value is specified, the paddingMode is used as the label padding mode.

If neither label padding mode nor label padding value are specified, paddingMode and paddingValue are used for label maps as well.

Note: Padding sizes are specified in pixels, and can be positive, negative or mixed. Negative padding means cropping.

Note: Both GPU and CPU implementations are provided.

Note: PaddingMode can be automatically converted from a string. This means you can directly pass a string like “zero”, “clamp”, or “mirror” to the padding_mode parameters instead of using the enum values.

Parameters:

pad_size_x – Padding width in pixels for X dimension [left, right]. Default: [0, 0]
pad_size_y – Padding width in pixels for Y dimension [top, bottom]. Default: [0, 0]
pad_size_z – Padding width in pixels for Z dimension [front, back]. Default: [0, 0]
padding_mode – Mode for padding in [“zero”, “clamp”, “mirror”]. Default: MIRROR
padding_value – Optional value to use for padding when using Zero mode. Default: None
label_padding_mode – Optional mode for padding label maps in [“zero”, “clamp”, “mirror”]. Default: None
label_padding_value – Optional value to use for padding label maps when using “zero” mode. Default: None
allow_dimension_change – Allow padding dimensions equal to 1, which can change image dimension (e.g. 2D to 3D). Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Identifier of this operation to retrieve inversion parameters from the record

class imfusion.machinelearning.ParamUnit(*args, **kwargs)

Bases: pybind11_object

Enum specifying the unit of measurement for operation parameters.

Values:: MM: Millimeters (physical world coordinates) FRACTION: Fraction of image size (0.0 to 1.0) VOXEL: Voxel units (image pixels/voxels)

Members:

MM : Millimeters - physical world coordinates

FRACTION : Fraction of image size (values between 0.0 and 1.0)

VOXEL : Voxel/pixel units in image space

Function overload documentation:

__init__(self: ParamUnit, value: int) → None

__init__(self: ParamUnit, arg0: str) → None

FRACTION = FRACTION

MM = MM

VOXEL = VOXEL

property name

property value

class imfusion.machinelearning.Phase(*args, **kwargs)

Bases: pybind11_object

Enum specifying the execution phase for machine learning operations.

This enum is used to control when operations in a data processing pipeline should be executed. It supports bitwise arithmetic to combine multiple phases.

Values:: TRAINING: Execute only during training phase VALIDATION: Execute only during validation phase INFERENCE: Execute only during inference/prediction phase ALWAYS: Execute in all phases

Example

>>> phase = ml.Phase.TRAINING | ml.Phase.VALIDATION  # Combine phases
>>> ml.Phase.TRAINING in phase  # Check if phase contains TRAINING
True

Members:

TRAINING : Execute only during the training phase

VALIDATION : Execute only during the validation phase

INFERENCE : Execute only during inference/prediction

ALWAYS : Execute in all phases (training, validation, and inference)

Function overload documentation:

__init__(self: Phase, value: int) → None

__init__(self: Phase, arg0: str) → None

__init__(self: Phase, arg0: list[str]) → None

ALWAYS = <Phase.ALWAYS: 7>

INFERENCE = <Phase.INFERENCE: 4>

TRAINING = <Phase.TRAINING: 1>

VALIDATION = <Phase.VALIDATION: 2>

property name

property value

class imfusion.machinelearning.PixelwiseClassificationMetrics(self: PixelwiseClassificationMetrics)

Bases: Metric

Computes pixelwise classification metrics for segmentation tasks.

This metric computes precision, recall, F1-score, and accuracy for each class in a segmentation task.

Constructs a PixelwiseClassificationMetrics object.

compute_per_label(self: PixelwiseClassificationMetrics, prediction: SharedImageSet, target: SharedImageSet) → list[dict[str, dict[int, float]]]

Computes classification metrics separately for each label/class.

This method calculates precision, recall, F1-score, and accuracy for each class in the segmentation task, providing detailed per-class performance metrics.

Parameters:

prediction – The predicted segmentation mask
target – The target/ground truth segmentation mask

Returns:

Dictionary with metrics (precision, recall, F1, accuracy) per label

Return type:

dict

class imfusion.machinelearning.PolyCropOperation(self: PolyCropOperation, points: list[ndarray[numpy.float64[3, 1]]] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Masks the image with a convex polygon as described in Markova et al. 2022. (https://arxiv.org/abs/2205.03439)

Parameters:

points – Each point (texture coordinates) in points defines a plane (perpendicular to the direction from the center to the point), this plane splits the volume in two parts, the part of the image that doesn’t contain the image center is discarded.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.PredictionOutput(*args, **kwargs)

Bases: pybind11_object

Enum specifying the output format of a machine learning model prediction.

Values:: UNKNOWN: Unknown output format VECTOR: Output is a vector (1D array of values) IMAGE: Output is an image (e.g., segmentation mask, reconstructed image) KEYPOINTS: Output is a set of keypoints (e.g., landmark coordinates) BOUNDING_BOXES: Output is a set of bounding boxes (e.g., object detection results)

Members:

UNKNOWN : Unknown or unspecified output format

VECTOR : Output is a 1D vector of values

IMAGE : Output is an image (e.g., segmentation mask)

KEYPOINTS : Output is a set of keypoint coordinates

BOUNDING_BOXES : Output is a set of bounding boxes with coordinates

Function overload documentation:

__init__(self: PredictionOutput, value: int) → None

__init__(self: PredictionOutput, arg0: str) → None

BOUNDING_BOXES = <PredictionOutput.BOUNDING_BOXES: 3>

IMAGE = <PredictionOutput.IMAGE: 1>

KEYPOINTS = <PredictionOutput.KEYPOINTS: 2>

UNKNOWN = <PredictionOutput.UNKNOWN: -1>

VECTOR = <PredictionOutput.VECTOR: 0>

property name

property value

class imfusion.machinelearning.PredictionType(*args, **kwargs)

Bases: pybind11_object

Enum specifying the type of prediction task.

Values:: UNKNOWN: Unknown prediction type CLASSIFICATION: Classification task (assigning discrete class labels) REGRESSION: Regression task (predicting continuous values) OBJECT_DETECTION: Object detection task (locating and classifying objects)

Members:

UNKNOWN : Unknown or unspecified prediction type

CLASSIFICATION : Classification task - assigning discrete class labels

REGRESSION : Regression task - predicting continuous values

OBJECT_DETECTION : Object detection task - locating and classifying objects in images

Function overload documentation:

__init__(self: PredictionType, value: int) → None

__init__(self: PredictionType, arg0: str) → None

CLASSIFICATION = <PredictionType.CLASSIFICATION: 0>

OBJECT_DETECTION = <PredictionType.OBJECT_DETECTION: 2>

REGRESSION = <PredictionType.REGRESSION: 1>

UNKNOWN = <PredictionType.UNKNOWN: -1>

property name

property value

class imfusion.machinelearning.ProcessingRecordComponent(self: ProcessingRecordComponent)

Bases: DataComponentBase

Component that stores a record of processing operations applied to data.

This component tracks the sequence of invertible operations that have been applied to a DataElement, enabling inversion of transformations when needed.

Initialize a ProcessingRecordComponent.

Creates a component that tracks processing operations applied to a DataElement.

class imfusion.machinelearning.RandomAddDegradedLabelAsChannelOperation(self: RandomAddDegradedLabelAsChannelOperation, blob_radius: float = 5.0, probability_no_blobs: float = 0.1, probability_invert: float = 0.0, mean_num_blobs: float = 100.0, only_positive: bool = False, dilation_range: ndarray[numpy.float64[2, 1]] = array([0., 0.]), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Append a channel to the image that contains a randomly degraded version of the label.

Parameters:

blob_radius – Radius of each blob, in pixel coordinates. Default: 5.0.
probability_no_blobs – Probability that zero blobs are chosen. Default: 0.1
probability_invert – Probability of inverting the blobs, in this case the extra channel is positive/negative based on the label except at blobs, where it is zero. Default: 0.0
mean_num_blobs – Mean of (Poisson-distributed) number of blobs to draw, conditional on probability_no_blobs. Default: 100.0
only_positive – If true, output channel is clamped to zero from below. Default: False
label_dilation_range – The label_dilation parameter of the underlying AddDegradedLabelAsChannelOperation is uniformly drawn from this range. Default: [0.0, 0.0]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomAddRandomNoiseOperation(self: RandomAddRandomNoiseOperation, type: str = 'uniform', intensity_range: ndarray[numpy.float64[2, 1]] = array([0., 0.]), probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply AddRandomNoiseOperation to images with randomized intensity parameter.

Parameters:

type – Distribution of the noise (‘uniform’, ‘gaussian’, ‘gamma’,’shot’). Default: ‘uniform’. See AddRandomNoiseOperation. intensity_range: Range of the interval used to draw the intensity parameter. Default: [0.0, 0.0]. Absolute values of drawn values are taken.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible
probability – Float in [0, 1] defining the probability for the operation to be executed. Default: 1.0

class imfusion.machinelearning.RandomAxisFlipOperation(self: RandomAxisFlipOperation, axes: list[str] = [], probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Flip image content along specified set of axes, with independent sampling for each axis.

Parameters:

axes – List of strings from {‘x’,’y’,’z’} specifying the axes to flip. For 2D images, only ‘x’ and ‘y’ are valid.
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomAxisRotationOperation(self: RandomAxisRotationOperation, axes: list[str] = [], probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Rotate image around image axis with independently drawn axis-specific random rotation angle of +-{90, 180, 270} degrees.

Parameters:

axes – List of strings from {‘x’,’y’,’z’} specifying the axes to rotate around. For 2D images, only [‘z’] is valid.
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomChannelDropoutOperation(*args, **kwargs)

Bases: Operation

Randomly sets a subset of input channels to zero. Each channel is independently dropped with the given probability. At least one channel is always preserved.

Parameters:

channel_drop_probability – Per-channel probability of being dropped. Values typically in [0.0, 1.0]. Default: [0.5]
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Function overload documentation:

__init__(self: RandomChannelDropoutOperation, channel_drop_probability: list[float] = [0.5], probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

__init__(self: RandomChannelDropoutOperation, channel_drop_probability: float = 0.5, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

class imfusion.machinelearning.RandomChoiceOperation(*args, **kwargs)

Bases: Operation

Meta-operation that picks one operation from its configuration randomly and executes it. This is particularly useful for image samplers, where we might want to alternate between different ways of sampling the input images.

Parameters:

operation_specs – List of operation Specs to configure the operations to be added.
operation_weights – Weights associated to the each operation during the sampling process. A higher relative weight given to an operation means that this operation will be sampled more often.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Function overload documentation:

__init__(self: RandomChoiceOperation, operation_specs: list[Specs] = [], operation_weights: list[float] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

__init__(self: RandomChoiceOperation, operation_specs: list[tuple[str, Properties, Phase]], operation_weights: list[float] = []) → None

Meta-operation that picks one operation from its configuration randomly and executes it. This is particularly useful for image samplers, where we might want to alternate between different ways of sampling the input images.

Parameters:

operation_specs – List of operation (name, Properties, Phase) casted into Specs to configure the operations to be added.
operation_weights – Weights associated to the each operation during the sampling process. A higher relative weight given to an operation means that this operation will be sampled more often.

__init__(self: RandomChoiceOperation, operations: list[Operation], operation_weights: list[float]) → None

Meta-operation that picks one operation from its configuration randomly and executes it. This is particularly useful for image samplers, where we might want to alternate between different ways of sampling the input images.

Parameters:

operations – List of operations to be added.
operation_weights – Weights associated to the each operation during the sampling process. A higher relative weight given to an operation means that this operation will be sampled more often.

class imfusion.machinelearning.RandomCropAroundLabelMapOperation(self: RandomCropAroundLabelMapOperation, margin: int = 1, reorder: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Crops the input image and label to the bounds of a random label value, and sets the label value to 1 and all other values to zero in the resulting label.

Parameters:

margin – Margin, in pixels. Default: 1
reorder – Whether label value in result should be mapped to 1. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomCropOperation(self: RandomCropOperation, crop_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Crop input images and label maps with a matching random size and offset.

Parameters:

crop_range – List of floats from [0;1] specifying the maximum percentage of the dimension to crop. Default: [0.0, 0.0, 0.0]
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomCutOutOperation(self: RandomCutOutOperation, cutout_size_lower: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), cutout_size_upper: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), cutout_value_range: ndarray[numpy.float32[2, 1]] = array([0., 0.], dtype=float32), cutout_number_range: ndarray[numpy.int32[2, 1]] = array([0, 0], dtype=int32), cutout_size_units: ParamUnit = MM, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a random cutout to the image.

Parameters:

cutout_size_lower – List of doubles specifying the lower bound of the cutout region size for each dimension in mm. Default: [0, 0, 0]
cutout_size_upper – List of doubles specifying the upper bound of the cutout region size for each dimension in mm. Default: [0, 0, 0]
cutout_value_range – List of floats specifying the minimum and maximum fill value for cutout regions. Default: [0, 0]
cutout_number_range – List of integers specifying the minimum and maximum number of cutout regions. Default: [0, 0]
cutout_size_units – Units of the cutout size. Default: MM
probability – Float in [0;1] defining the probability for the operation to be executed.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomDeformationOperation(self: RandomDeformationOperation, num_subdivisions: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), max_abs_displacement: float = 1, padding_mode: PaddingMode = PaddingMode.ZERO, probability: float = 1.0, adjust_size: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a deformation to the image using a specified control point grid and random displacements

Parameters:

num_subdivisions – list specifying the number of subdivisions for each dimension (the number of control points is subdivisions+1). For 2D images, the last component will be ignored. Default: [1, 1, 1]
max_abs_displacement – absolute value of the maximum possible displacement (mm). Default: 1
padding_mode – defines which type of padding is used in [“zero”, “clamp”, “mirror”]. Default: ZERO
probability – probability of applying this Operation. Default: 1.0
adjust_size – configures whether the resulting image should adjust its size to encompass the deformation. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomDiffeomorphismOperation(self: RandomDiffeomorphismOperation, velocity_field_resolution: ndarray[numpy.float64[3, 1]] = array([20., 20., 20.]), max_abs_displacement: float = 20.0, smoothing_kernel_half_size: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), kernel_size_in_mm: bool = True, smooth_velocityField: bool = True, padding_mode: PaddingMode = PaddingMode.CLAMP, adjust_size: bool = False, scale_and_square: bool = True, num_integration_steps: int = 5, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a diffeomorphism to the data derived by integrating a randomly sampled stationary velocity field.

Parameters:

velocity_field_resolution – Resolution (in mm) at which the random velocity field is generated. Lower resolutions lead to smoother deformations. Default: [20, 20, 20]
max_abs_displacement – Absolute value of the maximum possible velocity (mm/T). Default: 20
smoothing_kernel_half_size – Half size of the smoothing convolution kernel in pixels or mm. Default: [1, 1, 1]
kernel_size_in_mm – Interpret kernel size as mm. Otherwise uses pixels. Default: True
smooth_velocityField – If true, smooths the randomly sampled velocity field for smoother diffeomorphisms. Default: True
padding_mode – defines which type of padding is used in [“zero”, “clamp”, “mirror”]. Default: CLAMP
adjust_size – configures whether the resulting image should adjust its size to encompass the deformation. Default: False
scale_and_square – If true, integrates the velocity fields with scaling and squaring, otherwise uses RK4. Default: True
num_integration_steps – Configures the number of integration steps. If using the scaling and squaring for integration, the result is equivalent to 2**num_integration_steps Euler integration steps. If using RK4, uses num_integration_steps integraiton steps with a step size of 1./num_integration_steps. Default: 5
probability – probability of applying this Operation. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomGammaCorrectionOperation(self: RandomGammaCorrectionOperation, random_range: float = 0.2, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a random gamma correction to the image intensities. Output = Unnormalize(pow(Normalize(Input), gamma)) where gamma is drawn uniformly in [1-random_range; 1+random_range].

Parameters:

random_range – Range of the interval used to draw the gamma correction, typically in [0; 0.5]. Default: 0.2
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomImageFromLabelOperation(self: RandomImageFromLabelOperation, mean_range: ndarray[numpy.float64[2, 1]] = array([-1., 1.]), standard_dev_range: ndarray[numpy.float64[2, 1]] = array([0., 1.]), output_field: str = 'ImageFromLabel', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Creates a random image from a label map, each label is sampled from a Gaussian distribution. Each Gaussian distribution parameters (mean and standard deviation) are uniformly sampled withing the provided intervals (respectively mean_range and standard_dev_range).

Parameters:

mean_range – Range of means for the intensities’ Gaussian distributions.
standard_dev_range – Range of standard deviations for the intensities’ Gaussian distributions.
output_field – Output field for the generated image.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomInvertOperation(self: RandomInvertOperation, probability: float = 0.5, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Invert the intensities of the image: \(\textnormal{output} = -\textnormal{input}\).

Parameters:

probability – Float in [0;1] defining the probability for the operation to be executed. Default: 0.5
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomKeypointJitterOperation(self: RandomKeypointJitterOperation, offset_std_dev: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Adds an individually and randomly sampled offset to each keypoint of each KeypointElement.

Parameters:

offset_std_dev – standard deviation of the normal distribution used to sample the jitter in mm
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomLinearIntensityMappingOperation(*args, **kwargs)

Bases: Operation

Apply a random linear shift and scale to the image intensities. \(\textnormal{output}_c = \textnormal{factor}_c \cdot \textnormal{input}_c + \textnormal{bias}_c\)

where \(\textnormal{factor}_c \sim \mathcal{U}(1 - \textnormal{random\_range}_c,\; 1 + \textnormal{random\_range}_c)\)
and \(\textnormal{bias}_c \sim \mathcal{U}(-\textnormal{bias\_range}_c \cdot \Delta_c,\; \textnormal{bias\_range}_c \cdot \Delta_c)\)
with \(\Delta_c = \max(\textnormal{input}_c) - \min(\textnormal{input}_c)\).

random_range controls the factor amplitude and, when random_bias_range is empty, also the bias amplitude. Setting random_bias_range overrides the bias amplitude independently.

A single-element list broadcasts to all channels. A multi-element list applies per-channel (using per-channel intensity ranges).

Parameters:

random_range – Half-width of the uniform factor perturbation (per channel). Values typically in [0.0, 1.0]. Default: [0.0]
random_bias_range – Half-width of the uniform bias perturbation (per channel), scaled by the channel intensity range. Empty list = use random_range. Default: []
probability – Float in [0, 1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Function overload documentation:

__init__(self: RandomLinearIntensityMappingOperation, random_range: list[float] = [0.0], random_bias_range: list[float] = [], probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

__init__(self: RandomLinearIntensityMappingOperation, random_range: float = 0.0, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

class imfusion.machinelearning.RandomMRIBiasFieldGenerationOperation(self: RandomMRIBiasFieldGenerationOperation, center_beta_dist_params: ndarray[numpy.float64[2, 1]] = array([0., 1.]), field_amplitude_random_range: ndarray[numpy.float64[2, 1]] = array([0.2, 0.5]), length_scale_mm_random_range: ndarray[numpy.float64[2, 1]] = array([50., 400.]), distance_scaling_random_range: ndarray[numpy.float64[2, 1]] = array([0.5, 1.]), invert_probability: float = 0.0, output_is_field: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply or generate a random multiplicative intensity modulation field. If the output is a field, it is shifted as close to mean 1 as possible while remaining positive everywhere. If the output is not a field, the image intensity is shifted so that the mean intensity of the input image is preserved.

Parameters:

center_beta_dist_params – Beta distribution parameters for sampling the relative center coordinate locations. Default: [0.0, 1.0]
field_amplitude_random_range – Amplitude of the field. Default: [0.2, 0.5]
length_scale_mm_random_range – Range of length scale of the distance kernel in mm. Default: [50.0, 400.0]
distance_scaling_random_range – Range of relative scaling of scanner space coordinates for anisotropic fields. Default: [0.5, 1.0]
invert_probability – Probability to invert the field (before normalization): field <- 2.0 - field. Default: 0.0
output_is_field – Produce field instead of corrupted image. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomPolyCropOperation(self: RandomPolyCropOperation, number_range: ndarray[numpy.int32[2, 1]] = array([5, 10], dtype=int32), min_radius: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Masks the image with a random convex polygon as described in Markova et al. 2022 (https://arxiv.org/abs/2205.03439). The convex polygon mask is constructed by sampling random planes, each plane splits the volume in two parts, the part of the image that doesn’t contain the image center is discarded.

Parameters:

number_range – Range of integers specifying the minimum and maximum number of cutting planes. Default: [5, 10]
min_radius – The minimum distance a cutting plane must have from the center (image coordinates are normalized to [-1, 1]). Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomROISampler(self: RandomROISampler, roi_size: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: ImageROISampler

Sampler which randomly samples ROIs from the input image and label map with a target The images will be padded if the target size is larger than the input image.

Parameters:

roi_size – Target size of the ROIs to be extracted as [Width, Height, Slices]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

padding_mode: Padding mode for input images. Default: CLAMP

label_padding_mode: Padding mode for target label maps. Default: CLAMP

class imfusion.machinelearning.RandomResolutionReductionOperation(self: RandomResolutionReductionOperation, max_spacing: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Downsamples the image to a target_spacing and upsamples again to the original spacing to reduce image information. The target_spacing is sampled uniformly and independently in each dimension between the corresponding image spacing and max_spacing.

Parameters:

max_spacing – maximum spacing per dimension which the target spacing is randomly sampled from. Minimum sampling spacing is the maximum (over all frames of the image set) spacing per dimension of the input SharedImageSet. Default: [0.0, 0.0, 0.0]
probability – probability of applying this Operation. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomRotationOperation(self: RandomRotationOperation, angles_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), adjust_size: bool = False, apply_now: bool = False, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Rotate input images and label maps with random angles.

Parameters:

angles_range – List of floats specifying the upper bound (in degrees) of the range from with the rotation angles will be drawn uniformly. Only the third component should be non-zero for 2D images. Default: [0, 0, 0]
adjust_size – Increase image size to include the whole rotated image or keep current dimensions. Default: False
apply_now – Bake transformation right way (otherwise, just changes the matrix). Default: False
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomScalingOperation(self: RandomScalingOperation, scales_range: ndarray[numpy.float64[3, 1]] = array([0.5, 0.5, 0.5]), log_scales_range: ndarray[numpy.float64[3, 1]] = array([2., 2., 2.]), log_parameterization: bool = False, apply_now: bool = False, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Scale input images and label maps with random factors.

Parameters:

scales_range (vec3) – List of floats specifying the upper bound of the range from which the scaling ofset will be sampled. The scaling factor will be drawn uniformly within [1-scale, 1+scale]. Scale should be between 0 and 1. Default: [0.5, 0.5, 0.5]
log_scales_range (vec3) – List of floats specifying the upper bound of the range from which the scaling factor will be drawn uniformly in log scale. The scaling will then be distributed within [1/log_scale, log_scale]. Default: [2., 2., 2.]
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible
log_parameterization (bool) – If true, uses the log scales range parameterization, otherwise uses the scales range parameterization. Default: False
apply_now (bool) – Bake transformation right way (otherwise, just changes the matrix). Default: False
probability (float) – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0

class imfusion.machinelearning.RandomSmoothOperation(self: RandomSmoothOperation, half_kernel_bounds: ndarray[numpy.float64[2, 1]] = array([1, 1], dtype=int32), kernel_size_in_mm: bool = False, isotropic: bool = True, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a random smoothing on the image (Gaussian kernel). The kernel can be parameterized either in pixel or in mm, and can be anisotropic. The half kernel size is distributed uniformly between half_kernel_bounds[0] and half_kernel_bounds[1]. \(\textnormal{image_output} = \textnormal{image} * \textnormal{gaussian_kernel}(\sigma)\) , with \(\sigma \sim U(\textnormal{half_kernel_bounds}[0], \textnormal{half_kernel_bounds}[1])\)

Parameters:

half_kernel_bounds – Bounds for the half kernel size. The final kernel size is 2 times the sampled half kernel size plus one. Default: [1, 1]
kernel_size_in_mm – Interpret kernel size as mm. Otherwise uses pixels. Default: False
isotropic – Forces the randomly drawn kernel size to be isotropic. Default: True
probability – Value in [0.0; 1.0] indicating the probability of this operation to be performed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RandomTemplateInpaintingOperation(self: RandomTemplateInpaintingOperation, template_paths: list[str] = [], rotation_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), translation_range: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), template_mult_factor_range: ndarray[numpy.float64[2, 1]] = array([0., 0.]), add_values_to_existing: bool = False, probability: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Inpaints a template into an image with randomly selected spatial and intensity transformation in a given range.

Parameters:

template_paths – paths from which a template .imf file is randomly loaded.
rotation_range – rotation of template in degrees per axis randomly sampled from [-rotation_range, rotation_range]. Default: [0, 0, 0]
translation_range – translation of template in degrees per axis randomly sampled from [-translation_range, translation_range]. Default: [0, 0, 0]
template_mult_factor_range – Multiply template intensities with a factor randomly sampled from this range. Default: [0.0, 0.0]
add_values_to_existing – Adding values to input image rather than replacing them. Default: False
probability – Float in [0;1] defining the probability for the operation to be executed. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RecombineMode(*args, **kwargs)

Bases: pybind11_object

Enum specifying the mode for recombining overlapping image patches.

This enum is used by RecombinePatchesOperation to determine how overlapping regions from multiple patches should be merged back into the full image.

Values:: DEFAULT: Simple averaging of overlapping regions. Each overlapping pixel is averaged equally. WEIGHTED: Weighted averaging of overlapping regions.

Members:

DEFAULT : Simple averaging of overlapping regions

WEIGHTED : Weighted averaging of overlapping regions

Function overload documentation:

__init__(self: RecombineMode, value: int) → None

__init__(self: RecombineMode, arg0: str) → None

DEFAULT = <RecombineMode.DEFAULT: 0>

WEIGHTED = <RecombineMode.WEIGHTED: 1>

property name

property value

class imfusion.machinelearning.RecombinePatchesOperation(self: RecombinePatchesOperation, mode: RecombineMode = RecombineMode.DEFAULT, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Operation to recombine image patches back into a full image. This operation is typically used in conjunction with SplitIntoPatchesOperation to reconstruct a full image from its patches after processing (e.g., after neural network inference).

The operation handles overlapping patches by averaging the overlapping regions. For each output pixel, the final value is computed as the weighted average of all patches that contain that pixel. The weighting mode is specified by the RecombineMode parameter.

It requires input images to have a PatchesFromImageDataComponent that stores the location of each patch in the original image. This component is automatically added by the SplitIntoPatchesOperation or by the SplitROISampler.

Two recombination modes are supported:

DEFAULT: Simple averaging of overlapping regions

WEIGHTED: Weighted averaging of overlapping regions

Note: Both GPU and CPU computing devices are supported, via the ComputingDevice parameter in Operation.

Note: RecombineMode can be automatically converted from a string. This means you can directly pass a string like “default” or “weighted” to the mode parameter instead of using the enum values.

Args:
mode: The mode for recombining the patches. Default: DEFAULT

device: Specifies whether this Operation should run on CPU or GPU. seed: Specifies seeding for any randomness that might be contained in this operation. error_on_unexpected_behaviour: Specifies whether to throw an exception instead of warning about unexpected behavior. apply_to: Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy) record_identifier: Unused for this operation as it is not invertible

class imfusion.machinelearning.RectifyRotationOperation(self: RectifyRotationOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Sets the image matrix to the closest xyz-axis aligned rotation, effectively making every rotation angle a multiple of 90 degrees. This is useful when the values of the rotation are unimportant but the axis flips need to be preserved. If used before BakeTransformationOperation, this operation will avoid oblique angles and a lot of zero padding.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RemoveMaskOperation(self: RemoveMaskOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Removes the mask of all input images.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RemoveOperation(self: RemoveOperation, apply_to: set[str] = set(), *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Removes a set of fields from a data item.

Parameters:

apply_to – fields to mark as targets (will initialize the underlying apply_to parameter)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RenameOperation(self: RenameOperation, source: list[str] = [], target: list[str] = [], throw_error_on_missing_source: bool = True, throw_error_on_existing_target: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Renames a set of fields of a data item.

Parameters:

source – list of the elements to be replaced
target – list of names of the new elements (must match the size of source)
throw_error_on_missing_source – if source field is missing, then throw an error (otherwise warn about unexpected behavior and do nothing). Default: True
throw_error_on_existing_target – if target field already exists, then throw an error (otherwise warn about unexpected behavior and overwrite it). Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ReplaceLabelsValuesOperation(self: ReplaceLabelsValuesOperation, old_values: list[int] = [], new_values: list[int] = [], update_labelsdatacomponent: bool = True, default_value: int | None = None, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Replace some label values with other values (only works for integer-typed labels).

For convenience purposes, a default value can be set, in which case all not explicitly defined non-zero input values will be assigned this value.

Parameters:

old_values – List of integer values to be replaced. All values that are not in this list will remain unchanged.
new_values – List of integer values to replace old_values. It must have the same size as old_values, since there should be a one-to-one mapping.
update_labelsdatacomponent – Replaces the old-values in the LabelsDataComponent with the mapped ones. Default: True
default_value – If set, this value will be assigned to all non-zero labels that have not been explicitly assigned. Default: None
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ResampleDimsOperation(self: ResampleDimsOperation, target_dims: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Resample the input to fixed target dimensions.

Parameters:

target_dims – Target dimensions in pixels as [Width, Height, Slices].
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ResampleKeepingAspectRatioOperation(self: ResampleKeepingAspectRatioOperation, keep_aspect_ratio_wrt: str = '', target_dim_x: int | None = 1, target_dim_y: int | None = 1, target_dim_z: int | None = 1, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Resample input to target dimensions while keeping aspect ratio of original images. The target dimensions are specified by either:

one target dimension, i.e.: target_dim_x: 128. In such case the resampling will keep the aspect ratio of dimension y and z wrt x.
two target dimensions, i.e.: target_dim_x: 128, i.e.: target_dim_y: 128 and which dimension to consider for preserving the aspect ratio of the leftover dimension, i.e. keep_aspect_ratio_wrt: x.

Parameters:

keep_aspect_ratio_wrt – specifies the dimension to which lock the aspect ratio, please assign either of “”, “x”, “y” or “z”. If only one target_dim is specified, then this can be empty (or must match the given target_dim). If all the target_dim args are specified, then this argument must be empty, however, in this case ResampleDims should then be preferred.
target_dim_x – either the target width or None if this dimension will be computed automatically by preserving the aspect ratio.
target_dim_y – either the target height or None if this dimension will be computed automatically by preserving the aspect ratio.
target_dim_z – for 3D images, either the target slices or None if this dimension will be computed automatically by preserving the aspect ratio.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ResampleOperation(self: ResampleOperation, resolution: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), preserve_extent: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Resample the input to a fixed target resolution.

Parameters:

resolution – Target spacing in mm.
preserve_extent – Preserve the exact spatial extent of the image, adjusting the output spacing resolution accordingly (since the extent is not always a multiple of resolution). Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ResampleToInputOperation(self: ResampleToInputOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Resample the input image with respect to the image in ReferenceImageDataComponent

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.ResetCriterion(*args, **kwargs)

Bases: pybind11_object

Enum specifying when to reset a dataset during iteration.

Values:: FIXED: Reset after a fixed number of items SMALLEST_LOADER: Reset when the smallest data loader is exhausted LARGEST_LOADER: Reset when the largest data loader is exhausted UNKNOWN: Default, invalid value

Members:

FIXED : Reset after processing a fixed number of items

SMALLEST_LOADER : Reset when the smallest loader runs out of data

LARGEST_LOADER : Reset when the largest loader runs out of data

UNKNOWN : Default, invalid value

Function overload documentation:

__init__(self: ResetCriterion, value: int) → None

__init__(self: ResetCriterion, arg0: str) → None

FIXED = <ResetCriterion.FIXED: 0>

LARGEST_LOADER = <ResetCriterion.LARGEST_LOADER: 2>

SMALLEST_LOADER = <ResetCriterion.SMALLEST_LOADER: 1>

UNKNOWN = <ResetCriterion.LARGEST_LOADER: 2>

property name

property value

class imfusion.machinelearning.ResolutionReductionOperation(self: ResolutionReductionOperation, target_spacing: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Downsamples the image to the target_spacing and upsamples again to the original spacing to reduce image information.

Parameters:

target_spacing – spacing per dimension to which the image is resampled before it is resampled back
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RotationOperation(self: RotationOperation, angles: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), adjust_size: bool = False, apply_now: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Rotate input images and label maps with fixed angles.

Parameters:

angles – Rotation angles in degrees. Only the third component should be non-zero for 2D images. Default: [0, 0, 0]
adjust_size – Increase image size to include the whole rotated image or keep current dimensions. Default: False
apply_now – Bake transformation right way (otherwise, just changes the matrix). Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.RunModelOperation(self: RunModelOperation, config_path: str = '', apply_to: set[str] | None = None, *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Run a machine learning model on the input item and merge the prediction to the input item. The input field names specified in the model config yaml will be use to determine which fields in the input data item the model is run. If the model doesn’t specify any input field, i.e. is a single input model, the user can either provide an input data item with a single image element, or use the apply_to to specify on which field the model should be run. The input item will be populated with the model prediction. The field names are those specified in the model configuration. If no output name is specified (i.e. single output case), the prediction will be associated to the field “Prediction”

Parameters:

config_path – path to the YAML configuration file of the pixelwise model
apply_to – fields the model should be run on
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SISBasedElement

Bases: DataElement

Base class for DataElements that wrap SharedImageSet data.

This class provides a common interface for elements that store their content as SharedImageSet objects, including images and vectors. It enables uniform access to the underlying image data structure.

to_sis(self: SISBasedElement) → SharedImageSet

Get the underlying SharedImageSet.

Deprecated since version Use: the sis property instead.

Returns:: The underlying SharedImageSet

property sis: Access to the underlying SharedImageSet.

class imfusion.machinelearning.ScalingOperation(self: ScalingOperation, scales: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), apply_now: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Scale input images and label maps with fixed factors.

Parameters:

scales – Scaling factor applied to each dimension. Default: [1, 1, 1]
apply_now – Bake transformation right way (otherwise, just changes the matrix). Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SelectChannelsOperation(self: SelectChannelsOperation, selected_channels: list[int] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Keeps a subset of the input channels specified by the selected channel indices (0-based indexing).

Parameters:

selected_channels – List of channels to be selected in input. If empty, use all channels.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SequenceOperation(*args, **kwargs)

Bases: Operation

Meta-operation that groups multiple operations together. This is particularly useful coupled with RandomChoiceOperation when more than one operations per choice branch need to be performed.

Parameters:

operation_specs – List of operation Specs to configure the operations to be added.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Function overload documentation:

__init__(self: SequenceOperation, operation_specs: list[Specs] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None) → None

__init__(self: SequenceOperation, operation_specs: list[tuple[str, Properties, Phase]]) → None

Meta-operation that groups multiple operations together. This is particularly useful coupled with RandomChoiceOperation when more than one operations per choice branch need to be performed.

Parameters:: operation_specs – List of operation (name, Properties, Phase) casted into Specs to configure the operations to be added.

__init__(self: SequenceOperation, operations: list[Operation]) → None

Meta-operation that groups multiple operations together. This is particularly useful coupled with RandomChoiceOperation when more than one operations per choice branch need to be performed.

Parameters:: operations – List of operations to be added.

class imfusion.machinelearning.SetLabelModalityOperation(self: SetLabelModalityOperation, label_names: list[str] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Sets the input modality. If the target modality is LABEL, warns and skips fields that are not unsigned 8-bit integer. The default processing policy is to apply to targets only.

Parameters:

label_names – List of non-background label names. The label with index zero is assigned the name ‘Background’.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SetMatrixToIdentityOperation(self: SetMatrixToIdentityOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Set the matrices of all images to identity (associated landmarks and boxes will be moved accordingly).

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SetModalityOperation(self: SetModalityOperation, modality: Modality = Modality.NA, label_names: list[str] = [], *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Sets the input modality. If the target modality is LABEL, warns and skips fields that are not unsigned 8-bit integer. The default processing policy is to apply to all fields.

Parameters:

modality – Modality to set the input to.
label_names – List of non-background label names. The label with index zero is assigned the name ‘Background’. Default: [].
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SetSpacingOperation(self: SetSpacingOperation, spacing: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Modify images so that image elements have specified spacing (associated landmarks and boxes will be moved accordingly). :param spacing: Target spacing. :param device: Specifies whether this Operation should run on CPU or GPU. :param seed: Specifies seeding for any randomness that might be contained in this operation. :param error_on_unexpected_behaviour: Specifies whether to throw an exception instead of warning about unexpected behavior. :param apply_to: Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy) :param record_identifier: Unused for this operation as it is not invertible

class imfusion.machinelearning.SigmoidOperation(self: SigmoidOperation, scale: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a sigmoid function on the input image. \(\textnormal{output} = 1.0/(1.0 + \exp(- \textnormal{scale} * \textnormal{input}))\)

Parameters:

scale – Scale parameter within the sigmoid function. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SmoothOperation(self: SmoothOperation, half_kernel_size: ndarray[numpy.float64[3, 1]] = array([1., 1., 1.]), kernel_size_in_mm: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Run a convolution with a Gaussian kernel on the input image. The kernel can be parameterized either in pixel or in mm, and can be anisotropic.

Parameters:

half_kernel_size – Half size of the convolution kernel in pixels or mm.
kernel_size_in_mm – Interpret kernel size as mm. Otherwise uses pixels. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SoftmaxOperation(self: SoftmaxOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Computes channel-wise softmax on input.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SplitIntoPatchesOperation(self: SplitIntoPatchesOperation, patch_size: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), patch_step_size: float = 0.8, padding_mode: PaddingMode = PaddingMode.MIRROR, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Operation which splits the input image into overlapping patches for sliding window inference.

The step size is used to compute valid patch positions that cover the full input image. The sampling behavior is controlled by the patch_step_size parameter, which is used to compute the patch offsets in the input image as a fraction of the specified patch size.

Parameters:

patch_size – Target size of the patches to be extracted as [Width, Height, Slices].
patch_step_size –
Controls the step size between patches as a fraction of the patch size. Range [0, 1]. In cases where the input image is a multiple of the patch size, a step size of 1.0 means no overlapping patches, while a lower step size means a higher number of overlapping patches.

Example: If the input image is 100x100 and the patch size is 50x50, a patch_step_size of 1.0 will result in a 2x2 grid of non-overlapping patches, while a patch_step_size of 0.5 will result in a 3x3 grid of patches, with a 25 pixel overlap between adjacent patches.

In cases where the input image is not a multiple of the ROI size, a step size of 1.0 indicates the optimal way of splitting the image in the least possible number of patches. Example: If the input image is 100x100 and the ROI size is 40x40, a patch_step_size of 1.0 will result in a 3x3 grid of patches, with a 10 pixel overlap between adjacent patches. Conversely, a patch_step_size of 0.5 will result in a 4x4 grid of patches, with a 20 pixel overlap between adjacent patches.
padding_mode – Specifies the padding mode used when the input image is smaller than the specified patch size. In this case, the image is padded to the patch size with the specified padding mode.
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

Note: This operation uses the SplitROISampler internally.

class imfusion.machinelearning.SplitROISampler(self: SplitROISampler, roi_size: ndarray[numpy.int32[3, 1]] = array([1, 1, 1], dtype=int32), patch_step_size: float = 0.8, extract_all_patches: bool = False, allow_dimension_change: bool = True, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: ImageROISampler

Sampler which splits the input image into overlapping ROIs for sliding window inference.

This sampler mimics the situation at test-time, when one image needs to be processed in regularly spaced patches. The step size is used to compute valid ROI positions that cover the full input image. The sampling behavior is controlled by the patch_step_size parameter, which is used to compute the ROIs offsets in the input image as a fraction of the specified ROI size.

Parameters:

roi_size – Target size of the ROIs to be extracted as [Width, Height, Slices].
patch_step_size – Parameter in [0,1] controlling the step size between ROIs as a fraction of the ROI size. In cases where the input image is a multiple of the ROI size, a step size of 1.0 means no overlapping patches, while a lower step size means a higher number of overlapping patches. Default: 0.8. Example: If the input image is 100x100 and the ROI size is 50x50, a patch_step_size of 1.0 will result in a 2x2 grid of non-overlapping patches, while a patch_step_size of 0.5 will result in a 3x3 grid of patches, with a 25 pixel overlap between adjacent patches. In cases where the input image is not a multiple of the ROI size, a step size of 1.0 indicates the optimal way of splitting the image in the least possible number of patches. Example: If the input image is 100x100 and the ROI size is 40x40, a patch_step_size of 1.0 will result in a 3x3 grid of patches, with a 10 pixel overlap between adjacent patches. Conversely, a patch_step_size of 0.5 will result in a 4x4 grid of patches, with a 20 pixel overlap between adjacent patches.
extract_all_patches – When true, returns all overlapping patches according to the step size. When false, returns a single randomly selected patch from all possible positions.
allow_dimension_change – If True, allow padding dimensions equal to 1. This results in changing image dimension e.g. from 2D to 3D. Default: True
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

padding_mode: Padding mode for input images. Default: CLAMP

label_padding_mode: Padding mode for target label maps. Default: CLAMP

class imfusion.machinelearning.StandardizeImageAxesOperation(self: StandardizeImageAxesOperation, coordinate_system: str = 'LPS', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Reorganize the memory buffer of a medical image to ensure anatomical consistency. This operation rearranges the axes and orientation of the input image to align with right-handed anatomical coordinate systems.

The coordinate system is specified as a 3-character string where: - 1st character: L (Left, +x) or R (Right, -x) - 2nd character: P (Posterior, +y) or A (Anterior, -y) - 3rd character: S (Superior, +z) or I (Inferior, -z)

Supported right-handed coordinate systems: - LPS: Left-Posterior-Superior (DICOM standard) - {+1, +1, +1} - RAS: Right-Anterior-Superior (neuroimaging) - {-1, -1, +1} - LAI: Left-Anterior-Inferior - {+1, -1, -1} - RPI: Right-Posterior-Inferior - {-1, +1, -1}

The operation uses the rotation matrix of the image and modifies it so that only a non-axis aligned rotation remains.

Note that this operation only re-arranges internal representations but does not modify the actual spatial position and orientation of the image (as opposed to RectifyRotationOperation). This operation differs from BakeTransformationOperation because it only applies axis-based rotations or flips and therefore does not do any kind of interpolation. Unlike BakeTransformationOperation, a residual rotation might remain in the matrix of the output image.

Parameters:

coordinate_system – Target coordinate system (3-character string). Default: “LPS”
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SurfaceDistancesMetric(self: SurfaceDistancesMetric, symmetric: bool = True, crop_margin: int = -1)

Bases: Metric

Computes surface distance metrics between predicted and target segmentation surfaces.

This metric computes various distance measures between the surfaces of segmented objects, including mean signed distance, mean absolute distance, and maximum distance.

Constructs a SurfaceDistancesMetric.

Parameters:

symmetric – If True, computes bidirectional distances (prediction to target and target to prediction). Default: True
crop_margin – Margin in voxels to crop before computing distances. If -1, no cropping is performed. Default: -1

class Results(self: Results)

Bases: pybind11_object

Results container for surface distance metric computations.

Initialize an empty Results object.

Creates a results container that will be populated by the SurfaceDistancesMetric.

property all_distances: Vector containing all computed distances in millimeters

property max_absolute_distance: Maximum absolute distance between surfaces in millimeters

property mean_absolute_distance: Mean absolute distance between surfaces in millimeters

property mean_signed_distance: Mean signed distance between surfaces in millimeters

compute_distances(self: SurfaceDistancesMetric, prediction: SharedImageSet, target: SharedImageSet) → list[dict[int, Results]]

Computes surface distances between prediction and target.

Parameters:

prediction – The predicted segmentation
target – The target/ground truth segmentation

Returns:

Object containing computed distance metrics

Return type:

Results

class imfusion.machinelearning.SwapImageAndLabelsOperation(self: SwapImageAndLabelsOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Swaps image and label map.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.SyncOperation(self: SyncOperation, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Synchronizes shared memory (CPU <-> OpenGL) of images.

Parameters:

device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.TanhOperation(self: TanhOperation, scale: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply a tanh function on the input image. \(\textnormal{output} = \tanh(\textnormal{scale} * \textnormal{input})\)

Parameters:

scale – Scale parameter within the tanh function. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.TargetTag(self: TargetTag)

Bases: DataComponentBase

Component tag to mark a DataElement as a target/label for training.

This tag is attached to DataElements to indicate they should be used as targets during training rather than as inputs. It enables automatic handling of target data in ML pipelines.

Initialize a TargetTag component.

Creates a tag that can be attached to a DataElement to mark it as a target/label.

class imfusion.machinelearning.TemplateInpaintingOperation(self: TemplateInpaintingOperation, template_path: str = '', template_rotation: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), template_translation: ndarray[numpy.float64[3, 1]] = array([0., 0., 0.]), add_values_to_existing: bool = False, template_mult_factor: float = 1.0, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Inpaints a template into an image with specified spatial and intensity transformation.

Parameters:

template_path – path to load template .imf file.
template_rotation – rotation of template in degrees per axis. Default: [0, 0, 0]
template_translation – translation of template in degrees per axis. Default: [0, 0, 0]
add_values_to_existing – Adding values to input image rather than replacing them. Default: False
template_mult_factor – Multiply template intensities with this factor. Default: 1.0
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.Tensor(self: Tensor, tensor: Buffer)

Bases: pybind11_object

Class for managing raw Tensors

This class is meant to have direct control over tensors either passed to, or received from a MachineLearningModel. Unlike the SISBasedElements, there is no inherent stacking/permuting of tensors, and there are no constraints on the order of the Tensor.

Note

The API for this class is experimental and may change soon.

Initialize a Tensor from a numpy array or buffer.

The tensor takes ownership of the data from the provided buffer. Supported types are float32 and int64. The buffer must be contiguous.

Parameters:: tensor – Numpy array or buffer object with float32 or int64 data

property shape: Return shape of tensor.

class imfusion.machinelearning.TensorSet(self: TensorSet, tensors: list[Tensor] = [])

Bases: Data

Class for managing TensorSets

This class is meant to have direct control over tensors either passed to, or received from a MachineLearningModel. Unlike the SISBasedElements, there is no inherent stacking/permuting of tensors, and there are no constraints on the order of the Tensor.

Note

The API for this class is experimental and may change soon.

Initialize a TensorSet

Parameters:: tensors – Set of tensors to initialize the TensorSet with.

add(self: TensorSet, tensor: Tensor) → None

Add a Tensor to this TensorSet.

Parameters:: tensor – The Tensor to add to the set

tensor(self: TensorSet, index: int = 0) → Tensor

Retrieve a Tensor at the specified index.

Parameters:: index – The index of the tensor to retrieve. Default: 0
Returns:: The Tensor at the specified index

tensors(self: TensorSet) → list[Tensor]: Retrieve Tensors

class imfusion.machinelearning.TensorSetElement(*args, **kwargs)

Bases: DataElement

Class for managing raw Tensorsets

This class is meant to have direct control over tensors either passed to, or received from a MachineLearningModel. Unlike the SISBasedElements, there is no inherent stacking/permuting of tensors, and there are no constraints on the order of the Tensor.

Note

The API for this class is experimental and may change soon.

Function overload documentation:

__init__(self: TensorSetElement, tensorset: TensorSet) → None

Initialize a TensorSetElement from a TensorSet.

Parameters:: tensorset – TensorSet containing one or more tensors

__init__(self: TensorSetElement, tensorset: TensorSet) → None

Initialize a TensorSetElement from a TensorSet.

Parameters:: tensorset – TensorSet containing one or more tensors

__init__(self: TensorSetElement, tensor: Tensor) → None

Initialize a TensorSetElement from a single Tensor.

The tensor will be wrapped in a TensorSet automatically.

Parameters:: tensor – Single Tensor to be wrapped in a TensorSetElement

tensor(self: TensorSetElement, index: int = 0) → Tensor

Access tensor as certain index.

Parameters:: index (int) –

property tensorset: Access to the underlying TensorSet.

class imfusion.machinelearning.ThresholdOperation(self: ThresholdOperation, value: float = 0.0, to_ubyte: bool = False, *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Threshold the input image to a binary map with only 0 or 1 values.

Parameters:

value – Threshold value (strictly) above which the pixel will set to 1. Default: 0.0
to_ubyte – Output image must be unsigned byte instead of float. Default: False
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.UndoPaddingOperation(self: UndoPaddingOperation, target_identifier: str = '', *, device: ComputingDevice | None = None, apply_to: list[str] | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Apply the inverse of a previously applied padding operation. This operation requires the input to have an InversionComponent containing padding information. The padding information must have been previously stored with a matching record identifier during the padding operation.

Note: Both GPU and CPU implementations are provided.

Note: If no InversionComponent is present, or no matching record identifier is found, the operation will return the input unchanged and warn about unexpected behavior. The operations throws an error if the number of images has changed since the padding was applied.

Parameters:

target_identifier – The identifier of the operation to undo. Default: “”
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
apply_to – Specifies fields in a DataItem that this Operation should process (if empty, will select suitable fields based on the current processing_policy)
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.UnmarkAsTargetOperation(self: UnmarkAsTargetOperation, apply_to: list[str] = [], *, device: ComputingDevice | None = None, seed: int | None = None, error_on_unexpected_behaviour: bool | None = None)

Bases: Operation

Unmark elements from the input data item as learning “target”. This operation is the opposite of MarkAsTargetOperation.

Parameters:

apply_to – fields to unmark as targets (will initialize the underlying apply_to parameter)
device – Specifies whether this Operation should run on CPU or GPU.
seed – Specifies seeding for any randomness that might be contained in this operation.
error_on_unexpected_behaviour – Specifies whether to throw an exception instead of warning about unexpected behavior.
record_identifier – Unused for this operation as it is not invertible

class imfusion.machinelearning.VectorElement(self: VectorElement, vectors: SharedImageSet)

Bases: SISBasedElement

DataElement for storing and processing vector/feature data.

VectorElement wraps a SharedImageSet to represent vector features or embeddings in ML pipelines. Despite using SharedImageSet internally, it represents 1D feature vectors rather than spatial images.

Initialize a VectorElement from a SharedImageSet.

Parameters:: vectors – SharedImageSet containing vector/feature data to be wrapped in a VectorElement

static from_torch(tensor: Tensor) → VectorElement

Create a VectorElement from a torch Tensor.

This is a convenience wrapper around SharedImageSet.from_torch() that automatically wraps the result in a VectorElement for 1D vector data.

Parameters:: tensor (Tensor) – Instance of torch.Tensor to convert
Returns:: New VectorElement containing the converted data
Return type:: VectorElement

imfusion.machinelearning.available_cpp_engines() → list[str]: Returns the list of registered C++ engines available for usage in MachineLearningModel.

imfusion.machinelearning.available_engines() → list[str]: Returns the list of all registered engines available for usage in MachineLearningModel.

imfusion.machinelearning.available_py_engines() → list[str]: Returns the list of registered Python engines available for usage in MachineLearningModel.

imfusion.machinelearning.is_semantic_segmentation_map(sis: SharedImageSet) → bool

Checks whether a SharedImageSet is a semantic segmentation map.

Parameters:: sis – The SharedImageSet to check
Returns:: True if the image is a semantic segmentation map, False otherwise
Return type:: bool

imfusion.machinelearning.is_target(sis: SharedImageSet) → bool

Checks whether a SharedImageSet is tagged as a target.

Parameters:: sis – The SharedImageSet to check
Returns:: True if the image is tagged as target, False otherwise
Return type:: bool

imfusion.machinelearning.maybe_get_reference_image(item: DataItem) → SharedImageSet

Determine reference image for output metadata if possible.

Checks for a reference image in the following order: 1. Explicit ReferenceImageDataComponent attached to the DataItem 2. Single image element (used as reference) 3. Multiple image elements with spatially compatible descriptors (first used as reference)

Parameters:: item – DataItem to examine
Returns:: Shallow-cloned SharedImageSet if found, None otherwise. The returned image is a shallow copy that shares pixel data with the original.
Return type:: Optional[SharedImageSet]

imfusion.machinelearning.propertylist_to_data_loader_specs(properties: list[Properties]) → list[DataLoaderSpecs]: Parse a properties object into a vector of DataLoaderSpecs.

imfusion.machinelearning.register_filter_func(name: str, func: Callable[[DataItem], bool]) → None

Register a user-defined function to be used as a Dataset filter operation.

This function registers a custom predicate function that can be used to filter DataItems in a Dataset pipeline using the Dataset.filter() decorator.

Parameters:

name – Unique identifier for the filter function
func – Function that takes a const DataItem pointer and returns True to keep the item, False to filter it out

imfusion.machinelearning.register_map_func(name: str, func: Callable[[DataItem], None]) → None

Register a user-defined function to be used as a Dataset map operation.

This function registers a custom transformation function that can be applied to DataItems in a Dataset pipeline using the Dataset.map() decorator.

Parameters:

name – Unique identifier for the map function
func – Function that takes a DataItem pointer and modifies it in-place

imfusion.machinelearning.register_py_op_cls(cls: object) → None

Register a Python Operation class with the operation factory.

This function is typically called automatically when inheriting from Operation or InvertibleOperation, but can be called manually if needed.

Parameters:: cls – The Python class to register

imfusion.machinelearning.tag_as_target(sis: SharedImageSet) → None

Tags a SharedImageSet as a target (ground truth) for machine learning.

Parameters:: sis – The SharedImageSet to tag as target

imfusion.machinelearning.to_torch(self: DataElement | SharedImageSet | SharedImage, device: device = None, dtype: dtype = None, same_as: Tensor = None) → Tensor

Convert SharedImageSet or a SharedImage to a torch.Tensor.

Parameters:

self (DataElement | SharedImageSet | SharedImage) – Instance of SharedImageSet or SharedImage (this function bound as a method to SharedImageSet and SharedImage)
device (device) – Target device for the new torch.Tensor
dtype (dtype) – Type of the new torch.Tensor
same_as (Tensor) – Template tensor whose device and dtype configuration should be matched. device and dtype are still applied afterwards.

Returns:

New torch.Tensor

Return type:

Tensor

imfusion.machinelearning.untag_as_target(sis: SharedImageSet) → None

Removes the target tag from a SharedImageSet.

Parameters:: sis – The SharedImageSet to untag

imfusion.machinelearning.update_model_configuration(input_path: str | ~pathlib.Path, output_path: str | ~pathlib.Path | None = None, verbose: bool = False, default_prediction_output: ~imfusion.machinelearning.PredictionOutput = <PredictionOutput.UNKNOWN: -1>) → None

Update an ImFusion ML model configuration file to the latest version.

This function loads a configuration file, upgrades it to the latest version format, and saves it to the specified output path. If no output path is provided, the input file will be overwritten.

Parameters:

input_path (str | Path) – Path to the input YAML configuration file
output_path (str | Path | None) – Path for the output YAML configuration file. If None, the input file will be overwritten
verbose (bool) – If True, print detailed information about the upgrade process
default_prediction_output (PredictionOutput) – Default prediction output type to use when not specified in the configuration file. This can happen in legacy configurations.

Return type:

None

imfusion.registration

This module contains functionality for all kinds of registration tasks. You can find a demonstration of how to perform image registration on our GitHub.

class imfusion.registration.AbstractImageRegistration: Bases: Algorithm

class imfusion.registration.DescriptorsRegistrationAlgorithm(self: DescriptorsRegistrationAlgorithm, arg0: SharedImageSet, arg1: SharedImageSet)

Bases: pybind11_object

Class for performing image registration using local feature descriptors.

This algorithm performs the following steps: 1) Preprocess the fixed and moving images to prepare them for feature extraction. This consists of resampling to spacing and baking-in the rotation. 2) Extract feature descriptors using either DISAFeaturesAlgorithm or MINDDescriptorAlgorithm depending on descriptor_type. 3) Computes the weight for the moving image features. 4) Instantiates and uses FeatureMapsRegistrationAlgorithm to register the feature descriptors images. The computed registration is then applied to the moving image.

class DescriptorType(self: DescriptorType, value: int)

Bases: pybind11_object

Members:

DISA : Use the DISA descriptors defined in the paper “DISA: DIfferentiable Similarity Approximation for Universal Multimodal Registration”, Ronchetti et al. 2023

MIND

DISA = <DescriptorType.DISA: 0>

MIND = <DescriptorType.MIND: 1>

property name

property value

globalRegistration(self: DescriptorsRegistrationAlgorithm) → None

heatmap(self: DescriptorsRegistrationAlgorithm, point: ndarray[numpy.float64[3, 1]]) → SharedImageSet

initialize_pose(self: DescriptorsRegistrationAlgorithm) → None

localRegistration(self: DescriptorsRegistrationAlgorithm) → None

processed_fixed(self: DescriptorsRegistrationAlgorithm) → SharedImageSet

processed_moving(self: DescriptorsRegistrationAlgorithm) → SharedImageSet

DISA = <DescriptorType.DISA: 0>

MIND = <DescriptorType.MIND: 1>

property registration_algorithm

property spacing

property type

property weight

class imfusion.registration.FeatureMapsRegistrationAlgorithm(self: FeatureMapsRegistrationAlgorithm, fixed: SharedImageSet, moving: SharedImageSet, weight: SharedImageSet = None)

Bases: pybind11_object

Algorithm for registering feature maps volumes

class Motion(self: Motion, value: int)

Bases: pybind11_object

Members:

RIGID

AFFINE

AFFINE = <Motion.AFFINE: 1>

RIGID = <Motion.RIGID: 0>

property name

property value

apply_registration(self: FeatureMapsRegistrationAlgorithm, params: ndarray[numpy.float64[m, 1]]) → None

batch_eval(self: FeatureMapsRegistrationAlgorithm, params: list[ndarray[numpy.float64[m, 1]]]) → list[ndarray[numpy.float64[m, 1]]]

bench_eval(self: FeatureMapsRegistrationAlgorithm, params: list[ndarray[numpy.float64[m, 1]]], num: int) → None

compute(self: FeatureMapsRegistrationAlgorithm) → None

eval(self: FeatureMapsRegistrationAlgorithm, params: ndarray[numpy.float64[m, 1]]) → ndarray[numpy.float64[m, 1]]

global_search(self: FeatureMapsRegistrationAlgorithm, lower_bound: ndarray[numpy.float64[m, 1]], upper_bound: ndarray[numpy.float64[m, 1]], population_size: int) → list[tuple[ndarray[numpy.float64[m, 1]], float]]

global_search(self: FeatureMapsRegistrationAlgorithm) → list[tuple[ndarray[numpy.float64[m, 1]], float]]

Function overload documentation:

global_search(self: FeatureMapsRegistrationAlgorithm, lower_bound: ndarray[numpy.float64[m, 1]], upper_bound: ndarray[numpy.float64[m, 1]], population_size: int) → list[tuple[ndarray[numpy.float64[m, 1]], float]]

global_search(self: FeatureMapsRegistrationAlgorithm) → list[tuple[ndarray[numpy.float64[m, 1]], float]]

num_evals(self: FeatureMapsRegistrationAlgorithm) → int

reset_pose(self: FeatureMapsRegistrationAlgorithm) → None

AFFINE = <Motion.AFFINE: 1>

RIGID = <Motion.RIGID: 0>

property motion

property quantize

class imfusion.registration.ImageRegistrationAlgorithm(self: ImageRegistrationAlgorithm, fixed: SharedImageSet, moving: SharedImageSet, model: TransformationModel = TransformationModel.LINEAR)

Bases: Algorithm

High-level interface for image registration. The image registration algorithm wraps several concrete image registration algorithms (e.g. linear and deformable) and extends them with pre-processing techniques. Available pre-processing options include downsampling and gradient-magnitude used for LC2. On creation, the algorithm tries to find the best settings for the registration problem depending on the modality, size and other properties of the input images. The image registration comes with a default set of different transformation models.

Parameters:

fixed – Input image that stays fixed during the registration.
moving – Input image that will be moving registration.
model – Defines the registration approach to use. Defaults to rigid / affine registration.

class PreprocessingOptions(self: PreprocessingOptions, value: int)

Bases: pybind11_object

Flags to enable/disable certain preprocessing options.

Members:

NO_PREPROCESSING : Disable preprocessing completely (this cannot be ORed with other options)

RESTRICT_MEMORY : Downsamples the images so that the registration will not use more than a given maximum of (video) memory

ADJUST_SPACING : if the spacing difference of both images is large, the spacing of the adjusted to the smaller one

IGNORE_FILTERING : Ignore any PreProcessingFilter required by the AbstractImageRegistration object

CACHE_RESULTS : Store PreProcessing results and only re-compute if necessary

NORMALIZE : Normalize images to float range [0.0, 1.0]

ADJUST_SPACING = <PreprocessingOptions.ADJUST_SPACING: 2>

CACHE_RESULTS = <PreprocessingOptions.CACHE_RESULTS: 16>

IGNORE_FILTERING = <PreprocessingOptions.IGNORE_FILTERING: 4>

NORMALIZE = <PreprocessingOptions.NORMALIZE: 32>

NO_PREPROCESSING = <PreprocessingOptions.NO_PREPROCESSING: 0>

RESTRICT_MEMORY = <PreprocessingOptions.RESTRICT_MEMORY: 1>

property name

property value

class TransformationModel(self: TransformationModel, value: int)

Bases: pybind11_object

Available transformation models. Each one represents a specific registration approach.

Members:

LINEAR : Rigid or affine DOF registration

FFD : Registration with non-linear Free-Form deformations

TPS : Registration with non-linear Thin-Plate-Splines deformations

DEMONS : Registration with non-linear dense (per-pixel) deformations

GREEDY_DEMONS : Registration with non-linear dense (per-pixel) deformations using patch-based SimilarityMeasures

POLY_RIGID : Registration with poly-rigid (i.e. partially piecewise rigid) deformations.

USER_DEFINED

DEMONS = <TransformationModel.DEMONS: 3>

FFD = <TransformationModel.FFD: 1>

GREEDY_DEMONS = <TransformationModel.GREEDY_DEMONS: 4>

LINEAR = <TransformationModel.LINEAR: 0>

POLY_RIGID = <TransformationModel.POLY_RIGID: 5>

TPS = <TransformationModel.TPS: 2>

USER_DEFINED = <TransformationModel.USER_DEFINED: 100>

property name

property value

compute_preprocessing(self: ImageRegistrationAlgorithm) → bool: Applies the pre-processing options on the input images. Results are cached so this is a no-op if the preprocessing options have not changed. This function is automatically called by the compute method, and therefore does not have to be explicitly called in most cases.

reset(self: ImageRegistrationAlgorithm) → None: Resets the transformation of moving to its initial transformation.

swap_fixed_and_moving(self: ImageRegistrationAlgorithm) → None: Swaps which image is considered fixed and moving.

ADJUST_SPACING = <PreprocessingOptions.ADJUST_SPACING: 2>

CACHE_RESULTS = <PreprocessingOptions.CACHE_RESULTS: 16>

DEMONS = <TransformationModel.DEMONS: 3>

FFD = <TransformationModel.FFD: 1>

GREEDY_DEMONS = <TransformationModel.GREEDY_DEMONS: 4>

IGNORE_FILTERING = <PreprocessingOptions.IGNORE_FILTERING: 4>

LINEAR = <TransformationModel.LINEAR: 0>

NORMALIZE = <PreprocessingOptions.NORMALIZE: 32>

NO_PREPROCESSING = <PreprocessingOptions.NO_PREPROCESSING: 0>

POLY_RIGID = <TransformationModel.POLY_RIGID: 5>

RESTRICT_MEMORY = <PreprocessingOptions.RESTRICT_MEMORY: 1>

TPS = <TransformationModel.TPS: 2>

USER_DEFINED = <TransformationModel.USER_DEFINED: 100>

property best_similarity: Returns the best value of the similarity measure after optimization.

property fixed: Returns input image that is currently considered to be fixed.

property is_deformable: Indicates whether the current configuration uses a deformable registration

property max_memory: Restrict the memory used by the registration to the given amount in mebibyte. The value can be set in any case but will only have an effect if the RestrictMemory option is enabled. This will restrict video memory as well. The minimum size is 64 MB (the value will be clamped).

property moving: Returns input image that is currently considered to be moving.

property optimizer: Reference to the underlying optimizer.

property param_registration: Reference to the underlying parametric registration object that actually performs the computation (e.g. parametric registration, deformable registration, etc.). Will return None if the transformation model is not parametric.

property preprocessing_options: Which options should be enabled for preprocessing. The options are bitwise OR combination of PreprocessingOptions.

property registration: Reference to the underlying registration object that actually performs the computation (e.g. parametric registration, deformable registration, etc.)

property transformation_model: Transformation model to be used for the registration. If the transformation model changes, internal objects will be deleted and recreated. The configuration of the current model will be saved and the new model will be configured with any previously saved configuration for that model. Any attached identity deformations are removed from both images.

property verbose: Indicates whether the algorithm is going to print additional and detailed info messages.

class imfusion.registration.ParametricImageRegistration: Bases: Algorithm

class imfusion.registration.RegistrationInitAlgorithm(self: RegistrationInitAlgorithm, image1: SharedImageSet, image2: SharedImageSet)

Bases: Algorithm

Initialize the registration of two volumes by moving the second one.

class Mode(self: Mode, value: int)

Bases: pybind11_object

Specifies how the distance between images should be computed.

Members:

BOUNDING_BOX

CENTER_OF_MASS

BOUNDING_BOX = <Mode.BOUNDING_BOX: 0>

CENTER_OF_MASS = <Mode.CENTER_OF_MASS: 1>

property name

property value

BOUNDING_BOX = <Mode.BOUNDING_BOX: 0>

CENTER_OF_MASS = <Mode.CENTER_OF_MASS: 1>

property mode: Initialization mode (align bounding box centers, or center of mass).

class imfusion.registration.RegistrationResults(self: RegistrationResults)

Bases: pybind11_object

Class responsible for handling and storing results of data registration. Provides functionality to add, remove, apply and manage registration results and their related data. RegistrationResults can be saved and loaded into ImFusion Registration Results (irr) files, potentially including data source information. When data source information is available this class can load the missing data to be able to apply the results. Each result contains a registration matrix and (when applicable) a deformation.

class Result

Bases: pybind11_object

apply(self: Result) → DataList: Applies the current result. Return: the list of affected data.

property ground_truth

property name

add(self: RegistrationResults, datalist: list[Data], name: str = '', ground_truth: bool = False) → None

clear(self: RegistrationResults) → None: Clears all results.

load_missing_data(self: RegistrationResults, result_index: int = -1) → list[Data]

remove(self: RegistrationResults, index: int) → bool: Removes the result at the given index.

resolve_data(self: RegistrationResults, datalist: list[Data]) → None

save(self: RegistrationResults, path: str | PathLike) → None

property has_ground_truth

property some_data_missing

property source_path: Returns the number of results.

class imfusion.registration.RegistrationResultsAlgorithm

Bases: Algorithm

property results

class imfusion.registration.VolumeBasedMeshRegistrationAlgorithm(self: VolumeBasedMeshRegistrationAlgorithm, fixed: Mesh, moving: Mesh, pointcloud: PointCloud = None)

Bases: Algorithm

Calculates a deformable registration between two meshes by calculating a deformable registration between distance volumes. Internally, an instance of the DemonsImageRegistration algorithm is used to register the “fixed” distance volume to the “moving” distance volume. As this registration computes the inverse of the mapping from the fixed to the moving volume, this directly yields a registration of the “moving” Mesh to the “fixed” Mesh.

imfusion.registration.apply_deformation(image: SharedImageSet, adjust_size: bool = True, nearest_interpolation: bool = False) → SharedImageSet

Creates a deformed image from the input image and its deformation.

Parameters:

image (SharedImageSet) – Input image assumed to have a deformation.
adjust_size (bool) – Whether the resulting image should adjust its size to encompass the deformation.
nearest_interpolation (bool) – Whether nearest or linear interpolation is used.

imfusion.registration.compute_rigid_pose_distance(first_pose: ndarray[numpy.float64[4, 4]], second_pose: ndarray[numpy.float64[4, 4]]) → object

Computes the distance in translation (mm) and rotation (degrees) between two rigid pose matrices.

Parameters:

first_pose – First pose matrix.
second_pose – Second pose matrix.

Returns:

namedtuple with fields ‘relative_rotation’ (degrees) and ‘relative_translation’ (millimeters)

imfusion.registration.load_registration_results(path: str) → RegistrationResults

imfusion.registration.scan_for_registration_results(directory: str) → list[RegistrationResults]

imfusion.graph

class imfusion.graph.Graph(self: Graph)

Bases: Data

Graph data structure consisting of nodes, edges, and features on either or both.

class GraphFeatureMode(self: GraphFeatureMode, value: int)

Bases: pybind11_object

Enum describing the feature computation mode used by compute_graph_features().

Members:

EDGE_LENGTH : Computes the geometric length of each edge.

EDGE_DIAMETER : Computes per-edge diameters derived directly from a label map.

EDGE_CROSS_SECTION : Computes the cross-sectional area of each edge using its diameter measurements.

NODE_DEGREE : Computes the degree of each node (i.e., number of incident edges).

VESSEL_DIAMETER : Computes vessel diameters using smoothing and clamping based on a label map.

EDGE_CROSS_SECTION = <GraphFeatureMode.EDGE_CROSS_SECTION: 2>

EDGE_DIAMETER = <GraphFeatureMode.EDGE_DIAMETER: 1>

EDGE_LENGTH = <GraphFeatureMode.EDGE_LENGTH: 0>

NODE_DEGREE = <GraphFeatureMode.NODE_DEGREE: 3>

VESSEL_DIAMETER = <GraphFeatureMode.VESSEL_DIAMETER: 4>

property name

property value

compute_graph_features(self: Graph, mode: GraphFeatureMode = GraphFeatureMode.EDGE_LENGTH, *, clamp_edges: bool = True, sliding_average: float | None = 3.0, label: SharedImageSet = None) → None

Computes common graph features such as edge lengths, diameters, and cross-sections and adds them to the underlying graph in-place.

Parameters:

mode –
The type of feature to compute
- EDGE_LENGTH: Compute edge lengths
- EDGE_DIAMETER: Compute edge diameters from label map
- EDGE_CROSS_SECTION: Compute edge cross-sections from diameters
- NODE_DEGREE: Compute node degrees
- VESSEL_DIAMETER: Compute vessel diameters with smoothing/clamping
clamp_edges: Optional boolean to apply clamping at segment ends when computing vessel diameters.
sliding_average: Optional integer specifying the size of the sliding window for median smoothing of computed diameters.
label – Optional SharedImageSet containing label map for diameter computation.

Example

>>> g.compute_graph_features(
...     mode=Graph.GraphFeatureMode.EDGE_DIAMETER,
...     label=label_image_set
... )

static extract_centerline_graph(image_set: SharedImageSet, *, close_holes_size: int = 2, min_component_size: int = 3, graph_smoothing: float = 2.0, prune_paths_sensitivity: float = 1.0, remove_cycles: bool = False) → Graph

Extracts the centerline graph from the given image set.

Parameters:

image_set – The input SharedImageSet containing images to process.
close_holes_size – Optional parameter kernel size in pixel for closing holes (label preprocessing).
min_component_size – Disconnected components of the graph smaller than this size (in nodes) are removed.
graph_smoothing – Optional parameter which governs degree of smoothing of computed path.
prune_paths_sensitivity – Optional parameter to govern extent to which small paths are pruned (more paths removed for higher sensitivity values).
remove_cycles – Optional parameter to apply the MinimumSpanningTree algorithm to remove cycles.

Returns:

Graph object representing the extracted centerlines.

Example:

>>> graph = Graph.extract_centerline_graph(
...     image_set,
... )

static from_graphml(file_path: str | PathLike) → Graph

Load a graph from a GraphML file.

Args:
file_path: Path to the input .graphml file.

Returns:
Loaded graph object.

Example

graph = imf.graph.Graph.from_graphml(“/path/file.graphml”) # creates a Graph instances from a gaphml file on disk

to_graphml(self: Graph, file_path: str | PathLike) → None

Save a Graph as GraphML to the specified file path.

Parameters:

graph – Graph to save.
file_path – Path to output file.

Example

>>> from imfusion.graph import Graph
>>> g = Graph(..)
>>> g.to_graphml("/path/file.graphml") # Saves the Graph as a graphml file

property num_edge_features

property num_edges

property num_node_features

property num_nodes

imfusion.ultrasound

The imfusion.ultrasound package exposes Python bindings for offline (non-streaming) ultrasound processing in ImFusion: freehand sweeps, frame geometry and metadata, compounding and reslicing, scan conversion, clip processing, and related registration or calibration helpers.

Typical use is to start from an UltrasoundSweep (or data convertible to one) and call the high-level free functions or algorithm classes bound on the module. Install the ultrasound module with pip install 'imfusion-sdk[ultrasound]' (see Installation).

For detailed documentation of specific classes and functions, use Python’s built-in help() function or access the docstrings directly.

Examples

Short workflows below complement the full API listing in Reference.

Loading sweeps

imfusion.load() returns a list of all Data subclasses which are stored in the file (see its docstring). Native ultrasound sweep blocks in .imf files deserialize as UltrasoundSweep. Many acquisitions are stored instead as TrackedSharedImageSet or SharedImageSet; those are not automatically an UltrasoundSweep. In that case call convert_to_sweep() on the image set (and pass tracking_sequence= explicitly when tracking is not already attached to the set).

import imfusion
import imfusion.ultrasound as us

first = imfusion.load("/path/to/sweep.imf")[0]
sweep = first if isinstance(first, us.UltrasoundSweep) else us.convert_to_sweep(first)

# view and scroll through the sweep using the ImFusionVisualizer
imfusion.show([sweep])

Exploring an `UltrasoundSweep`

UltrasoundSweep subclasses TrackedSharedImageSet, so you can use inherited methods for frames, poses, and tracking (for example len(sweep), sweep.focus, sweep.mem(i), sweep.tracking()). Ultrasound-specific helpers also expose frame_geometry(), bounding-box queries and other sweep properties.

import imfusion
import imfusion.ultrasound as us

sweep = imfusion.load("/path/to/sweep.imf")[0]

n = len(sweep)
geom = sweep.frame_geometry()
gbox = sweep.global_bounding_box(use_selection=False, use_frame_geometry=True)

print(sweep)
print(geom)
print("Depth:", geom.depth, "Coordinate system:", geom.coordinate_system)
print("Global bbox center:", gbox.center, "Extent:", gbox.extent)

ts = sweep.tracking()
print("tracking samples:", ts.size if ts is not None else None)

Compounding

An UltrasoundSweep can be compounded into a regularly sampled 3D volume for tasks that cannot be performed with sweeps natively, such as the application of 3D machine learning models (e.g. segmentation)”.

import imfusion
import imfusion.ultrasound as us

first = imfusion.load("/path/to/sweep.imf")[0]
sweep = first if isinstance(first, us.UltrasoundSweep) else us.convert_to_sweep(first)

volume = us.compound_sweep(
    sweep,
    mode=us.CompoundingMode.GPU,
    bounding_box_mode=us.CompoundingBoundingBoxMode.HEURISTIC_ALIGNMENT,
)

Registration

register_sweep_to_volume() aligns a sweep to a tomographic reference (for example CT or MRI). The sweep must carry a valid tracking sequence (see sweep.tracking() above). LC2 similarity is the standard intensity-based option; DISA is available only when the ML stack is present—see Similarity and the reference.

import imfusion
import imfusion.ultrasound as us

sweep = imfusion.load("/path/to/sweep.imf")[0]
ct = imfusion.load("/path/to/ct.imf")[0]

us.register_sweep_to_volume(
    sweep,
    ct,
    similarity=us.Similarity.LC2,
    move_sweep=True,
    spacing_mm=1.0,
)

For finer control (modes, initialization, slice-based registration), use UltrasoundRegistrationAlgorithm and its methods such as prepare_data() and compute().

Note: This module requires the ImFusion US plugin to be properly installed and licensed.

class imfusion.ultrasound.CalibrationMultisweepMode(self: CalibrationMultisweepMode, value: int)

Bases: pybind11_object

Mode for handling multiple sweeps in ultrasound calibration.

Members:

CONCATENATE : The first half of sweeps are used to reconstruct frames from the second half, and vice versa. Useful for expanding the lateral field of view (e.g., with two shifted acquisitions for each orientation).

SUCCESSIVE_PAIRS : Each pair of successive sweeps is calibrated together and included in the same cost function. Useful for imaging different calibration objects with pairs of sweeps, improving stability by joint optimization.

CONCATENATE = <CalibrationMultisweepMode.CONCATENATE: 0>

SUCCESSIVE_PAIRS = <CalibrationMultisweepMode.SUCCESSIVE_PAIRS: 1>

property name

property value

class imfusion.ultrasound.CalibrationSimilarityMeasureConfig(self: CalibrationSimilarityMeasureConfig, mode: int, patch_size: int = 9)

Bases: pybind11_object

Configuration for similarity measure used in ultrasound calibration.

property mode: Mode of similarity measure used for ultrasound calibration: SAD (0): Sum of Absolute Differences. Measures similarity by summing the absolute differences between corresponding pixel values. SSD (1): Sum of Squared Differences. Measures similarity by summing the squared differences between corresponding pixel values. NCC (2): Normalized Cross-Correlation. Measures similarity by computing the normalized correlation between image patches. LNCC (3): Local Normalized Cross-Correlation. Measures similarity using normalized cross-correlation computed over local regions.

property patch_size: Patch size for the local regions of the LNCC similarity measure, in pixels.

class imfusion.ultrasound.CompoundingBoundingBoxMode(self: CompoundingBoundingBoxMode, value: int)

Bases: pybind11_object

Output volume bounding box orientation mode for the compound_sweep function.

Members:

GLOBAL_COORDINATES : Bounding box axes are aligned to global coordinate axes

FRAME_NORMAL : First bounding box axis is derived as mean frame normal vector

HEURISTIC_ALIGNMENT : Bounding box axes are derived from a combination of frame normal and PCA of image center points

FIT_BOUNDING_BOX : Fitted minimal bounding box

FIT_BOUNDING_BOX = <CompoundingBoundingBoxMode.FIT_BOUNDING_BOX: 3>

FRAME_NORMAL = <CompoundingBoundingBoxMode.FRAME_NORMAL: 1>

GLOBAL_COORDINATES = <CompoundingBoundingBoxMode.GLOBAL_COORDINATES: 0>

HEURISTIC_ALIGNMENT = <CompoundingBoundingBoxMode.HEURISTIC_ALIGNMENT: 2>

property name

property value

class imfusion.ultrasound.CompoundingMode(self: CompoundingMode, value: int)

Bases: pybind11_object

Compounding method for the compound_sweep function.

Members:

GPU : GPU-based direct compounding with linear interpolation.

GPU_NEAREST : GPU-based direct compounding with nearest neighbor interpolation.

GPU_BACKWARD : GPU-based backward compounding with linear interpolation.

GPU = <CompoundingMode.GPU: 0>

GPU_BACKWARD = <CompoundingMode.GPU_BACKWARD: 8>

GPU_NEAREST = <CompoundingMode.GPU_NEAREST: 1>

property name

property value

class imfusion.ultrasound.CoordinateSystem(self: CoordinateSystem, value: int)

Bases: pybind11_object

Coordinate system the geometry is defined in. See Coordinate Systems.

Members:

PIXELS

IMAGE

IMAGE = <CoordinateSystem.IMAGE: 1>

PIXELS = <CoordinateSystem.PIXELS: 0>

property name

property value

class imfusion.ultrasound.FrameGeometry

Bases: pybind11_object

Represents the (fan) geometry of an ultrasound frame.

Currently, there are four types of possible frame geometries:

Linear: The scanlines are parallel to each other and originate from a flat transducer array, i.e. shaped like a parallelogram.

Convex: The scanlines diverge from a virtual center point somewhere inside or behind a curved transducer array, i.e. shaped like a ring sector.

Sector: The scanlines diverge from a virtual center point somewhere inside or behind a linear transducer array, i.e. shaped like a trapezoid, with an optionally round bottom.

Circular: The scanlines extend radially from a center point up to a given radius. Unlike the other two geometries above, the offset is the center of ring.

Each type is implemented on its own separate class, but they all share common properties:

Support image and pixel coordinate system. The method convertTo() can be used to convert between the two.

The offset is the center of the transducer array in the coordinate system. As ultrasounds frames are defined top-left, the offset is given relative to the image center in image coordinates, and top left corner in pixel coordinates.

Can be defined top-down or bottom-up for convenience. For instance, prostate ultrasounds are usually bottom-up.

The orientation indicator refers to a physical landmark on the transducers to help physicians identify left and right when they hold the probe. Only influences how the ruler triangle is rendered.

See the C++ documentation for more details on geometry types and coordinate systems.

class OrientationIndicatorPosition(self: OrientationIndicatorPosition, value: int)

Bases: pybind11_object

Position of the external orientation indicator (e.g. colored knob) on the probe.

Members:

NEARSIDE : Indicator is at the near side of the US frame (close to the first beam)

FARSIDE : Indicator is at the far side of the US frame (close to the last beam)

FARSIDE = <OrientationIndicatorPosition.FARSIDE: 1>

NEARSIDE = <OrientationIndicatorPosition.NEARSIDE: 0>

property name

property value

class TransformationMode(self: TransformationMode, value: int)

Bases: pybind11_object

Used in transform_point() to specify which geometric transformation to apply.

Members:

NORM_PRESCAN_TO_SCAN_CONVERTED : Transformation from normalized pre-scanconverted coordinates to scan-converted coordinates.

SCAN_CONVERTED_TO_NORM_PRESCAN : Transformation from scan-converted coordinates to normalized pre-scanconverted coordinates.

NORM_PRESCAN_TO_SCAN_CONVERTED = <TransformationMode.NORM_PRESCAN_TO_SCAN_CONVERTED: 0>

SCAN_CONVERTED_TO_NORM_PRESCAN = <TransformationMode.SCAN_CONVERTED_TO_NORM_PRESCAN: 1>

property name

property value

clone(self: FrameGeometry) → FrameGeometry: Clones the current frame geometry, including the image descriptor.

contains(self: FrameGeometry, coordinate: ndarray[numpy.float64[2, 1]]) → bool: Returns true if the given point is within the fan.

convert_to(self: FrameGeometry, coordinate_system: CoordinateSystem) → FrameGeometry: Returns a copy where internal values were converted to new units.

is_similar(self: FrameGeometry, other: FrameGeometry, ignore_offset: bool = False, eps: float = 0.1) → bool: True if the given frame geometry is similar to this one, within a given tolerance.

transform_point(self: FrameGeometry, p: ndarray[numpy.float64[2, 1]], mode: TransformationMode) → ndarray[numpy.float64[2, 1]]: Applies the specified geometric transformation to a point.

FARSIDE = <OrientationIndicatorPosition.FARSIDE: 1>

NEARSIDE = <OrientationIndicatorPosition.NEARSIDE: 0>

NORM_PRESCAN_TO_SCAN_CONVERTED = <TransformationMode.NORM_PRESCAN_TO_SCAN_CONVERTED: 0>

SCAN_CONVERTED_TO_NORM_PRESCAN = <TransformationMode.SCAN_CONVERTED_TO_NORM_PRESCAN: 1>

property coordinate_system: Coordinate system used in the frame geometry.

property depth: Depth of the frame geometry, in mm or pixels, depending on the coordinate system.

property frame_center: Returns the center of the frame, in mm or pixels, depending on the coordinate system.

property img_desc: ImageDescriptor for the frame geometry.

property img_desc_prescan: ImageDescriptor for the image before scan conversion (scanlines).

property indicator_pos: Position of the external orientation indicator (e.g. colored knob).

property is_circular: True if geometry is circular type.

property is_convex: True if geometry is convex type.

property is_linear: True if geometry is linear type.

property is_sector: True if geometry is sector type.

property offset: Offset of the geometry within the image.

property top_down

top-down or bottom-up.

Type:: Orientation of the geometry

class imfusion.ultrasound.FrameGeometryCircular(self: FrameGeometryCircular, *, coord_sys: CoordinateSystem, depth: float = 0.0, top_down: bool = True, offset: ndarray[numpy.float64[2, 1]] = array([0., 0.]), indicator_pos: OrientationIndicatorPosition = OrientationIndicatorPosition.NEARSIDE, img_desc: ImageDescriptor = None, img_desc_prescan: ImageDescriptor = None, short_radius: float = 0.0, long_radius: float = 0.0)

Bases: FrameGeometry

FrameGeometry specialization for circular frame geometries.

Specialization for circular frame geometries. The US frame is defined by the ring between the short and long radii relative to some center point.

Parameters:

coord_sys – Coordinate system of the geometry.
depth – Depth of the frame annulus, in mm or pixels, depending on the coordinate system.
top_down – If True, the offset is at the top center of the frame; otherwise at the bottom.
offset – 2D offset of the frame origin, in coordinate system units.
indicator_pos – Position of the orientation indicator on the frame.
img_desc – Optional image descriptor associated with the frame.
img_desc_prescan – Optional pre-scan image descriptor associated with the frame.
short_radius – Inner radius of the frame annulus, in mm or pixels, depending on the coordinate system.
long_radius – Outer radius of the frame annulus, in mm or pixels, depending on the coordinate system.

Returns:

The constructed FrameGeometryCircular instance.

property depth: Depth of the frame annulus, in mm or pixels, depending on the coordinate system.

property long_radius: Long radius of the frame annulus, in mm or pixels, depending on the coordinate system.

property short_radius: Inner radius of the frame annulus, in mm or pixels, depending on the coordinate system.

class imfusion.ultrasound.FrameGeometryConvex(self: FrameGeometryConvex, *, coord_sys: CoordinateSystem, depth: float = 0.0, top_down: bool = True, offset: ndarray[numpy.float64[2, 1]] = array([0., 0.]), indicator_pos: OrientationIndicatorPosition = OrientationIndicatorPosition.NEARSIDE, img_desc: ImageDescriptor = None, img_desc_prescan: ImageDescriptor = None, opening_angle: float = 0.0, short_radius: float = 0.0, long_radius: float = 0.0)

Bases: FrameGeometry

FrameGeometry specialization for convex frame geometries.

Specialization for convex frame geometries. The US frame is defined by the ring sector between a short and a long radius. The angular width of this sector is defined by the aperture angle around the vertical line.

Parameters:

coord_sys – Coordinate system of the geometry.
depth – Depth of the frame sector, in mm or pixels, depending on the coordinate system.
top_down – If True, the offset is at the top center of the frame; otherwise at the bottom.
offset – 2D offset of the frame origin, in coordinate system units.
indicator_pos – Position of the orientation indicator on the frame.
img_desc – Optional image descriptor associated with the frame.
img_desc_prescan – Optional pre-scan image descriptor associated with the frame.
opening_angle – Opening angle of the frame sector [deg]. Measured from the vertical line.
short_radius – Inner radius of the frame sector, in mm or pixels, depending on the coordinate system.
long_radius – Outer radius of the frame sector, in mm or pixels, depending on the coordinate system.

Returns:

The constructed FrameGeometryConvex instance.

apex(self: FrameGeometryConvex) → ndarray[numpy.float64[2, 1]]: The virtual point beyond the probe surface where all the rays would intersect.

property depth: Depth of the frame sector, in mm or pixels, depending on the coordinate system. Adapts the long radius.

property long_radius: Outer radius of the frame sector, in mm or pixels, depending on the coordinate system.

property opening_angle: Opening angle of the frame sector [deg]. Measured from the vertical line.

property short_radius: Inner radius of the frame sector, in mm or pixels, depending on the coordinate system.

class imfusion.ultrasound.FrameGeometryLinear(self: FrameGeometryLinear, *, coord_sys: CoordinateSystem, width: float = 0.0, depth: float = 0.0, steering_angle: float = 0.0, top_down: bool = True, offset: ndarray[numpy.float64[2, 1]] = array([0., 0.]), indicator_pos: OrientationIndicatorPosition = OrientationIndicatorPosition.NEARSIDE, img_desc: ImageDescriptor = None, img_desc_prescan: ImageDescriptor = None)

Bases: FrameGeometry

FrameGeometry specialization for linear frame geometries.

Specialization for linear frame geometries. The US frames are defined by a parallelogram of width, height and steering.

Parameters:

coord_sys – Coordinate system of the geometry.
width – Width of the frame sector, in mm or pixels, depending on the coordinate system.
depth – Depth of the frame sector, in mm or pixels, depending on the coordinate system.
steering_angle – Steering angle of the frame sector [deg]. Positive when tilted to the right.
top_down – If True, the offset is at the top center of the frame, otherwise at the bottom.
offset – 2D offset of the frame origin, in coordinate system units.
indicator_pos – Position of the orientation indicator on the frame.
img_desc – Optional image descriptor associated with the frame.
img_desc_prescan – Optional pre-scan image descriptor associated with the frame.

Returns:

The constructed FrameGeometryLinear instance.

property depth: Depth of the frame sector, in mm or pixels, depending on the coordinate system.

property steering_angle: Steering angle of the frame sector [deg]. Positive when tilted to the right.

property width: Width of the frame sector, in mm or pixels, depending on the coordinate system.

class imfusion.ultrasound.FrameGeometryMetadata(self: FrameGeometryMetadata, *, frame_geometry: FrameGeometry | None = None)

Bases: DataComponentBase

Holds metadata for a frame geometry, including configuration and reference to the geometry object.

Metadata for the frame geometry of an ultrasound sweep.

Parameters:: frame_geometry – Optional FrameGeometry object to initialize the metadata. If provided, the geometry must have a valid image descriptor, otherwise an exception is thrown.
Returns:: The constructed FrameGeometryMetadata instance.

property frame_geometry: Returns the associated FrameGeometry object.

class imfusion.ultrasound.FrameGeometrySector(self: FrameGeometrySector, *, coord_sys: CoordinateSystem, depth: float = 0.0, top_down: bool = True, offset: ndarray[numpy.float64[2, 1]] = array([0., 0.]), indicator_pos: OrientationIndicatorPosition = OrientationIndicatorPosition.NEARSIDE, img_desc: ImageDescriptor = None, img_desc_prescan: ImageDescriptor = None, opening_angle: float = 0.0, short_radius: float = 0.0, long_radius: float = 0.0, bottom_curvature: float = 0.0)

Bases: FrameGeometry

FrameGeometry specialization for sector frame geometries.

Specialization for sector frame geometries. The US frame is defined as the trapezoid inscribed inside the ring sector between a short and a long radius, such that the middle point of top side of the trapezoid is tangent to the inner ring, and the lateral sides are fully contained within the sector straight sides. The bottom side can be straight or present a bottom curvature.

Parameters:

coord_sys – Coordinate system of the geometry.
depth – Depth of the frame sector, in mm or pixels, depending on the coordinate system.
top_down – If True, the offset is at the top center of the frame; otherwise at the bottom.
offset – 2D offset of the frame origin, in coordinate system units.
indicator_pos – Position of the orientation indicator on the frame.
img_desc – Optional image descriptor associated with the frame.
img_desc_prescan – Optional pre-scan image descriptor associated with the frame.
opening_angle – Opening angle of the frame sector [deg]. Measured from the vertical line.
short_radius – Inner radius of the frame sector, in mm or pixels, depending on the coordinate system.
long_radius – Outer radius of the frame sector, in mm or pixels, depending on the coordinate system.
bottom_curvature – Curvature of the bottom line (0.0 is flat, 1.0 full circle).

Returns:

The constructed FrameGeometrySector instance.

apex(self: FrameGeometrySector) → ndarray[numpy.float64[2, 1]]: The virtual point beyond the probe surface where all the rays would intersect.

property bottom_curvature: Curvature of the bottom line (0.0 is flat, 1.0 full circle).

property depth: Depth of the frame sector, in mm or pixels, depending on the coordinate system. Adapts the long radius.

property long_radius: Outer radius of the frame sector, in mm or pixels, depending on the coordinate system.

property opening_angle: Opening angle of the frame sector [deg]. Measured from the vertical line.

property short_radius: Inner radius of the frame sector, in mm or pixels, depending on the coordinate system.

class imfusion.ultrasound.GlProbeDeformation(self: GlProbeDeformation, dist_img: SharedImageSet = None)

Bases: Deformation

Deformation model for a radial compression emanating from an ultrasound probe. Supports configuration of geometric parameters such as the probe position and compression radii, as well as deformation characteristics like amplitude and non-linearity.

GlProbeDeformation constructor.

Creates a new GlProbeDeformation simulating radial compression from an ultrasound probe.

Parameters:: dist_img – Optional ultrasound sweep containing the deformation parameters.
Returns:: class: GlProbeDeformation instance.
Return type:: A

set_probe_parameters(self: GlProbeDeformation, sweep_or_volume: SharedImageSet) → None: Set the geometric parameters of the compression model from the ultrasound sweep.

property amplitude: Amount of the overall compression.

property bulge_amp: Additional bulging away from the central beam axis.

property bulge_shape: Controls how the amount of bulging scales with depth.

property deformation_non_linearity: Non-linearity, higher means more deformed at smaller radius.

property mode: Deformation mode (0=spherical,1=ellipsoid,2=distance volume,4=bulging).

property probe_elev_ratio: Elevational expansion ratio of probe model.

property probe_position: Position of the compression origin in world coordinates.

property probe_radius_max: Radius where the change in compression ends.

property probe_radius_min: Radius where the change in compression starts.

class imfusion.ultrasound.ProcessUltrasound(self: ProcessUltrasound, *, parameters: ProcessUltrasoundParameters)

Bases: Configurable

Processes ultrasound data, applying various corrections and enhancements.

ProcessUltrasound constructor.

Creates a new ProcessUltrasound object for processing 2D/3D ultrasound data, the object manages the FrameGeometry and processes a single frame according to its parameters, and can remove duplicate frames calling remove_duplicate_frames internally.

Parameters:: parameters – A ProcessUltrasoundParameters instance specifying the processing options.
Returns:: A ProcessUltrasound instance.

set_remove_duplicates(self: ProcessUltrasound, arg0: bool) → None: If true, removes duplicate frames during processing.

update_geometry(self: ProcessUltrasound, geom: FrameGeometry, depth: float) → None: Updates the geometry with a new FrameGeometry and depth.

property parameters: Processing parameters.

class imfusion.ultrasound.ProcessUltrasoundParameters(self: ProcessUltrasoundParameters, *, apply_crop: bool = False, apply_mask: bool = False, apply_depth: bool = False, depth: float = 0.0, remove_color_threshold: bool = False, inpaint: bool = False, extra_crop: ndarray[numpy.int32[4, 1]] = array([0, 0, 0, 0], dtype=int32), use_absolute_extra_crop: bool = False)

Bases: pybind11_object

Parameters for processing ultrasound data, such as cropping, masking, and depth adjustment.

ProcessUltrasoundParameters constructor.

Creates a new set of parameters for processing ultrasound images.

Parameters:

apply_crop – If True, cropping is applied to the input images (default: False).
apply_mask – If True, masking is applied (default: False).
apply_depth – If True, depth adjustment is applied (default: False).
depth – Depth value for processing in millimeters (default: 0.0).
remove_color_threshold – If True, pixels above the color threshold are removed (default: False).
inpaint – If True, inpainting is applied to fill missing regions (default: False).
extra_crop – Optional additional cropping margins as a 4-tuple (left, right, top, bottom) (default: (0,0,0,0)).
use_absolute_extra_crop – If True, extra_crop is relative to the original image; otherwise, it is applied on top of already cropped region (default: False).

Returns:

A ProcessUltrasoundParameters instance.

property apply_crop: If true, cropping is applied.

property apply_depth: If true, depth adjustment is applied.

property apply_mask: If true, masking is applied.

property depth: Depth value for processing.

property extra_crop: Extra cropping margins (left,right,top,bottom).

property inpaint: If true, inpainting is applied.

property remove_color_threshold: If > 0, color pixels are set to zero with given threshold.

property use_absolute_extra_crop: If true, extra cropping margins are w.r.t. the original image stream, otherwise - on top of the already clipped fan

class imfusion.ultrasound.Similarity(self: Similarity, value: int)

Bases: pybind11_object

Similarities for ultrasound registration

Members:

LC2 : LC2 (Linear Correlation of Linear Combination) similarity.

DISA : DISA (Differentiable Similarity Approximation) similarity. Requires ML module.

DISA = <Similarity.DISA: 1>

LC2 = <Similarity.LC2: 0>

property name

property value

class imfusion.ultrasound.SweepCalibrator(self: SweepCalibrator, *, forces_no_probe_names: bool = False)

Bases: Configurable

Performs calibration of tracked ultrasound sweeps.

SweepCalibrator constructor.

Creates a new SweepCalibrator object, which can be used to calibrate UltrasoundSweep data.

Parameters:: forces_no_probe_names – If True, disables probe name checks during calibration (default: False).
Returns:: A SweepCalibrator instance.

add_tip_of_probe_calibration(self: SweepCalibrator, matrix: ndarray[numpy.float64[4, 4]], probe_name: str = '') → None

add_tip_of_probe_calibration(self: SweepCalibrator, sweep: UltrasoundSweep) → None

Function overload documentation:

add_tip_of_probe_calibration(self: SweepCalibrator, matrix: ndarray[numpy.float64[4, 4]], probe_name: str = '') → None: Adds a tip-of-probe calibration matrix for a given probe name.

add_tip_of_probe_calibration(self: SweepCalibrator, sweep: UltrasoundSweep) → None: Adds a tip-of-probe calibration from a sweep.

calibrate(self: SweepCalibrator, sweep: UltrasoundSweep) → bool: Performs calibration on the given sweep.

calibration_data_count(self: SweepCalibrator, probe_name: str = '') → int: Returns the number of calibration data entries for a given probe name.

static find_depth(sweep: UltrasoundSweep) → float: Finds the imaging depth for a given sweep.

static find_probe_name(sweep: UltrasoundSweep) → str: Finds the probe name for a given sweep.

remove_calibration_data(self: SweepCalibrator, probe_name: str) → None: Removes calibration data for a given probe name.

rename_calibration_data(self: SweepCalibrator, old_name: str, new_name: str) → None: Renames calibration data from old_name to new_name.

tip_of_probe_calibration(self: SweepCalibrator, probe_name: str = '') → ndarray[numpy.float64[4, 4]] | None: Returns the tip-of-probe calibration matrix for a given probe name.

property forces_no_probe_names: If true, disables probe name checks during calibration.

property known_probes: List of known probe names with calibration data.

class imfusion.ultrasound.UltrasoundDISARegistrationAlgorithm(self: UltrasoundDISARegistrationAlgorithm, *, sweep: UltrasoundSweep, volume: SharedImageSet, weight: SharedImageSet | None = None, spacing: float = 1.0, mode: Mode = Mode.LOCAL, weighting: WeightType = WeightType.GENERIC, probe_deformation: bool = False, consider_point_correspondences: bool = False, ultrasound_model_path: str = '', volume_model_path: str = '', weight_model_path: str = '')

Bases: Algorithm

Performs deep learning-based registration of ultrasound sweeps.

UltrasoundDISARegistrationAlgorithm constructor.

Initializes algorithm for registering an ultrasound sweep to a volume using DISA.

Parameters:

sweep – The input UltrasoundSweep to register.
volume – The reference SharedImageSet volume.
weight – Optional SharedImageSet containing voxel-wise weights (default: None).
spacing – Resampling spacing in mm for the sweep and volume (default: 1.0).
mode – Registration mode, either Mode.LOCAL or Mode.GLOBAL (default: Mode.LOCAL).
weighting – Type of feature weighting to use (WeightType.GENERIC, WeightType.ABDOMEN, WeightType.BRAIN) (default: GENERIC).
probe_deformation – If True, applies a probe deformation model during registration (default: False).
consider_point_correspondences – If True, penalizes distance of point correspondences > 10mm (default: False).
ultrasound_model_path – Path to a custom ML model for ultrasound feature extraction (default: empty string).
volume_model_path – Path to a custom ML model for volume feature extraction (default: empty string).
weight_model_path – Path to a custom ML model for computing weighting (default: empty string).

Returns:

A UltrasoundDISARegistrationAlgorithm instance.

class Mode(self: Mode, value: int)

Bases: pybind11_object

DISA registration mode

Members:

LOCAL : Local registration using the BFGS optimizer

GLOBAL : Global registration using multiple BFGS optimizers with different starting parameters

GLOBAL = <Mode.GLOBAL: 1>

LOCAL = <Mode.LOCAL: 0>

property name

property value

class WeightType(self: WeightType, value: int)

Bases: pybind11_object

DISA registration weight type

Members:

GENERIC : Generic weight based on local variance of voxel intensities

ABDOMEN : Uses a specialized CNN to compute the weight for abdominal ultrasound

BRAIN : Uses a specialized CNN to compute the weight for brain ultrasound

ABDOMEN = <WeightType.ABDOMEN: 1>

BRAIN = <WeightType.BRAIN: 2>

GENERIC = <WeightType.GENERIC: 0>

property name

property value

initialize_pose(self: UltrasoundDISARegistrationAlgorithm) → None: Moves the sweep to a default pose relative to the volume.

prepare(self: UltrasoundDISARegistrationAlgorithm) → bool: Performs preprocessing and feature extraction. returns True if successful, false otherwise.

ABDOMEN = <WeightType.ABDOMEN: 1>

BRAIN = <WeightType.BRAIN: 2>

GENERIC = <WeightType.GENERIC: 0>

GLOBAL = <Mode.GLOBAL: 1>

LOCAL = <Mode.LOCAL: 0>

property mode: Registration mode.

property probe_deformation: If True, applies a probe deformation model during registration

property spacing: Resampling spacing in mm for the sweep and volume.

property weighting: Type of feature weighting used.

class imfusion.ultrasound.UltrasoundMetadata(self: UltrasoundMetadata, *, scan_mode: ScanMode = ScanMode.BMODE, device: str = '', probe: str = '', preset: str = '', scan_converted: bool = True, image_enhanced: bool = False, number_of_beams: int = 0, samples_per_beam: int = 0, start_depth: float = 0.0, end_depth: float = 0.0, focal_depth: float = 0.0, brightness: float = 0.0, dynamic_range: float = 0.0, frequency: float = 0.0)

Bases: DataComponentBase

Holds metadata for an ultrasound frame, such as scan mode, device, probe, and imaging parameters.

Metadata for a medical ultrasound image.

See US.FrameGeometryMetadata for the description of a frame’s geometry.

Parameters:

scan_mode – Principal ultrasound imaging mode. One of UltrasoundMetadata.ScanMode`.
device – Manufacturer and device description.
probe – Probe model used for imaging.
preset – Name of the imaging preset used.
scan_converted – True if the image is scan-converted.
image_enhanced – True if filtering or enhancement has been applied.
number_of_beams – Number of scanline beams used to form the image.
samples_per_beam – Number of samples used per beam.
start_depth – Start depth of the imaging region in [mm].
end_depth – End depth of the imaging region in [mm].
focal_depth – Focal depth if applicable in [mm].
brightness – Brightness setting.
dynamic_range – Dynamic range setting.
frequency – Transducer frequency in MHz.

Returns:

The constructed US.UltrasoundMetadata instance.

class ScanMode(self: ScanMode, value: int)

Bases: pybind11_object

Members:

BMODE : Standard B-Mode ultrasound

PDI : Power Doppler Imaging

PWD : Pulsed Wave Doppler Imaging

CFM : Color Flow Mapping

THI : Tissue Harmonic Imaging

MMODE : M-Mode ultrasound imaging

OTHER : Other or undefined mode

BMODE = <ScanMode.BMODE: 0>

CFM = <ScanMode.CFM: 3>

MMODE = <ScanMode.MMODE: 5>

OTHER = <ScanMode.OTHER: 6>

PDI = <ScanMode.PDI: 1>

PWD = <ScanMode.PWD: 2>

THI = <ScanMode.THI: 4>

property name

property value

BMODE = <ScanMode.BMODE: 0>

CFM = <ScanMode.CFM: 3>

MMODE = <ScanMode.MMODE: 5>

OTHER = <ScanMode.OTHER: 6>

PDI = <ScanMode.PDI: 1>

PWD = <ScanMode.PWD: 2>

THI = <ScanMode.THI: 4>

property brightness: Brightness setting.

property depth: Returns the imaging depth in [mm].

property device: Device name or identifier.

property dynamic_range: Dynamic range setting.

property end_depth: End depth of the imaging region in [mm].

property focal_depth: Focal depth of the imaging region in [mm].

property frequency: Imaging frequency.

property image_enhanced: True if the image is enhanced.

property number_of_beams: Number of beams in the frame.

property preset: Imaging preset used for acquisition.

property probe: Probe name or identifier.

property samples_per_beam: Number of samples per beam.

property scan_converted: True if the image is scan-converted.

property scan_mode: Scan mode of the ultrasound frame.

property start_depth: Start depth of the imaging region in [mm].

class imfusion.ultrasound.UltrasoundRegistrationAlgorithm(self: UltrasoundRegistrationAlgorithm, us_volume_or_sweep: SharedImageSet, tomographic_volume: SharedImageSet, *, distance_volume: SharedImageSet | None = None, target_volume_spacing_mm: float = 1.0, relative_sweep_spacing_percent: int = 100, use_probe_compression: bool = False, is_ultrasound_moving: bool = False, initialization_mode: InitializationMode = InitializationMode.NONE, use_slice_based: bool = False, optimize_gating_offset: bool = False)

Bases: Algorithm

Registration of an ultrasound sweep or volume to a tomographic scan (CT or MRI).

UltrasoundRegistrationAlgorithm constructor.

Initializes a registration algorithm that aligns an ultrasound sweep or volume to a tomographic reference volume (e.g., CT or MRI).

Parameters:

us_volume_or_sweep – Input ultrasound sweep or compounded volume.
tomographic_volume – Tomographic volume (CT or MRI) to register against.
distance_volume – Optional distance volume for probe compression.
target_volume_spacing_mm – Spacing (millimeters) of the tomographic volume.
relative_sweep_spacing_percent – Relative spacing (percent) of the ultrasound sweep with respect to the tomographic volume.
use_probe_compression – Whether to use a probe compression deformation model.
is_ultrasound_moving – Specifies if the ultrasound data is the moving image in registration.
initialization_mode – Initialization mode for registration.
use_slice_based – Use slice-to-volume (2D-3D) registration instead of 3D-3D registration.
optimize_gating_offset –
If true, optimizes the gating metadata phase offset.

returns:

An instance of UltrasoundRegistrationAlgorithm.

class InitializationMode(self: InitializationMode, value: int)

Bases: pybind11_object

Initialization modes for ultrasound registration.

Members:

NONE : No initialization.

PREDICTION_MAPS : Use prediction maps for initialization.

DISA_GLOBAL : Use DISA global search for initialization.

DISA_GLOBAL = <InitializationMode.DISA_GLOBAL: 2>

NONE = <InitializationMode.NONE: 0>

PREDICTION_MAPS = <InitializationMode.PREDICTION_MAPS: 1>

property name

property value

class RegistrationMode(self: RegistrationMode, value: int)

Bases: pybind11_object

Registration modes that are used sequentially within the pipeline. Multiple modes can be combined.

Members:

TRANSLATION_SEARCH : The moving volume is placed on a grid search for initialization

LOCAL_RIGID : The 6-DoF pose of the moving volume is optimized around the starting point

LOCAL_AFFINE : An affine transformation is also applied to the volume

LOCAL_AFFINE = <RegistrationMode.LOCAL_AFFINE: 4>

LOCAL_RIGID = <RegistrationMode.LOCAL_RIGID: 2>

TRANSLATION_SEARCH = <RegistrationMode.TRANSLATION_SEARCH: 1>

property name

property value

prepare_data(self: UltrasoundRegistrationAlgorithm) → None: Run compounding, downsampling, and pose initialization as needed.

set_mode(self: UltrasoundRegistrationAlgorithm, mode: RegistrationMode) → None

Set the registration mode flags.

Parameters:: mode – Registration mode flags.

set_use_default_weighting(self: UltrasoundRegistrationAlgorithm) → None: Use default weighting based on the variance of each ultrasound patch.

set_use_landmark_weighting(self: UltrasoundRegistrationAlgorithm, fwhm: float) → None

Use a weight volume composed of Gaussians centered around each landmark.

Parameters:: fwhm – Full width at half maximum (FWHM) of the Gaussian (in mm).

set_use_segmentation_weighting(self: UltrasoundRegistrationAlgorithm, model_path: str, max_distance: float = 20.0, strength: float = 1.0) → None

Enable segmentation-based weighting for registration.

The provided model will be executed on each frame of the ultrasound sweep, the resulting labelmaps will be compounded into a volume. The weight at each voxel is computed as 1.0 - strength * min(distance_to_segmentation / max_distance, 1.0)

Parameters:

model_path – Path to the segmentation model.
max_distance – Maximum distance in mm for weighting. Default is 20.0.
strength – Strength of weighting in [0, 1]. Default is 1.0.

property has_landmarks

Returns True if landmarks are available for weighting.

Returns:: bool

property initialization_mode: Initialization mode for registration.

property is_ultrasound_moving: Specifies if the ultrasound data is the moving image in registration.

property num_evals: Returns the number of optimizer evaluations performed.

property optimize_gating_offset: If true, optimizes the gating metadata phase offset.

property relative_sweep_spacing: Relative spacing (percent) of the ultrasound sweep with respect to the tomographic volume.

property target_volume_spacing: Target volume spacing (millimeters) of the tomographic volume.

property use_probe_compression: Whether to use a probe compression deformation model.

property use_slice_based: Use slice-to-volume registration instead of 3D-3D registration.

class imfusion.ultrasound.UltrasoundSweep(self: UltrasoundSweep, image: SharedImage = None, axis:

Reference

imfusion

imfusion - ImFusion SDK for Medical Imaging

imfusion.processing

imfusion.io

imfusion.typing

imfusion.algorithm

imfusion.algorithm.typing

imfusion.anatomy

ImFusion Anatomy Plugin Python Bindings

Core Functionality Areas

Example Usage

imfusion.spine

ImFusion Spine Plugin Python Bindings

Core Functionality Areas

Example Usage

imfusion.dicom

imfusion.stream

imfusion.igtl

imfusion.navigation

imfusion.machinelearning

Implementation Patterns

Complete Workflow Example

How It Works Internally

imfusion.registration

imfusion.graph

imfusion.ultrasound

Loading sweeps

Exploring an UltrasoundSweep

Compounding

Registration

Exploring an `UltrasoundSweep`