.. _bindings:

Python API
==========

.. warning:: This feature is still experimental. The provided API might change in the future.

ImFusion Labels comes with a Python module that provides an API to interact with a project from Python.
The module can be imported with ``imfusion.labels`` and is distributed on `pypi.org. <https://pypi.org/project/imfusion-sdk-labels/>`_.

The ``imfusion.labels`` module provides some documentation and examples in its Docstring (``help(imfusion.labels)``).

Example 1: Create and edit a Project
------------------------------------

Creating or editing a project programmatically is practical if the project contains many labels that are e.g. pulled from another source.
This example creates a local or remote project depending on whether a path to an empty folder or a URL to a Labels server instance is passed.

.. literalinclude:: samples/create_and_edit_project.py
  :language: python


Example 2: Clear labels of all datasets
---------------------------------------

A common requirement is to run an algorithm or filter on all datasets.
This example opens a project, iterates over each dataset and layer and calls the ``algorithm`` function for each labelmap.
In this case, the ``algorithm`` only clears all labels but can be extended to e.g. automatically segment some structures.
Since the image and labelmap can be converted to regular numpy arrays, they can be passed to any library that can handle numpy such as scipy or PyTorch.

.. literalinclude:: samples/clear_labels_all_datasets.py
  :language: python

Example 3: Batch import datasets with custom grouping
-----------------------------------------------------

The grouping option in the database view is currently only available for DICOMs.
If your want to import non-DICOM data or need some custom grouping, the best way is to batch import your
data. The following example uses the folder names for grouping.

.. literalinclude:: samples/batch_import_grouping.py
  :language: python

.. _python_example_grouping:

Example 4: Reset grouping to default value
------------------------------------------

The following script iterates all datasets of a project, reads the meta-data and resets the grouping information to the default.

.. literalinclude:: samples/reset_grouping.py
  :language: python


.. _python-thumbnails:

Example 5: Re-generate labelmap thumbnails
------------------------------------------

The following script re-generates the thumbnail of all labelmaps.

.. literalinclude:: samples/generate_labelmap_thumbnails.py
  :language: python


Reference
---------

.. automodule:: imfusion.labels
 :members:
 :undoc-members:
 :show-inheritance:
 :imported-members: