slide2vec 5.4.0__tar.gz → 5.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.4.0
+Version: 5.5.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.4.0"
+version = "5.5.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -167,7 +167,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.4.0"
+current_version = "5.5.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.4.0 → slide2vec-5.5.0}/slide2vec/__init__.py

@@ -1,8 +1,10 @@
 from slide2vec.api import (
+    DenseImageOptions,
     DenseOptions,
     EmbeddedPatient,
     EmbeddedSlide,
     ExecutionOptions,
+    ImageSpec,
     Model,
     Pipeline,
     PreprocessingConfig,
@@ -11,14 +13,16 @@ from slide2vec.api import (
     list_models,
 )
 from slide2vec.artifacts import (
+    DenseImageArtifact,
     DenseRegionArtifact,
     HierarchicalEmbeddingArtifact,
+    ImageEmbeddingArtifact,
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
 )
 
 
-__version__ = "5.4.0"
+__version__ = "5.5.0"
 
 __all__ = [
     "Model",
@@ -26,7 +30,9 @@ __all__ = [
     "Pipeline",
     "PreprocessingConfig",
     "DenseOptions",
+    "DenseImageOptions",
     "SlideRegions",
+    "ImageSpec",
     "ExecutionOptions",
     "RunResult",
     "EmbeddedPatient",
@@ -35,5 +41,7 @@ __all__ = [
     "HierarchicalEmbeddingArtifact",
     "TileEmbeddingArtifact",
     "DenseRegionArtifact",
+    "DenseImageArtifact",
+    "ImageEmbeddingArtifact",
     "__version__",
 ]

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

@@ -11,8 +11,10 @@ import torch
 from hs2p import SlideSpec
 
 from slide2vec.artifacts import (
+    DenseImageArtifact,
     DenseRegionArtifact,
     HierarchicalEmbeddingArtifact,
+    ImageEmbeddingArtifact,
     PatientEmbeddingArtifact,
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
@@ -29,7 +31,8 @@ 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.runtime.effective_encoder_input import format_input_size
+from slide2vec.runtime.encoder_input_contract import EncoderInputContract
 from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
 
 PathLike = str | Path
@@ -352,6 +355,51 @@ class DenseOptions:
     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.
+    #: Together with ``target_size`` this fixes the *effective encoder input* — the geometry
+    #: handed to ``encode_tiles_dense`` — from which the encoder's variable-input constructor
+    #: settings are derived; hence no ``dynamic_img_size`` knob here.
+    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 DenseImageOptions:
+    """Dense ``(d, gh, gw)`` grid extraction over pre-cropped images (issue #235).
+
+    :class:`DenseOptions` minus everything that only a slide has: there is no spacing, no
+    tolerance and no reading backend here, because the image *is* the region — it is read
+    from disk at the size it was written. What remains is the same supervision geometry and
+    the same dense encode knobs, so a run migrating from ROIs to image/mask pairs keeps its
+    recipe.
+
+    ``target_size`` is a **declaration**, not a resize: the dense transform is
+    normalization-only, so every image must already be exactly this size and one that is not
+    is an error rather than a silent rescale. Declaring it up front is what lets the
+    effective encoder input be validated (and the encoder's variable-input constructor
+    settings resolved) before a single image is decoded. A run whose images are not all the
+    same size is therefore several runs, one per geometry — which is also the only way their
+    grids could be batched downstream.
+    """
+
+    #: Supervision geometry in pixels the dense grid registers to: a square side length, or
+    #: an explicit ``(height, width)`` for non-square images.
+    target_size: int | tuple[int, int]
+    #: Padding mode used to pad the image 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-image 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``).
@@ -382,6 +430,22 @@ class SlideRegions:
     annotation: str | None = None
 
 
+@dataclass(frozen=True, kw_only=True)
+class ImageSpec:
+    """One pre-cropped image to embed: ``(sample_id, image_path)``.
+
+    The input unit of :meth:`Model.embed_images` — the Given-geometry counterpart of
+    :class:`SlideRegions`. There is no slide, no coordinate and no spacing here: the caller
+    holds an image file it never asked slide2vec to produce (a public patch benchmark
+    sample), and names it. ``sample_id`` is the artifact's whole identity, so it must be
+    unique within a run and a valid filename component; slide2vec never derives it from the
+    path, because two directories can hold the same filename.
+    """
+
+    sample_id: str
+    image_path: PathLike
+
+
 @dataclass(frozen=True, kw_only=True)
 class RunResult:
     """Return value of :meth:`Pipeline.run`."""
@@ -463,8 +527,13 @@ 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
+        # Unset, deliberately: a Model has no encoder-input contract until a route
+        # declares one. There is no initial Given contract, because an initial value is
+        # a default by another name — it would silently hand the shipped transform to
+        # any route that forgot to declare, which is the confusion this contract exists
+        # to delete. ``_load_backend`` refuses to load until this is set.
+        self._encoder_input: EncoderInputContract | None = None
+        self._backend_encoder_input: EncoderInputContract | None = None
 
     @classmethod
     def from_preset(
@@ -484,11 +553,13 @@ class Model:
 
     @property
     def device(self) -> Any:
-        return self._load_backend().device
+        # Construction fact, not an encode: see _load_backend_without_transform.
+        return self._load_backend_without_transform().device
 
     @property
     def feature_dim(self) -> int:
-        return int(self._load_backend().feature_dim)
+        # Construction fact, not an encode: see _load_backend_without_transform.
+        return int(self._load_backend_without_transform().feature_dim)
 
     def embed_tiles(
         self,
@@ -678,6 +749,12 @@ class Model:
         (``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.
+
+        The effective encoder input — the padded ROI for a whole-tile run, one
+        patch-aligned window for a sliding one — is declared before any region is read, so
+        a geometry the encoder cannot accept raises here rather than at the first forward
+        pass. Variable-input capable encoders get their registry-declared constructor
+        settings applied automatically; there is nothing for the caller to pass.
         """
         from slide2vec.runtime.dense_stage import embed_regions_dense
 
@@ -686,18 +763,99 @@ class Model:
         with _auto_progress_reporting(output_dir=resolved.output_dir):
             return embed_regions_dense(self, regions, dense=dense, execution=resolved)
 
-    def _prepare_pooled_input(
+    def embed_images_dense(
+        self,
+        images: "Sequence[ImageSpec]",
+        *,
+        dense: "DenseImageOptions",
+        execution: ExecutionOptions | None = None,
+    ) -> list[DenseImageArtifact]:
+        """Extract + persist a dense ``(d, gh, gw)`` grid per caller-supplied image.
+
+        The image-sourced counterpart of :meth:`embed_regions_dense`, for consumers whose
+        supervision arrives as image/mask pairs rather than as slides (segmentation,
+        detection): each :class:`ImageSpec` is decoded, run through the encoder's
+        **normalization-only** transform, padded up to the encoder's patch multiple, encoded
+        — whole-image, or by sliding the encoder's native field and blending the token grids
+        — and written to ``dense_image_embeddings/<sample_id>.pt`` plus a geometry sidecar.
+        The run splits its images across all visible GPUs (``execution.num_gpus``);
+        ``num_gpus=1`` encodes fully in-process. Resume is automatic — images whose sidecar
+        already exists are skipped. Returns one
+        :class:`~slide2vec.artifacts.DenseImageArtifact` per input image, in input order.
+
+        It differs from :meth:`embed_regions_dense` in exactly one respect: there is no
+        slide, no coordinate and no spacing→level plan, because the image *is* the region.
+        Everything else is shared, including the effective encoder input — the padded image
+        for a whole-image run, one patch-aligned window for a sliding one — which is declared
+        before any image is decoded, so a geometry the encoder cannot accept raises here
+        rather than on a torchrun rank's first forward pass.
+
+        ``dense.target_size`` is a declaration, not a resize request: dense extraction never
+        rescales, so every image must already be that size (a non-square ``(h, w)`` is fine).
+        """
+        from slide2vec.runtime.dense_image_stage import embed_images_dense
+
+        resolved = _coerce_execution_options(execution, model=self)
+        _require_output_dir_for_persistence(resolved, method_name="Model.embed_images_dense(...)")
+        with _auto_progress_reporting(output_dir=resolved.output_dir):
+            return embed_images_dense(self, images, dense=dense, execution=resolved)
+
+    def embed_images(
+        self,
+        images: "Sequence[ImageSpec]",
+        *,
+        execution: ExecutionOptions | None = None,
+    ) -> list[ImageEmbeddingArtifact]:
+        """Embed + persist one embedding per caller-supplied image.
+
+        The Given-geometry entry point: the caller already holds pre-cropped images — a
+        public patch benchmark (BACH, CRC, Gleason, BreakHis, MHIST, PCam), an exported ROI
+        set — and slide2vec neither tiles nor reads a slide. Each :class:`ImageSpec` is
+        decoded, preprocessed with the encoder's **shipped** transform, encoded, and written
+        to ``image_embeddings/<sample_id>.pt`` plus a provenance sidecar. The run splits its
+        images across all visible GPUs (``execution.num_gpus``); ``num_gpus=1`` encodes
+        fully in-process. Resume is automatic — images whose sidecar already exists are
+        skipped. Returns one :class:`~slide2vec.artifacts.ImageEmbeddingArtifact` per input
+        image, in input order.
+
+        Unlike the pooled and dense paths there is no geometry to declare: the images are
+        heterogeneously sized (2048x1536 beside 96x96) and were never requested, so the
+        encoder's shipped transform is the contract and slide2vec *records* the resulting
+        encoder input size as run provenance rather than validating it. That also means
+        preprocessing runs itemwise in the loader workers — differently sized images cannot
+        be stacked before they are resized.
+        """
+        from slide2vec.runtime.image_stage import embed_images
+
+        resolved = _coerce_execution_options(execution, model=self)
+        _require_output_dir_for_persistence(resolved, method_name="Model.embed_images(...)")
+        with _auto_progress_reporting(output_dir=resolved.output_dir):
+            return embed_images(self, images, execution=resolved)
+
+    def _declare_encoder_input(
         self,
         preprocessing: PreprocessingConfig,
         *,
         emit_run_info: bool,
-    ) -> PooledEncoderInputPlan:
-        plan = PooledEncoderInputPlan.resolve(
+    ) -> EncoderInputContract:
+        """Declare the pooled encoder input geometry this run requested, or raise.
+
+        Idempotent: resolving the same preprocessing twice yields an equal contract, so
+        every layer that reaches the encoder may declare for itself rather than trust
+        the layer above to have done it.
+        """
+        if preprocessing.requested_tile_size_px is None:
+            raise ValueError(
+                "requested_tile_size_px must be resolved before declaring the encoder "
+                "input geometry; a pooled run reads tiles at a size it requested."
+            )
+        contract = EncoderInputContract.declared_pooled(
             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
+        self._encoder_input = contract
+        plan = contract.plan
         if emit_run_info and plan.requires_variable_model_input:
             logging.getLogger("slide2vec").info(
                 "Pooled encoder input for '%s': preset %dpx, requested %dpx, "
@@ -707,24 +865,122 @@ class Model:
                 plan.requested_tile_size_px,
                 plan.expected_encoder_input_size_px,
             )
-        return plan
+        return contract
+
+    def _declare_dense_encoder_input(
+        self,
+        dense: "DenseOptions",
+        *,
+        emit_run_info: bool,
+    ) -> EncoderInputContract:
+        """Declare the dense encoder input geometry this run requested, or raise.
+
+        Dense states a supervision geometry (``target_size``, optional ``window_size``)
+        rather than an encoder input; the contract derives the tensor the backbone will
+        actually see and validates it exactly as the pooled path's is validated. Like the
+        pooled declaration this is idempotent, so each layer that reaches the encoder — the
+        parent stage and every torchrun rank — declares for itself.
+
+        *dense* is a :class:`DenseOptions` (ROIs on a slide) or a :class:`DenseImageOptions`
+        (pre-cropped images); only the supervision geometry is read here, and the two state
+        it the same way.
+        """
+        contract = EncoderInputContract.declared_dense(
+            self.name,
+            target_size_px=dense.target_size,
+            window_size=None if dense.window_size is None else int(dense.window_size),
+        )
+        self._encoder_input = contract
+        plan = contract.plan
+        if emit_run_info and plan.requires_variable_model_input:
+            logging.getLogger("slide2vec").info(
+                "Dense encoder input for '%s': native %dpx, effective encoder input %s "
+                "(target_size=%s, window_size=%s); enabling variable input size via %s.",
+                self.name,
+                plan.preset_input_size_px,
+                format_input_size(plan.effective_encoder_input_size_px),
+                format_input_size(plan.target_size_px),
+                plan.window_size_px,
+                plan.model_construction_kwargs or "no constructor setting",
+            )
+        return contract
+
+    def _declare_given_encoder_input(self, *, emit_run_info: bool) -> EncoderInputContract:
+        """Declare that this run's encoder input is whatever the caller handed over.
+
+        The Given regime's affirmative statement. It is deliberately not the same thing as
+        leaving ``_encoder_input`` unset: an absent contract means "this route forgot", and
+        the contract refuses to guess between the two. Like the declared variants this is
+        idempotent, so the parent stage and every torchrun rank declare for themselves.
+        """
+        contract = EncoderInputContract.given()
+        self._encoder_input = contract
+        if emit_run_info:
+            logging.getLogger("slide2vec").info(
+                "Given encoder input for '%s': using the encoder's shipped preprocessing; "
+                "the observed encoder input size is recorded per artifact, not validated.",
+                self.name,
+            )
+        return contract
 
     def _load_backend(self) -> LoadedModel:
-        if (
-            self._backend is None
-            or self._backend_pooled_input_plan != self._pooled_input_plan
-        ):
+        """Load the backend under this run's declared encoder-input contract.
+
+        Every caller that reads ``loaded.transforms`` — i.e. everything that turns
+        pixels into features — must come through here, and must therefore have
+        declared its geometry first.
+        """
+        if self._encoder_input is None:
+            raise ValueError(
+                f"No encoder-input contract has been declared for model '{self.name}'. "
+                "A route that encodes pixels must state its geometry before the "
+                "backend is loaded: call _declare_encoder_input(preprocessing, ...) "
+                "for a pooled run, or _declare_dense_encoder_input(dense, ...) for a "
+                "dense one. Callers that never read loaded.transforms use "
+                "_load_backend_without_transform() instead."
+            )
+        return self._load_backend_under(self._encoder_input)
+
+    def _load_backend_without_transform(self) -> LoadedModel:
+        """Load the backend for callers that never read ``loaded.transforms``.
+
+        Two kinds of caller need the constructed encoder module without ever selecting a
+        tile transform: the ``device``/``feature_dim`` properties (pure construction
+        facts) and tile→slide/patient aggregation (``encode_slide`` / ``encode_patient``
+        consume already-computed features). They cannot observe, let alone encode
+        through, the transform the backend happens to carry.
+
+        Dense extraction is deliberately NOT in this set. It builds its own normalization
+        transform and never reads ``loaded.transforms``, but it does need the
+        variable-input constructor settings its geometry implies — which is exactly what
+        an encoder-input contract carries — so it declares (see
+        ``_declare_dense_encoder_input``) and loads through ``_load_backend``.
+
+        A declared contract is honored when one exists so the cached backend is shared;
+        otherwise an explicit Given contract is used for this load only. This never
+        assigns ``_encoder_input``: an embed route still has to declare, and
+        ``_load_backend`` reloads when the declared contract differs from the one the
+        cached backend was built under.
+        """
+        return self._load_backend_under(
+            self._encoder_input
+            if self._encoder_input is not None
+            else EncoderInputContract.given()
+        )
+
+    def _load_backend_under(self, encoder_input: EncoderInputContract) -> LoadedModel:
+        if self._backend is None or self._backend_encoder_input != encoder_input:
             from slide2vec.inference import load_model
 
             emit_progress("model.loading", model_name=self.name)
             self._backend = load_model(
                 name=self.name,
+                encoder_input=encoder_input,
                 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
+            self._backend_encoder_input = encoder_input
             emit_progress("model.ready", model_name=self.name, device=str(self._backend.device))
         return self._backend
 
@@ -965,7 +1221,7 @@ 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)
+    model._declare_encoder_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