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#

Type:: str

property is_hidden#

Type:: bool

property name#

Type:: str

__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.

Type:: list[Action]

property id#

Type:: str

property input#

Type:: list

property name#

Type:: str

property status#

Type:: 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#

Type:: bool

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=<not given>, *values, 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'#

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.

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: PathLike | str | bytes, path_type: PathType = PathType.OPEN_FILE, caption: str | None = None, filters: Sequence[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=<not given>, *values, 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 = 'SaveFile'#

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=<not given>, *values, 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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

ERROR = 1#

INCOMPLETE_INPUT = 3#

INVALID_INPUT = 2#

OUT_OF_MEMORY_GPU = 5#

OUT_OF_MEMORY_HOST = 4#

SUCCESS = 0#

UNKNOWN = -1#

UNKNOWN_ACTION = 7#

UNSUPPORTED_GPU = 6#

USER = 1000#

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#

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.