Basic Usage

Start by importing the module:

>>> import imfusion

This will create an internal OpenGL context and load all available plugins. Call imfusion.info() to get some basic information about the framework.

If the OpenGL context could not be created, an exception is raised. See the Troubleshooting for possible solutions. If OpenGL is absolutely not available, the IMFUSION_WITHOUT_OPENGL environment variable can be set before importing the module. This will significantly limit the available features of the SDK and will lead to crashes if not used very carefully!

Some of the plugins included in the ImFusion SDK might conflict with a package installed in your Python environment. If this is the case, you can blacklist the offending ImFusion plugin by defining the IMFUSION_PLUGIN_BLACKLIST environment variable. This variable is expected to contain a list of filenames separated by a semi-colon, for instance “foo.dll;bar.so”.

Loading Data

Let’s begin with loading some data:

>>> imfusion.load('ct_image.png')
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(USHORT width: 512 height: 512 spacing: 0.661813x0.661813x1 mm)])]

This returns a list of datasets that have been loaded. In this case it loaded an image set which contains only a single 2D image.

The ImFusion framework supports a wide variety of different data, not limited to image data but also polygon meshes, point clouds and more. The Working with Images chapter will explain what exactly a imfusion.SharedImageSet is but for now it is enough to think of it as a simple image.

Running Algorithms

Algorithms are the main building block of the ImFusion framework. An algorithm retrieves input data, performs some calculations and optionally returns output data. Additionally algorithms support certain properties that can influence the computation.

Algorithms are referred to by their id. To get a list of all available algorithms:

>>> imfusion.available_algorithms()
[..., 'Base.MorphologicalOperations', ...]

The list might change depending on the available plugins. Let’s execute the ‘Base.MorphologicalOperations’ algorithm on our image:

>>> img = imfusion.load('ct_image.png')[0]
>>> imfusion.execute_algorithm('Base.MorphologicalOperations', [img])
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(USHORT width: 512 height: 512 spacing: 0.661813x0.661813x1 mm)])]

The first argument is the id of the algorithm we want to execute and the second one a list of input images. Each algorithm only works on a particular set of inputs, e.g. some algorithm will only work on 2D ultrasound images. If an algorithm is incompatible with the given input data, a imfusion.IncompatibleError will be generated. Check the algorithm documentation to find out what input a particular algorithm expects.

In this case the algorithm returns a list of output data.

By default, the ‘Morphological Operations’ algorithm performs dilation with a size of 3. These parameters can be changed by passing an optional imfusion.Properties object to imfusion.execute_algorithm(). To figure out which parameters are supported use imfusion.algorithm_properties():

>>> p = imfusion.algorithm_properties('Base.MorphologicalOperations', [img])
>>> p.params()
['inPlace', 'opMode', 'opSize', 'distance', 'useCPU', 'padding', 'paddingSize', 'paddingMode', 'avoidGlDriverTimeout']

For more information about the algorithms and their configurations please consult the user documentation of the ImFusion Suite.

The imfusion.Properties class is similar to a Python dict: it stores key-value pairs and a list of attributes for each key.

Let’s change the pixel size of the dilation to 5:

>>> p = imfusion.Properties()
>>> p['opSize'] = 5
>>> imfusion.execute_algorithm('Filters;Morphological Operations', [img], p)
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(USHORT width: 512 height: 512 spacing: 0.661813x0.661813x1 mm)])]

Alternatively, you can also use a dict directly which is converted to a imfusion.Properties implicitly:

>>> imfusion.execute_algorithm('Base.MorphologicalOperations', [img], { 'opSize': 5 })
[imfusion.SharedImageSet(size: 1, [imfusion.SharedImage(USHORT width: 512 height: 512 spacing: 0.661813x0.661813x1 mm)])]

Saving Data

If you now want to save files to disk, you can use the imfusion.save() function. For now, ImFusion files (ending with ‘.imf’) are the only supported format. Additional bindings for supporting other formats will come soon.

You can save to disk the same kinds of data that are supported by the imfusion.load() function, i.e. SharedImageSet, Mesh, PointCloud, etc…:

>>> image_set = imfusion.SharedImageSet(...)  
>>> mesh = imfusion.Mesh(...)  
>>> point_cloud = imfusion.PointCloud(...)  
>>> another_image_set = imfusion.SharedImageSet(...)  
>>> imfusion.save([image_set, mesh, point_cloud, another_image_set], 'path/to/imf/file.imf')  

Visualizing Data

Warning

This functionality is only available if you have the ImFusion Suite installed and it must be available in your PATH.

A practical way to visualize one or multiple images is to start an ImFusion Suite instance from Python. This can be done via the imfusion.open_in_suite() function:

>>> image_set_1 = SharedImageSet(...)  
>>> image_set_2 = SharedImageSet(...)  
>>> mesh = Mesh(...)  
>>> imfusion.open_in_suite([image_set_1, image_set_2, mesh])  

This is a (hopefully temporary) one-way solution only meant for visualization and not processing: changes in the Suite cannot be transferred back to the Python interpreter.

With this, you should have the basic knowledge to write scripts with the ImFusion framework. The following chapters will describe the introduced parts in more detail.