Topolosses Documentation

Topolosses is a Python package providing topology-aware loss functions for segmentation tasks. It contains losses designed to improve the topological correctness of model predictions, such as CLDiceLoss, BettiMatchingLoss, TopographLoss, and more.

Getting Started

The easiest way to install Topolosses (with all pre-built C++ extensions) is via PyPI: Install Topolosses from PyPI:

pip install topolosses

Pre-built wheels are available for Linux platforms. If no compatible wheel exists, pip will compile from source locally. See Working with Source Code for more details.

Once installed, import and use any of the topology-aware losses just like a standard PyTorch loss:

from topolosses.losses import DiceLoss, BettiMatchingLoss

# Combine topological (BettiMatchingLoss) with base component (DiceLoss)
loss = BettiMatchingLoss(
   alpha=0.5,  # Weight for the topological component
   softmax=True,
   base_loss=DiceLoss(softmax=True, smooth=1e-3)
)
result = loss.forward(prediction, target)

Common Loss Structure

Since most topology-aware loss functions combine the sparse topological component with a dense region loss like Dice to ensure both shape accuracy and topological correctness, this project follows the same approach. By default, it uses Dice as the base loss, but you can easily replace it with any custom loss you prefer—or even use just the topology component if that’s all you need.

  • alpha (float): Weight for combining the topology-aware component and the base loss component. Default: 0.5.

  • sigmoid (bool): Applies sigmoid activation to the forward-pass input before computing the topology-aware component. If using the default Dice loss, the sigmoid-transformed input is also used; for a custom base loss, the raw input is passed. Default: False.

  • softmax (bool): Applies softmax activation to the forward-pass input before computing the topology-aware component. If using the default Dice loss, the softmax-transformed input is also used; for a custom base loss, the raw input is passed. Default: False.

  • use_base_component (bool): If False, only the topology-aware component is computed. Default: True.

  • base_loss (Loss, optional): The base loss function used with the topology-aware component. Default: None.

API References

Losses:

utils:

Working with Source Code

If no binary for your plattform is available or if you want to modify the code (e.g., adjust a loss function), you’ll need to build the C++ extensions locally.

If no compatible wheel exists, pip will compile from source locally. To compile the C++ extension you require a C++ compiler, Python development headers, OpenCV, Boost, and Eigen libraries. (TODO: specify which versions are needed and where to locate the libraries). However, because this approach is very error prone it is better to clone source-code from GitHub. You can tweak pyproject.toml and CMakeLists.txt to point at your local library paths.

  • Option 1: After cloning the repo you can tweak pyproject.toml and CMakeLists.txt to point at your local library paths. Then you can use python -m build to build the wheels and pip install {path}.whl.

  • Option 2: When not wanting to build but working directly inside the package it requires manual building of the C++ extensions. Might require adjusting the import statements. (TODO explain how to install c++ extensions)

Indices and tables