Skip to main content

Exhale

Efficient X-ray Hub Aiding Lung Explorations

EXHALE segmentation results

This project aims to develop a specialized tool for investigating elemental aspects of chronic lung diseases.

From the VINNOVA project description:
The purpose of this project is to advance understanding and treatment of chronic lung diseases, leading causes of mortality worldwide, by characterizing elements in lung tissue suspected to impact their pathogenesis. The industrial partners TrulyLabs and AnaMar in collaboration with MAX IV, Lung Biology and Correlative Image Processing and Analysis (CIPA) fom Lund University, aim to streamline a workflow of X-ray imaging studies for lung diseases, making these methods more accessible for biomedical companies and clinical researchers.

Currect functionality

  • Loading HDF5 files with XRF data from the NanoMAX beamline at MAX IV.
  • Composing element maps into publication-ready figures.
  • Segmentation of cells and clustering of areas in element maps.

Installation

Linux

Install uv if needed, then choose the segmentation backends you want.

For StarDist (TensorFlow):

uv tool install --python 3.12 'exhale-xrf[stardist]'

For Cellpose, MONAI U-Net and SMP U-Net (PyTorch; Cellpose also needs DINOv3):

uv tool install --python 3.12 --with-requirements https://raw.githubusercontent.com/ctroein/exhale/main/requirements-cellpose.txt 'exhale-xrf[cellpose,monai,smp]'

For MONAI U-Net alone:

uv tool install --python 3.12 'exhale-xrf[monai]'

MONAI U-Net's 1.6 MB trained checkpoint downloads on first use.

For SMP U-Net with its trained ResNet18 encoder:

uv tool install --python 3.12 'exhale-xrf[smp]'

Its 50 MB trained checkpoint downloads on first use. No DINOv3 installation is needed.

To also include StarDist, use 'exhale-xrf[stardist,cellpose,monai,smp]' with the same additional requirements argument. Plain exhale-xrf installs viewing, composition and analysis of existing results without neural segmentation backends. Unavailable backends are disabled in the application.

Run exhale to start the application. To add it to the current user's desktop environment and application menu:

exhale --install-desktop

To update the application and its selected backends:

uv tool upgrade exhale-xrf

On Linux, Settings also offers daily update checks and a Check now button. Checks notify you of newer stable releases without installing anything. For a writable uv tool installation owned by your account, Update now closes Exhale, runs the upgrade, checks startup, and reopens it. Normal project saving applies before closing. Other Exhale instances must be closed first. Update results and the log location are shown after restarting. Automatic checks can be disabled in Settings.

uv retains the installation settings, including extras and additional requirements. To change backend selection, rerun uv tool install with the wanted extras and, for Cellpose, the requirements argument.

To uninstall, remove the desktop/menu entry before removing the application:

exhale --remove-desktop
uv tool uninstall exhale-xrf

Windows

Windows 10 or later with 64-bit compatibility is required. Download the exhale-…-setup.exe installer from the GitHub releases page and run it.

The installer offers StarDist, Cellpose, both, or neither before setup. It downloads a private Python environment and the selected packages; internet access is required, but an existing Python or uv installation is not. Use the Start menu or optional desktop shortcut to launch EXHALE.

Settings offers daily update checks, Check now, and Update now. Application updates preserve the selected backends and validate a new runtime before switching to it. You can also download and run a newer installer; use that to update the launcher/setup tools, change backends, or repair the installation. Uninstall through Windows Settings; the private runtime and shortcuts are removed while projects, trained models and application settings are retained.

macOS

Download the Apple Silicon (arm64) or Intel (x86_64) DMG from the GitHub releases page, drag EXHALE.app into Applications, and open it there. Setup downloads Python and the selected segmentation backends; neither Python nor uv needs to be installed beforehand. Intel Macs support StarDist but not the current Cellpose backend. The launcher requires macOS 13 or newer; Cellpose's PyTorch requires at least macOS 14 on Apple Silicon, and dependencies may require newer versions.

