slide2vec 4.2.0__tar.gz → 4.3.0__tar.gz

{slide2vec-4.2.0 → slide2vec-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 4.2.0
+Version: 4.3.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: hs2p[asap,cucim,openslide,vips]>=3.2.1
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.0.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -65,7 +65,7 @@ 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,vips]>=3.2.1; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.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"
@@ -89,6 +89,12 @@ 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"
@@ -101,9 +107,12 @@ 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` is a Python package for efficient encoding of whole-slide images using publicly available foundation models. It builds on [`hs2p`](https://pypi.org/project/hs2p/) for fast preprocessing and exposes a focused surface around `Model`, `Pipeline`, and `ExecutionOptions`.
 
+Documentation site: [https://clemsgrs.github.io/slide2vec/](https://clemsgrs.github.io/slide2vec/)
+
 ## Installation
 
 ```shell
@@ -121,6 +130,8 @@ 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.
+
 ## Python API
 
 ```python
@@ -137,6 +148,17 @@ x = embedded.x
 y = embedded.y
 ```
 
+Use `list_models()` when you want to inspect the shipped presets programmatically:
+
+```python
+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:
 
 ```python
@@ -235,7 +257,8 @@ docker run --rm -it \
 
 ## Documentation
 
-- [`docs/cli.md`](docs/cli.md) for the config-driven CLI guide
+- [Documentation website](https://clemsgrs.github.io/slide2vec/) for the polished docs site
 - [`docs/python-api.md`](docs/python-api.md) for the detailed API reference
-- [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API
+- [`docs/cli.md`](docs/cli.md) for the config-driven CLI guide
 - [`docs/models.md`](docs/models.md) for the full supported-model catalog
+- [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

{slide2vec-4.2.0 → slide2vec-4.3.0}/README.md

@@ -1,9 +1,12 @@
 # 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` is a Python package for efficient encoding of whole-slide images using publicly available foundation models. It builds on [`hs2p`](https://pypi.org/project/hs2p/) for fast preprocessing and exposes a focused surface around `Model`, `Pipeline`, and `ExecutionOptions`.
 
+Documentation site: [https://clemsgrs.github.io/slide2vec/](https://clemsgrs.github.io/slide2vec/)
+
 ## Installation
 
 ```shell
@@ -21,6 +24,8 @@ 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.
+
 ## Python API
 
 ```python
@@ -37,6 +42,17 @@ x = embedded.x
 y = embedded.y
 ```
 
+Use `list_models()` when you want to inspect the shipped presets programmatically:
+
+```python
+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:
 
 ```python
@@ -135,7 +151,8 @@ docker run --rm -it \
 
 ## Documentation
 
-- [`docs/cli.md`](docs/cli.md) for the config-driven CLI guide
+- [Documentation website](https://clemsgrs.github.io/slide2vec/) for the polished docs site
 - [`docs/python-api.md`](docs/python-api.md) for the detailed API reference
-- [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API
+- [`docs/cli.md`](docs/cli.md) for the config-driven CLI guide
 - [`docs/models.md`](docs/models.md) for the full supported-model catalog
+- [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

{slide2vec-4.2.0 → slide2vec-4.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "4.2.0"
+version = "4.3.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "hs2p[asap,cucim,openslide,vips]>=3.2.1",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.0.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -88,7 +88,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,vips]>=3.2.1",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.0.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -113,6 +113,13 @@ fm = [
     "ninja==1.11.1.1",
     "psutil<6",
 ]
+docs = [
+    "sphinx>=8.1",
+    "furo",
+    "myst-parser",
+    "sphinx-copybutton",
+    "sphinx-autodoc-typehints",
+]
 testing = [
     "pytest>=6.0",
     "pytest-cov>=2.0",
@@ -157,7 +164,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "4.2.0"
+current_version = "4.3.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false       # We do version bumping in CI, not as a commit
 tag = false          # Git tag already exists — we don't auto-tag

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/__init__.py

@@ -1,11 +1,20 @@
-from slide2vec.api import EmbeddedSlide, ExecutionOptions, Model, Pipeline, PreprocessingConfig, RunResult
+from slide2vec.api import (
+    EmbeddedSlide,
+    ExecutionOptions,
+    Model,
+    Pipeline,
+    PreprocessingConfig,
+    RunResult,
+    list_models,
+)
 from slide2vec.artifacts import HierarchicalEmbeddingArtifact, SlideEmbeddingArtifact, TileEmbeddingArtifact
 
 
-__version__ = "4.2.0"
+__version__ = "4.3.0"
 
 __all__ = [
     "Model",
+    "list_models",
     "Pipeline",
     "PreprocessingConfig",
     "ExecutionOptions",

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/api.py

@@ -20,9 +20,9 @@ from slide2vec.encoders.registry import (
     resolve_preprocessing_defaults,
 )
 from slide2vec.encoders.validation import validate_encoder_config
-from slide2vec.model_settings import canonicalize_model_name, normalize_precision_name
+from slide2vec.runtime.model_settings import canonicalize_model_name, normalize_precision_name
 from slide2vec.progress import emit_progress
-from slide2vec.runtime_types import LoadedModel
+from slide2vec.runtime.types import LoadedModel
 from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
 
 PathLike = str | Path
@@ -72,8 +72,17 @@ class PreprocessingConfig:
         gpu_decode = bool(tiling.gpu_decode)
         adaptive_batching = bool(tiling.adaptive_batching)
         preview_cfg = tiling.preview
-        preview_save = bool(preview_cfg.save)
-        preview_downsample = int(preview_cfg.downsample)
+        preview_save = bool(preview_cfg.save_mask_preview)
+        preview_tiling_save = bool(preview_cfg.save_tiling_preview)
+        preview_kwargs: dict[str, Any] = {
+            "save_mask_preview": preview_save,
+            "save_tiling_preview": preview_tiling_save,
+            "downsample": int(preview_cfg.downsample),
+        }
+        preview_kwargs["tissue_contour_color"] = tuple(
+            int(channel) for channel in preview_cfg.tissue_contour_color
+        )
+        preview_kwargs["mask_overlay_alpha"] = float(preview_cfg.mask_overlay_alpha)
         return cls(
             backend=tiling.backend,
             requested_spacing_um=float(tiling.params.requested_spacing_um),
@@ -104,11 +113,7 @@ class PreprocessingConfig:
             resume=bool(cfg.resume),
             segmentation=dict(tiling.seg_params),
             filtering=dict(tiling.filter_params),
-            preview={
-                "save_mask_preview": preview_save,
-                "save_tiling_preview": preview_save,
-                "downsample": preview_downsample,
-            },
+            preview=preview_kwargs,
         )
 
     def with_backend(self, backend: str) -> "PreprocessingConfig":
@@ -444,6 +449,27 @@ class Model:
         return self._backend
 
 
+def list_models(level: str | None = None) -> list[str]:
+    """Return the available preset model names in a stable order.
+
+    Args:
+        level: Optional model level filter. Supported values are ``"tile"``,
+            ``"slide"``, and ``"patient"``.
+    """
+    if level is None:
+        return sorted(encoder_registry.names())
+
+    normalized_level = str(level).strip().lower()
+    if normalized_level not in {"tile", "slide", "patient"}:
+        raise ValueError("list_models(level=...) must be one of: tile, slide, patient")
+
+    return sorted(
+        name
+        for name in encoder_registry.names()
+        if encoder_registry.info(name)["level"] == normalized_level
+    )
+
+
 class Pipeline:
     def __init__(
         self,

slide2vec-4.3.0/slide2vec/configs/__init__.py

@@ -0,0 +1,4 @@
+from slide2vec.configs.resources import load_config
+
+
+default_config = load_config("default")

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/configs/default.yaml

@@ -38,12 +38,14 @@ tiling:
     # downsample controls which pyramid level is read for tissue segmentation.
     # Larger values are faster and use less memory; smaller values can improve mask precision.
     downsample: 64 # find the closest downsample in the slide for tissue segmentation
-    sthresh: 8 # segmentation threshold (positive integer, using a higher threshold leads to less foreground and more background detection) (not used when use_otsu=True)
+    sthresh: 8 # segmentation threshold (positive integer, using a higher threshold leads to less foreground and more background detection) (not used when method="otsu")
     sthresh_up: 255 # upper threshold value for scaling the binary mask
     mthresh: 7 # median filter size (positive, odd integer)
     close: 4 # additional morphological closing to apply following initial thresholding (positive integer)
-    use_otsu: false # use otsu's method instead of simple binary thresholding
-    use_hsv: true # use HSV thresholding instead of simple binary thresholding
+    method: "hsv" # tissue segmentation method: "hsv", "otsu", "threshold", or "sam2"
+    sam2_checkpoint_path: # optional when method="sam2"; if empty, hs2p downloads the default AtlasPatch checkpoint from Hugging Face
+    sam2_config_path: # optional local override for the SAM2 model config; if empty, hs2p downloads the default AtlasPatch config from Hugging Face
+    sam2_device: "cpu" # device for SAM2 inference, e.g. "cpu", "cuda", or "cuda:0"
   filter_params:
     ref_tile_size: ${tiling.params.requested_tile_size_px} # reference tile size at the target spacing
     a_t: 4 # area filter threshold for tissue (positive integer, the minimum size of detected foreground contours to consider, relative to the reference tile size ref_tile_size, e.g. a value 10 means only detected foreground contours of size greater than 10 [ref_tile_size, ref_tile_size] tiles at spacing tiling.params.requested_spacing_um will be kept)
@@ -60,9 +62,10 @@ tiling:
     blur_threshold: 50.0 # minimum blur score (higher is sharper)
     qc_spacing_um: 2.0 # spacing at which pixel-based QC is evaluated
   preview:
-    save: true # save preview images of slide tiling and mask overlays
+    save_mask_preview: true # save preview images of mask overlays
+    save_tiling_preview: true # save preview images of tile layouts
     downsample: 32 # downsample to use for preview rendering
-    mask_overlay_color: [157, 219, 129] # RGB color used for tissue overlays in batch mask previews
+    tissue_contour_color: [157, 219, 129] # RGB color used for tissue contours in batch mask previews
     mask_overlay_alpha: 0.5 # alpha used for tissue overlays in batch mask previews
 
 speed:

{slide2vec-4.2.0/slide2vec → slide2vec-4.3.0/slide2vec/configs}/resources.py

@@ -1,7 +1,7 @@
+from contextlib import contextmanager
 from importlib.resources import as_file, files
 from pathlib import Path
 from typing import Iterator
-from contextlib import contextmanager
 
 
 def config_resource(*parts: str):
@@ -24,3 +24,4 @@ def config_path(*parts: str) -> Iterator[Path]:
     resource = config_resource(*parts)
     with as_file(resource) as resolved:
         yield resolved
+

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/distributed/direct_embed_worker.py

@@ -26,11 +26,10 @@ def main(argv=None) -> int:
         _compute_tile_embeddings_for_slide,
         _is_hierarchical_preprocessing,
         _resolve_hierarchical_geometry,
-        deserialize_execution,
-        deserialize_preprocessing,
         load_successful_tiled_slides,
     )
     from slide2vec.progress import JsonlProgressReporter, activate_progress_reporter
+    from slide2vec.runtime.serialization import deserialize_execution, deserialize_preprocessing
 
     parser = get_args_parser(add_help=True)
     args = parser.parse_args(argv)
@@ -49,6 +48,7 @@ def main(argv=None) -> int:
             model_spec["name"],
             device=f"cuda:{local_rank}",
             output_variant=model_spec.get("output_variant"),
+            allow_non_recommended_settings=bool(model_spec["allow_non_recommended_settings"]),
         )
         preprocessing = deserialize_preprocessing(request["preprocessing"])
         execution = deserialize_execution(request["execution"])

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/distributed/pipeline_worker.py

@@ -3,7 +3,7 @@ from contextlib import nullcontext
 import json
 from pathlib import Path
 
-from slide2vec.inference import _assign_slides_to_ranks
+from slide2vec.runtime.distributed import assign_slides_to_ranks
 
 
 def get_args_parser(add_help: bool = True) -> argparse.ArgumentParser:
@@ -21,11 +21,10 @@ def main(argv=None) -> int:
     from slide2vec.inference import (
         _compute_embedded_slides,
         _persist_embedded_slide,
-        deserialize_execution,
-        deserialize_preprocessing,
         load_successful_tiled_slides,
     )
     from slide2vec.progress import JsonlProgressReporter, activate_progress_reporter
+    from slide2vec.runtime.serialization import deserialize_execution, deserialize_preprocessing
 
     parser = get_args_parser(add_help=True)
     args = parser.parse_args(argv)
@@ -43,11 +42,12 @@ def main(argv=None) -> int:
             model_spec["name"],
             device=f"cuda:{local_rank}",
             output_variant=model_spec.get("output_variant"),
+            allow_non_recommended_settings=bool(model_spec["allow_non_recommended_settings"]),
         )
         preprocessing = deserialize_preprocessing(request["preprocessing"])
         execution = deserialize_execution(request["execution"])
         slide_records, tiling_results = load_successful_tiled_slides(output_dir)
-        assignments = _assign_slides_to_ranks(slide_records, tiling_results, num_gpus=world_size)
+        assignments = assign_slides_to_ranks(slide_records, tiling_results, num_gpus=world_size)
         assigned_ids = assignments.get(global_rank, [])
         if not assigned_ids:
             return 0

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/encoders/registry.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-from slide2vec.registry import Registry
+from slide2vec.runtime.registry import Registry
 
 encoder_registry = Registry("encoders")
 

{slide2vec-4.2.0 → slide2vec-4.3.0}/slide2vec/encoders/validation.py

@@ -8,7 +8,7 @@ from slide2vec.encoders.registry import (
     resolve_encoder_output,
     resolve_preprocessing_requirements,
 )
-from slide2vec.model_settings import normalize_precision_name
+from slide2vec.runtime.model_settings import normalize_precision_name
 
 logger = logging.getLogger("slide2vec")