slide2vec 5.1.1__tar.gz → 5.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.1.1
+Version: 5.3.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -225,7 +225,7 @@ The package writes explicit artifact directories:
 
 ### Supported Models
 
-`slide2vec` currently ships preset configs for 17 tile-level models and 3 slide-level models.  
+`slide2vec` currently ships preset configs for 22 tile-level models and 3 slide-level models.  
 For the full catalog and preset names, see [`docs/models.md`](docs/models.md).
 
 ## CLI

{slide2vec-5.1.1 → slide2vec-5.3.0}/README.md

@@ -119,7 +119,7 @@ The package writes explicit artifact directories:
 
 ### Supported Models
 
-`slide2vec` currently ships preset configs for 17 tile-level models and 3 slide-level models.  
+`slide2vec` currently ships preset configs for 22 tile-level models and 3 slide-level models.  
 For the full catalog and preset names, see [`docs/models.md`](docs/models.md).
 
 ## CLI

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

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

@@ -11,7 +11,7 @@ from slide2vec.api import (
 from slide2vec.artifacts import HierarchicalEmbeddingArtifact, SlideEmbeddingArtifact, TileEmbeddingArtifact
 
 
-__version__ = "5.1.1"
+__version__ = "5.3.0"
 
 __all__ = [
     "Model",

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

@@ -21,7 +21,11 @@ from slide2vec.encoders.registry import (
     resolve_preprocessing_defaults,
 )
 from slide2vec.encoders.validation import validate_encoder_config
-from slide2vec.runtime.model_settings import canonicalize_model_name, normalize_precision_name
+from slide2vec.runtime.model_settings import (
+    canonicalize_model_name,
+    normalize_output_dtype,
+    normalize_precision_name,
+)
 from slide2vec.progress import emit_progress
 from slide2vec.runtime.types import LoadedModel
 from slide2vec.utils.utils import cpu_worker_limit, slurm_cpu_limit
@@ -226,6 +230,10 @@ class ExecutionOptions:
     #: Forward-pass dtype — ``"fp16"``, ``"bf16"``, ``"fp32"``,
     #: or ``None`` (auto-determined from the model preset).
     precision: str | None = None
+    #: On-disk feature dtype — ``"fp16"``, ``"fp32"``, or ``None`` to follow
+    #: :attr:`precision` (fp16 → fp16, else fp32). Applies to tile, slide, hierarchical,
+    #: and patient artifacts; ``"bf16"`` is rejected (numpy has no bfloat16).
+    output_dtype: str | None = None
     #: DataLoader prefetch queue depth per worker (default ``4``).
     prefetch_factor: int = 4
     #: Persist tile embeddings to disk when running a slide-level model.
@@ -253,6 +261,7 @@ class ExecutionOptions:
             ),
             num_gpus=1 if run_on_cpu else (int(configured_num_gpus) if configured_num_gpus is not None else None),
             precision="fp32" if run_on_cpu else requested_precision,
+            output_dtype=getattr(cfg.speed, "output_dtype", None),
             prefetch_factor=prefetch_factor,
             save_tile_embeddings=bool(cfg.model.save_tile_embeddings),
             save_slide_embeddings=bool(cfg.model.save_slide_embeddings),
@@ -263,6 +272,7 @@ class ExecutionOptions:
         resolved_num_gpus = _default_num_gpus() if self.num_gpus is None else self.num_gpus
         object.__setattr__(self, "num_gpus", resolved_num_gpus)
         object.__setattr__(self, "precision", normalize_precision_name(self.precision))
+        object.__setattr__(self, "output_dtype", normalize_output_dtype(self.output_dtype))
         if resolved_num_gpus < 1:
             raise ValueError("ExecutionOptions.num_gpus must be at least 1")
         if self.prefetch_factor < 1:

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

@@ -7,6 +7,8 @@ import numpy as np
 import torch
 from hs2p.fileops import is_flattened_annotation
 
+from slide2vec.runtime.model_settings import output_torch_dtype
+
 
 @dataclass(frozen=True, kw_only=True)
 class TileEmbeddingArtifact:
@@ -74,6 +76,26 @@ def _validate_output_format(output_format: str) -> str:
     return normalized
 
 
+_OUTPUT_NUMPY_DTYPE = {"fp16": np.float16, "fp32": np.float32}
+
+
+def cast_feature_dtype(data: Any, precision: str) -> Any:
+    """Cast features to the on-disk ``precision`` (``"fp16"`` / ``"fp32"``), keeping their kind.
+
+    Torch tensors are cast via ``.to`` and arrays via ``astype``; ``None`` (no features)
+    passes through. This is what makes the pooled tile/slide/hierarchical/patient artifacts
+    land in a deterministic dtype, mirroring the dense path's ``output_dtype``. The precision
+    is resolved upstream by :func:`slide2vec.runtime.model_settings.resolve_output_precision`,
+    so only ``"fp16"`` / ``"fp32"`` reach here.
+    """
+    if data is None:
+        return data
+    torch_dtype = output_torch_dtype(precision)  # validates precision (shared string→dtype map)
+    if torch.is_tensor(data):
+        return data.to(torch_dtype)
+    return np.asarray(data).astype(_OUTPUT_NUMPY_DTYPE[precision], copy=False)
+
+
 def _ensure_array(data: Any) -> np.ndarray:
     if isinstance(data, np.ndarray):
         return data

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

@@ -88,6 +88,7 @@ tiling:
 
 speed:
   precision: # model inference precision ["fp32", "fp16", "bf16"]; if not set, determined automatically based on model recommendations
+  output_dtype: # on-disk feature dtype ["fp16", "fp32"]; if not set, follows speed.precision (fp16 -> fp16, otherwise fp32)
   num_dataloader_workers: # number of DataLoader worker processes per GPU rank for reading tiles during embedding; defaults to auto (job CPU budget split across GPUs, except cuCIM on-the-fly uses per-GPU budget // speed.num_cucim_workers)
   num_gpus: # number of GPUs to use for feature extraction; defaults to all available GPUs
   num_preprocessing_workers: # number of workers for hs2p tiling (WSI reading, JPEG encoding, tar writing); defaults to the runtime CPU budget capped at 64

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/__init__.py

@@ -16,8 +16,10 @@ from slide2vec.encoders.base import (
 )
 from slide2vec.encoders.registry import (
     encoder_registry,
+    normalize_patch_size,
     register_encoder,
     resolve_encoder_output,
+    resolve_patch_size,
     resolve_preprocessing_requirements,
     resolve_tile_dependency_output,
 )
@@ -35,7 +37,9 @@ __all__ = [
     "resolve_recommended_dynamic_img_size",
     "resolve_requested_output_variant",
     "encoder_registry",
+    "normalize_patch_size",
     "register_encoder",
+    "resolve_patch_size",
     "resolve_preprocessing_requirements",
     "resolve_encoder_output",
     "resolve_tile_dependency_output",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/__init__.py

@@ -5,12 +5,16 @@ Importing this package registers all encoders in the encoder_registry.
 
 from . import (
     conch,
+    dinov2,
+    genbio,
     gigapath,
+    gpfm,
     hibou,
     hoptimus,
     lunit,
     midnight,
     moozy,
+    mstar,
     musk,
     phikon,
     prost40m,
@@ -22,12 +26,16 @@ from . import (
 
 __all__ = [
     "conch",
+    "dinov2",
+    "genbio",
     "gigapath",
+    "gpfm",
     "hibou",
     "hoptimus",
     "lunit",
     "midnight",
     "moozy",
+    "mstar",
     "musk",
     "phikon",
     "prost40m",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/conch.py

@@ -78,6 +78,7 @@ def _encode_trunk_dense(*, trunk, batch: Tensor, encoder_name: str) -> Tensor:
     output_variants={"default": {"encode_dim": 512}},
     default_output_variant="default",
     input_size=448,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="MahmoodLab/conch",
@@ -163,6 +164,7 @@ class CONCH(TileEncoder):
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
     input_size=448,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp16",
     source="MahmoodLab/TITAN",

slide2vec-5.3.0/slide2vec/encoders/models/dinov2.py

@@ -0,0 +1,56 @@
+"""Natural-image DINOv2 ViT-B/14 control encoder.
+
+``dinov2-vitb14`` is a **non-pathology** ViT: the original DINOv2 ViT-B/14
+(Oquab et al., 2024) self-supervised on LVD-142M *natural* images, shipped by
+``timm`` as ``vit_base_patch14_dinov2.lvd142m`` (weights hosted on Hugging Face
+under ``timm/vit_base_patch14_dinov2.lvd142m`` — public, no gated access).
+
+It exists as a **control**: nearly every pathology tile encoder here (UNI,
+Virchow, GigaPath, H-optimus, Midnight, …) is a DINOv2-family ViT, so pairing
+them with a DINOv2 ViT trained on natural images holds the architecture and the
+self-supervised objective fixed and varies only the *pretraining domain*. That
+isolates the question "does pathology-pretraining actually pay off?" for a
+downstream task (e.g. cell detection).
+
+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).
+
+Spacing note: a natural-image model has **no** intrinsic micron-per-pixel
+spacing, so it declares ``supported_spacing_um=None`` — it is *spacing-agnostic*
+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, so selecting this encoder by name lands on identical tile geometry and
+it drops in as a matched control. 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 slide2vec.encoders.base import TimmTileEncoder
+from slide2vec.encoders.registry import register_encoder
+
+
+@register_encoder(
+    "dinov2-vitb14",
+    output_variants={"default": {"encode_dim": 768}},
+    default_output_variant="default",
+    input_size=224,
+    patch_size=14,
+    supported_spacing_um=None,  # spacing-agnostic: no intrinsic µm/px, so no validation constraint
+    default_spacing_um=0.5,  # tiling default: match the pathology encoders' task-spacing
+    precision="fp16",
+    source="timm/vit_base_patch14_dinov2.lvd142m",
+)
+class DINOv2ViTB14(TimmTileEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        super().__init__(
+            "vit_base_patch14_dinov2.lvd142m",
+            output_variant=output_variant,
+            dynamic_img_size=True,  # enable dense extraction; no-op at native size
+        )

slide2vec-5.3.0/slide2vec/encoders/models/genbio.py

@@ -0,0 +1,155 @@
+"""GenBio-PathFM tile encoder.
+
+GenBio-PathFM (GenBio AI, 2024; ``genbio-ai/genbio-pathfm``) is a 1.1B-param ViT
+histopathology tile encoder (JEDI = JEPA + DINO training on public data). It is
+loaded via HF ``AutoModel(trust_remote_code=True)`` (auto_map ->
+``GenBioPathFMModel``), so it is a custom :class:`TileEncoder`, not a
+``TimmTileEncoder``. Weights are openly downloadable (safetensors); released
+under the custom **GenBio AI Community License** (not OSI-approved — read it for
+acceptable-use / commercial restrictions; slide2vec only wraps user-downloaded
+weights and does not redistribute them).
+
+Output dim (4608, verified on real weights): the backbone is a *single-channel*
+ViT (``in_chans=1``, ``embed_dim=1536``). The model's canonical ``forward`` takes
+an RGB ``[B, 3, H, W]`` tensor, treats each colour channel as a separate
+single-channel image, encodes all three, and concatenates the three per-channel
+CLS tokens -> ``[B, embed_dim * 3] = [B, 4608]``. This per-channel-CLS
+concatenation is the model's intrinsic design (matching the HF card's advertised
+feature dimension of 4608), not an ad-hoc CLS+patch pooling; ``encode_tiles``
+therefore returns the model's default ``forward`` output directly. (Confirmed by
+running a ``(1, 3, 224, 224)`` dummy through the real weights -> shape
+``(1, 4608)``; see ``tests/test_gpfm_genbio_heavy.py``.)
+
+Normalization is **non-ImageNet** (``config.json`` ``image_mean`` / ``image_std``)
+and must be set explicitly.
+
+Dense (spatial-grid) extraction is supported via the model's
+``forward_with_patches`` (a DINOv2-style ``x_norm_patchtokens`` path): it returns
+the fused per-channel patch tokens ``(B, T, 4608)`` — the three single-channel
+patch-token grids concatenated along the feature dim, with the prefix tokens
+(CLS + storage tokens) already stripped — which fold straight into a
+``(B, 4608, h, w)`` grid. The patch size is 16 (a 224 tile -> a 14x14 = 196 grid).
+
+Attention-map extraction is **not** supported. The backbone computes attention
+with a fused ``F.scaled_dot_product_attention`` (no materialized weights, no
+``output_attentions``), and — more fundamentally — it encodes the three colour
+channels as three independent single-channel images, so there is no single
+coherent CLS-over-patches attention to extract: any "attention grid" would be
+three separate grayscale-channel attentions. Recovering it would need a bespoke
+per-channel recompute path that diverges from the shared timm/HF attention
+helpers, so GenBio deliberately opts out of ``encode_tiles_attention``.
+"""
+
+from typing import Callable
+
+import torch
+from torch import Tensor
+from torchvision.transforms import v2
+
+from slide2vec.encoders.base import (
+    TileEncoder,
+    preferred_default_device,
+    reshape_tokens_to_grid,
+    resolve_requested_output_variant,
+)
+from slide2vec.encoders.registry import register_encoder
+
+_HF_REPO_ID = "genbio-ai/genbio-pathfm"
+# Non-ImageNet normalization from the model's config.json (image_mean / image_std).
+_GENBIO_MEAN = (0.697, 0.575, 0.728)
+_GENBIO_STD = (0.188, 0.240, 0.187)
+
+
+@register_encoder(
+    "genbio-pathfm",
+    # encode_dim 4608 = embed_dim (1536) x 3 colour channels; patch_size 16 (a 224
+    # tile -> a 14x14 = 196 patch-token grid) — see module docstring.
+    output_variants={"default": {"encode_dim": 4608}},
+    default_output_variant="default",
+    input_size=224,
+    patch_size=16,
+    supported_spacing_um=0.5,  # 20x; card states no magnification, house default
+    precision="fp32",  # upstream runs plain fp32, no autocast
+    source="genbio-ai/genbio-pathfm",
+)
+class GenBioPathFM(TileEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        from transformers import AutoModel
+
+        self._model = AutoModel.from_pretrained(_HF_REPO_ID, trust_remote_code=True).eval()
+        self._device = preferred_default_device()
+        self._output_variant = resolve_requested_output_variant(output_variant)
+
+    def get_transform(self) -> Callable:
+        # Mirrors the model card: Resize to an exact 224x224 (tuple form, as the
+        # card's ``Resize((224, 224))``) + custom Normalize. No CenterCrop: the card
+        # has none, and after a square resize it would be a no-op anyway.
+        return v2.Compose([
+            v2.ToImage(),
+            v2.Resize((224, 224), interpolation=v2.InterpolationMode.BICUBIC, antialias=True),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=_GENBIO_MEAN, std=_GENBIO_STD),
+        ])
+
+    def get_dense_transform(self) -> Callable:
+        # Normalization only — no Resize/CenterCrop (see TileEncoder.get_dense_transform),
+        # so the dense grid stays registered to the full source tile.
+        return v2.Compose([
+            v2.ToImage(),
+            v2.ToDtype(torch.float32, scale=True),
+            v2.Normalize(mean=_GENBIO_MEAN, std=_GENBIO_STD),
+        ])
+
+    def encode_tiles(self, batch: Tensor) -> Tensor:
+        # Canonical forward: per-channel CLS tokens concatenated -> (B, 4608).
+        return self._model(batch)
+
+    @property
+    def patch_size(self) -> tuple[int, int]:
+        return (16, 16)
+
+    def encode_tiles_dense(self, batch: Tensor) -> Tensor:
+        """Encode tiles into a dense spatial grid. (B, C, H, W) -> (B, d, h, w).
+
+        Uses the model's ``forward_with_patches`` (DINOv2-style), which returns the
+        fused per-channel patch tokens ``(B, T, 4608)`` — the three single-channel
+        patch-token grids concatenated along the feature dim, with the prefix
+        tokens (CLS + storage tokens) already stripped — then folds that token
+        sequence back into its spatial grid (``num_prefix_tokens=0``). ``H, W`` must
+        be divisible by the patch size; non-224 inputs rely on the backbone's
+        DINOv2 positional-embedding interpolation.
+        """
+        if batch.ndim != 4:
+            raise ValueError(
+                "encode_tiles_dense expects a (B, C, H, W) batch, got shape "
+                f"{tuple(batch.shape)}."
+            )
+        _, _, height, width = batch.shape
+        patch_h, patch_w = self.patch_size
+        if height % patch_h != 0 or width % patch_w != 0:
+            raise ValueError(
+                f"Dense extraction for '{type(self).__name__}' requires input "
+                f"divisible by the patch size: got {height}x{width}, patch "
+                f"{patch_h}x{patch_w}. Pad the tile up to a patch multiple first."
+            )
+        _, patch_tokens = self._model.forward_with_patches(batch)
+        return reshape_tokens_to_grid(
+            patch_tokens,
+            grid_h=height // patch_h,
+            grid_w=width // patch_w,
+            num_prefix_tokens=0,
+            encoder_name=type(self).__name__,
+        )
+
+    @property
+    def encode_dim(self) -> int:
+        return 4608
+
+    @property
+    def device(self) -> torch.device:
+        return self._device
+
+    def to(self, device: torch.device | str) -> "GenBioPathFM":
+        self._device = torch.device(device)
+        self._model = self._model.to(self._device)
+        return self

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/gigapath.py

@@ -27,6 +27,7 @@ _GIGAPATH_STD = (0.229, 0.224, 0.225)
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=256,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="prov-gigapath/prov-gigapath",

slide2vec-5.3.0/slide2vec/encoders/models/gpfm.py

@@ -0,0 +1,89 @@
+"""GPFM tile encoder (Generalizable Pathology Foundation Model).
+
+GPFM (Ma et al., 2024; ``birkhoffkiki/GPFM``) is a ``ViT-L/14`` DINOv2 tile
+encoder (embedding dim 1024, patch_size 14). Weights are openly available under
+the MIT license at ``majiabo/GPFM`` but ship as a standalone ``GPFM.pth``
+checkpoint, so — unlike ``hf-hub:`` timm presets — we build the timm arch
+unpretrained and ``load_state_dict`` the downloaded checkpoint (the MOOZY
+loading pattern).
+
+The published ``GPFM.pth`` is a bare DINOv2 ``state_dict`` (``cls_token``,
+``pos_embed``, ``blocks.*``, …) that loads into
+``vit_large_patch14_dinov2.lvd142m`` with ``strict=True`` and zero missing /
+unexpected keys (verified on the real weights; see
+``tests/test_gpfm_genbio_heavy.py``). The loader below still defensively unwraps
+common checkpoint wrappers (``{"model": ...}`` / ``{"teacher": ...}`` /
+``{"student": ...}`` / ``{"state_dict": ...}``) and strips ``module.`` /
+``backbone.`` prefixes so a re-exported checkpoint keeps loading strictly.
+"""
+
+from typing import Mapping
+
+import torch
+from huggingface_hub import hf_hub_download
+
+from slide2vec.encoders.base import TimmTileEncoder
+from slide2vec.encoders.registry import register_encoder
+
+_HF_REPO_ID = "majiabo/GPFM"
+_HF_CHECKPOINT = "GPFM.pth"
+_CHECKPOINT_WRAPPER_KEYS = ("model", "teacher", "student", "state_dict", "teacher_backbone")
+_STATE_DICT_PREFIXES = ("module.", "backbone.")
+
+
+def _unwrap_gpfm_state_dict(payload: Mapping[str, object]) -> dict[str, torch.Tensor]:
+    """Reduce a GPFM checkpoint payload to a bare ``state_dict``.
+
+    Unwraps a single common wrapper key if present, then strips ``module.`` /
+    ``backbone.`` prefixes off every key. A no-op on the published bare
+    ``GPFM.pth`` (no wrapper, no prefixes), so it preserves strict loading there
+    while tolerating a re-wrapped/prefixed re-export.
+    """
+    state: object = payload
+    for wrapper in _CHECKPOINT_WRAPPER_KEYS:
+        if isinstance(state, Mapping) and wrapper in state and isinstance(state[wrapper], Mapping):
+            state = state[wrapper]
+            break
+    if not isinstance(state, Mapping):
+        raise ValueError(
+            f"Unexpected GPFM checkpoint payload: expected a state_dict mapping, got {type(state)}"
+        )
+    cleaned: dict[str, torch.Tensor] = {}
+    for key, value in state.items():
+        name = key
+        for prefix in _STATE_DICT_PREFIXES:
+            if name.startswith(prefix):
+                name = name[len(prefix):]
+        cleaned[name] = value
+    return cleaned
+
+
+@register_encoder(
+    "gpfm",
+    output_variants={"default": {"encode_dim": 1024}},
+    default_output_variant="default",
+    input_size=224,
+    patch_size=14,
+    supported_spacing_um=0.5,  # 512px@0.25um (128um FOV) resized to 224 => ~0.5um/px effective (20x), as for UNI
+    precision="fp32",  # upstream runs plain fp32, no autocast
+    source="majiabo/GPFM",
+)
+class GPFM(TimmTileEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        super().__init__(
+            "vit_large_patch14_dinov2.lvd142m",
+            output_variant=output_variant,
+            pretrained=False,
+            img_size=224,
+            init_values=1e-5,
+            dynamic_img_size=True,
+        )
+        checkpoint_path = hf_hub_download(repo_id=_HF_REPO_ID, filename=_HF_CHECKPOINT)
+        payload = torch.load(checkpoint_path, map_location="cpu", weights_only=False)
+        if not isinstance(payload, Mapping):
+            raise ValueError(
+                f"Invalid GPFM checkpoint payload: expected a dict, got {type(payload)}"
+            )
+        state_dict = _unwrap_gpfm_state_dict(payload)
+        self._model.load_state_dict(state_dict, strict=True)
+        self._model.eval()

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/hibou.py

@@ -151,6 +151,7 @@ class _HibouBase(TileEncoder):
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="histai/hibou-b",
@@ -167,6 +168,7 @@ class HibouB(_HibouBase):
     output_variants={"default": {"encode_dim": 1024}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="histai/hibou-L",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/hoptimus.py

@@ -72,6 +72,7 @@ class _HOptimusBase(TimmTileEncoder):
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="bioptimus/H-optimus-0",
@@ -108,6 +109,7 @@ class HOptimus0(TimmTileEncoder):
     output_variants={"default": {"encode_dim": 1536}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="bioptimus/H-optimus-1",
@@ -145,6 +147,7 @@ class HOptimus1(TimmTileEncoder):
     },
     default_output_variant="cls_patch_mean",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=0.5,
     precision="fp16",
     source="bioptimus/H0-mini",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/lunit.py

@@ -9,6 +9,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 384}},
     default_output_variant="default",
     input_size=224,
+    patch_size=8,
     supported_spacing_um=0.5,
     precision="fp32",
     source="1aurent/vit_small_patch8_224.lunit_dino",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/midnight.py

@@ -27,6 +27,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 3072}},
     default_output_variant="default",
     input_size=224,
+    patch_size=14,
     supported_spacing_um=[0.25, 0.5, 1.0, 2.0],
     precision="fp16",
     source="kaiko-ai/midnight",

slide2vec-5.3.0/slide2vec/encoders/models/mstar.py

@@ -0,0 +1,34 @@
+"""mSTAR tile encoder implementation.
+
+mSTAR (Wang et al., 2024; ``Innse/mSTAR``) is released as a ``ViT-L/16`` patch
+encoder, not a slide aggregator: the published checkpoint is a per-tile feature
+extractor and slide2vec handles WSI -> coordinates -> per-tile features itself.
+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.
+"""
+
+from slide2vec.encoders.base import TimmTileEncoder
+from slide2vec.encoders.registry import register_encoder
+
+
+@register_encoder(
+    "mstar",
+    output_variants={"default": {"encode_dim": 1024}},
+    default_output_variant="default",
+    input_size=224,
+    patch_size=16,
+    supported_spacing_um=0.5,  # 256px @ 20x, resized to 224 (per paper)
+    precision="fp32",  # upstream runs plain fp32, no autocast
+    source="Wangyh/mSTAR",
+)
+class mSTAR(TimmTileEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        super().__init__(
+            "hf-hub:Wangyh/mSTAR",
+            output_variant=output_variant,
+            init_values=1e-5,
+            dynamic_img_size=True,
+        )

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/musk.py

@@ -35,6 +35,7 @@ def _as_hw(value: int | tuple[int, int] | list[int]) -> tuple[int, int]:
     },
     default_output_variant="ms_aug",
     input_size=384,
+    patch_size=16,
     supported_spacing_um=[0.25, 0.5, 1.0],
     precision="fp16",
     source="xiangjx/musk",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/phikon.py

@@ -148,6 +148,7 @@ class _PhikonBase(TileEncoder):
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="owkin/phikon",
@@ -165,6 +166,7 @@ class Phikon(_PhikonBase):
     output_variants={"default": {"encode_dim": 1024}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="owkin/phikon-v2",

{slide2vec-5.1.1 → slide2vec-5.3.0}/slide2vec/encoders/models/prost40m.py

@@ -9,6 +9,7 @@ from slide2vec.encoders.registry import register_encoder
     output_variants={"default": {"encode_dim": 384}},
     default_output_variant="default",
     input_size=224,
+    patch_size=16,
     supported_spacing_um=0.5,
     precision="fp32",
     source="waticlems/Prost40M",