slide2vec 6.1.1__tar.gz → 6.2.0__tar.gz

{slide2vec-6.1.1 → slide2vec-6.2.0}/PKG-INFO

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

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

{slide2vec-6.1.1 → slide2vec-6.2.0}/slide2vec/__init__.py

@@ -31,7 +31,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "6.1.1"
+__version__ = "6.2.0"
 
 __all__ = [
     "Model",

{slide2vec-6.1.1 → slide2vec-6.2.0}/slide2vec/encoders/models/__init__.py

@@ -14,6 +14,7 @@ from . import (
     hoptimus,
     isight,
     lunit,
+    mettle,
     midnight,
     moozy,
     mstar,
@@ -40,6 +41,7 @@ __all__ = [
     "hoptimus",
     "isight",
     "lunit",
+    "mettle",
     "midnight",
     "moozy",
     "mstar",

{slide2vec-6.1.1 → slide2vec-6.2.0}/slide2vec/encoders/models/dinov2.py

@@ -16,9 +16,17 @@ Structurally it is a plain :class:`TimmTileEncoder` (mirroring ``lunit`` /
 ``prost40m`` / ``uni``): the dense (``encode_tiles_dense``) and attention
 (``encode_tiles_attention``) paths are inherited unchanged from the timm ViT
 base, so the control is dense-extraction- and attention-capable exactly like the
-pathology encoders. ``dynamic_img_size=True`` lets the (natively 518px) backbone
-run at the 224px detection tile geometry via positional-embedding interpolation,
-a no-op at the native size (verified in the shared dense-extraction suite).
+pathology encoders. ``dynamic_img_size=True`` lets the natively 518px backbone
+run at other patch-aligned sizes via positional-embedding interpolation.
+
+Input size follows Meta's DINOv2 evaluation recipe
+(``make_classification_eval_transform``: bicubic Resize 256 -> CenterCrop 224
+-> ImageNet normalization), not timm's 518px checkpoint config. The registry
+``input_size`` is 224, the size the encoder sees; 256 would make declared runs
+encode 256px. Declared pooled runs read and encode 224px tiles with
+normalization only (112 µm at the default 0.5 µm/px, 16x16 tokens). Native
+518px is an explicit request with ``allow_non_recommended_settings=True``.
+Given pre-cropped tiles use Meta's Resize 256 -> CenterCrop 224 recipe.
 
 Spacing note: a natural-image model has **no** intrinsic micron-per-pixel
 spacing, so it declares ``supported_spacing_um=None`` — it is *spacing-agnostic*
@@ -26,15 +34,17 @@ and :func:`validate_encoder_config` never rejects a requested spacing for it
 (unlike the pathology encoders, which are validated at a specific spacing). It
 still needs *a* spacing to tile a slide, so ``default_spacing_um=0.5`` sets the
 tiling default: 0.5 µm/px is the task-spacing the pathology tile encoders
-declare. Declared pooled runs read and encode the requested tile size with
-normalization only: 518px by default, or 224px for matched-resolution
-experiments when requested explicitly with ``allow_non_recommended_settings=True``.
-Given pre-cropped tiles still use the shipped Resize 518 -> CenterCrop 518
-transform. Because it is agnostic, sweeping other task-spacings (e.g. 0.25)
+declare. Because it is agnostic, sweeping other task-spacings (e.g. 0.25)
 needs no ``allow_non_recommended_settings`` escape hatch — any requested spacing
 is accepted as-is.
 """
 
+from typing import Callable
+
+import torch
+from timm.data import IMAGENET_DEFAULT_MEAN, IMAGENET_DEFAULT_STD
+from torchvision.transforms import v2
+
 from slide2vec.encoders.base import TimmTileEncoder
 from slide2vec.encoders.registry import register_encoder
 
@@ -43,7 +53,7 @@ from slide2vec.encoders.registry import register_encoder
     "dinov2-vitb14",
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
-    input_size=518,
+    input_size=224,
     supports_variable_input_size=True,
     patch_size=14,
     supported_spacing_um=None,  # spacing-agnostic: no intrinsic µm/px, so no validation constraint
@@ -56,5 +66,17 @@ class DINOv2ViTB14(TimmTileEncoder):
         super().__init__(
             "vit_base_patch14_dinov2.lvd142m",
             output_variant=output_variant,
-            dynamic_img_size=True,  # enable dense extraction; no-op at native size
+            dynamic_img_size=True,  # 224 default, 518 opt-in and dense sizes; no-op at native 518
         )
+
+    def get_transform(self) -> Callable:
+        # Meta's DINOv2 eval recipe for given pre-cropped images; timm's packaged
+        # pretrained_cfg would instead Resize 518 -> CenterCrop 518. Declared runs
+        # use get_normalization_transform() and encode exactly the requested size.
+        return v2.Compose([
+            v2.ToImage(),
+            v2.Resize(256, interpolation=v2.InterpolationMode.BICUBIC, antialias=True),
+            v2.CenterCrop(224),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=IMAGENET_DEFAULT_MEAN, std=IMAGENET_DEFAULT_STD),
+        ])

{slide2vec-6.1.1 → slide2vec-6.2.0}/slide2vec/encoders/models/gigapath.py

@@ -3,6 +3,8 @@
 from typing import Callable
 
 import torch
+from huggingface_hub import hf_hub_download
+from huggingface_hub.errors import LocalEntryNotFoundError
 from torchvision.transforms import v2
 
 from slide2vec.encoders.base import (
@@ -13,6 +15,18 @@ from slide2vec.encoders.base import (
 )
 from slide2vec.encoders.registry import register_encoder
 
+_HF_REPO_ID = "prov-gigapath/prov-gigapath"
+_HF_SLIDE_CHECKPOINT = "slide_encoder.pth"
+
+
+def _slide_checkpoint_path() -> str:
+    # A default hf_hub_download queries the Hub on every call, even when cached.
+    try:
+        return hf_hub_download(repo_id=_HF_REPO_ID, filename=_HF_SLIDE_CHECKPOINT, local_files_only=True)
+    except LocalEntryNotFoundError:
+        return hf_hub_download(repo_id=_HF_REPO_ID, filename=_HF_SLIDE_CHECKPOINT)
+
+
 # Prov-GigaPath model card transform (given pre-cropped images only): resize to 256,
 # center-crop to the model's native 224, ImageNet normalization. timm's packaged
 # pretrained_cfg reports crop_pct=1.0 -> the timm default would instead Resize(224),
@@ -38,12 +52,12 @@ _GIGAPATH_STD = (0.229, 0.224, 0.225)
     patch_size=16,
     supported_spacing_um=0.5,
     precision="fp16",
-    source="prov-gigapath/prov-gigapath",
+    source=_HF_REPO_ID,
 )
 class GigaPath(TimmTileEncoder):
     def __init__(self, *, output_variant: str | None = None):
         super().__init__(
-            "hf_hub:prov-gigapath/prov-gigapath",
+            f"hf_hub:{_HF_REPO_ID}",
             output_variant=output_variant,
             dynamic_img_size=True,
         )
@@ -70,17 +84,16 @@ class GigaPath(TimmTileEncoder):
     default_output_variant="default",
     supported_spacing_um=0.5,
     precision="fp16",
-    source="prov-gigapath/prov-gigapath",
+    source=_HF_REPO_ID,
 )
 class GigaPathSlideEncoder(SlideEncoder):
     def __init__(self, *, output_variant: str | None = None):
         from gigapath.slide_encoder import create_model
 
-        self._model = create_model(
-            "hf_hub:prov-gigapath/prov-gigapath",
-            "gigapath_slide_enc12l768d",
-            1536,
-        )
+        # create_model given an "hf_hub:" name force-downloads into ~/.cache/ on every
+        # load, ignoring HF_HOME; a local path skips that download.
+        checkpoint_path = _slide_checkpoint_path()
+        self._model = create_model(checkpoint_path, "gigapath_slide_enc12l768d", 1536)
         self._device = preferred_default_device()
         self._output_variant = resolve_requested_output_variant(output_variant)
 

slide2vec-6.2.0/slide2vec/encoders/models/lunit.py

@@ -0,0 +1,55 @@
+"""Lunit ViT-S/8 tile encoder implementation.
+
+The ``1aurent`` hub ``config.json`` carries timm's stock ``vit_small_patch8_224.dino``
+data config (ImageNet mean/std, crop_pct 0.9). Lunit publishes no transform, so the
+geometry keeps that config (``Resize(248)`` -> ``CenterCrop(224)``), but both
+transforms normalize with Lunit's ViT-S training stats, as documented by kaiko-ai/eva
+(https://github.com/kaiko-ai/eva/blob/main/src/eva/vision/models/networks/backbones/pathology/lunit.py).
+"""
+
+from typing import Callable
+
+import torch
+from torchvision import transforms
+from torchvision.transforms import v2
+
+from slide2vec.encoders.base import TimmTileEncoder
+from slide2vec.encoders.registry import register_encoder
+
+_LUNIT_MEAN = (0.70322989, 0.53606487, 0.66096631)
+_LUNIT_STD = (0.21716536, 0.26081574, 0.20723464)
+
+
+@register_encoder(
+    "lunit",
+    output_variants={"default": {"encode_dim": 384}},
+    default_output_variant="default",
+    input_size=224,
+    supports_variable_input_size=True,
+    patch_size=8,
+    supported_spacing_um=0.5,
+    precision="fp32",
+    source="1aurent/vit_small_patch8_224.lunit_dino",
+)
+class LunitTileEncoder(TimmTileEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        super().__init__(
+            "hf_hub:1aurent/vit_small_patch8_224.lunit_dino",
+            output_variant=output_variant,
+            dynamic_img_size=True,  # enable dense extraction; no-op at native size
+        )
+
+    def get_transform(self) -> Callable:
+        return transforms.Compose([
+            transforms.Resize(248, interpolation=transforms.InterpolationMode.BICUBIC),
+            transforms.CenterCrop(224),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=_LUNIT_MEAN, std=_LUNIT_STD),
+        ])
+
+    def get_normalization_transform(self) -> Callable:
+        return v2.Compose([
+            v2.ToImage(),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=_LUNIT_MEAN, std=_LUNIT_STD),
+        ])

slide2vec-6.2.0/slide2vec/encoders/models/mettle.py

@@ -0,0 +1,183 @@
+"""Mettle tile encoder.
+
+Mettle (slideflow labs; ``slideflow-labs/Mettle``) is H-optimus-0's ViT-g/14
+DINOv2 reg4 backbone (``vit_giant_patch14_reg4_dinov2``), fine-tuned for scanner
+and stain robustness, plus a small ``MettleRefineHead`` applied to the CLS
+token. Weights are openly downloadable (not gated) and released under
+**CC-BY-NC-ND-4.0** (academic, non-commercial use); slide2vec only wraps
+user-downloaded weights and does not redistribute them.
+
+Upstream loads it with ``AutoModel(trust_remote_code=True)``; the remote code is
+timm plus the head. slide2vec builds the timm backbone unpretrained, vendors
+:class:`MettleRefineHead`, and strictly loads ``model.safetensors``
+(``backbone.*`` into the backbone, ``head.*`` into the head), so no remote code
+runs.
+
+Output variants (upstream ``feature_view``):
+
+* ``cls`` (1536): the headed CLS token.
+* ``cls_patch_mean`` (3072, default; upstream ``cls_mean``, the card's benchmark
+  representation): the headed CLS token concatenated with the *unheaded* mean
+  of the spatial patch tokens (CLS and the 4 register tokens excluded).
+
+The head and the patch mean run in fp32 with autocast disabled, matching
+upstream's explicit ``.to(torch.float32)``; only the backbone runs under fp16
+autocast. Dense extraction returns the unheaded patch-token grid (1536 channels).
+
+Spacing: the model card does not state one. ``0.5`` um/px is inherited from
+H-optimus-0, the parent model.
+"""
+
+from typing import Callable
+
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+from torch import Tensor, nn
+from torchvision.transforms import v2
+
+from slide2vec.encoders.base import (
+    TimmTileEncoder,
+    resolve_recommended_dynamic_img_size,
+    resolve_requested_output_variant,
+)
+from slide2vec.encoders.models.hoptimus import (
+    _HOPTIMUS_MEAN,
+    _HOPTIMUS_STD,
+    _hoptimus_transform,
+)
+from slide2vec.encoders.registry import register_encoder
+
+_HF_REPO_ID = "slideflow-labs/Mettle"
+_HF_CHECKPOINT = "model.safetensors"
+_EMBED_DIM = 1536
+_OUTPUT_DIMS = {"cls": _EMBED_DIM, "cls_patch_mean": 2 * _EMBED_DIM}
+# MettleRefineHead hyperparameters, from the repo's config.json.
+_HEAD_NUM_ATOMS = 16
+_HEAD_RANK = 8
+_HEAD_HIDDEN_SIZE = 256
+
+
+class MettleRefineHead(nn.Module):
+    """Content-conditional refinement of the CLS embedding (vendored from upstream)."""
+
+    def __init__(self, dim: int, num_atoms: int, rank: int, hidden_size: int):
+        super().__init__()
+        self.P = nn.Parameter(torch.zeros(num_atoms, dim, rank))
+        self.Q = nn.Parameter(torch.zeros(num_atoms, dim, rank))
+        self.mix = nn.Sequential(
+            nn.Linear(dim, hidden_size),
+            nn.GELU(),
+            nn.Linear(hidden_size, num_atoms),
+        )
+        self.shift = nn.Sequential(
+            nn.Linear(dim, hidden_size),
+            nn.GELU(),
+            nn.Linear(hidden_size, dim),
+        )
+
+    def forward(self, embedding: Tensor) -> Tensor:
+        mixture = self.mix(embedding)
+        shift = self.shift(embedding)
+        projected = torch.einsum("bd,kdr->bkr", embedding, self.P)
+        delta = torch.einsum("bkr,kdr->bkd", projected, self.Q)
+        return embedding + (mixture.unsqueeze(-1) * delta).sum(1) + shift
+
+
+@register_encoder(
+    "mettle",
+    output_variants={
+        "cls": {"encode_dim": _OUTPUT_DIMS["cls"]},
+        "cls_patch_mean": {"encode_dim": _OUTPUT_DIMS["cls_patch_mean"]},
+    },
+    default_output_variant="cls_patch_mean",
+    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 Mettle(TimmTileEncoder):
+    # Upstream builds the backbone with dynamic_img_size=False, so that is the
+    # recommended default. Dense extraction needs variable input size and opts in
+    # via dynamic_img_size=True + allow_non_recommended_settings=True.
+    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_patch_mean",
+            allowed=tuple(_OUTPUT_DIMS),
+        )
+        super().__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",
+            ),
+        )
+        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))
+        unexpected = [key for key in state_dict if not key.startswith(("backbone.", "head."))]
+        if unexpected:
+            raise ValueError(f"Unexpected keys in Mettle 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()
+
+    @property
+    def encode_dim(self) -> int:
+        return _OUTPUT_DIMS[self._output_variant]
+
+    def encode_tiles(self, batch: Tensor) -> Tensor:
+        tokens = self._model.forward_features(batch)
+        with torch.autocast(device_type=batch.device.type, enabled=False):
+            cls = self._head(tokens[:, 0].float())
+            if self._output_variant == "cls":
+                return cls
+            patch_mean = tokens[:, self._model.num_prefix_tokens:].float().mean(dim=1)
+            return torch.cat([cls, patch_mean], dim=-1)
+
+    # The generic timm arch carries an ImageNet pretrained_cfg; Mettle's
+    # preprocessor_config.json uses the H-optimus mean/std, so both transforms
+    # hardcode them.
+    def get_transform(self) -> Callable:
+        return _hoptimus_transform()
+
+    def get_normalization_transform(self) -> Callable:
+        return v2.Compose([
+            v2.ToImage(),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=_HOPTIMUS_MEAN, std=_HOPTIMUS_STD),
+        ])
+
+    def to(self, device: torch.device | str) -> "Mettle":
+        super().to(device)
+        self._head = self._head.to(self._device)
+        return self
+
+
+def _strip_prefix(state_dict: dict[str, Tensor], prefix: str) -> dict[str, Tensor]:
+    return {
+        key[len(prefix):]: value
+        for key, value in state_dict.items()
+        if key.startswith(prefix)
+    }

{slide2vec-6.1.1 → slide2vec-6.2.0}/slide2vec/encoders/models/mstar.py

@@ -8,11 +8,25 @@ We therefore register it as a **tile** encoder.
 The weights live in the **gated** Hugging Face repo `Wangyh/mSTAR`
 (``hf-hub:Wangyh/mSTAR``). Loading them requires access approval on Hugging Face
 and an ``HF_TOKEN`` in the environment.
+
+The hub ``config.json`` carries timm's stock ``vit_large_patch16_224`` data config
+(mean/std 0.5, crop_pct 0.9), not the authors' recipe. Both transforms below use the
+published recipe instead: ``Resize(224)`` -> ``ToTensor`` -> ImageNet ``Normalize``,
+no center crop (https://huggingface.co/Wangyh/mSTAR, https://github.com/Innse/mSTAR).
 """
 
+from typing import Callable
+
+import torch
+from torchvision import transforms
+from torchvision.transforms import v2
+
 from slide2vec.encoders.base import TimmTileEncoder
 from slide2vec.encoders.registry import register_encoder
 
+_MSTAR_MEAN = (0.485, 0.456, 0.406)
+_MSTAR_STD = (0.229, 0.224, 0.225)
+
 
 @register_encoder(
     "mstar",
@@ -33,3 +47,17 @@ class mSTAR(TimmTileEncoder):
             init_values=1e-5,
             dynamic_img_size=True,
         )
+
+    def get_transform(self) -> Callable:
+        return transforms.Compose([
+            transforms.Resize((224, 224), interpolation=transforms.InterpolationMode.BICUBIC),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=_MSTAR_MEAN, std=_MSTAR_STD),
+        ])
+
+    def get_normalization_transform(self) -> Callable:
+        return v2.Compose([
+            v2.ToImage(),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=_MSTAR_MEAN, std=_MSTAR_STD),
+        ])