slide2vec 4.1.1__tar.gz → 4.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 4.1.1
+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.0
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.0.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -50,6 +50,8 @@ Requires-Dist: xformers==0.0.31; extra == "prism"
 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"
@@ -63,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.0; 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"
@@ -87,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"
@@ -99,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
@@ -119,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
@@ -135,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
@@ -210,7 +234,7 @@ The CLI is a thin wrapper over the package API.
 Bundled configs live under `slide2vec/configs/preprocessing/` and `slide2vec/configs/models/`.
 
 ```shell
-python -m slide2vec --config-file /path/to/config.yaml
+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.
@@ -233,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.1.1 → 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
@@ -112,7 +128,7 @@ The CLI is a thin wrapper over the package API.
 Bundled configs live under `slide2vec/configs/preprocessing/` and `slide2vec/configs/models/`.
 
 ```shell
-python -m slide2vec --config-file /path/to/config.yaml
+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.
@@ -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.1.1 → slide2vec-4.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "4.1.1"
+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.0",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.0.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -42,7 +42,7 @@ Homepage = "https://github.com/clemsgrs/slide2vec"
 "Bug Tracker" = "https://github.com/clemsgrs/slide2vec/issues"
 
 [project.scripts]
-slide2vec = "slide2vec.cli:main"
+slide2vec = "slide2vec.cli:entrypoint"
 
 [project.optional-dependencies]
 hoptimus = [
@@ -71,6 +71,9 @@ hibou = [
     "scipy~=1.8.1",
     "scikit-image~=0.19.3",
 ]
+moozy = [
+    "huggingface_hub>=0.30.0,<1.0",
+]
 titan = [
     "torch==2.0.1",
     "timm==1.0.3",
@@ -85,7 +88,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,vips]>=3.2.0",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.0.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -110,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",
@@ -154,7 +164,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "4.1.1"
+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.1.1 → 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.1.1"
+__version__ = "4.3.0"
 
 __all__ = [
     "Model",
+    "list_models",
     "Pipeline",
     "PreprocessingConfig",
     "ExecutionOptions",

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

@@ -11,6 +11,7 @@ from hs2p import SlideSpec
 
 from slide2vec.artifacts import (
     HierarchicalEmbeddingArtifact,
+    PatientEmbeddingArtifact,
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
 )
@@ -19,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
@@ -71,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),
@@ -103,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":
@@ -127,6 +133,7 @@ class ExecutionOptions:
     prefetch_factor: int = 4
     persistent_workers: bool = True
     save_tile_embeddings: bool = False
+    save_slide_embeddings: bool = False
     save_latents: bool = False
 
     @classmethod
@@ -151,6 +158,7 @@ class ExecutionOptions:
             prefetch_factor=prefetch_factor,
             persistent_workers=persistent_workers,
             save_tile_embeddings=bool(cfg.model.save_tile_embeddings),
+            save_slide_embeddings=bool(cfg.model.save_slide_embeddings),
             save_latents=bool(cfg.model.save_latents),
         )
 
@@ -200,9 +208,17 @@ class RunResult:
     tile_artifacts: list[TileEmbeddingArtifact]
     hierarchical_artifacts: list[HierarchicalEmbeddingArtifact]
     slide_artifacts: list[SlideEmbeddingArtifact]
+    patient_artifacts: list[PatientEmbeddingArtifact] = field(default_factory=list)
     process_list_path: Path | None = None
 
 
+@dataclass(frozen=True, kw_only=True)
+class EmbeddedPatient:
+    patient_id: str
+    patient_embedding: Any  # torch.Tensor [D]
+    slide_embeddings: dict[str, Any]  # {sample_id: torch.Tensor [D]}
+
+
 @dataclass(frozen=True, kw_only=True)
 class EmbeddedSlide:
     sample_id: str
@@ -343,6 +359,82 @@ class Model:
                 execution=resolved,
             )
 
