Metadata-Version: 2.4
Name: slide2vec
Version: 6.1.0
Summary: Embedding of whole slide images with Foundation Models
Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/clemsgrs/slide2vec
Project-URL: Bug Tracker, https://github.com/clemsgrs/slide2vec/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
Requires-Dist: omegaconf
Requires-Dist: matplotlib
Requires-Dist: numpy<2
Requires-Dist: pandas
Requires-Dist: pillow
Requires-Dist: rich
Requires-Dist: torch
Requires-Dist: torchvision
Requires-Dist: transformers
Requires-Dist: wandb
Requires-Dist: einops
Requires-Dist: timm
Requires-Dist: huggingface_hub
Provides-Extra: hoptimus
Requires-Dist: torch>=2.0; extra == "hoptimus"
Requires-Dist: torchvision>=0.15.0; extra == "hoptimus"
Requires-Dist: xformers>=0.0.18; extra == "hoptimus"
Provides-Extra: virchow
Requires-Dist: timm>=0.9.11; extra == "virchow"
Requires-Dist: torch>=2.0; extra == "virchow"
Provides-Extra: uni
Requires-Dist: torch>=2.0; extra == "uni"
Requires-Dist: timm>=0.9.8; extra == "uni"
Requires-Dist: xformers>=0.0.18; extra == "uni"
Provides-Extra: prism
Requires-Dist: transformers~=4.53.0; extra == "prism"
Requires-Dist: torch<2.8,>=2.3; extra == "prism"
Requires-Dist: einops==0.8.0; extra == "prism"
Requires-Dist: environs==11.0.0; extra == "prism"
Requires-Dist: sacremoses==0.1.1; extra == "prism"
Requires-Dist: xformers==0.0.31; extra == "prism"
Provides-Extra: prism2
Requires-Dist: torch>=2.3; extra == "prism2"
Requires-Dist: transformers==4.51.3; extra == "prism2"
Requires-Dist: safetensors; extra == "prism2"
Requires-Dist: einops; extra == "prism2"
Requires-Dist: flash-attn>=2.6.3; extra == "prism2"
Provides-Extra: hibou
Requires-Dist: scipy~=1.8.1; extra == "hibou"
Requires-Dist: scikit-image~=0.19.3; extra == "hibou"
Provides-Extra: moozy
Requires-Dist: huggingface_hub<1.0,>=0.30.0; extra == "moozy"
Provides-Extra: titan
Requires-Dist: torch==2.0.1; extra == "titan"
Requires-Dist: timm==1.0.3; extra == "titan"
Requires-Dist: einops==0.6.1; extra == "titan"
Requires-Dist: einops-exts==0.0.4; extra == "titan"
Requires-Dist: transformers==4.46.0; extra == "titan"
Provides-Extra: waiv
Requires-Dist: transformers<6,>=5.14; extra == "waiv"
Requires-Dist: safetensors>=0.8; extra == "waiv"
Requires-Dist: huggingface_hub==1.25.1; extra == "waiv"
Provides-Extra: fm
Requires-Dist: omegaconf>=2.3.0; extra == "fm"
Requires-Dist: matplotlib; extra == "fm"
Requires-Dist: numpy<2; extra == "fm"
Requires-Dist: pandas; extra == "fm"
Requires-Dist: pillow; extra == "fm"
Requires-Dist: rich; extra == "fm"
Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0; extra == "fm"
Requires-Dist: wandb; extra == "fm"
Requires-Dist: torch<2.8,>=2.3; extra == "fm"
Requires-Dist: torchvision>=0.18.0; extra == "fm"
Requires-Dist: einops>=0.8.0; extra == "fm"
Requires-Dist: timm>=1.0.20; extra == "fm"
Requires-Dist: huggingface_hub<1.0,>=0.30.0; extra == "fm"
Requires-Dist: environs; extra == "fm"
Requires-Dist: einops-exts>=0.0.4; extra == "fm"
Requires-Dist: transformers>=4.53; extra == "fm"
Requires-Dist: sacremoses; extra == "fm"
Requires-Dist: xformers>=0.0.31; extra == "fm"
Requires-Dist: scipy>=1.8.1; extra == "fm"
Requires-Dist: scikit-image>=0.19.3; extra == "fm"
Requires-Dist: torchmetrics>=0.10.3; extra == "fm"
Requires-Dist: fvcore; extra == "fm"
Requires-Dist: iopath; extra == "fm"
Requires-Dist: webdataset; extra == "fm"
Requires-Dist: scikit-survival; extra == "fm"
Requires-Dist: scikit-learn; extra == "fm"
Requires-Dist: fairscale; extra == "fm"
Requires-Dist: packaging==23.2; extra == "fm"
Requires-Dist: ninja==1.11.1.1; extra == "fm"
Requires-Dist: psutil<6; extra == "fm"
Provides-Extra: docs
Requires-Dist: sphinx>=8.1; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Provides-Extra: testing
Requires-Dist: pytest>=6.0; extra == "testing"
Requires-Dist: pytest-cov>=2.0; extra == "testing"
Requires-Dist: mypy>=0.910; extra == "testing"
Requires-Dist: flake8>=3.9; extra == "testing"
Requires-Dist: flake8-pyproject>=1.2.3; extra == "testing"
Requires-Dist: tox>=3.24; extra == "testing"
Dynamic: license-file

