slide2vec
slide2vec is a Python package for efficient encoding of whole-slide images using publicly available foundation models. It builds on hs2p for fast preprocessing and exposes a focused surface around Model, Pipeline, and ExecutionOptions.
Documentation site: https://clemsgrs.github.io/slide2vec/
Installation
pip install slide2vec
pip install "slide2vec[fm]"
slide2vec keeps the base install focused on the core package surface. Use slide2vec[fm] when you want the PyPI-hosted FM dependencies.
Some model backends still rely on upstream Git repositories that PyPI will not accept as package metadata. Install those separately when needed:
pip install git+https://github.com/lilab-stanford/MUSK.git
pip install git+https://github.com/Mahmoodlab/CONCH.git
pip install git+https://github.com/prov-gigapath/prov-gigapath.git
AtlasPatch-backed tissue segmentation is available through hs2p's sam2 path in the bundled install.
Waiv encoders use a separately tested Transformers 5 runtime. Install them in
their own environment with pip install "slide2vec[waiv]"; the waiv extra is
incompatible with the existing fm, prism, and titan dependency pins.
Python API
from slide2vec import Model
from slide2vec.utils.config import hf_login
hf_login()
model = Model.from_preset("virchow2")
embedded = model.embed_slide("/path/to/slide.svs")
tile_embeddings = embedded.tile_embeddings
x = embedded.x
y = embedded.y
Use list_models() when you want to inspect the shipped presets programmatically:
from slide2vec import list_models
all_models = list_models()
tile_models = list_models("tile")
slide_models = list_models("slide")
patient_models = list_models("patient")
Use Pipeline(...) for manifest-driven batch processing when you want artifacts written to disk instead of only in-memory outputs:
from slide2vec import ExecutionOptions, Pipeline, PreprocessingConfig
pipeline = Pipeline(
model=model,
preprocessing=PreprocessingConfig(
requested_spacing_um=0.5,
requested_tile_size_px=224,
masks={"min_coverage": {"tissue": 0.1}},
),
execution=ExecutionOptions(output_dir="outputs/demo"),
)
result = pipeline.run(manifest_path="/path/to/slides.csv")
By default, ExecutionOptions() uses all available GPUs. Set ExecutionOptions(num_gpus=4) when you want to cap the sharding explicitly.
Hierarchical Feature Extraction
Tile embeddings can be spatially grouped into regions for downstream models that consume region-level structure. Enable it by setting region_tile_multiple on PreprocessingConfig:
preprocessing = PreprocessingConfig(
requested_spacing_um=0.5,
requested_tile_size_px=224,
region_tile_multiple=6, # 6x6 tiles per region
)
embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)
Hierarchical outputs have shape (num_regions, tiles_per_region, feature_dim) and are written to hierarchical_embeddings/ when persisted.
See the hierarchical features guide for details.
Input Manifest
Manifest-driven runs use the schema below. mask_path and spacing_at_level_0 are optional.
sample_id,image_path,mask_path,spacing_at_level_0
slide-1,/path/to/slide-1.svs,/path/to/mask-1.png,0.25
slide-2,/path/to/slide-2.svs,,
...
Use spacing_at_level_0 when the slide file reports a missing or incorrect level-0 spacing and you want to override it.
Outputs
The package writes explicit artifact directories:
tile_embeddings/<sample_id>.ptor.npztile_embeddings/<sample_id>.meta.jsonhierarchical_embeddings/<sample_id>.ptor.npz(whenregion_tile_multipleis set)hierarchical_embeddings/<sample_id>.meta.jsonslide_embeddings/<sample_id>.ptor.npzslide_embeddings/<sample_id>.meta.json- optional
slide_latents/<sample_id>.ptor.npz
.pt remains the default format. .npz is available through ExecutionOptions(output_format="npz").
Supported Models
slide2vec currently ships presets for 28 tile-level models, 4 slide-level models,
and 1 patient-level model.
For the full catalog and preset names, see the model zoo.
CLI
The CLI is a thin wrapper over the package API.
Bundled configs live under slide2vec/configs/preprocessing/ and slide2vec/configs/models/.
slide2vec /path/to/config.yaml
By default, manifest-driven CLI runs use all available GPUs. Set speed.num_gpus=4 when you want to cap the sharding explicitly.
New to the CLI or doing batch runs to disk? Start with the CLI guide for the config-driven workflow and common run patterns.
Docker
Docker remains available when you prefer a containerized runtime:
docker pull waticlems/slide2vec:latest
docker run --rm -it \
-v /path/to/your/data:/data \
-e HF_TOKEN=<your-huggingface-api-token> \
waticlems/slide2vec:latest
Documentation
- Documentation website
- API guide
- CLI guide
- Model zoo
tutorials/api_walkthrough.ipynbfor a notebook walkthrough of the API
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file slide2vec-5.8.2.tar.gz.
File metadata
- Download URL: slide2vec-5.8.2.tar.gz
- Upload date:
- Size: 362.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3d192da8ee4b3151fbb8fd9a3d74863eb64412f7bd23925718cca5c86d2d69ab
|
|
| MD5 |
337173d5e7e4cabda44669ebbd65ab55
|
|
| BLAKE2b-256 |
95ca1782c6a4460993cae01f7e32d7ec4aa8036fee3aa4829f3fdce31422bde7
|
File details
Details for the file slide2vec-5.8.2-py3-none-any.whl.
File metadata
- Download URL: slide2vec-5.8.2-py3-none-any.whl
- Upload date:
- Size: 254.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.11.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
23136a1c64cc53af6fc945a422fe3ec24f5a2536a90b9847910d6dadf4ee3040
|
|
| MD5 |
db81d060233b42ecca4b056160ed58e2
|
|
| BLAKE2b-256 |
4569de09d98ae1713fe0627cfd5c119e43d707d834b57901da205ee4d8a06fc4
|
