slide2vec
slide2vec encodes whole-slide images with publicly available pathology foundation models. It uses hs2p for tissue detection and tiling, and handles batching, multi-GPU execution, and embedding storage.
Install
Python 3.10 or newer is required:
pip install slide2vec
Many models need additional dependencies available through pip install "slide2vec[fm]". See the model installation guide 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
from hs2p import TilingConfig
from slide2vec import Model, PreprocessingConfig
model = Model.from_preset("virchow2")
preprocessing = PreprocessingConfig(
tiling=TilingConfig(
requested_spacing_um=0.5, requested_tile_size_px=224, tolerance=0.05, overlap=0.0
),
)
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
tiling is an hs2p TilingConfig. Leave it unset to take spacing and tile size from the preset; Virchow2 supports several scales, so it needs an explicit one. The preset also supplies precision. Use list_models() to list presets, or filter with list_models("tile"), list_models("slide"), or list_models("patient").
See getting started for preprocessing and execution settings, and the API guide for patient embeddings, image inputs, and dense grids.
Save a batch
Create a CSV manifest:
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.
from slide2vec import ExecutionOptions, Model, Pipeline
pipeline = Pipeline(
model=Model.from_preset("virchow2"),
preprocessing=preprocessing, # from the example above
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 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.
The same batch workflow is available from the terminal:
slide2vec /path/to/config.yaml
The CLI guide provides a complete config example, overrides, and resume instructions.
Docker
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
1 maintainer
Metadata
1 maintainer
Release files for slide2vec 7.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| slide2vec-7.1.0.tar.gz | 429.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| slide2vec-7.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 710.0 kB
Release files / slide2vec-7.1.0.tar.gz
| Download URL | slide2vec-7.1.0.tar.gz |
|---|---|
| Size | 429.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
579ef97ddeede1f798bf4f01a1d2e21f21bccb16cc2722d0ba525d5ca0b20786
|
|
BLAKE2b-256 checksum How to use checksums |
da746ae20fd9e17ea328a382c0e9c39432eecddd08cbfb46c8865747585ccd70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / slide2vec-7.1.0-py3-none-any.whl
| Download URL | slide2vec-7.1.0-py3-none-any.whl |
|---|---|
| Size | 280.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ea45b49ed8b0044bbc4381e518d7fec31509cccecb0419eb56fbfd4799df743
|
|
BLAKE2b-256 checksum How to use checksums |
2451641bda4080c2b77ab35fca8d675bd6beb10bb7a8aa9528852792fcfb9731
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