# slide2vec

[![PyPI version](https://img.shields.io/pypi/v/slide2vec?label=pypi&logo=pypi&color=3776AB)](https://pypi.org/project/slide2vec/)
[![Docs](https://img.shields.io/badge/docs-website-blue)](https://clemsgrs.github.io/slide2vec/)

`slide2vec` encodes whole-slide images with publicly available pathology foundation models. It uses [`hs2p`](https://pypi.org/project/hs2p/) for tissue detection and tiling, and handles batching, multi-GPU execution, and embedding storage.

## Install

Python 3.10 or newer is required:

```shell
pip install slide2vec
```

Many models need additional dependencies available through `pip install "slide2vec[fm]"`. See the [model installation guide](https://clemsgrs.github.io/slide2vec/models.html#model-installation) for model-specific extras, separate environments, and upstream packages.

For gated models such as Virchow2, request access on the model's Hugging Face page and authenticate with `hf auth login` or an `HF_TOKEN` environment variable.

## Embed a slide

```python
from slide2vec import Model, PreprocessingConfig

model = Model.from_preset("virchow2")
preprocessing = PreprocessingConfig(requested_spacing_um=0.5)
embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)

tile_embeddings = embedded.tile_embeddings  # (N, 2560)
x, y = embedded.x, embedded.y               # level-0 tile coordinates
```

The preset supplies tile size and precision defaults. Declare spacing explicitly for models such as Virchow2 that support several scales. Use `list_models()` to list presets, or filter with `list_models("tile")`, `list_models("slide")`, or `list_models("patient")`.

See [getting started](https://clemsgrs.github.io/slide2vec/getting-started.html) for preprocessing and execution settings, and the [API guide](https://clemsgrs.github.io/slide2vec/api.html) for patient embeddings, image inputs, and dense grids.

## Save a batch

Create a CSV manifest:

```csv
sample_id,image_path
slide-1,/data/slide-1.svs
slide-2,/data/slide-2.svs
```

Optional `mask_path` and `spacing_at_level_0` columns supply a mask or correct missing or incorrect level-0 spacing. Patient-level models also require `patient_id`; see the [manifest schema](https://clemsgrs.github.io/slide2vec/manifest.html).

```python
from slide2vec import ExecutionOptions, Model, Pipeline, PreprocessingConfig

pipeline = Pipeline(
    model=Model.from_preset("virchow2"),
    preprocessing=PreprocessingConfig(requested_spacing_um=0.5),
    execution=ExecutionOptions(output_dir="outputs/run"),
)
result = pipeline.run(manifest_path="/path/to/slides.csv")
```

Runs use all available GPUs by default; set `ExecutionOptions(num_gpus=2)` to limit them. Embeddings are saved as `.pt` tensors with metadata sidecars. Use `ExecutionOptions(output_format="npz")` for NumPy archives. The [output guide](https://clemsgrs.github.io/slide2vec/output-layout.html) describes directories, shapes, coordinates, and progress records.

Add `region_tile_multiple=6` to the preprocessing config to group tiles into 6×6 regions. These produce `(num_regions, 36, feature_dim)` tensors in `hierarchical_embeddings/`; see [hierarchical features](https://clemsgrs.github.io/slide2vec/hierarchical.html).

The same batch workflow is available from the terminal:

```shell
slide2vec /path/to/config.yaml
```

The [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html) provides a complete config example, overrides, and resume instructions.

## Docker

[![Docker Version](https://img.shields.io/docker/v/waticlems/slide2vec?sort=semver&label=docker&logo=docker&color=2496ED)](https://hub.docker.com/r/waticlems/slide2vec)

```shell
docker pull waticlems/slide2vec:latest
docker run --rm -it \
    -v /path/to/your/data:/data \
    -e HF_TOKEN \
    waticlems/slide2vec:latest
```

Set `HF_TOKEN` in your shell before starting the container.

## More documentation

- [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
- [Performance benchmarks and QA](https://clemsgrs.github.io/slide2vec/performance.html)
- [API walkthrough notebook](tutorials/api_walkthrough.ipynb)