+    def embed_patient(
+        self,
+        slides: SlideSequence,
+        patient_id: str | None = None,
+        *,
+        preprocessing: PreprocessingConfig | None = None,
+        execution: ExecutionOptions | None = None,
+    ) -> "EmbeddedPatient":
+        """Embed a single patient's slides and return one ``EmbeddedPatient``.
+
+        Convenience wrapper around :meth:`embed_patients` for the common case
+        where all *slides* belong to the same patient.
+
+        Args:
+            slides: All slides for this patient.
+            patient_id: Optional patient identifier applied to every slide.
+                When omitted, ``patient_id`` is read from slide dict keys or
+                object attributes; slides that carry no ``patient_id`` fall
+                back to ``sample_id``.
+        """
+        patient_id_map: dict | None = None
+        if patient_id is not None:
+            patient_id_map = {}
+            for s in slides:
+                if isinstance(s, (str, Path)):
+                    patient_id_map[Path(s).stem] = patient_id
+                elif isinstance(s, dict):
+                    patient_id_map[str(s["sample_id"])] = patient_id
+                else:
+                    patient_id_map[str(s.sample_id)] = patient_id
+        return self.embed_patients(
+            slides,
+            patient_id_map=patient_id_map,
+            preprocessing=preprocessing,
+            execution=execution,
+        )[0]
+
+    def embed_patients(
+        self,
+        slides: SlideSequence,
+        patient_id_map: dict | None = None,
+        *,
+        preprocessing: PreprocessingConfig | None = None,
+        execution: ExecutionOptions | None = None,
+    ) -> "list[EmbeddedPatient]":
+        """Embed slides and aggregate them into patient-level embeddings.
+
+        Requires a patient-level model (e.g. ``moozy``).  For each patient
+        all contributing slide embeddings are aggregated by the model's
+        ``encode_patient`` method.
+
+        Args:
+            slides: Slides to process.  Each entry may be a path, a
+                ``SlideSpec``, or a dict with ``sample_id`` / ``image_path``
+                keys.  When *patient_id_map* is ``None`` a ``patient_id``
+                key in each dict is used to group slides.
+            patient_id_map: Optional explicit ``{sample_id: patient_id}``
+                mapping.  When provided it takes precedence over any
+                ``patient_id`` key embedded in the slide dicts.  When
+                omitted and the slide dicts carry no ``patient_id``, each
+                slide is treated as its own patient.
+        """
+        from slide2vec.inference import embed_patients
+
+        resolved = _coerce_execution_options(execution, model=self)
+        resolved_preprocessing = _resolve_direct_api_preprocessing(self, preprocessing)
+        with _auto_progress_reporting(output_dir=resolved.output_dir):
+            _validate_model_config(self, resolved_preprocessing, resolved)
+            return embed_patients(
+                self,
+                slides,
+                patient_id_map=patient_id_map,
+                preprocessing=resolved_preprocessing,
+                execution=resolved,
+            )
+
     def _load_backend(self) -> LoadedModel:
         if self._backend is None:
             from slide2vec.inference import load_model
@@ -357,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.1.1 → slide2vec-4.3.0}/slide2vec/artifacts.py

@@ -35,6 +35,20 @@ class SlideEmbeddingArtifact:
         return load_metadata(self.metadata_path)
 
 
+@dataclass(frozen=True, kw_only=True)
+class PatientEmbeddingArtifact:
+    patient_id: str
+    path: Path
+    metadata_path: Path
+    format: str
+    feature_dim: int
+    num_slides: int
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return load_metadata(self.metadata_path)
+
+
 @dataclass(frozen=True, kw_only=True)
 class HierarchicalEmbeddingArtifact:
     sample_id: str
@@ -223,6 +237,45 @@ def write_slide_embeddings(
     )
 
 
