Installation ============ The :mod:`imfusion` module is distributed in the form of Python wheels (.whl files) either hosted on our package index or provided directly by us: 1. **Package Index:** All releases of the ImFusion Python SDK (``imfusion-sdk`` packages) are hosted on ``pypi.imfusion.com/simple``. Each release depends on a stable version of the ImFusion C++ SDK, which is also hosted as Python packages (``libimfusion``) on the same index. See :ref:`installation-package-index` for more information. 2. **Custom wheels:** If you are contracting us for a R&D / consulting project, you might receive wheel files (.whl) from us for custom builds as part of the project. See :ref:`installation-wheel` for further information. .. warning:: The :mod:`imfusion` module requires Python 3.10 or higher. We recommend using official Python interpreters from `python.org `__. Installers obtained with `uv `_ are also compatible. Currently, this package is not tested with interpreters from Anaconda, so use them at your own risk. .. _installation-package-index: Installation from package index ------------------------------- The :mod:`imfusion` package can be installed directly using a package manager, e.g. pip, from our package index ``pypi.imfusion.com/simple``: .. code:: sh pip install imfusion-sdk --extra-index-url https://pypi.imfusion.com/simple We offer many additional modules as separate plugin packages, e.g. ``imfusion-sdk-machinelearning``, ``imfusion-sdk-dicom``, etc. You can either install them explicitly by name, or specify them as optional dependencies, as shown below. .. code:: sh pip install imfusion-sdk[machinelearning, dicom, ...] --extra-index-url https://pypi.imfusion.com/simple .. 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 `_. The ``imfusion-sdk`` package and all plugins that are part of the base package covered by all our SDK `subscription plans `_ (Free, Starter, Professional) can be installed through ``imfusion-sdk[webshop-base]``. Our modality specific plugins like :mod:`imfusion.vision` or :mod:`imfusion.computed_tomography` are also available, e.g. via ``imfusion-sdk[vision]``, however you will need to purchase an `additional license `_. These plugins are only usable with the "Starter" and "Professional" plan licenses. We also provide optional dependencies for the following `webshop bundles `_: - ``imfusion-sdk[webshop-ultrasound]`` - ``imfusion-sdk[webshop-vision]`` - ``imfusion-sdk[webshop-xray-ct]`` - ``imfusion-sdk[webshop-navigation]`` - ``imfusion-sdk[webshop-robotics]`` - ``imfusion-sdk[webshop-spine]`` Besides the ``imfusion-sdk`` packages, these bundles also contain `libimfusion` packages which represent plugins for the ImFusion C++ SDK. While you cannot interact with them directly via a Python API, they offer additional functionality accessible through the generic algorithm API, e.g. :meth:`imfusion.algorithm.execute`. The ``libimfusion`` packages can also be installed individually. To get a full list of all provided optional dependencies you can run the following command after installing ``imfusion-sdk``: .. code:: sh python -c "from importlib import metadata;print(*metadata.metadata('imfusion-sdk').get_all('Provides-Extra'), sep='\n')" .. _installation-wheel: Installation from wheel files ----------------------------- If you receive .whl files from us directly for a custom build, the installation process is analogous to what is described in :ref:`installation-package-index`. The only difference is that your package manager must be configured to resolve dependencies locally: For ``pip`` (and ``uv pip``), the ``-f `` option specifies the directory where dependencies can be found. Additionally, you need to substitute ``imfusion-sdk`` with your local wheel ``imfusion_sdk----.whl`` (on macOS and Linux you can simply use ``imfusion_sdk-*.whl``). As an example, if you want to install imfusion-sdk with the machinelearning + ultrasound from provided wheel files your command would look like this: .. code:: sh cd pip install -f . ./imfusion_sdk----.whl[machinelearning,ultrasound] You can also install individual .whl files, as long as ``-f`` is set correctly to find potential dependencies locally. License Activation ------------------ Before you can import :mod:`imfusion`, you must activate it once. You can obtain a license key from our `webshop `_. If you intend to use :mod`imfusion` strictly for non-commercial applications and don't need any modality-specific modules you can get a license key for `free `_ 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: .. code-block:: sh IMFUSION_LICENSE_KEY= python3 -c "import imfusion" Windows CMD: .. code-block:: sh set IMFUSION_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 :envvar:`HTTPS_PROXY` environment variable. The :envvar:`IMFUSION_LICENSE_KEY` only needs to be set once for the initial activation. Uninstalling ------------ To easily uninstall all imfusion packages from your venv you can simply run ``imfusion uninstall -y`` after activating the respective venv. .. _installation-installer: With the ImFusion Suite ----------------------- The ImFusion Suite provides an embedded Python interpreter and console. .. figure:: images/python_console_in_suite.png :alt: Python console in the ImFusion Suite :align: center Python console in the ImFusion Suite 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. Additionally, if you start the Suite from an active Python virtual environment, the Suite's interpreter will also use that environment, irrespective of what is stored in the Settings. .. 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``, ``virtualenv`` or `uv`. Anaconda is not supported at the moment. 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.