slide2vec 7.1.3__tar.gz → 7.1.5__tar.gz

{slide2vec-7.1.3 → slide2vec-7.1.5}/PKG-INFO

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

{slide2vec-7.1.3 → slide2vec-7.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "7.1.3"
+version = "7.1.5"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -240,7 +240,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "7.1.3"
+current_version = "7.1.5"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec/__init__.py

@@ -36,7 +36,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "7.1.3"
+__version__ = "7.1.5"
 
 __all__ = [
     "Model",

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec/api.py

@@ -708,6 +708,45 @@ class Model:
             encoded_pixels=encoded_pixels,
         )
 
+    def dense_identity_differences(
+        self,
+        recorded: Mapping[str, Any],
+        *,
+        dense: "DenseOptions | DenseImageOptions",
+        execution: ExecutionOptions | None = None,
+    ) -> dict[str, tuple[Any, Any]]:
+        """Compare a dense sidecar's ``compatibility`` block with the current request.
+
+        The dense counterpart of :meth:`pooled_identity_differences`. Pass the
+        ``dense`` options and ``execution`` of :meth:`embed_regions_dense` (a
+        :class:`DenseOptions`) or :meth:`embed_images_dense` (a
+        :class:`DenseImageOptions`). Returns ``{field: (recorded, current)}`` for every
+        request-wide field that the record holds with a different value or does not
+        hold. A field the record does not hold is reported as
+        :data:`slide2vec.MISSING_FIELD`. Per-sample fields (the sample, its path and its
+        read plan) are not compared. An empty result means the record proves the
+        current request-wide identity. The caller owns the policy for a difference.
+
+        An invalid request raises as it does in the embed methods. ``execution``
+        defaults to the model's recommended precision and needs no output directory.
+        Comparing the ``transform`` loads weights, on an isolated CPU model. This method
+        does not change this model's input contract or loaded backend, encode pixels,
+        or write files.
+        """
+        from slide2vec.runtime.feature_identity import dense_identity_differences
+
+        if not isinstance(dense, (DenseOptions, DenseImageOptions)):
+            raise TypeError(
+                "Model.dense_identity_differences(dense=...) expects DenseOptions "
+                f"or DenseImageOptions, got {type(dense).__name__}"
+            )
+        return dense_identity_differences(
+            self,
+            dict(recorded),
+            dense=dense,
+            execution=_coerce_execution_options(execution, model=self),
+        )
+
     def prepare_dense_encoder(
         self,
         *,
@@ -1085,6 +1124,11 @@ class Model:
         non-timm backbone, say) fails before any backend is loaded and before resume
         inspects or invalidates an existing artifact.
         """
+        if self.level != "tile":
+            raise ValueError(
+                "Dense extraction requires a tile-level foundation encoder; model "
+                f"{self.name!r} is registered at level {self.level!r}."
+            )
         contract = EncoderInputContract.declared_dense(
             self.name,
             target_size_px=dense.target_size,

slide2vec-7.1.5/slide2vec/encoders/models/mettle_1_5.py

@@ -0,0 +1,129 @@
+"""Mettle-1.5 tile encoder.
+
+Mettle-1.5 (slideflow labs; ``slideflow-labs/mettle-1.5``) is a later scanner and
+stain robustness fine-tune of H-optimus-0. It shares ``mettle``'s backbone,
+``MettleRefineHead``, H-optimus mean/std and feature views, so this module reuses
+:mod:`.mettle`. Weights are openly downloadable (not gated). The model card states
+no license; slide2vec only wraps user-downloaded weights and does not redistribute
+them.
+
+The given recipe resizes directly to 224x224, as upstream's
+``preprocessor_config.json`` does. ``mettle`` resizes the shortest side and
+center-crops instead. The two agree on square tiles.
+
+slide2vec strictly loads ``model.safetensors`` at a pinned revision, as for
+``mettle``; no remote code runs.
+
+Output variants (upstream ``feature_view``):
+
+* ``cls`` (1536, default): the headed CLS token. The card and upstream
+  ``config.json`` default to it; the card makes no benchmark claims for this
+  checkpoint.
+* ``cls_patch_mean`` (3072; upstream ``cls_mean``): the headed CLS token
+  concatenated with the *unheaded* mean of the spatial patch tokens (CLS and the
+  4 register tokens excluded).
+
+``mettle`` defaults to ``cls_patch_mean``, so a config moved from ``mettle`` to
+``mettle-1.5`` changes the feature dimension from 3072 to 1536.
+
+Precision, dense extraction and spacing are as for ``mettle``.
+"""
+
+from typing import Callable
+
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+from torchvision.transforms import v2
+
+from slide2vec.encoders.base import (
+    resolve_recommended_dynamic_img_size,
+    resolve_requested_output_variant,
+)
+from slide2vec.encoders.models.hoptimus import _HOPTIMUS_MEAN, _HOPTIMUS_STD
+from slide2vec.encoders.models.mettle import (
+    _EMBED_DIM,
+    _HEAD_HIDDEN_SIZE,
+    _HEAD_NUM_ATOMS,
+    _HEAD_RANK,
+    _HF_CHECKPOINT,
+    _OUTPUT_DIMS,
+    Mettle,
+    MettleRefineHead,
+    _strip_prefix,
+)
+from slide2vec.encoders.registry import register_encoder
+
+_HF_REPO_ID = "slideflow-labs/mettle-1.5"
+_HF_REVISION = "0ab55fcbf1b8d4e3c73885fc56f822fb568ff570"
+
+
+@register_encoder(
+    "mettle-1.5",
+    output_variants={
+        "cls": {"encode_dim": _OUTPUT_DIMS["cls"]},
+        "cls_patch_mean": {"encode_dim": _OUTPUT_DIMS["cls_patch_mean"]},
+    },
+    default_output_variant="cls",
+    input_size=224,
+    supports_variable_input_size=True,
+    variable_input_model_kwargs={"dynamic_img_size": True},
+    patch_size=14,
+    supported_spacing_um=0.5,  # not stated on the card; inherited from H-optimus-0
+    precision="fp16",
+    source=_HF_REPO_ID,
+)
+class Mettle15(Mettle):
+    # Mettle.__init__ hardcodes the Mettle-1 repo, so this one calls
+    # TimmTileEncoder.__init__ directly. mettle.py stays unchanged: its file hash is
+    # part of the feature identity of every cached mettle feature.
+    def __init__(
+        self,
+        *,
+        output_variant: str | None = None,
+        dynamic_img_size: bool | None = None,
+        allow_non_recommended_settings: bool = False,
+    ):
+        self._output_variant = resolve_requested_output_variant(
+            output_variant,
+            default="cls",
+            allowed=tuple(_OUTPUT_DIMS),
+        )
+        super(Mettle, self).__init__(
+            "vit_giant_patch14_reg4_dinov2",
+            output_variant="default",
+            pretrained=False,
+            init_values=1e-5,
+            img_size=224,
+            dynamic_img_size=resolve_recommended_dynamic_img_size(
+                requested=dynamic_img_size,
+                recommended=False,
+                allow_non_recommended=allow_non_recommended_settings,
+                encoder_name="mettle-1.5",
+            ),
+        )
+        self._head = MettleRefineHead(
+            dim=_EMBED_DIM,
+            num_atoms=_HEAD_NUM_ATOMS,
+            rank=_HEAD_RANK,
+            hidden_size=_HEAD_HIDDEN_SIZE,
+        )
+        state_dict = load_file(
+            hf_hub_download(repo_id=_HF_REPO_ID, filename=_HF_CHECKPOINT, revision=_HF_REVISION)
+        )
+        unexpected = [key for key in state_dict if not key.startswith(("backbone.", "head."))]
+        if unexpected:
+            raise ValueError(f"Unexpected keys in Mettle-1.5 checkpoint: {unexpected}")
+        self._model.load_state_dict(_strip_prefix(state_dict, "backbone."), strict=True)
+        self._head.load_state_dict(_strip_prefix(state_dict, "head."), strict=True)
+        self._model.eval()
+        self._head.eval()
+
+    def get_transform(self) -> Callable:
+        # Upstream's ViTImageProcessor resizes directly to 224x224, with no crop.
+        return v2.Compose([
+            v2.ToImage(),
+            v2.Resize((224, 224), interpolation=v2.InterpolationMode.BICUBIC, antialias=True),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=_HOPTIMUS_MEAN, std=_HOPTIMUS_STD),
+        ])

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec/runtime/dense_image_recipe.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+import math
+from dataclasses import dataclass, fields
 from pathlib import Path
 from typing import Any
 
 from slide2vec.encoders.code import encoder_code
-from slide2vec.encoders.registry import resolve_encoder_output
+from slide2vec.encoders.registry import resolve_encoder_output, resolve_preprocessing_defaults
+from slide2vec.encoders.validation import validate_encoder_config
 from slide2vec.runtime.model_settings import output_dtype_name, resolve_output_precision
 
 
@@ -134,6 +136,20 @@ class DenseImageRecipe:
             payload["transform"] = self.transform
         return payload
 
+    def request_identity(self) -> dict[str, Any]:
+        """The request-wide fields of :meth:`for_image`: the recipe without per-image fields.
+
+        The per-image fields are the read plan's, which :meth:`for_image` replaces, and
+        the read sizes.
+        """
+        from slide2vec.runtime.dense_image_reading import DenseImageReadPlan
+
+        per_image = {field.name for field in fields(DenseImageReadPlan)} | {
+            "read_tile_size_px",
+            "requested_tile_size_px",
+        }
+        return {key: value for key, value in self.to_dict().items() if key not in per_image}
+
     def for_image(self, spec, read_plan=None) -> dict[str, Any]:
         """Add the normalized source identity to this request-wide recipe."""
         if read_plan is None:
@@ -225,6 +241,38 @@ class DenseImageRecipe:
         )
 
 
+def resolve_dense_image_spacing(model, dense) -> tuple[float, str]:
+    """Resolve and validate the run spacing of *dense*: ``(spacing_um, spacing_source)``.
+
+    An omitted spacing resolves the encoder's single registry default.
+    """
+    spacing_source = "explicit"
+    if dense.spacing_um is None:
+        try:
+            spacing_um = float(
+                resolve_preprocessing_defaults(model.name)["spacing_um"]
+            )
+        except (KeyError, ValueError) as exc:
+            raise ValueError(
+                "DenseImageOptions.spacing_um must be explicit when encoder "
+                f"{model.name!r} has no single resolvable model default: {exc}"
+            ) from exc
+        spacing_source = "model_default"
+    else:
+        spacing_um = float(dense.spacing_um)
+    if not math.isfinite(spacing_um) or spacing_um <= 0:
+        raise ValueError(
+            "DenseImageOptions.spacing_um must be a positive, finite value or None."
+        )
+    validate_encoder_config(
+        model.name,
+        requested_spacing_um=spacing_um,
+        allow_non_recommended=bool(model.allow_non_recommended_settings),
+        require_known_spacing=True,
+    )
+    return spacing_um, spacing_source
+
+
 def resolve_dense_image_recipe(
     *,
     model,

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec/runtime/dense_image_stage.py

@@ -29,7 +29,6 @@ from __future__ import annotations
 
 import json
 import logging
-import math
 from dataclasses import replace
 from pathlib import Path
 from subprocess import Popen
@@ -37,8 +36,6 @@ from typing import Callable, Sequence
 
 from slide2vec.api import DenseImageOptions, ImageSpec
 from slide2vec.artifacts import DenseImageArtifact
-from slide2vec.encoders.registry import resolve_preprocessing_defaults
-from slide2vec.encoders.validation import validate_encoder_config
 from slide2vec.progress import emit_progress
 from slide2vec.runtime.dense_image_shard import (
     dense_image_artifact_from_disk,
@@ -48,6 +45,7 @@ from slide2vec.runtime.dense_image_shard import (
 from slide2vec.runtime.dense_image_recipe import (
     DenseImageRecipe,
     resolve_dense_image_recipe,
+    resolve_dense_image_spacing,
 )
 from slide2vec.runtime.dense_image_reading import DenseImageReadPlan, resolve_spacing_read_plan
 from slide2vec.runtime.dense_stage import resolve_output_torch_dtype
@@ -115,31 +113,8 @@ def embed_images_dense(
         artifact_location="dense_image_embeddings/<sample_id>",
     )
     reader_regime, probed_auto_backends = validate_dense_image_reader_regime(specs)
-    spacing_source = "explicit"
-    if dense.spacing_um is None:
-        try:
-            spacing_um = float(
-                resolve_preprocessing_defaults(model.name)["spacing_um"]
-            )
-        except (KeyError, ValueError) as exc:
-            raise ValueError(
-                "DenseImageOptions.spacing_um must be explicit when encoder "
-                f"{model.name!r} has no single resolvable model default: {exc}"
-            ) from exc
-        spacing_source = "model_default"
-        dense = replace(dense, spacing_um=spacing_um)
-    else:
-        spacing_um = float(dense.spacing_um)
-    if spacing_um is not None and (not math.isfinite(spacing_um) or spacing_um <= 0):
-        raise ValueError(
-            "DenseImageOptions.spacing_um must be a positive, finite value or None."
-        )
-    validate_encoder_config(
-        model.name,
-        requested_spacing_um=spacing_um,
-        allow_non_recommended=bool(model.allow_non_recommended_settings),
-        require_known_spacing=True,
-    )
+    spacing_um, spacing_source = resolve_dense_image_spacing(model, dense)
+    dense = replace(dense, spacing_um=spacing_um)
     # Declare the effective encoder input before anything is decoded, sharded or launched: an
     # image geometry this encoder cannot accept must fail here, not on the first forward pass
     # of a torchrun rank. Idempotent, so every rank re-declares for itself (dense_image_worker).

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec/runtime/feature_identity.py

@@ -225,6 +225,69 @@ def pooled_identity_differences(
     )
 
 
+def dense_identity_differences(
+    model,
+    recorded: dict[str, Any],
+    *,
+    dense,
+    execution,
+) -> dict[str, tuple[Any, Any]]:
+    """Compare a recorded dense identity with the request-wide identity of the current request.
+
+    A :class:`~slide2vec.api.DenseImageOptions` request is compared with the image recipe,
+    any other with the region identity. The request is validated as the embed methods
+    validate it, on an isolated CPU copy of *model* that declares the dense encoder-input
+    contract, so *model* keeps its contract and backend. The transform is that copy's
+    ``get_normalization_transform()``, as the shards record it.
+    """
+    from slide2vec.api import DenseImageOptions, Model
+
+    source = Model.from_preset(
+        model.name,
+        device="cpu",
+        output_variant=model._output_variant,
+        allow_non_recommended_settings=model.allow_non_recommended_settings,
+    )
+    if isinstance(dense, DenseImageOptions):
+        from slide2vec.runtime.dense_image_recipe import (
+            resolve_dense_image_recipe,
+            resolve_dense_image_spacing,
+        )
+
+        resolve_dense_image_spacing(source, dense)  # validates; the spacing is per-sample
+        contract = source._declare_dense_encoder_input(dense, emit_run_info=False)
+        requested = resolve_dense_image_recipe(
+            model=source, contract=contract, dense=dense, execution=execution
+        ).request_identity()
+    else:
+        from slide2vec.encoders.registry import resolve_patch_size
+        from slide2vec.runtime.dense_regions import (
+            compute_dense_geometry,
+            validate_dense_request_settings,
+        )
+
+        plan = source._declare_dense_encoder_input(dense, emit_run_info=False).plan
+        # The region shards validate the same settings when they encode.
+        validate_dense_request_settings(
+            compute_dense_geometry(
+                target_size=plan.target_size_px,
+                patch_size=resolve_patch_size(plan.tile_encoder_name),
+            ),
+            pad_mode=dense.pad_mode,
+            window_size=dense.window_size,
+            overlap=dense.overlap,
+            feature_kind=dense.feature_kind,
+            attention_blocks=dense.attention_blocks,
+            attention_include_registers=dense.attention_include_registers,
+        )
+        requested = dense_feature_identity(source, dense=dense, execution=execution)
+
+    def resolve_transform() -> dict[str, Any]:
+        return transform_record(source._load_backend().model.get_normalization_transform())
+
+    return differing_fields(recorded, requested, resolve_transform=resolve_transform)
+
+
 class PooledResumeCheck:
     """Compare the completed pooled artifacts of one resume with the run's feature identity.
 

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec.egg-info/PKG-INFO

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

{slide2vec-7.1.3 → slide2vec-7.1.5}/slide2vec.egg-info/SOURCES.txt

@@ -49,6 +49,7 @@ slide2vec/encoders/models/hoptimus.py
 slide2vec/encoders/models/isight.py
 slide2vec/encoders/models/lunit.py
 slide2vec/encoders/models/mettle.py
+slide2vec/encoders/models/mettle_1_5.py
 slide2vec/encoders/models/midnight.py
 slide2vec/encoders/models/mstar.py
 slide2vec/encoders/models/musk.py
@@ -123,6 +124,7 @@ tests/test_cufile_compat_mode.py
 tests/test_dense_encode_kit.py
 tests/test_dense_encoder_input.py
 tests/test_dense_extraction.py
+tests/test_dense_identity_api.py
 tests/test_dense_image_reading.py
 tests/test_dense_image_resume.py
 tests/test_dense_image_shard.py