+def write_patient_embeddings(
+    patient_id: str,
+    embedding,
+    *,
+    output_dir: str | Path,
+    output_format: str = "pt",
+    metadata: dict[str, Any] | None = None,
+    num_slides: int = 0,
+) -> PatientEmbeddingArtifact:
+    output_format = _validate_output_format(output_format)
+    artifact_path, metadata_path = _setup_artifact_paths(
+        output_dir, "patient_embeddings", patient_id, output_format
+    )
+    embedding_array = _ensure_array(embedding)
+    if output_format == "pt":
+        torch.save(_ensure_tensor(embedding), artifact_path)
+    else:
+        np.savez_compressed(artifact_path, features=embedding_array)
+
+    patient_metadata = {
+        "patient_id": patient_id,
+        "artifact_type": "patient_embeddings",
+        "format": output_format,
+        "feature_dim": int(embedding_array.shape[-1]) if embedding_array.ndim else 1,
+        "num_slides": num_slides,
+    }
+    if metadata:
+        patient_metadata.update(metadata)
+    _write_metadata(metadata_path, patient_metadata)
+    return PatientEmbeddingArtifact(
+        patient_id=patient_id,
+        path=artifact_path,
+        metadata_path=metadata_path,
+        format=output_format,
+        feature_dim=patient_metadata["feature_dim"],
+        num_slides=num_slides,
+    )
+
+
 def write_hierarchical_embeddings(
     sample_id: str,
     features,

{slide2vec-4.1.1 → slide2vec-4.3.0}/slide2vec/cli.py

@@ -7,20 +7,21 @@ import slide2vec.progress as progress
 
 def get_args_parser(add_help: bool = True):
     parser = argparse.ArgumentParser("slide2vec", add_help=add_help)
-    parser.add_argument("--config-file", default="", metavar="FILE", help="path to config file")
+    parser.add_argument("config_file", metavar="CONFIG", help="path to config file")
     parser.add_argument("--skip-datetime", action="store_true", help="skip run id datetime prefix")
     parser.add_argument("--tiling-only", action="store_true", help="only run slide tiling")
     parser.add_argument("--run-on-cpu", action="store_true", help="run inference on cpu")
     parser.add_argument("--output-dir", type=str, default=None, help="output directory to save artifacts")
-    parser.add_argument(
-        "opts",
-        help='Modify config options at the end of the command using "path.key=value".',
-        default=None,
-        nargs=argparse.REMAINDER,
-    )
     return parser
 
 
+def parse_args(argv=None):
+    parser = get_args_parser(add_help=True)
+    args, opts = parser.parse_known_args(argv)
+    args.opts = opts
+    return args
+
+
 def build_model_and_pipeline(args):
     cfg, _cfg_path = setup(args)
     hf_login()
@@ -39,8 +40,7 @@ def build_model_and_pipeline(args):
 
 
 def main(argv=None):
-    parser = get_args_parser(add_help=True)
-    args = parser.parse_args(argv)
+    args = parse_args(argv)
     pipeline, cfg = build_model_and_pipeline(args)
     reporter = progress.create_cli_progress_reporter(output_dir=getattr(cfg, "output_dir", None))
     with progress.activate_progress_reporter(reporter):
@@ -50,3 +50,6 @@ def main(argv=None):
         )
 
 
+def entrypoint(argv=None):
+    main(argv)
+    return 0

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.1.1 → slide2vec-4.3.0}/slide2vec/configs/default.yaml

@@ -13,6 +13,7 @@ model:
   output_variant: # requested output variant for presets that expose multiple outputs
   batch_size: 32
   save_tile_embeddings: false # whether to save tile embeddings alongside the pooled slide embedding when level is "slide"
+  save_slide_embeddings: false # whether to save per-slide embeddings when level is "patient" (e.g. moozy); requires a 'patient_id' column in the input CSV
   save_latents: false # whether to save the latent representations from the model alongside the slide embedding (only supported for 'prism')
   allow_non_recommended_settings: false # when true, non-recommended spacing / tile size / precision combinations warn instead of erroring
 
@@ -37,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)
@@ -59,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.1.1/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.1.1 → 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"])