Installation

There are three ways to obtain the imfusion package:

  1. From the Webshop: The latest versions of the python SDK are available via direct download from our webshop. Here you can choose between the free for non-commercial and the professional version of the SDK.

  2. Standalone from PyPI via pip: (obsolete) This is a public beta release of the imfusion for non-commercial use containing only restricted functionality. See Installation via pip for more information.

  3. From a custom ImFusion Suite installer: This can be either an installer that you purchased from our webshop or a custom installer that you have received from us as part of an ongoing cooperation. See With the ImFusion Suite, specifically Using the imfusion package of the installed ImFusion Suite in your own Python environment, for further information.

Note: we are currently actively working on unifying the installation process across wheel, PyPI and installers. Keep an eye on this page!

Installation via pip

Attention

The latest version of the python SDK are available via direct download from our webshop. Older versions are still available on PyPI, we are actively working on modularizing the imfusion-sdk wheel to be back on PyPI soon.

The public beta release of imfusion package can be installed directly from pip:

pip install imfusion-sdk

Warning

This installation method does not apply to customers who have an installer of the ImFusion Suite. See With the ImFusion Suite for the relevant information in that scenario.

We also offer more advanced versions with specialty modules for ultrasound, x-ray & computed tomography, mesh-based anatomy representation and registration, spine workflows, and many more. You can get them from our webshop or by contacting us directly for a custom package.

Warning

The imfusion module requires Python 3.10 or higher. We recommend using official Python interpreters from python.org. Currently, this package is not tested with interpreters from Anaconda, so use them at your own risk.

Note

While pip install can be run with the base interpreter, we highly recommend creating a virtual environment to avoid potential conflicts with other packages. See venv documentation and virtualenv documentation for more information on virtual environments in Python.

Note

If your Python interpreter does not come with pip (it normally does), please consult the pip installation guide from PyPA.

License Activation

Before you can import imfusion, you must activate it once. If you have purchased imfusion in a bundle with the ImFusion Suite from our webshop, you should already have a license key. For installations from pypi.org (i.e. pip install), please visit our `webshop`_ for a free license key.

The activation can be done either through the ImFusionSuite (a prompt will appear the first time you start it) or through the Python CLI:

Linux and macOS:

env IMFUSION_LICENSE_KEY=<your-license-key> python3 -c "import imfusion"

Windows CMD:

set IMFUSION_LICENSE_KEY=<your-license-key> && python.exe -c "import imfusion"

A successful activation will exit without an error, while an unsuccessful one will print details of why the activation failed. The activation requires an active internet connection. A proxy can be set with the HTTPS_PROXY environment variable. The IMFUSION_LICENSE_KEY only needs to be set once for the initial activation.

With the ImFusion Suite

The ImFusion Suite provides an embedded Python interpreter and console, and comes bundled with the imfusion package (see Using the imfusion package of the installed ImFusion Suite in your own Python environment).

Python console in the ImFusion Suite

Python console in the ImFusion Suite

Note

The imfusion package requires the numpy package to be installed. While the ImFusion Suite installers provide the files of imfusion, they do not install them for any specific interpreter. It is therefore on the user to install numpy for whichever interpreter they intend to use imfusion with.

On first start, the ImFusionSuite will try to automatically detect an installed Python environment. If this doesn’t work or if you want to use, e.g., a different Python version, you can configure different versions in Settings -> Python -> Active Environment. Click on the ‘+’ button to add the path to the Python interpreter you want to use. If the interpreter is located inside a virtual environment, the ImFusion Suite interpreter will use the corresponding environment.

Warning

The Python integration in the ImFusion Suite works only if you have a shared library for the interpreter you want to use on your system. On Windows / macOS, it is included in the installers provided on python.org in the form of a .dll / .dylib (e.g., libpython310.dll or libpython3.10.dylib). If you are on Ubuntu and you install your Python interpreter from the deadsnakes PPA, you must also install the pythonX.YY-dev package to obtain the shared library. If loading the library fails, you won’t see the Python console, and an error will be printed in the log window.

Note

The interpreter in the ImFusion Suite currently only supports virtual environments created through venv or virtualenv. Anaconda is not supported at the moment.

It is also possible to select a Python dynamic library directly, instead of choosing an interpreter. You will have to change the filter (lower right) in the file dialog to dynamic libraries to show up. This approach is not recommended, however, as it implies that you will be using the base interpreter, requiring all necessary packages to be installed there. This option is mostly kept for backwards compatibility.

If the environment is correctly configured, the interpreter is automatically initialised when the ImFusionPython plugin is loaded. Otherwise, an error is displayed in the log window. Depending on the size of your log window the error might go out of the visible scope and you have to scroll up to see it.

Note

If you cannot see a Python console in the bottom right of the window, go to Settings -> Python and select the desired console.

Using the imfusion package of the installed ImFusion Suite in your own Python environment

When you have installed the ImFusion Suite, the imfusion package is also installed on your system and you can use it in your own Python environment, independent of the ImFusion Suite. In order to do so, you may need to modify the module search paths, depending on your operating system and installation method.

Ubuntu

If you have installed the ImFusionSuite through the Ubuntu .deb package, the imfusion module will be installed to the default directory for Python modules (/usr/lib/python3/dist-packages) and will therefore be available when you use the system interpreter (i.e. python3). If you are working with virtual environments, you must pass the --system-site-packages flag during the creation of the environment to include the respective directory in its Python path. You also have the option enabling this behavior for existing environments by setting the value of ìnclude-system-site-packages to true in <path-to-your-venv>/pyvenv.cfg.

Standalone Linux

With the Standalone Linux installer, you have to point your PYTHONPATH or sys.path to the directory containing the imfusion module. The actual path depends on where you installed the ImFusionLib, e.g., if installed to opt, the path is /opt/ImFusionSuite/lib/python3/dist-packages.

If you wish to add the path to your virtual environment permanently, you can execute the following command in your shell after activating your virtual environment:

echo "<path to ImFusionSuite/lib/python3/dist-packages>" >> "${VIRTUAL_ENV}/lib/python$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')/site-packages/imfusionsuite.pth"
# e.g.
echo "/opt/ImFusionSuite/lib/python3/dist-packages" >> "${VIRTUAL_ENV}/lib/python$(python -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')/site-packages/imfusionsuite.pth"

Windows

On Windows, you also have to set the PYTHONPATH or sys.path.

In powershell / “Terminal” (ps):

$env:PYTHONPATH = $env:PYTHONPATH + ";C:\Program Files\ImFusion\ImFusion Suite\Suite"

In the command line (cmd):

if defined PYTHONPATH (
    set PYTHONPATH=%MY_VAR%;C:\\Program Files\\ImFusion\\ImFusion Suite\\Suite
) else (
    set PYTHONPATH=C:\\Program Files\\ImFusion\\ImFusion Suite\\Suite
)

In order to make this permanent in your virtual environment, execute the following in PowerShell while your virtual environment is active: .. code-block:: sh

Add-Content -Path $env:VIRTUAL_ENVLibsite-packagesimfusionsuite.pth -Value “C:Program FilesImFusionImFusion SuiteSuite”