slide2vec 5.3.0__tar.gz → 5.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.3.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
@@ -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.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.3.0"
+version = "5.5.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.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.3.0 → slide2vec-5.5.0}/slide2vec/__init__.py

@@ -1,23 +1,38 @@
 from slide2vec.api import (
+    DenseImageOptions,
+    DenseOptions,
     EmbeddedPatient,
     EmbeddedSlide,
     ExecutionOptions,
+    ImageSpec,
     Model,
     Pipeline,
     PreprocessingConfig,
     RunResult,
+    SlideRegions,
     list_models,
 )
-from slide2vec.artifacts import HierarchicalEmbeddingArtifact, SlideEmbeddingArtifact, TileEmbeddingArtifact
+from slide2vec.artifacts import (
+    DenseImageArtifact,
+    DenseRegionArtifact,
+    HierarchicalEmbeddingArtifact,
+    ImageEmbeddingArtifact,
+    SlideEmbeddingArtifact,
+    TileEmbeddingArtifact,
+)
 
 
-__version__ = "5.3.0"
+__version__ = "5.5.0"
 
 __all__ = [
     "Model",
     "list_models",
     "Pipeline",
     "PreprocessingConfig",
+    "DenseOptions",
+    "DenseImageOptions",
+    "SlideRegions",
+    "ImageSpec",
     "ExecutionOptions",
     "RunResult",
     "EmbeddedPatient",
@@ -25,5 +40,8 @@ __all__ = [
     "SlideEmbeddingArtifact",
     "HierarchicalEmbeddingArtifact",
     "TileEmbeddingArtifact",
+    "DenseRegionArtifact",
+    "DenseImageArtifact",
+    "ImageEmbeddingArtifact",
     "__version__",
 ]

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

@@ -11,7 +11,10 @@ import torch
 from hs2p import SlideSpec
 
 from slide2vec.artifacts import (
+    DenseImageArtifact,
+    DenseRegionArtifact,
     HierarchicalEmbeddingArtifact,
+    ImageEmbeddingArtifact,
     PatientEmbeddingArtifact,
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
@@ -28,6 +31,8 @@ from slide2vec.runtime.model_settings import (
 )
 from slide2vec.progress import emit_progress
 from slide2vec.runtime.types import LoadedModel
+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
@@ -101,6 +106,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 +193,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 +221,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 +328,124 @@ 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.
+    #: 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``).
+    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 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`."""
@@ -374,6 +508,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 +527,13 @@ class Model:
         self.allow_non_recommended_settings = bool(allow_non_recommended_settings)
         self._output_variant = output_variant
         self._backend: LoadedModel | 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(
@@ -410,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,
@@ -588,16 +733,254 @@ 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.
+
+        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
+
+        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 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,
+    ) -> 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._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, "
+                "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 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:
+        """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,
             )
+            self._backend_encoder_input = encoder_input
             emit_progress("model.ready", model_name=self.name, device=str(self._backend.device))
         return self._backend
 
@@ -838,12 +1221,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._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
     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,