slide2vec 4.1.0__tar.gz → 4.1.1__tar.gz

{slide2vec-4.1.0 → slide2vec-4.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 4.1.0
+Version: 4.1.1
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: hs2p[asap,cucim,openslide,vips]>=3.1.4
+Requires-Dist: hs2p[asap,cucim,openslide,vips]>=3.2.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -63,7 +63,7 @@ Requires-Dist: numpy<2; extra == "fm"
 Requires-Dist: pandas; extra == "fm"
 Requires-Dist: pillow; extra == "fm"
 Requires-Dist: rich; extra == "fm"
-Requires-Dist: hs2p[asap,cucim,openslide,vips]>=3.1.4; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,vips]>=3.2.0; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"
@@ -143,8 +143,8 @@ from slide2vec import ExecutionOptions, Pipeline, PreprocessingConfig
 pipeline = Pipeline(
     model=model,
     preprocessing=PreprocessingConfig(
-        target_spacing_um=0.5,
-        target_tile_size_px=224,
+        requested_spacing_um=0.5,
+        requested_tile_size_px=224,
         tissue_threshold=0.1,
     ),
     execution=ExecutionOptions(output_dir="outputs/demo"),
@@ -160,8 +160,8 @@ Tile embeddings can be spatially grouped into regions for downstream models that
 
 ```python
 preprocessing = PreprocessingConfig(
-    target_spacing_um=0.5,
-    target_tile_size_px=224,
+    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)

{slide2vec-4.1.0 → slide2vec-4.1.1}/README.md

@@ -45,8 +45,8 @@ from slide2vec import ExecutionOptions, Pipeline, PreprocessingConfig
 pipeline = Pipeline(
     model=model,
     preprocessing=PreprocessingConfig(
-        target_spacing_um=0.5,
-        target_tile_size_px=224,
+        requested_spacing_um=0.5,
+        requested_tile_size_px=224,
         tissue_threshold=0.1,
     ),
     execution=ExecutionOptions(output_dir="outputs/demo"),
@@ -62,8 +62,8 @@ Tile embeddings can be spatially grouped into regions for downstream models that
 
 ```python
 preprocessing = PreprocessingConfig(
-    target_spacing_um=0.5,
-    target_tile_size_px=224,
+    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)

{slide2vec-4.1.0 → slide2vec-4.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "4.1.0"
+version = "4.1.1"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "hs2p[asap,cucim,openslide,vips]>=3.1.4",
+    "hs2p[asap,cucim,openslide,vips]>=3.2.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -85,7 +85,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,vips]>=3.1.4",
+    "hs2p[asap,cucim,openslide,vips]>=3.2.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -154,7 +154,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "4.1.0"
+current_version = "4.1.1"
 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-4.1.0 → slide2vec-4.1.1}/slide2vec/__init__.py

@@ -2,7 +2,7 @@ from slide2vec.api import EmbeddedSlide, ExecutionOptions, Model, Pipeline, Prep
 from slide2vec.artifacts import HierarchicalEmbeddingArtifact, SlideEmbeddingArtifact, TileEmbeddingArtifact
 
 
-__version__ = "4.1.0"
+__version__ = "4.1.1"
 
 __all__ = [
     "Model",

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/api.py

@@ -42,9 +42,9 @@ TilingResultsInput = Sequence[Any] | Mapping[str, Any]
 @dataclass(frozen=True, kw_only=True)
 class PreprocessingConfig:
     backend: str = "auto"
-    target_spacing_um: float | None = None
-    target_tile_size_px: int | None = None
-    target_region_size_px: int | None = None
+    requested_spacing_um: float | None = None
+    requested_tile_size_px: int | None = None
+    requested_region_size_px: int | None = None
     region_tile_multiple: int | None = None
     tolerance: float = 0.05
     overlap: float = 0.0
@@ -75,11 +75,11 @@ class PreprocessingConfig:
         preview_downsample = int(preview_cfg.downsample)
         return cls(
             backend=tiling.backend,
-            target_spacing_um=float(tiling.params.target_spacing_um),
-            target_tile_size_px=int(tiling.params.target_tile_size_px),
-            target_region_size_px=(
+            requested_spacing_um=float(tiling.params.requested_spacing_um),
+            requested_tile_size_px=int(tiling.params.requested_tile_size_px),
+            requested_region_size_px=(
                 int(v)
-                if (v := getattr(tiling.params, "target_region_size_px", None)) is not None
+                if (v := getattr(tiling.params, "requested_region_size_px", None)) is not None
                 else None
             ),
             region_tile_multiple=(
@@ -454,28 +454,28 @@ def _resolve_direct_api_preprocessing(
         return defaults
 
     if preprocessing is None:
-        target_tile_size_px, target_spacing_um = ensure_defaults()
+        requested_tile_size_px, requested_spacing_um = ensure_defaults()
         return _resolve_hierarchical_preprocessing(
             PreprocessingConfig(
                 backend="auto",
-                target_spacing_um=target_spacing_um,
-                target_tile_size_px=target_tile_size_px,
+                requested_spacing_um=requested_spacing_um,
+                requested_tile_size_px=requested_tile_size_px,
             )
         )
 
-    target_spacing_um = preprocessing.target_spacing_um
-    target_tile_size_px = preprocessing.target_tile_size_px
-    if target_spacing_um is None or target_tile_size_px is None:
+    requested_spacing_um = preprocessing.requested_spacing_um
+    requested_tile_size_px = preprocessing.requested_tile_size_px
+    if requested_spacing_um is None or requested_tile_size_px is None:
         default_tile_size_px, default_spacing_um = ensure_defaults()
-        if target_spacing_um is None:
-            target_spacing_um = default_spacing_um
-        if target_tile_size_px is None:
-            target_tile_size_px = default_tile_size_px
+        if requested_spacing_um is None:
+            requested_spacing_um = default_spacing_um
+        if requested_tile_size_px is None:
+            requested_tile_size_px = default_tile_size_px
     return _resolve_hierarchical_preprocessing(
         replace(
             preprocessing,
-            target_spacing_um=target_spacing_um,
-            target_tile_size_px=target_tile_size_px,
+            requested_spacing_um=requested_spacing_um,
+            requested_tile_size_px=requested_tile_size_px,
         )
     )
 
@@ -484,7 +484,7 @@ def _default_preprocessing_from_registry(name: str | None) -> tuple[int, float]:
     if not name or name not in encoder_registry:
         raise ValueError(
             "Cannot infer preprocessing defaults without a registered model. "
-            "Pass preprocessing.target_spacing_um and preprocessing.target_tile_size_px explicitly."
+            "Pass preprocessing.requested_spacing_um and preprocessing.requested_tile_size_px explicitly."
         )
 
     defaults = resolve_preprocessing_defaults(name)
@@ -499,7 +499,7 @@ def _validate_model_config(
     name = model.name
     if name not in encoder_registry:
         return
-    if preprocessing.region_tile_multiple is not None or preprocessing.target_region_size_px is not None:
+    if preprocessing.region_tile_multiple is not None or preprocessing.requested_region_size_px is not None:
         info = encoder_registry.info(name)
         if info["level"] != "tile":
             raise ValueError("Hierarchical preprocessing is only supported for tile encoders")
@@ -508,8 +508,8 @@ def _validate_model_config(
     precision = None if on_cpu or execution is None else execution.precision
     validate_encoder_config(
         name,
-        target_tile_size_px=preprocessing.target_tile_size_px,
-        target_spacing_um=preprocessing.target_spacing_um,
+        requested_tile_size_px=preprocessing.requested_tile_size_px,
+        requested_spacing_um=preprocessing.requested_spacing_um,
         precision=precision,
         output_variant=model._output_variant,
         allow_non_recommended=bool(model.allow_non_recommended_settings),
@@ -518,32 +518,32 @@ def _validate_model_config(
 
 def _resolve_hierarchical_preprocessing(preprocessing: PreprocessingConfig) -> PreprocessingConfig:
     multiple = preprocessing.region_tile_multiple
-    target_region_size_px = preprocessing.target_region_size_px
+    requested_region_size_px = preprocessing.requested_region_size_px
     if multiple is not None:
         multiple = int(multiple)
         if multiple < 2:
             raise ValueError("region_tile_multiple must be at least 2")
-    if multiple is None and target_region_size_px is None:
+    if multiple is None and requested_region_size_px is None:
         return preprocessing
-    if preprocessing.target_tile_size_px is None:
+    if preprocessing.requested_tile_size_px is None:
         raise ValueError(
-            "target_tile_size_px must be resolved before deriving hierarchical region geometry"
+            "requested_tile_size_px must be resolved before deriving hierarchical region geometry"
         )
-    if target_region_size_px is None:
-        target_region_size_px = int(preprocessing.target_tile_size_px) * int(multiple)
+    if requested_region_size_px is None:
+        requested_region_size_px = int(preprocessing.requested_tile_size_px) * int(multiple)
     elif multiple is None:
-        if int(target_region_size_px) % int(preprocessing.target_tile_size_px) != 0:
+        if int(requested_region_size_px) % int(preprocessing.requested_tile_size_px) != 0:
             raise ValueError(
-                "target_region_size_px must be an exact multiple of target_tile_size_px"
+                "requested_region_size_px must be an exact multiple of requested_tile_size_px"
             )
-        multiple = int(target_region_size_px) // int(preprocessing.target_tile_size_px)
-    elif int(target_region_size_px) != int(preprocessing.target_tile_size_px) * int(multiple):
+        multiple = int(requested_region_size_px) // int(preprocessing.requested_tile_size_px)
+    elif int(requested_region_size_px) != int(preprocessing.requested_tile_size_px) * int(multiple):
         raise ValueError(
-            "target_region_size_px must match target_tile_size_px * region_tile_multiple"
+            "requested_region_size_px must match requested_tile_size_px * region_tile_multiple"
         )
     return replace(
         preprocessing,
-        target_region_size_px=int(target_region_size_px),
+        requested_region_size_px=int(requested_region_size_px),
         region_tile_multiple=int(multiple),
     )
 

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/configs/default.yaml

@@ -26,10 +26,10 @@ tiling:
   read_tiles_from: # path to an existing directory containing pre-extracted `.tiles.tar` tile stores to reuse instead of starting tiling from scratch
   backend: "auto" # backend to use for slide reading; "auto" lets hs2p resolve the best backend per slide, preferring cuCIM when available
   params:
-    target_spacing_um: # spacing at which to tile the slide, in microns per pixel; filled from a preset model when available
+    requested_spacing_um: # spacing at which to tile the slide, in microns per pixel; filled from a preset model when available
     tolerance: 0.05 # tolerance for matching the spacing (float between 0 and 1, deciding how much the spacing can deviate from the one specified in the slide metadata)
-    target_tile_size_px: # size of the tiles to extract, in pixels; filled from a preset model when available
-    target_region_size_px: # size of hierarchical parent regions in pixels; when unset and region_tile_multiple is set, derived from target_tile_size_px * region_tile_multiple
+    requested_tile_size_px: # size of the tiles to extract, in pixels; filled from a preset model when available
+    requested_region_size_px: # size of hierarchical parent regions in pixels; when unset and region_tile_multiple is set, derived from requested_tile_size_px * region_tile_multiple
     region_tile_multiple: # hierarchical region grid width/height in tiles; e.g. 6 means 6x6 tiles per region
     overlap: 0.0 # percentage of overlap between two consecutive tiles (float between 0 and 1)
     tissue_threshold: 0.1 # minimum fraction of pixels that must be tissue to keep a tile (float between 0 and 1)
@@ -44,8 +44,8 @@ tiling:
     use_otsu: false # use otsu's method instead of simple binary thresholding
     use_hsv: true # use HSV thresholding instead of simple binary thresholding
   filter_params:
-    ref_tile_size: ${tiling.params.target_tile_size_px} # reference tile size at the target spacing
-    a_t: 4 # area filter threshold for tissue (positive integer, the minimum size of detected foreground contours to consider, relative to the reference tile size ref_tile_size, e.g. a value 10 means only detected foreground contours of size greater than 10 [ref_tile_size, ref_tile_size] tiles at spacing tiling.params.target_spacing_um will be kept)
+    ref_tile_size: ${tiling.params.requested_tile_size_px} # reference tile size at the target spacing
+    a_t: 4 # area filter threshold for tissue (positive integer, the minimum size of detected foreground contours to consider, relative to the reference tile size ref_tile_size, e.g. a value 10 means only detected foreground contours of size greater than 10 [ref_tile_size, ref_tile_size] tiles at spacing tiling.params.requested_spacing_um will be kept)
     a_h: 2 # area filter threshold for holes (positive integer, the minimum size of detected holes/cavities in foreground contours to avoid, once again relative to the reference tile size ref_tile_size)
     filter_white: false # whether to filter out mostly white tiles
     filter_black: false # whether to filter out mostly black tiles
@@ -78,7 +78,7 @@ wandb:
   project: "" # wandb project name
   username: "" # wandb username
   exp_name: "" # wandb experiment name
-  tags: ["features", "${model.name}", "${tiling.params.target_tile_size_px}"] # wandb tags
+  tags: ["features", "${model.name}", "${tiling.params.requested_tile_size_px}"] # wandb tags
   dir: "/home/user/"
   group:
   resume_id: "${resume_dirname}"

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/data/tile_reader.py

@@ -89,7 +89,7 @@ class WSITileReader:
         self._num_cucim_workers = num_cucim_workers
         self._gpu_decode = gpu_decode
         self._read_level = int(tiling_result.read_level)
-        self._tile_size_px = int(tiling_result.effective_tile_size_px)
+        self._tile_size_px = int(tiling_result.read_tile_size_px)
         self._x = tiling_result.x
         self._y = tiling_result.y
         self._reader = None
@@ -215,7 +215,7 @@ class OnTheFlyBatchTileCollator:
         gpu_decode: bool = False,
         use_supertiles: bool = True,
     ):
-        self.tile_size = int(tiling_result.effective_tile_size_px)
+        self.tile_size = int(tiling_result.read_tile_size_px)
         self._reader = WSITileReader(
             image_path,
             tiling_result,
@@ -354,8 +354,8 @@ class OnTheFlyHierarchicalBatchCollator:
         tiling_result: TilingResult,
         region_index: np.ndarray,
         subtile_index_within_region: np.ndarray,
-        effective_region_size_px: int,
-        effective_tile_size_px: int,
+        read_region_size_px: int,
+        read_tile_size_px: int,
         backend: str = "cucim",
         num_cucim_workers: int = 4,
         gpu_decode: bool = False,
@@ -363,11 +363,11 @@ class OnTheFlyHierarchicalBatchCollator:
         self._region_index = np.asarray(region_index, dtype=np.int32)
         self._subtile_index_within_region = np.asarray(subtile_index_within_region, dtype=np.int32)
         self._tiles_per_region = int(self._subtile_index_within_region.max()) + 1 if len(self._subtile_index_within_region) else 0
-        self._tile_size = int(effective_tile_size_px)
+        self._tile_size = int(read_tile_size_px)
         self._reader = WSIRegionReader(
             image_path,
             read_level=int(tiling_result.read_level),
-            region_size_px=int(effective_region_size_px),
+            region_size_px=int(read_region_size_px),
             backend=backend,
             num_cucim_workers=num_cucim_workers,
             gpu_decode=gpu_decode,

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/encoders/base.py

@@ -90,7 +90,7 @@ class SlideEncoder(Encoder):
         coordinates: Tensor,
         *,
         base_spacing_um: float,
-        target_spacing_um: float,
+        requested_spacing_um: float,
     ) -> Tensor:
         """Hook for model-specific coordinate normalization."""
         return coordinates

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/encoders/models/gigapath.py

@@ -69,9 +69,9 @@ class GigaPathSlideEncoder(SlideEncoder):
         coordinates: torch.Tensor,
         *,
         base_spacing_um: float,
-        target_spacing_um: float,
+        requested_spacing_um: float,
     ) -> torch.Tensor:
-        scale = float(base_spacing_um) / float(target_spacing_um)
+        scale = float(base_spacing_um) / float(requested_spacing_um)
         return torch.floor(coordinates.to(torch.float32) * scale).to(torch.long)
 
     def encode_slide(

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/encoders/registry.py

@@ -131,8 +131,8 @@ def resolve_preprocessing_defaults(
             supported_text = ", ".join(f"{s:g}" for s in unique_spacings)
             raise ValueError(
                 f"Encoder '{encoder_name}' supports multiple spacings [{supported_text}]; "
-                "cannot infer a default target_spacing_um. "
-                "Pass preprocessing.target_spacing_um explicitly."
+                "cannot infer a default requested_spacing_um. "
+                "Pass preprocessing.requested_spacing_um explicitly."
             )
         spacing_um = unique_spacings[0]
     return {

{slide2vec-4.1.0 → slide2vec-4.1.1}/slide2vec/encoders/validation.py

@@ -17,8 +17,8 @@ def validate_encoder_config(
     encoder_name: str,
     *,
     info: dict[str, Any] | None = None,
-    target_tile_size_px: int | None = None,
-    target_spacing_um: float | None = None,
+    requested_tile_size_px: int | None = None,
+    requested_spacing_um: float | None = None,
     precision: str | None = None,
     output_variant: str | None = None,
     allow_non_recommended: bool = False,
@@ -44,20 +44,20 @@ def validate_encoder_config(
             )
 
     rec_spacing = info["supported_spacing_um"] if "supported_spacing_um" in info else None
-    if target_spacing_um is not None and rec_spacing is not None:
+    if requested_spacing_um is not None and rec_spacing is not None:
         valid_spacings = rec_spacing if isinstance(rec_spacing, list) else [rec_spacing]
-        if not any(abs(float(target_spacing_um) - float(s)) <= 1e-8 for s in valid_spacings):
+        if not any(abs(float(requested_spacing_um) - float(s)) <= 1e-8 for s in valid_spacings):
             supported_text = ", ".join(f"{s:g}" for s in valid_spacings)
             mismatches.append(
-                f"target_spacing_um={float(target_spacing_um):g} (recommended: [{supported_text}])"
+                f"requested_spacing_um={float(requested_spacing_um):g} (recommended: [{supported_text}])"
             )
 
-    if target_tile_size_px is not None:
+    if requested_tile_size_px is not None:
         reqs = resolve_preprocessing_requirements(encoder_name, info)
         rec_tile_size = reqs["tile_size_px"]
-        if rec_tile_size is not None and int(target_tile_size_px) != int(rec_tile_size):
+        if rec_tile_size is not None and int(requested_tile_size_px) != int(rec_tile_size):
             mismatches.append(
-                f"target_tile_size_px={target_tile_size_px} (recommended: {rec_tile_size})"
+                f"requested_tile_size_px={requested_tile_size_px} (recommended: {rec_tile_size})"
             )
 
     if not mismatches: