Metadata-Version: 2.4
Name: sphero-vem
Version: 0.1.1
Summary: Quantitative 3D analysis of volume electron microscopy data with ML and classical image processing
License: MIT License
         
         Copyright (c) 2026 Davide Bottone
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
License-File: LICENSE
Author: Davide Bottone
Author-email: d.bottone@pm.me
Requires-Python: >=3.12,<3.14
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: OS Independent
Provides-Extra: cuda
Requires-Dist: careamics (>=0.0.9)
Requires-Dist: cellpose (>=4.0.3,<5.0.0)
Requires-Dist: cucim-cu12 (>=25.12.0,<26.0.0) ; extra == "cuda"
Requires-Dist: cupy-cuda12x (>=13.6.0,<14.0.0) ; extra == "cuda"
Requires-Dist: dacite (>=1.9.2,<2.0.0)
Requires-Dist: dask-image (>=2025.11.0,<2026.0.0)
Requires-Dist: dotenv (>=0.9.9,<0.10.0)
Requires-Dist: kornia (>=0.8.0,<0.9.0)
Requires-Dist: lightning (>=2.5.1,<3.0.0)
Requires-Dist: numpy (>=2.0.0,<3.0.0)
Requires-Dist: pandas (>=2.3.0,<3.0.0)
Requires-Dist: polars (>=1.39.2,<2.0.0)
Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
Requires-Dist: torch (>=2.0.0,<2.7.0)
Requires-Dist: torchvision (>=0.15.0,<0.22.0)
Requires-Dist: wandb (>=0.19.10,<0.20.0)
Requires-Dist: zarr (>=3.0.0,<4.0.0)
Project-URL: Documentation, https://dv-bt.github.io/sphero-vem/
Project-URL: Homepage, https://dv-bt.github.io/sphero-vem/
Project-URL: Repository, https://github.com/dv-bt/sphero-vem/
Description-Content-Type: text/markdown

# sphero-vem

[![PyPI](https://img.shields.io/pypi/v/sphero-vem)](https://pypi.org/project/sphero-vem/)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://www.python.org)
[![CI](https://github.com/dv-bt/sphero-vem/actions/workflows/ci.yml/badge.svg)](https://github.com/dv-bt/sphero-vem/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/dv-bt/sphero-vem/graph/badge.svg?token=0VqxCn7LKp)](https://codecov.io/gh/dv-bt/sphero-vem)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

Python library for quantitative analysis of volumetric electron microscopy (vEM) data.

`sphero-vem` was developed for the end-to-end analysis pipeline described in:

> Bottone et al., *3D Reconstruction of Nanoparticle Distribution in Tumor Spheroids with Volume Electron Microscopy*, Preprint: [https://doi.org/10.64898/2026.04.17.719153](https://doi.org/10.64898/2026.04.17.719153)

While the library was originally developed for SBF-SEM data of nanoparticle-loaded tumor spheroids, the individual components are designed to be reusable for other vEM datasets and workflows.

## Capabilities

- **Denoising**: self-supervised Noise2Void via CAREamics on large zarr volumes
- **Registration**: intensity-based pairwise slice alignment with multi-resolution PyTorch optimization
- **Segmentation**: fine-tuning and inference with Cellpose-SAM for cells and nuclei; empirical Bayes approach for nanoparticles
- **Shape analysis**: 3D morphological descriptors via signed distance functions and mesh-based curvature (mean curvature, curvedness, shape index, fractal dimension)
- **Spatial analysis**: nanoparticle-to-nucleus distance quantification per cell
- **Data management**: zarr-native I/O with OME-NGFF multiscale support and processing metadata tracking

## Installation

The library is available on [PyPI](https://pypi.org/project/sphero-vem/). We recommend installing it in a dedicated virtual environment.

```bash
pip install sphero-vem
```

For full CUDA 12.x GPU acceleration (Linux only; Windows untested):

```bash
pip install "sphero-vem[cuda]"
```

PyTorch-based stages (denoising, registration, Cellpose-based segmentation) support GPU execution
via PyTorch's native device management, including CUDA and MPS (Apple Silicon),
with no additional dependencies.

Array operation stages (nanoparticle segmentation, shape analysis, spatial analysis)
additionally support CUDA acceleration via CuPy and CuCIM, available with the
`cuda` extra above.

### Development install

Clone the repository and install with [Poetry](https://python-poetry.org/):

```bash
git clone https://github.com/dv-bt/sphero-vem.git
cd sphero-vem
poetry install           # base install
poetry install -E cuda   # with CUDA 12.x GPU acceleration (Linux only; Windows untested)
```

## Documentation

Full documentation is available on the [official website](https://dv-bt.github.io/sphero-vem/).

## Requirements

- Python 3.12–3.13
- [PyTorch](https://pytorch.org/) ≥ 2.0
- [NumPy](https://numpy.org/) ≥ 2.0
- [zarr](https://zarr.readthedocs.io/) ≥ 3.0
- [Cellpose](https://cellpose.readthedocs.io/) ≥ 4.0
- [CAREamics](https://careamics.github.io/) ≥ 0.0.9

## Dataset and model weights

The annotated SBF-SEM dataset used to develop this pipeline is available at BioImage Archive (https://doi.org/10.6019/S-BIAD3263). Fine-tuned Cellpose-SAM model weights are available on Zenodo (https://doi.org/10.5281/zenodo.19616546).

## Citation

If you use this library, please cite the accompanying paper:

```bibtex
@article {Bottone2026,
	author = {Bottone, Davide and Gerken, Lukas RH and Habermann, Sebastian and Mateos, Jose Maria and Lucas, Miriam S and Riemann, Johannes and Fachet, Melanie and Resch-Genger, Ute and Kissling, Vera M and Roesslein, Matthias and Gogos, Alexander and Herrmann, Inge K},
	title = {3D Reconstruction of Nanoparticle Distribution in Tumor Spheroids with Volume Electron Microscopy},
	year = {2026},
	doi = {10.64898/2026.04.17.719153},
	eprint = {https://www.biorxiv.org/content/early/2026/04/21/2026.04.17.719153},
}
```

## License

See [LICENSE](LICENSE) for details.