The Mac app is not Developer ID signed or notarized. macOS may block its first launch; see Apple's explanation and opening options.

Subsequent launches open the installed application. Hold Option while opening EXHALE.app to change backends, repair the installation, or remove the private runtime. Settings offers daily update checks and Update now, which preserves the backends and validates a new runtime before switching to it. To update the launcher/setup tools, quit EXHALE and replace the app with a newer release; setup will install its bundled release with your previous backend choices. For removal, use Remove Runtime in setup, then move EXHALE.app to Trash. Projects, model files, and application settings are retained.

Alternatively, use the same uv installation, backend selection and update commands as on Linux. Start the application with exhale. The desktop/menu registration commands are Linux-only; to uninstall a Mac uv installation, run:

uv tool uninstall exhale-xrf

App-managed environments are separate from installations made with uv tool install.

pip and source installations

Use a virtual environment with a supported Python version (3.11–3.13). Windows StarDist requires Python 3.11 because of its TensorFlow dependency.

For StarDist:

python -m pip install 'exhale-xrf[stardist]'

For Cellpose, MONAI U-Net and SMP U-Net (Apple Silicon required on macOS):

python -m pip install 'exhale-xrf[cellpose,monai,smp]' -r https://raw.githubusercontent.com/ctroein/exhale/main/requirements-cellpose.txt

For SMP U-Net alone, use python -m pip install 'exhale-xrf[smp]'. For MONAI U-Net alone, use python -m pip install 'exhale-xrf[monai]'; no DINOv3 requirements file is needed. Use 'exhale-xrf[stardist,cellpose,monai,smp]' with the same requirements argument to include all four methods. For a Git checkout:

python -m pip install -e '.[stardist,cellpose,monai,smp]' -r requirements-cellpose.txt
./run_exhale.py

Omit unwanted extras and the requirements file when Cellpose is not needed. On Windows, launch the checkout with python run_exhale.py.

DINOv3 and trained models

The additional requirements file pins DINOv3 to a tested source archive; Git is not required. For a particular EXHALE release, replace main in the requirements URL with its vVERSION tag and append ==VERSION to the package specification. A version-pinned uv installation must be reinstalled with a newer version specification to upgrade.

Trained weights for all four methods are downloaded on first use to the model directory in application settings. The same mechanism is used for installed applications and Git checkouts; the weights are not included in the application installer. DINOv3 code and derived model weights retain the DINOv3 license.

Developer documentation

Developer documentation is located in docs/.

Metadata

Release files for exhale-xrf 1.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for exhale-xrf 1.5.3
File Size Uploaded Provenance Actions
exhale_xrf-1.5.3.tar.gz 6.4 MB With provenance Details for exhale_xrf-1.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for exhale-xrf 1.5.3
File Interpreter ABI Platform Actions
exhale_xrf-1.5.3-py3-none-any.whl Python 3 none any Details for exhale_xrf-1.5.3-py3-none-any.whl

Total release size: 13.0 MB

Release files / exhale_xrf-1.5.3.tar.gz

Download URL exhale_xrf-1.5.3.tar.gz
Size 6.4 MB
Tags Source
SHA-256 checksum
How to use checksums
59d5973ffe3c9a5eb733ca89a5a08dcc34bc380a1c17a3654b49ac942dedff6f
BLAKE2b-256 checksum
How to use checksums
ec40744706dee62882b2cbb383c9f6ab8691972fe9d7c79892d8c915e16bbdb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / exhale_xrf-1.5.3-py3-none-any.whl

Download URL exhale_xrf-1.5.3-py3-none-any.whl
Size 6.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c6cd5144c411a3df0eaa1f49007da112aca55b0a1fce9d06c0080cc16503f9a7
BLAKE2b-256 checksum
How to use checksums
31cca90e3439d531d4aa6f19a0a69429f9f7288e7fd25eb48ac06c4a8ae7fdcc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for exhale-xrf 1.5.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for exhale_xrf-1.5.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page