Metadata-Version: 2.4
Name: sphero-vem
Version: 0.1.0
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

[![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

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           # CPU and limited GPU acceleration
poetry install -E cuda   # with full CUDA 12.x GPU acceleration (Linux/Windows only)
```

## 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

## GPU acceleration

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

Array operation stages (nanoparticle segmentation, shape analysis, spatial analysis) additionally support CUDA acceleration via CuPy and CuCIM, installed with the `cuda` optional dependency group above. GPU acceleration is handled automatically with a custom orchestrator.

## 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.

