slide2vec 5.3.0__tar.gz → 5.4.0__tar.gz

{slide2vec-5.3.0 → slide2vec-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.3.0
+Version: 5.4.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,sam2,vips]>=4.2.0
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.3.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,sam2,vips]>=4.2.0; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.3.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"

{slide2vec-5.3.0 → slide2vec-5.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.3.0"
+version = "5.4.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,sam2,vips]>=4.2.0",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.3.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -88,7 +88,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.2.0",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.3.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -167,7 +167,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.3.0"
+current_version = "5.4.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-5.3.0 → slide2vec-5.4.0}/slide2vec/__init__.py

@@ -1,4 +1,5 @@
 from slide2vec.api import (
+    DenseOptions,
     EmbeddedPatient,
     EmbeddedSlide,
     ExecutionOptions,
@@ -6,18 +7,26 @@ from slide2vec.api import (
     Pipeline,
     PreprocessingConfig,
     RunResult,
+    SlideRegions,
     list_models,
 )
-from slide2vec.artifacts import HierarchicalEmbeddingArtifact, SlideEmbeddingArtifact, TileEmbeddingArtifact
+from slide2vec.artifacts import (
+    DenseRegionArtifact,
+    HierarchicalEmbeddingArtifact,
+    SlideEmbeddingArtifact,
+    TileEmbeddingArtifact,
+)
 
 
-__version__ = "5.3.0"
+__version__ = "5.4.0"
 
 __all__ = [
     "Model",
     "list_models",
     "Pipeline",
     "PreprocessingConfig",
+    "DenseOptions",
+    "SlideRegions",
     "ExecutionOptions",
     "RunResult",
     "EmbeddedPatient",
@@ -25,5 +34,6 @@ __all__ = [
     "SlideEmbeddingArtifact",
     "HierarchicalEmbeddingArtifact",
     "TileEmbeddingArtifact",
+    "DenseRegionArtifact",
     "__version__",
 ]

{slide2vec-5.3.0 → slide2vec-5.4.0}/slide2vec/api.py

@@ -11,6 +11,7 @@ import torch
 from hs2p import SlideSpec
 
 from slide2vec.artifacts import (
+    DenseRegionArtifact,
     HierarchicalEmbeddingArtifact,
     PatientEmbeddingArtifact,
     SlideEmbeddingArtifact,
@@ -28,6 +29,7 @@ from slide2vec.runtime.model_settings import (
 )
 from slide2vec.progress import emit_progress
 from slide2vec.runtime.types import LoadedModel
+from slide2vec.runtime.pooled_encoder_input import PooledEncoderInputPlan
 from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
 
 PathLike = str | Path
@@ -101,6 +103,13 @@ class PreprocessingConfig:
     #: Slide reading backend. ``"auto"`` tries cucim → openslide → vips in order.
     #: Explicit choices: ``"cucim"``, ``"openslide"``, ``"vips"``, ``"asap"``.
     backend: str = "auto"
+    #: Source-mask reading backend, resolved independently from the *mask* path
+    #: (hs2p ≥ 4.3.0). ``"auto"`` probes openability just like :attr:`backend`. Set this
+    #: explicitly (e.g. ``"openslide"``) when a precomputed tissue or annotation mask needs
+    #: a different decoder than its slide — hs2p no longer silently falls back to another
+    #: reader, so a mask the slide backend cannot decode fails unless overridden here.
+    #: Accepts the same values as :attr:`backend`; ignored for slides with no source mask.
+    mask_backend: str = "auto"
     #: Target spacing in µm/px. Resolved from the model preset when ``None``.
     requested_spacing_um: float | None = None
     #: Tile side length in pixels at *requested_spacing_um*.
@@ -181,6 +190,7 @@ class PreprocessingConfig:
         region_tile_multiple = getattr(tiling.params, "region_tile_multiple", None)
         return cls(
             backend=tiling.backend,
+            mask_backend=getattr(tiling, "mask_backend", "auto"),
             requested_spacing_um=float(tiling.params.requested_spacing_um),
             requested_tile_size_px=int(tiling.params.requested_tile_size_px),
             requested_region_size_px=int(region_size_px) if region_size_px is not None else None,
@@ -208,6 +218,9 @@ class PreprocessingConfig:
     def with_backend(self, backend: str) -> "PreprocessingConfig":
         return replace(self, backend=backend)
 
+    def with_mask_backend(self, mask_backend: str) -> "PreprocessingConfig":
+        return replace(self, mask_backend=mask_backend)
+
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -312,6 +325,63 @@ class ExecutionOptions:
         return replace(self, output_dir=Path(output_dir))
 
 
+@dataclass(frozen=True, kw_only=True)
+class DenseOptions:
+    """Dense ``(d, gh, gw)`` grid extraction settings (issue #217).
+
+    The dense counterpart of the pooled :class:`PreprocessingConfig`: it names the
+    extraction geometry (spacing → level, supervision ``target_size``, padding) and the
+    dense encode knobs (whole-tile vs sliding-window, patch grid vs CLS-attention). Unlike
+    the pooled path there is no tiling — the caller supplies ROI coordinates directly (see
+    :class:`SlideRegions`) — so a ``DenseOptions`` carries only what slide2vec needs to read
+    and encode each ROI. ``ExecutionOptions`` is reused unchanged for output/precision/GPUs.
+    """
+
+    #: Target spacing in µm/px the ROI is read at (resolved to a pyramid level per slide).
+    spacing_um: float
+    #: Supervision tile side length in pixels at *spacing_um* (the dense grid registers to it).
+    target_size: int
+    #: Relative spacing tolerance for pyramid level selection.
+    tolerance: float = 0.05
+    #: Slide reading backend. ``"auto"`` resolves per slide (cucim → openslide → vips).
+    backend: str = "auto"
+    #: Padding mode used to pad the tile up to the encoder's patch multiple.
+    #: One of ``"reflect"`` / ``"replicate"`` / ``"constant"`` / ``"zero"``.
+    pad_mode: str = "reflect"
+    #: Constant fill value for ``pad_mode in {"constant", "zero"}`` (ignored otherwise).
+    image_pad_value: float | None = None
+    #: Encoder field-of-view chunk fed through the backbone per forward. ``None`` (default)
+    #: is one whole-tile forward; a smaller value slides the encoder and blends token grids.
+    window_size: int | None = None
+    #: Fractional window overlap in ``[0, 1)`` for the sliding path (ignored when
+    #: ``window_size is None``).
+    overlap: float = 0.0
+    #: ``"patch_features"`` (the patch-token grid) or ``"cls_attention"`` (CLS/register
+    #: self-attention grid).
+    feature_kind: str = "patch_features"
+    #: Transformer blocks whose CLS attention is read (``cls_attention`` only).
+    attention_blocks: tuple[int, ...] = (-1,)
+    #: Include register-token query rows as extra attention channels (``cls_attention`` only).
+    attention_include_registers: bool = False
+
+
+@dataclass(frozen=True, kw_only=True)
+class SlideRegions:
+    """One slide's ROIs for dense extraction: ``(sample_id, image_path, coordinates, annotation)``.
+
+    The dense input unit soma's slide-manifest path hands to
+    :meth:`Model.embed_regions_dense`. ``coordinates`` is an ``(N, 2)`` array of level-0
+    top-left ``(x, y)`` pixel coordinates; each ROI is read + encoded into one persisted
+    ``(d, gh, gw)`` grid named ``<x>_<y>.pt``. ``annotation`` namespaces the output under a
+    per-class subdirectory (reusing the pooled convention); ``None`` is the flat layout.
+    """
+
+    sample_id: str
+    image_path: PathLike
+    coordinates: Any
+    annotation: str | None = None
+
+
 @dataclass(frozen=True, kw_only=True)
 class RunResult:
     """Return value of :meth:`Pipeline.run`."""
@@ -374,6 +444,8 @@ class EmbeddedSlide:
     tiling_preview_path: Path | None = None
     #: Encoder latent representations when available; ``None`` otherwise.
     latents: Any | None = None
+    #: Factual square tensor side length immediately before tile encoding.
+    encoder_input_size_px: int | None = None
 
 
 class Model:
@@ -391,6 +463,8 @@ class Model:
         self.allow_non_recommended_settings = bool(allow_non_recommended_settings)
         self._output_variant = output_variant
         self._backend: LoadedModel | None = None
+        self._pooled_input_plan: PooledEncoderInputPlan | None = None
+        self._backend_pooled_input_plan: PooledEncoderInputPlan | None = None
 
     @classmethod
     def from_preset(
@@ -588,8 +662,58 @@ class Model:
                 execution=resolved,
             )
 
+    def embed_regions_dense(
+        self,
+        regions: "Sequence[SlideRegions]",
+        *,
+        dense: "DenseOptions",
+        execution: ExecutionOptions | None = None,
+    ) -> list[DenseRegionArtifact]:
+        """Extract + persist a dense ``(d, gh, gw)`` grid per caller-supplied ROI.
+
+        The dense counterpart of the pooled coordinate path: each ``SlideRegions`` names a
+        slide + a set of level-0 ROI coordinates, and every ROI is read, encoded through the
+        dense transform, and written to ``dense_embeddings/[<class>/]<sample_id>/<x>_<y>.pt``
+        plus a geometry sidecar. The run splits its ROIs across all visible GPUs
+        (``execution.num_gpus``); ``num_gpus=1`` encodes fully in-process. Resume is
+        automatic — ROIs whose sidecar already exists are skipped. Returns one
+        :class:`~slide2vec.artifacts.DenseRegionArtifact` per input ROI.
+        """
+        from slide2vec.runtime.dense_stage import embed_regions_dense
+
+        resolved = _coerce_execution_options(execution, model=self)
+        _require_output_dir_for_persistence(resolved, method_name="Model.embed_regions_dense(...)")
+        with _auto_progress_reporting(output_dir=resolved.output_dir):
+            return embed_regions_dense(self, regions, dense=dense, execution=resolved)
+
+    def _prepare_pooled_input(
+        self,
+        preprocessing: PreprocessingConfig,
+        *,
+        emit_run_info: bool,
+    ) -> PooledEncoderInputPlan:
+        plan = PooledEncoderInputPlan.resolve(
+            self.name,
+            requested_tile_size_px=int(preprocessing.requested_tile_size_px),
+            allow_non_recommended_settings=self.allow_non_recommended_settings,
+        )
+        self._pooled_input_plan = plan
+        if emit_run_info and plan.requires_variable_model_input:
+            logging.getLogger("slide2vec").info(
+                "Pooled encoder input for '%s': preset %dpx, requested %dpx, "
+                "exact encoder input %dpx; using normalization-only preprocessing.",
+                self.name,
+                plan.preset_input_size_px,
+                plan.requested_tile_size_px,
+                plan.expected_encoder_input_size_px,
+            )
+        return plan
+
     def _load_backend(self) -> LoadedModel:
-        if self._backend is None:
+        if (
+            self._backend is None
+            or self._backend_pooled_input_plan != self._pooled_input_plan
+        ):
             from slide2vec.inference import load_model
 
             emit_progress("model.loading", model_name=self.name)
@@ -597,7 +721,10 @@ class Model:
                 name=self.name,
                 device=self._requested_device,
                 output_variant=self._output_variant,
+                allow_non_recommended_settings=self.allow_non_recommended_settings,
+                pooled_input_plan=self._pooled_input_plan,
             )
+            self._backend_pooled_input_plan = self._pooled_input_plan
             emit_progress("model.ready", model_name=self.name, device=str(self._backend.device))
         return self._backend
 
@@ -838,12 +965,12 @@ def _validate_model_config(
         info = encoder_registry.info(name)
         if info["level"] != "tile":
             raise ValueError("Hierarchical preprocessing is only supported for tile encoders")
+    model._prepare_pooled_input(preprocessing, emit_run_info=True)
     # Skip precision validation for CPU execution (fp32 is always valid on CPU).
     on_cpu = model._requested_device == "cpu"
     precision = None if on_cpu or execution is None else execution.precision
     validate_encoder_config(
         name,
-        requested_tile_size_px=preprocessing.requested_tile_size_px,
         requested_spacing_um=preprocessing.requested_spacing_um,
         precision=precision,
         output_variant=model._output_variant,

{slide2vec-5.3.0 → slide2vec-5.4.0}/slide2vec/artifacts.py

@@ -1,7 +1,9 @@
 from dataclasses import dataclass
 import json
-from pathlib import Path
+import os
+from pathlib import Path, PureWindowsPath
 from typing import Any
+from uuid import uuid4
 
 import numpy as np
 import torch
@@ -69,6 +71,30 @@ class HierarchicalEmbeddingArtifact:
         return load_metadata(self.metadata_path)
 
 
+@dataclass(frozen=True, kw_only=True)
+class DenseRegionArtifact:
+    """One persisted dense ROI grid: the ``(d, gh, gw)`` payload + its geometry sidecar.
+
+    Dense emits one *directory* per slide (``dense_embeddings/[<class>/]<sample_id>/``) and
+    one ``<x>_<y>.pt`` / ``<x>_<y>.meta.json`` pair per ROI — the counterpart of the pooled
+    one-file-per-slide artifacts. Named from what slide2vec knows (slide + level-0 top-left
+    coordinate); soma maps its ROI ``sample_id`` back onto ``(x, y)``.
+    """
+
+    sample_id: str
+    x: int
+    y: int
+    path: Path
+    metadata_path: Path
+    feature_dim: int
+    grid_shape: tuple[int, int]
+    annotation: str | None = None
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return load_metadata(self.metadata_path)
+
+
 def _validate_output_format(output_format: str) -> str:
     normalized = output_format.lower()
     if normalized not in {"pt", "npz"}:
@@ -112,7 +138,15 @@ def _ensure_tensor(data: Any):
 
 def _write_metadata(path: Path, metadata: dict[str, Any]) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(metadata, indent=2, sort_keys=True), encoding="utf-8")
+    tmp_path = path.with_name(f".{path.name}.tmp-{os.getpid()}-{uuid4().hex}")
+    try:
+        tmp_path.write_text(
+            json.dumps(metadata, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+        os.replace(tmp_path, path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
 
 
 def tile_embeddings_subdir(annotation: str | None) -> str:
@@ -162,6 +196,89 @@ def hierarchical_embeddings_subdir(annotation: str | None) -> str:
     return f"hierarchical_embeddings/{annotation}"
 
 
+def _validate_path_component(value: str, *, field: str) -> str:
+    component = str(value)
+    if (
+        not component
+        or component in {".", ".."}
+        or "/" in component
+        or "\\" in component
+        or "\x00" in component
+        or PureWindowsPath(component).drive
+    ):
+        raise ValueError(f"{field} must be a non-empty filesystem path component")
+    return component
+
+
+def dense_embeddings_subdir(annotation: str | None) -> str:
+    """Namespace the ``dense_embeddings`` output dir per annotation class.
+
+    Reuses hs2p's flatten rule (the single source of truth, shared with
+    :func:`tile_embeddings_subdir` and the other pooled subdir helpers): ``None`` and the
+    sentinel ``"tissue"`` collapse to the flat ``dense_embeddings`` root; any real class
+    label gets its own ``dense_embeddings/<class>`` subdirectory.
+    """
+    if is_flattened_annotation(annotation):
+        return "dense_embeddings"
+    annotation_component = _validate_path_component(annotation, field="annotation")
+    return f"dense_embeddings/{annotation_component}"
+
+
+def region_dense_paths(
+    output_dir: str | Path, *, sample_id: str, annotation: str | None, x: int, y: int
+) -> tuple[Path, Path]:
+    """``(payload_path, sidecar_path)`` for one ROI: ``.../<sample_id>/<x>_<y>.{pt,meta.json}``.
+
+    Geometry-independent (named only from slide + level-0 ``(x, y)`` + class), so the resume
+    check can test sidecar existence before any slide is opened.
+    """
+    output_root = Path(output_dir).expanduser().resolve()
+    sample_component = _validate_path_component(sample_id, field="sample_id")
+    slide_dir = (output_root / dense_embeddings_subdir(annotation) / sample_component).resolve()
+    if not slide_dir.is_relative_to(output_root):
+        raise ValueError("Dense artifact path must stay within output_dir")
+    stem = f"{int(x)}_{int(y)}"
+    return slide_dir / f"{stem}.pt", slide_dir / f"{stem}.meta.json"
+
+
+def write_dense_region(
+    grid,
+    *,
+    output_dir: str | Path,
+    sample_id: str,
+    annotation: str | None,
+    x: int,
+    y: int,
+    metadata: dict[str, Any],
+) -> DenseRegionArtifact:
+    """Persist one ``(d, gh, gw)`` grid + its geometry sidecar, atomically and sidecar-last.
+
+    Write order (D6): payload to a temp file in the destination directory → ``os.replace``
+    into ``<x>_<y>.pt`` (atomic on the same filesystem) → then the ``<x>_<y>.meta.json``
+    sidecar. A payload present without its sidecar therefore unambiguously means an
+    incomplete ROI, and resume treats the sidecar as the done-marker.
+    """
+    payload_path, metadata_path = region_dense_paths(
+        output_dir, sample_id=sample_id, annotation=annotation, x=x, y=y
+    )
+    payload_path.parent.mkdir(parents=True, exist_ok=True)
+    grid_array = _ensure_array(grid)
+    tmp_path = payload_path.with_name(f"{payload_path.name}.tmp-{os.getpid()}")
+    torch.save(_ensure_tensor(grid), tmp_path)
+    os.replace(tmp_path, payload_path)
+    _write_metadata(metadata_path, metadata)
+    return DenseRegionArtifact(
+        sample_id=sample_id,
+        x=int(x),
+        y=int(y),
+        path=payload_path,
+        metadata_path=metadata_path,
+        feature_dim=int(grid_array.shape[0]),
+        grid_shape=(int(grid_array.shape[1]), int(grid_array.shape[2])),
+        annotation=annotation,
+    )
+
+
 def _setup_artifact_paths(
     output_dir: str | Path, subdir: str, sample_id: str, output_format: str
 ) -> tuple[Path, Path]:

{slide2vec-5.3.0 → slide2vec-5.4.0}/slide2vec/configs/default.yaml

@@ -26,6 +26,7 @@ tiling:
   read_coordinates_from: # path to an existing directory containing pre-extracted `.coordinates.npz` / `.coordinates.meta.json` artifacts to reuse instead of starting tiling from scratch
   read_tiles_from: # path to an existing directory containing pre-extracted `.tiles.tar` tile stores to reuse instead of starting tiling from scratch
   backend: "auto" # backend to use for slide reading; "auto" lets hs2p resolve the best backend per slide, preferring cuCIM when available
+  mask_backend: "auto" # backend for reading source masks (precomputed tissue / annotation), resolved independently from the mask path; "auto" probes openability like `backend`. Set explicitly (e.g. "openslide") when a mask needs a different decoder than its slide — hs2p (>=4.3.0) no longer silently falls back
   independent_sampling: true # selection strategy when annotation sampling is active. true: sample each class independently against its own binary mask (independent selection); false: sample once over the union of active classes, then post-filter per class by coverage (joint selection). Ignored when the masks vocabulary is left at the tissue-only default.
   masks:
     # Annotation-mask vocabulary forwarded to hs2p's sampling resolver. The shipped default