slide2vec 5.9.2__tar.gz → 6.0.0__tar.gz

{slide2vec-5.9.2 → slide2vec-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.9.2
+Version: 6.0.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -80,7 +80,7 @@ Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"
 Requires-Dist: einops>=0.8.0; extra == "fm"
-Requires-Dist: timm>=1.0.3; extra == "fm"
+Requires-Dist: timm>=1.0.20; extra == "fm"
 Requires-Dist: huggingface_hub<1.0,>=0.30.0; extra == "fm"
 Requires-Dist: environs; extra == "fm"
 Requires-Dist: einops-exts>=0.0.4; extra == "fm"
@@ -119,162 +119,88 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/slide2vec?label=pypi&logo=pypi&color=3776AB)](https://pypi.org/project/slide2vec/)
 [![Docs](https://img.shields.io/badge/docs-website-blue)](https://clemsgrs.github.io/slide2vec/)
 
-`slide2vec` is a Python package for efficient encoding of whole-slide images using publicly available foundation models. It builds on [`hs2p`](https://pypi.org/project/hs2p/) for fast preprocessing and exposes a focused surface around `Model`, `Pipeline`, and `ExecutionOptions`.
+`slide2vec` encodes whole-slide images with publicly available pathology foundation models. It uses [`hs2p`](https://pypi.org/project/hs2p/) for tissue detection and tiling, and handles batching, multi-GPU execution, and embedding storage.
 
-Documentation site: [https://clemsgrs.github.io/slide2vec/](https://clemsgrs.github.io/slide2vec/)
+## Install
 
-## Installation
+Python 3.10 or newer is required:
 
 ```shell
 pip install slide2vec
-pip install "slide2vec[fm]"
 ```
 
-`slide2vec` keeps the base install focused on the core package surface. Use `slide2vec[fm]` when you want the PyPI-hosted FM dependencies.
+Many models need additional dependencies available through `pip install "slide2vec[fm]"`. See the [model installation guide](https://clemsgrs.github.io/slide2vec/models.html#model-installation) for model-specific extras, separate environments, and upstream packages.
 
-Some model backends still rely on upstream Git repositories that PyPI will not accept as package metadata. Install those separately when needed:
+For gated models such as Virchow2, request access on the model's Hugging Face page and authenticate with `hf auth login` or an `HF_TOKEN` environment variable.
 
-```shell
-pip install git+https://github.com/lilab-stanford/MUSK.git
-pip install git+https://github.com/Mahmoodlab/CONCH.git
-pip install git+https://github.com/prov-gigapath/prov-gigapath.git
-```
-
-AtlasPatch-backed tissue segmentation is available through hs2p's `sam2` path in the bundled install.
-
-Waiv encoders use a separately tested Transformers 5 runtime. Install them in
-their own environment with `pip install "slide2vec[waiv]"`; the `waiv` extra is
-incompatible with the existing `fm`, `prism`, and `titan` dependency pins.
-
-## Python API
+## Embed a slide
 
 ```python
-from slide2vec import Model
-from slide2vec.utils.config import hf_login
-
-hf_login()
+from slide2vec import Model, PreprocessingConfig
 
 model = Model.from_preset("virchow2")
-embedded = model.embed_slide("/path/to/slide.svs")
+preprocessing = PreprocessingConfig(requested_spacing_um=0.5)
+embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)
 
-tile_embeddings = embedded.tile_embeddings
-x = embedded.x
-y = embedded.y
+tile_embeddings = embedded.tile_embeddings  # (N, 2560)
+x, y = embedded.x, embedded.y               # level-0 tile coordinates
 ```
 
-Use `list_models()` when you want to inspect the shipped presets programmatically:
+The preset supplies tile size and precision defaults. Declare spacing explicitly for models such as Virchow2 that support several scales. Use `list_models()` to list presets, or filter with `list_models("tile")`, `list_models("slide")`, or `list_models("patient")`.
 
-```python
-from slide2vec import list_models
+See [getting started](https://clemsgrs.github.io/slide2vec/getting-started.html) for preprocessing and execution settings, and the [API guide](https://clemsgrs.github.io/slide2vec/api.html) for patient embeddings, image inputs, and dense grids.
+
+## Save a batch
 
-all_models = list_models()
-tile_models = list_models("tile")
-slide_models = list_models("slide")
-patient_models = list_models("patient")
+Create a CSV manifest:
+
+```csv
+sample_id,image_path
+slide-1,/data/slide-1.svs
+slide-2,/data/slide-2.svs
 ```
 
-Use `Pipeline(...)` for manifest-driven batch processing when you want artifacts written to disk instead of only in-memory outputs:
+Optional `mask_path` and `spacing_at_level_0` columns supply a mask or correct missing or incorrect level-0 spacing. Patient-level models also require `patient_id`; see the [manifest schema](https://clemsgrs.github.io/slide2vec/manifest.html).
 
 ```python
-from slide2vec import ExecutionOptions, Pipeline, PreprocessingConfig
+from slide2vec import ExecutionOptions, Model, Pipeline, PreprocessingConfig
 
 pipeline = Pipeline(
-    model=model,
-    preprocessing=PreprocessingConfig(
-        requested_spacing_um=0.5,
-        requested_tile_size_px=224,
-        masks={"min_coverage": {"tissue": 0.1}},
-    ),
-    execution=ExecutionOptions(output_dir="outputs/demo"),
+    model=Model.from_preset("virchow2"),
+    preprocessing=PreprocessingConfig(requested_spacing_um=0.5),
+    execution=ExecutionOptions(output_dir="outputs/run"),
 )
 result = pipeline.run(manifest_path="/path/to/slides.csv")
 ```
 
-By default, `ExecutionOptions()` uses all available GPUs. Set `ExecutionOptions(num_gpus=4)` when you want to cap the sharding explicitly.
-
-### Hierarchical Feature Extraction
-
-Tile embeddings can be spatially grouped into regions for downstream models that consume region-level structure. Enable it by setting `region_tile_multiple` on `PreprocessingConfig`:
-
-```python
-preprocessing = PreprocessingConfig(
-    requested_spacing_um=0.5,
-    requested_tile_size_px=224,
-    region_tile_multiple=6,  # 6x6 tiles per region
-)
-embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)
-```
-
-Hierarchical outputs have shape `(num_regions, tiles_per_region, feature_dim)` and are written to `hierarchical_embeddings/` when persisted.
-
-See the [hierarchical features guide](https://clemsgrs.github.io/slide2vec/hierarchical.html) for details.
-
-### Input Manifest
-
-Manifest-driven runs use the schema below. `mask_path` and `spacing_at_level_0` are optional.
-
-```csv
-sample_id,image_path,mask_path,spacing_at_level_0
-slide-1,/path/to/slide-1.svs,/path/to/mask-1.png,0.25
-slide-2,/path/to/slide-2.svs,,
-...
-```
-
-Use `spacing_at_level_0` when the slide file reports a missing or incorrect level-0 spacing and you want to override it.
-
+Runs use all available GPUs by default; set `ExecutionOptions(num_gpus=2)` to limit them. Embeddings are saved as `.pt` tensors with metadata sidecars. Use `ExecutionOptions(output_format="npz")` for NumPy archives. The [output guide](https://clemsgrs.github.io/slide2vec/output-layout.html) describes directories, shapes, coordinates, and progress records.
 
-### Outputs
+Add `region_tile_multiple=6` to the preprocessing config to group tiles into 6×6 regions. These produce `(num_regions, 36, feature_dim)` tensors in `hierarchical_embeddings/`; see [hierarchical features](https://clemsgrs.github.io/slide2vec/hierarchical.html).
 
-The package writes explicit artifact directories:
-
-- `tile_embeddings/<sample_id>.pt` or `.npz`
-- `tile_embeddings/<sample_id>.meta.json`
-- `hierarchical_embeddings/<sample_id>.pt` or `.npz` (when `region_tile_multiple` is set)
-- `hierarchical_embeddings/<sample_id>.meta.json`
-- `slide_embeddings/<sample_id>.pt` or `.npz`
-- `slide_embeddings/<sample_id>.meta.json`
-- optional `slide_latents/<sample_id>.pt` or `.npz`
-
-`.pt` remains the default format. `.npz` is available through `ExecutionOptions(output_format="npz")`.
-
-### Supported Models
-
-`slide2vec` currently ships presets for 28 tile-level models, 4 slide-level models,
-and 1 patient-level model.
-For the full catalog and preset names, see the [model zoo](https://clemsgrs.github.io/slide2vec/models.html).
-
-## CLI
-
-The CLI is a thin wrapper over the package API.  
-Bundled configs live under `slide2vec/configs/preprocessing/` and `slide2vec/configs/models/`.
+The same batch workflow is available from the terminal:
 
 ```shell
 slide2vec /path/to/config.yaml
 ```
 
-By default, manifest-driven CLI runs use all available GPUs. Set `speed.num_gpus=4` when you want to cap the sharding explicitly.
-
-New to the CLI or doing batch runs to disk? Start with the [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html) for the config-driven workflow and common run patterns.
+The [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html) provides a complete config example, overrides, and resume instructions.
 
 ## Docker
 
 [![Docker Version](https://img.shields.io/docker/v/waticlems/slide2vec?sort=semver&label=docker&logo=docker&color=2496ED)](https://hub.docker.com/r/waticlems/slide2vec)
 
-Docker remains available when you prefer a containerized runtime:
-
 ```shell
 docker pull waticlems/slide2vec:latest
 docker run --rm -it \
     -v /path/to/your/data:/data \
-    -e HF_TOKEN=<your-huggingface-api-token> \
+    -e HF_TOKEN \
     waticlems/slide2vec:latest
 ```
 
-## Documentation
+Set `HF_TOKEN` in your shell before starting the container.
+
+## More documentation
 
-- [Documentation website](https://clemsgrs.github.io/slide2vec/)
-- [API guide](https://clemsgrs.github.io/slide2vec/api.html)
-- [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html)
 - [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
-- [Performance benchmarks and QA](docs/performance.md)
-- [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API
+- [Performance benchmarks and QA](https://clemsgrs.github.io/slide2vec/performance.html)
+- [API walkthrough notebook](tutorials/api_walkthrough.ipynb)

slide2vec-6.0.0/README.md

@@ -0,0 +1,90 @@
+# slide2vec
+
+[![PyPI version](https://img.shields.io/pypi/v/slide2vec?label=pypi&logo=pypi&color=3776AB)](https://pypi.org/project/slide2vec/)
+[![Docs](https://img.shields.io/badge/docs-website-blue)](https://clemsgrs.github.io/slide2vec/)
+
+`slide2vec` encodes whole-slide images with publicly available pathology foundation models. It uses [`hs2p`](https://pypi.org/project/hs2p/) for tissue detection and tiling, and handles batching, multi-GPU execution, and embedding storage.
+
+## Install
+
+Python 3.10 or newer is required:
+
+```shell
+pip install slide2vec
+```
+
+Many models need additional dependencies available through `pip install "slide2vec[fm]"`. See the [model installation guide](https://clemsgrs.github.io/slide2vec/models.html#model-installation) for model-specific extras, separate environments, and upstream packages.
+
+For gated models such as Virchow2, request access on the model's Hugging Face page and authenticate with `hf auth login` or an `HF_TOKEN` environment variable.
+
+## Embed a slide
+
+```python
+from slide2vec import Model, PreprocessingConfig
+
+model = Model.from_preset("virchow2")
+preprocessing = PreprocessingConfig(requested_spacing_um=0.5)
+embedded = model.embed_slide("/path/to/slide.svs", preprocessing=preprocessing)
+
+tile_embeddings = embedded.tile_embeddings  # (N, 2560)
+x, y = embedded.x, embedded.y               # level-0 tile coordinates
+```
+
+The preset supplies tile size and precision defaults. Declare spacing explicitly for models such as Virchow2 that support several scales. Use `list_models()` to list presets, or filter with `list_models("tile")`, `list_models("slide")`, or `list_models("patient")`.
+
+See [getting started](https://clemsgrs.github.io/slide2vec/getting-started.html) for preprocessing and execution settings, and the [API guide](https://clemsgrs.github.io/slide2vec/api.html) for patient embeddings, image inputs, and dense grids.
+
+## Save a batch
+
+Create a CSV manifest:
+
+```csv
+sample_id,image_path
+slide-1,/data/slide-1.svs
+slide-2,/data/slide-2.svs
+```
+
+Optional `mask_path` and `spacing_at_level_0` columns supply a mask or correct missing or incorrect level-0 spacing. Patient-level models also require `patient_id`; see the [manifest schema](https://clemsgrs.github.io/slide2vec/manifest.html).
+
+```python
+from slide2vec import ExecutionOptions, Model, Pipeline, PreprocessingConfig
+
+pipeline = Pipeline(
+    model=Model.from_preset("virchow2"),
+    preprocessing=PreprocessingConfig(requested_spacing_um=0.5),
+    execution=ExecutionOptions(output_dir="outputs/run"),
+)
+result = pipeline.run(manifest_path="/path/to/slides.csv")
+```
+
+Runs use all available GPUs by default; set `ExecutionOptions(num_gpus=2)` to limit them. Embeddings are saved as `.pt` tensors with metadata sidecars. Use `ExecutionOptions(output_format="npz")` for NumPy archives. The [output guide](https://clemsgrs.github.io/slide2vec/output-layout.html) describes directories, shapes, coordinates, and progress records.
+
+Add `region_tile_multiple=6` to the preprocessing config to group tiles into 6×6 regions. These produce `(num_regions, 36, feature_dim)` tensors in `hierarchical_embeddings/`; see [hierarchical features](https://clemsgrs.github.io/slide2vec/hierarchical.html).
+
+The same batch workflow is available from the terminal:
+
+```shell
+slide2vec /path/to/config.yaml
+```
+
+The [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html) provides a complete config example, overrides, and resume instructions.
+
+## Docker
+
+[![Docker Version](https://img.shields.io/docker/v/waticlems/slide2vec?sort=semver&label=docker&logo=docker&color=2496ED)](https://hub.docker.com/r/waticlems/slide2vec)
+
+```shell
+docker pull waticlems/slide2vec:latest
+docker run --rm -it \
+    -v /path/to/your/data:/data \
+    -e HF_TOKEN \
+    waticlems/slide2vec:latest
+```
+
+Set `HF_TOKEN` in your shell before starting the container.
+
+## More documentation
+
+- [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
+- [Performance benchmarks and QA](https://clemsgrs.github.io/slide2vec/performance.html)
+- [API walkthrough notebook](tutorials/api_walkthrough.ipynb)

{slide2vec-5.9.2 → slide2vec-6.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.9.2"
+version = "6.0.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -105,7 +105,7 @@ fm = [
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
     "einops>=0.8.0",
-    "timm>=1.0.3",
+    "timm>=1.0.20",
     "huggingface_hub>=0.30.0,<1.0",
     "environs",
     "einops-exts>=0.0.4",
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.9.2"
+current_version = "6.0.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

{slide2vec-5.9.2 → slide2vec-6.0.0}/slide2vec/__init__.py

@@ -27,7 +27,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "5.9.2"
+__version__ = "6.0.0"
 
 __all__ = [
     "Model",

{slide2vec-5.9.2 → slide2vec-6.0.0}/slide2vec/api.py

@@ -1010,14 +1010,14 @@ class Model:
         )
         self._encoder_input = contract
         plan = contract.plan
-        if emit_run_info and plan.requires_variable_model_input:
+        if emit_run_info:
             logging.getLogger("slide2vec").info(
-                "Pooled encoder input for '%s': preset %dpx, requested %dpx, "
-                "exact encoder input %dpx; using normalization-only preprocessing.",
+                "Pooled encoder input for '%s': preset %dpx, requested %dpx; encoding "
+                "exactly %dpx with geometry-preserving preprocessing.",
                 self.name,
                 plan.preset_input_size_px,
                 plan.requested_tile_size_px,
-                plan.expected_encoder_input_size_px,
+                plan.requested_tile_size_px,
             )
         return contract
 

{slide2vec-5.9.2 → slide2vec-6.0.0}/slide2vec/encoders/base.py

@@ -7,6 +7,7 @@ from typing import Callable
 import timm
 import torch
 from timm.data import create_transform, resolve_data_config
+from timm.layers import apply_rot_embed_cat
 from torch import Tensor
 from torchvision.transforms import v2
 
@@ -192,7 +193,7 @@ def prefix_attention_to_grid(
     return maps.reshape(batch_size, num_query * num_heads, grid_h, grid_w)
 
 
-def timm_self_attention_weights(attn_module, x: Tensor) -> Tensor:
+def timm_self_attention_weights(attn_module, x: Tensor, *, rope: Tensor | None = None) -> Tensor:
     """Recompute a timm ``Attention`` block's softmax weights ``(B, nh, N, N)``.
 
     timm's attention runs a *fused* SDPA kernel by default, which never
@@ -202,12 +203,23 @@ def timm_self_attention_weights(attn_module, x: Tensor) -> Tensor:
     / ``num_heads`` / ``head_dim`` / ``scale`` — i.e. exactly the non-fused branch of
     ``Attention.forward``, so the result is bit-equivalent to the weights the fused
     kernel applies internally. Dropout is omitted (extraction runs under ``eval``).
+
+    ``rope`` is the rotary embedding an ``EvaAttention`` block (DINOv3) receives
+    as its ``rope`` forward argument; when given, it is applied to the q/k rows
+    from ``attn_module.num_prefix_tokens`` onward (spatial tokens only, CLS and
+    registers untouched), exactly as ``EvaAttention.forward`` does. ``None`` for
+    plain ``Attention`` blocks leaves the recompute unchanged.
     """
-    if not hasattr(attn_module, "qkv"):
+    if getattr(attn_module, "qkv", None) is None:
         raise NotImplementedError(
             f"{type(attn_module).__name__} has no fused 'qkv' projection; attention "
             "extraction currently supports timm ViT Attention blocks only."
         )
+    if getattr(attn_module, "q_bias", None) is not None:
+        raise NotImplementedError(
+            f"{type(attn_module).__name__} uses separate q/k/v biases; attention "
+            "extraction supports fused-qkv blocks only."
+        )
     batch_size, num_tokens, _ = x.shape
     num_heads = int(attn_module.num_heads)
     head_dim = int(getattr(attn_module, "head_dim", x.shape[-1] // num_heads))
@@ -220,6 +232,11 @@ def timm_self_attention_weights(attn_module, x: Tensor) -> Tensor:
     # q_norm / k_norm are Identity unless the model uses QK-norm; apply them either way.
     q = attn_module.q_norm(q)
     k = attn_module.k_norm(k)
+    if rope is not None:
+        npt = int(attn_module.num_prefix_tokens)
+        half = getattr(attn_module, "rotate_half", False)
+        q = torch.cat([q[:, :, :npt], apply_rot_embed_cat(q[:, :, npt:], rope, half=half)], dim=2).type_as(x)
+        k = torch.cat([k[:, :, :npt], apply_rot_embed_cat(k[:, :, npt:], rope, half=half)], dim=2).type_as(x)
     q = q * attn_module.scale
     attn = q @ k.transpose(-2, -1)
     return attn.softmax(dim=-1)
@@ -291,16 +308,22 @@ def timm_trunk_attention(
     resolved = resolve_block_indices(blocks, len(block_list), encoder_name=encoder_name)
 
     captured: dict[int, Tensor] = {}
+    captured_rope: dict[int, Tensor | None] = {}
 
     def _make_hook(index: int):
-        def _hook(_module, inputs):
-            captured[index] = inputs[0]
+        def _hook(_module, args, kwargs):
+            captured[index] = args[0]
+            # EvaAttention (RoPE models) receives the rotary embedding as its
+            # second forward argument; plain Attention blocks receive none.
+            captured_rope[index] = kwargs.get("rope", args[1] if len(args) > 1 else None)
 
         return _hook
 
     handles = []
     for index in sorted(set(resolved)):
-        handles.append(block_list[index].attn.register_forward_pre_hook(_make_hook(index)))
+        handles.append(
+            block_list[index].attn.register_forward_pre_hook(_make_hook(index), with_kwargs=True)
+        )
     try:
         trunk.forward_features(batch)
     finally:
@@ -311,7 +334,9 @@ def timm_trunk_attention(
     num_prefix = int(getattr(trunk, "num_prefix_tokens", 1))
     grids = []
     for index in resolved:
-        attn_weights = timm_self_attention_weights(block_list[index].attn, captured[index])
+        attn_weights = timm_self_attention_weights(
+            block_list[index].attn, captured[index], rope=captured_rope[index]
+        )
         grids.append(
             prefix_attention_to_grid(
                 attn_weights,
@@ -463,26 +488,23 @@ class TileEncoder(Encoder):
         )
 
     def get_normalization_transform(self) -> Callable:
-        """Geometry-preserving photometric transform.
-
-        Returns a transform that applies ONLY this encoder's normalization
-        (per-channel mean/std) — **no Resize, no CenterCrop** — so callers can
-        preserve the full input geometry. This deliberately differs from
-        ``get_transform`` (the shipped pooled recipe):
-        some encoders resize-then-center-crop there (GigaPath ``Resize(256) ->
-        CenterCrop(224)``; Lunit ``crop_pct=0.9 -> Resize(248) -> CenterCrop(224)``),
-        which drops the tile margins. Geometry policy remains the caller's
-        responsibility. Default: unsupported, mirroring ``encode_tiles_dense``.
+        """Geometry-preserving photometric transform. Required for every tile encoder.
+
+        Returns a transform that applies ONLY this encoder's photometrics — dtype
+        conversion, intensity scaling, channel handling and per-channel mean/std
+        normalization — with **no Resize and no CenterCrop**. Every *declared* run
+        (pooled slide tiles and dense ROIs) encodes exactly the geometry it requested
+        through this transform; ``get_transform`` (the shipped recipe, which may
+        resize-then-center-crop) is applied only to *given* pre-cropped images.
+        ``register_encoder`` rejects a tile encoder that does not override it.
         """
         raise NotImplementedError(
             f"{type(self).__name__} does not provide a normalization transform. "
-            "The encoder cannot preserve caller-requested image geometry."
+            "Override get_normalization_transform with this encoder's photometric-only "
+            "preprocessing (dtype, scaling, normalization; no Resize/CenterCrop) so "
+            "declared runs can encode exactly the requested tile geometry."
         )
 
-    def get_dense_transform(self) -> Callable:
-        """Backward-compatible alias for the shared normalization primitive."""
-        return self.get_normalization_transform()
-
 
 class SlideEncoder(Encoder):
     """Base class for encoders that pool tile features into slide features."""

{slide2vec-5.9.2 → slide2vec-6.0.0}/slide2vec/encoders/models/__init__.py

@@ -6,6 +6,7 @@ Importing this package registers all encoders in the encoder_registry.
 from . import (
     conch,
     dinov2,
+    dinov3,
     genbio,
     gigapath,
     gpfm,
@@ -31,6 +32,7 @@ from . import (
 __all__ = [
     "conch",
     "dinov2",
+    "dinov3",
     "genbio",
     "gigapath",
     "gpfm",

{slide2vec-5.9.2 → slide2vec-6.0.0}/slide2vec/encoders/models/dinov2.py

@@ -26,10 +26,13 @@ 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.
+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)
+needs no ``allow_non_recommended_settings`` escape hatch — any requested spacing
+is accepted as-is.
 """
 
 from slide2vec.encoders.base import TimmTileEncoder
@@ -40,7 +43,7 @@ from slide2vec.encoders.registry import register_encoder
     "dinov2-vitb14",
     output_variants={"default": {"encode_dim": 768}},
     default_output_variant="default",
-    input_size=224,
+    input_size=518,
     supports_variable_input_size=True,
     patch_size=14,
     supported_spacing_um=None,  # spacing-agnostic: no intrinsic µm/px, so no validation constraint

slide2vec-6.0.0/slide2vec/encoders/models/dinov3.py

@@ -0,0 +1,79 @@
+"""Natural-image DINOv3 ViT-B/16 encoder.
+
+``dinov3-vitb16`` is the DINOv3 ViT-B/16 (Siméoni et al., 2025) distilled on
+LVD-1689M natural images, shipped by ``timm`` as
+``vit_base_patch16_dinov3.lvd1689m`` (weights on Hugging Face under
+``timm/vit_base_patch16_dinov3.lvd1689m``; DINOv3 license). It complements the
+``dinov2-vitb14`` natural-image baseline but is not architecture-identical:
+16px patches, four register tokens and rotary positional embeddings (RoPE)
+instead of 14px patches and learned positional embeddings.
+
+The timm backbone is an ``Eva`` model whose checkpoint defaults to
+``global_pool="avg"``: the pooled output is the mean of the **spatial patch
+tokens** after the final LayerNorm, excluding the CLS token and the four
+registers. That shipped output is the default ``patch_mean`` variant; ``cls``
+exposes the CLS token after the same final norm. Both are 768-d.
+
+Spacing-agnostic like ``dinov2-vitb14`` (``supported_spacing_um=None``,
+``default_spacing_um=0.5``). Declared pooled runs encode exactly the requested
+tile size with normalization only: 256px by default, or 224px with
+``allow_non_recommended_settings=True``. Given pre-cropped tiles use the shipped
+Resize 256 -> CenterCrop 256 recipe.
+"""
+
+import timm
+from packaging.version import Version
+from torch import Tensor
+
+from slide2vec.encoders.base import TimmTileEncoder, resolve_requested_output_variant
+from slide2vec.encoders.registry import register_encoder
+
+_POOL_TYPES = {"patch_mean": "avg", "cls": "token"}
+_MIN_TIMM_VERSION = "1.0.20"  # first release registering vit_base_patch16_dinov3
+
+
+def require_timm_for_dinov3() -> None:
+    if Version(timm.__version__) < Version(_MIN_TIMM_VERSION):
+        raise ImportError(
+            f"dinov3-vitb16 requires timm>={_MIN_TIMM_VERSION} (the DINOv3 "
+            f"architectures were added in that release); found timm=={timm.__version__}. "
+            "Note that the 'titan' extra pins timm==1.0.3 and cannot be installed "
+            "alongside dinov3-vitb16."
+        )
+
+
+@register_encoder(
+    "dinov3-vitb16",
+    output_variants={
+        "patch_mean": {"encode_dim": 768},
+        "cls": {"encode_dim": 768},
+    },
+    default_output_variant="patch_mean",
+    input_size=256,
+    supports_variable_input_size=True,
+    patch_size=16,
+    supported_spacing_um=None,  # spacing-agnostic: no intrinsic µm/px
+    default_spacing_um=0.5,  # tiling default: match the pathology encoders' task-spacing
+    precision="fp16",
+    source="timm/vit_base_patch16_dinov3.lvd1689m",
+)
+class DINOv3ViTB16(TimmTileEncoder):
+    def __init__(self, *, output_variant: str | None = None):
+        require_timm_for_dinov3()
+        self._output_variant = resolve_requested_output_variant(
+            output_variant, default="patch_mean", allowed=tuple(_POOL_TYPES)
+        )
+        super().__init__(
+            "vit_base_patch16_dinov3.lvd1689m",
+            output_variant=self._output_variant,
+            dynamic_img_size=True,
+        )
+
+    def encode_tiles(self, batch: Tensor) -> Tensor:
+        # forward_features applies the final LayerNorm to every token; Eva.pool
+        # then reduces with the backbone's own num_prefix_tokens (CLS + 4 reg):
+        # "avg" = mean over spatial tokens only, "token" = CLS. fc_norm is
+        # Identity for this checkpoint (kept for parity with forward_head).
+        tokens = self._model.forward_features(batch)
+        pooled = self._model.pool(tokens, pool_type=_POOL_TYPES[self._output_variant])
+        return self._model.fc_norm(pooled)