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 and MONAI 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]'

For MONAI U-Net alone:

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

MONAI U-Net's trained weights are bundled; no model download is needed.

To also include StarDist, use 'exhale-xrf[stardist,cellpose,monai]' 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 and MONAI U-Net (Apple Silicon required on macOS):

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

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]' with the same requirements argument to include all three methods. For a Git checkout:

python -m pip install -e '.[stardist,cellpose,monai]' -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 Cellpose weights are downloaded on first use to the model directory in application settings. The same mechanism is used for installed applications and Git checkouts; the large 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.1

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.1
File Size Uploaded Provenance Actions
exhale_xrf-1.5.1.tar.gz 13.2 MB With provenance Details for exhale_xrf-1.5.1.tar.gz

Built distribution (wheel)

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

Total release size: 26.5 MB

Release files / exhale_xrf-1.5.1.tar.gz

Download URL exhale_xrf-1.5.1.tar.gz
Size 13.2 MB
Tags Source
SHA-256 checksum
How to use checksums
332defbab2cd8d594ea8d52f0d01bc8a7c300873d98d2409f6526ef067587e7f
BLAKE2b-256 checksum
How to use checksums
e8415ec8770aa784e35e1cf2ebddb9ed5c6a0ff19050cb962ebb1d679896955d
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 9, 2026.

Transparency log

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

Download URL exhale_xrf-1.5.1-py3-none-any.whl
Size 13.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
a3c84b8e87656049d5eb32d28095045e4db0b514c17405406c06d2d2fded3c11
BLAKE2b-256 checksum
How to use checksums
022066a7c4a2eae79998b900c7a3cb69664e99b9559a6c8659cadfd68c56f39f
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 9, 2026.

Transparency log

Security for exhale-xrf 1.5.1

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.1.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 9, 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