Metadata-Version: 2.4
Name: imzdesk
Version: 0.1.0
Summary: Open-source workbench for Whole-Slide Imaging (WSI) and Mass Spectrometry Imaging (MSI) visualization, co-registration, and dataset curation.
Keywords: spatial metabolomics,mass spectrometry imaging,whole slide imaging,image registration,histopathology,dataset curation,medical imaging
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: fastapi>=0.138.0
Requires-Dist: h5py>=3.16.0
Requires-Dist: huggingface-hub>=1.23.0
Requires-Dist: lxml>=6.1.1
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.4.2
Requires-Dist: openslide-python>=1.4.6
Requires-Dist: pillow>=12.1.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: pydantic-settings>=2.13.4
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyimzml>=1.5.5
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: scikit-image>=0.26.0
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.17.0
Requires-Dist: simpleitk>=2.3.1
Requires-Dist: starlette>=1.3.1
Requires-Dist: tqdm>=4.68.4
Requires-Dist: uvicorn[standard]>=0.48.0
Requires-Dist: safetensors>=0.8.0 ; extra == 'embeddings'
Requires-Dist: torchvision~=0.27.1 ; extra == 'embeddings'
Requires-Dist: torch~=2.12.1 ; extra == 'embeddings'
Requires-Dist: jupyter>=1.1.1 ; extra == 'examples'
Requires-Python: >=3.12
Project-URL: Homepage, https://med-i-lab.gitbook.io/imzdesk
Project-URL: Documentation, https://med-i-lab.gitbook.io/imzdesk
Project-URL: Repository, https://github.com/aryan-f/imzDesk
Project-URL: Issues, https://github.com/aryan-f/imzDesk/issues
Project-URL: Changelog, https://github.com/aryan-f/imzDesk/releases
Provides-Extra: embeddings
Provides-Extra: examples
Description-Content-Type: text/markdown

# imzDesk

![Build Status](https://img.shields.io/github/actions/workflow/status/aryan-f/imzDesk/build.yml)
[![codecov](https://codecov.io/gh/aryan-f/imzDesk/graph/badge.svg)](https://codecov.io/gh/aryan-f/imzDesk)
![PyPI Python Version](https://img.shields.io/pypi/pyversions/imzdesk)
[![PyPI Version](https://img.shields.io/pypi/v/imzdesk)](https://pypi.org/project/imzdesk/)
[![GitHub Repo](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/aryan-f/imzDesk/)
[![Documentation](https://img.shields.io/badge/gitbook-docs-3884FF?logo=gitbook&logoColor=white)](https://med-i-lab.gitbook.io/imzdesk)

<p align="center">
  <img
    src="https://raw.githubusercontent.com/aryan-f/imzDesk/master/assets/imzdesk-demo.webp"
    alt="imzDesk software demo showing MSI and WSI visualization and co-registration"
    width="1000"
  />
</p>

imzDesk is an open-source workbench and Python library for working with whole-slide imaging (WSI) and mass
spectrometry imaging (MSI) data. Its browser-based workspace supports image inspection, MSI visualization, pixel-level
spectrum comparison, WSI-MSI registration, annotation, and dataset curation. The Python API provides the same image
types and preprocessing tools for building reproducible analysis and model-training pipelines.

## Requirements

- Python 3.12 or newer
- The native [OpenSlide](https://openslide.org/download/) library

OpenSlide must be installed through your operating system before installing imzDesk. For example:

```shell
# Ubuntu or Debian
sudo apt install libopenslide0

# macOS with Homebrew
brew install openslide
```

See the [OpenSlide installation instructions](https://openslide.org/download/) for other platforms.

## Installation

Install imzDesk from PyPI:

```shell
python -m pip install imzdesk
```

Optional dependency groups add model-based spectral embeddings or the Jupyter environment used by the example
notebooks:

```shell
# Model-based embeddings with PyTorch
python -m pip install "imzdesk[embeddings]"

# Jupyter example notebooks
python -m pip install "imzdesk[examples]"

# Both optional groups
python -m pip install "imzdesk[embeddings,examples]"
```

## Start the Workbench

Point imzDesk at a directory containing the images you want to work with:

```shell
imzdesk /path/to/workspace
```

Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in a browser. imzDesk scans the workspace recursively for
supported WSI files and imzML datasets. Each `.imzML` file must have its corresponding `.ibd` file beside it.
Application metadata, annotations, cached data, registrations, and dataset manifests are stored in hidden `.imzDesk`
directories alongside the source data.

Run `imzdesk --help` to see server options such as the host, port, inference device, and logging level.

## Documentation

The [imzDesk documentation](https://med-i-lab.gitbook.io/imzdesk) contains manuals for the web workbench and the Python
API reference. The [`examples`](examples) directory also contains executable notebooks covering image transforms,
registration, and PyTorch dataset preparation.

## License

imzDesk is distributed under the [Apache License 2.0](LICENSE).
