slide2vec 6.0.1__tar.gz → 6.1.0__tar.gz

{slide2vec-6.0.1 → slide2vec-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.0.1
+Version: 6.1.0
 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,sam2,vips]>=4.4.3
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -75,7 +75,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,sam2,vips]>=4.4.3; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.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"

{slide2vec-6.0.1 → slide2vec-6.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "6.0.1"
+version = "6.1.0"
 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,sam2,vips]>=4.4.3",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -100,7 +100,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "6.0.1"
+current_version = "6.1.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

{slide2vec-6.0.1 → slide2vec-6.1.0}/slide2vec/__init__.py

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

{slide2vec-6.0.1 → slide2vec-6.1.0}/slide2vec/api.py

@@ -145,13 +145,18 @@ class PreprocessingConfig:
 
     #: Slide reading backend. ``"auto"`` tries cucim → vips → openslide → asap.
     #: Explicit choices: ``"cucim"``, ``"openslide"``, ``"vips"``, ``"asap"``.
+    #: Slides without spacing metadata require ``spacing_at_level_0``, including
+    #: untagged TIFFs read with VIPS.
     backend: str = "auto"
-    #: Source-mask reading backend, resolved independently from the *mask* path
-    #: (hs2p ≥ 4.3.0). ``"auto"`` probes openability just like :attr:`backend`. Set this
+    #: Source-mask reading backend, resolved independently from the *mask* path.
+    #: ``"auto"`` probes openability just like :attr:`backend`. Set this
     #: explicitly (e.g. ``"openslide"``) when a precomputed tissue or annotation mask needs
     #: a different decoder than its slide — hs2p no longer silently falls back to another
     #: reader, so a mask the slide backend cannot decode fails unless overridden here.
-    #: Accepts the same values as :attr:`backend`; ignored for slides with no source mask.
+    #: Accepts the same values as :attr:`backend` plus ``"pil"`` for PNG/JPEG masks;
+    #: ``"auto"`` selects PIL for these masks. Ignored for slides with no source mask.
+    #: Masks need no spacing metadata, but must align to the slide's field of view and
+    #: contain only declared label IDs. See :doc:`preprocessing` for hs2p 5 validation.
     mask_backend: str = "auto"
     #: Target spacing in µm/px. Resolved from the model preset when ``None``.
     requested_spacing_um: float | None = None

{slide2vec-6.0.1 → slide2vec-6.1.0}/slide2vec/configs/default.yaml

@@ -36,7 +36,7 @@ tiling:
     # where `mask_path` is read as a multi-label raster. The `tissue` min_coverage entry below is
     # the single source of truth for the tissue threshold.
     output_mode: per_annotation # how sampled tiles are grouped into artifacts. per_annotation: one flat artifact set per sampled class, namespaced under a `<class>/` subdir (the `tissue` class collapses to the flat root). merged: a single flat artifact set per slide over the union of tiles passing any active class threshold — it carries no class label, so it lands at the flat output root (no `<class>/` subdir).
-    pixel_mapping: # {class_name: integer pixel value in the mask raster}
+    pixel_mapping: # {class_name: integer pixel value in the mask raster}; a list (e.g. tumor: [2, 3]) merges several values into one class; every mask value must be declared
       background: 0
       tissue: 1
     colors: # {class_name: [r, g, b] | null} used when rendering previews

{slide2vec-6.0.1 → slide2vec-6.1.0}/slide2vec.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 6.0.1
+Version: 6.1.0
 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,sam2,vips]>=4.4.3
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -75,7 +75,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,sam2,vips]>=4.4.3; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=5.0.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"

{slide2vec-6.0.1 → slide2vec-6.1.0}/slide2vec.egg-info/SOURCES.txt

@@ -139,6 +139,7 @@ tests/test_encoder_preprocessing.py
 tests/test_encoder_provider_failures.py
 tests/test_encoder_registry.py
 tests/test_gpfm_genbio_heavy.py
+tests/test_hs2p5_integration.py
 tests/test_hs2p_package_cutover.py
 tests/test_image_shard.py
 tests/test_image_stage.py

{slide2vec-6.0.1 → slide2vec-6.1.0}/slide2vec.egg-info/requires.txt

@@ -1,4 +1,4 @@
-hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
+hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 omegaconf
 matplotlib
 numpy<2
@@ -27,7 +27,7 @@ numpy<2
 pandas
 pillow
 rich
-hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3
+hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0
 wandb
 torch<2.8,>=2.3
 torchvision>=0.18.0

slide2vec-6.1.0/tests/test_hs2p5_integration.py

@@ -0,0 +1,207 @@
+"""Exercise the slide2vec/hs2p boundary with real readers and persisted artifacts."""
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+from hs2p import BatchPartialFailureWarning, SlideSpec
+from PIL import Image
+
+from slide2vec.api import PreprocessingConfig
+from slide2vec.runtime.embedding import tiling_result_annotation
+from slide2vec.runtime.tiling_pipeline import prepare_tiled_slides
+
+
+def _flat_slide(tmp_path: Path, labels: np.ndarray) -> SlideSpec:
+    image_path = tmp_path / "slide.png"
+    mask_path = tmp_path / "mask.png"
+    Image.new("RGB", (128, 128), (160, 70, 110)).save(image_path)
+    Image.fromarray(labels).save(mask_path)
+    return SlideSpec(
+        sample_id="slide",
+        image_path=image_path,
+        mask_path=mask_path,
+        spacing_at_level_0=0.5,
+    )
+
+
+def _preprocessing(**kwargs) -> PreprocessingConfig:
+    return PreprocessingConfig(
+        backend="auto",
+        requested_spacing_um=0.5,
+        requested_tile_size_px=32,
+        segmentation={"downsample": 1},
+        filtering={"a_t": 0, "a_h": 0},
+        preview={"save_mask_preview": False, "save_tiling_preview": False},
+        **kwargs,
+    )
+
+
+def test_spacingless_tissue_mask_aligns_and_round_trips(tmp_path):
+    slide = _flat_slide(tmp_path, np.ones((32, 32), dtype=np.uint8))
+
+    slides, results, process_list = prepare_tiled_slides(
+        [slide], _preprocessing(), output_dir=tmp_path / "out", num_workers=1
+    )
+
+    assert slides == [slide]
+    result, = results
+    expected = np.array([(x, y) for x in range(0, 128, 32) for y in range(0, 128, 32)])
+    np.testing.assert_array_equal(np.column_stack((result.x, result.y)), expected)
+    assert result.spacing_at_level_0 == 0.5
+    assert result.mask_spacing_um == 2.0
+    assert result.mask_level == 0
+    assert result.mask_backend == "pil"
+    row = pd.read_csv(process_list).iloc[0]
+    assert row["tiling_status"] == "success"
+    assert row["requested_mask_backend"] == "auto"
+    assert row["mask_backend"] == "pil"
+    assert row["num_tiles"] == 16
+
+
+@pytest.mark.parametrize("output_mode", ["per_annotation", "merged"])
+def test_spacingless_annotation_mask_groups_values_and_preserves_bag_identity(tmp_path, output_mode):
+    labels = np.full((32, 32), 2, dtype=np.uint8)
+    labels[:, 16:] = 3
+    slide = _flat_slide(tmp_path, labels)
+    preprocessing = _preprocessing(masks={
+        "pixel_mapping": {"tumor": [2, 3]},
+        "min_coverage": {"tissue": None, "tumor": 0.5},
+        "colors": {"tumor": [255, 0, 0]},
+        "output_mode": output_mode,
+    })
+
+    slides, results, process_list = prepare_tiled_slides(
+        [slide], preprocessing, output_dir=tmp_path / "out", num_workers=1
+    )
+
+    assert slides == [slide]
+    result, = results
+    annotation = "tumor" if output_mode == "per_annotation" else "merged"
+    assert tiling_result_annotation(result) == annotation
+    assert result.output_mode == output_mode
+    assert result.mask_spacing_um == 2.0
+    assert len(result.x) == 16
+    row = pd.read_csv(process_list).iloc[0]
+    assert row["annotation"] == annotation
+    assert row["mask_backend"] == "pil"
+    assert row["tiling_status"] == "success"
+
+
+@pytest.mark.parametrize(
+    "labels, error",
+    [
+        (np.ones((32, 16), dtype=np.uint8), "Mask alignment failed"),
+        (np.full((32, 32), 255, dtype=np.uint8), "undeclared label IDs"),
+    ],
+    ids=["misaligned-mask", "undeclared-tissue-value"],
+)
+def test_invalid_source_masks_surface_hs2p_errors(tmp_path, labels, error):
+    slide = _flat_slide(tmp_path, labels)
+    output_dir = tmp_path / "out"
+
+    with pytest.warns(BatchPartialFailureWarning, match=error):
+        with pytest.raises(RuntimeError, match=error):
+            prepare_tiled_slides(
+                [slide], _preprocessing(), output_dir=output_dir, num_workers=1
+            )
+
+    row = pd.read_csv(output_dir / "process_list.csv").iloc[0]
+    assert row["tiling_status"] == "failed"
+    assert error in row["error"]
+    assert pd.isna(row["coordinates_npz_path"])
+
+
+def test_wsi_mask_coordinates_and_previews_remain_compatible(tmp_path):
+    pytest.importorskip("openslide")
+    from tests.output_consistency_config import (
+        TILING_FILTER_PARAMS,
+        TILING_MASKS,
+        TILING_PARAMS,
+        TILING_SEG_PARAMS,
+    )
+
+    fixtures = Path(__file__).parent / "fixtures"
+    slide = SlideSpec(
+        sample_id="test-wsi",
+        image_path=fixtures / "input" / "test-wsi.tif",
+        mask_path=fixtures / "input" / "test-mask.tif",
+    )
+    preprocessing = PreprocessingConfig(
+        backend="openslide",
+        mask_backend="openslide",
+        masks=TILING_MASKS,
+        segmentation=TILING_SEG_PARAMS,
+        filtering=TILING_FILTER_PARAMS,
+        **TILING_PARAMS,
+    )
+
+    slides, results, process_list = prepare_tiled_slides(
+        [slide], preprocessing, output_dir=tmp_path / "out", num_workers=1
+    )
+
+    assert slides == [slide]
+    result, = results
+    with np.load(fixtures / "gt" / "test-wsi.coordinates.npz") as expected:
+        np.testing.assert_array_equal(result.x, expected["x"])
+        np.testing.assert_array_equal(result.y, expected["y"])
+    # hs2p 5 records dimension-derived mask spacing, not the TIFF's nominal tag.
+    assert result.mask_level == 1
+    assert result.mask_spacing_um == pytest.approx(result.base_spacing_um * 32)
+    row = pd.read_csv(process_list).iloc[0]
+    for field in ("mask_preview_path", "tiling_preview_path"):
+        path = getattr(result, field)
+        assert path.is_file()
+        assert Path(row[field]) == path
+        with Image.open(path) as preview:
+            preview.verify()
+
+
+@pytest.mark.parametrize("output_mode", ["per_annotation", "merged"])
+def test_wsi_annotation_previews_accept_spacingless_masks(tmp_path, output_mode):
+    pytest.importorskip("openslide")
+    labels = np.full((200, 216), 2, dtype=np.uint8)
+    labels[:, 108:] = 3
+    mask_path = tmp_path / "annotations.png"
+    Image.fromarray(labels).save(mask_path)
+    slide = SlideSpec(
+        sample_id="test-wsi",
+        image_path=Path(__file__).parent / "fixtures" / "input" / "test-wsi.tif",
+        mask_path=mask_path,
+    )
+    preprocessing = PreprocessingConfig(
+        backend="openslide",
+        requested_spacing_um=0.5,
+        requested_tile_size_px=512,
+        filtering={"a_t": 0, "a_h": 0},
+        masks={
+            "pixel_mapping": {"tumor": [2, 3]},
+            "min_coverage": {"tissue": None, "tumor": 0.5},
+            "colors": {"tumor": [255, 0, 0]},
+            "output_mode": output_mode,
+        },
+    )
+
+    _, results, process_list = prepare_tiled_slides(
+        [slide], preprocessing, output_dir=tmp_path / "out", num_workers=1
+    )
+
+    result, = results
+    assert len(result.x) > 0
+    assert result.backend == "openslide"
+    assert result.mask_backend == "pil"
+    assert result.mask_spacing_um == pytest.approx(result.base_spacing_um * 64)
+    annotation = "tumor" if output_mode == "per_annotation" else "merged"
+    assert tiling_result_annotation(result) == annotation
+    preview_dir = tmp_path / "out" / "preview" / "tiling"
+    if output_mode == "per_annotation":
+        preview_dir /= "tumor"
+    assert result.tiling_preview_path == preview_dir / "test-wsi.jpg"
+    row = pd.read_csv(process_list).iloc[0]
+    for field in ("mask_preview_path", "tiling_preview_path"):
+        path = getattr(result, field)
+        assert path.is_file()
+        assert Path(row[field]) == path
+        with Image.open(path) as preview:
+            preview.verify()

{slide2vec-6.0.1 → slide2vec-6.1.0}/tests/test_hs2p_package_cutover.py

@@ -23,7 +23,7 @@ def test_package_root_exports_api():
     assert hasattr(package, "DenseRegionArtifact")
 
 
-def test_dependency_declarations_require_hs2p_4_4_3_with_consistent_extras():
+def test_dependency_declarations_require_hs2p_5_0_0_with_consistent_extras():
     project = tomllib.loads(
         (Path(__file__).resolve().parents[1] / "pyproject.toml").read_text(
             encoding="utf-8"
@@ -39,8 +39,8 @@ def test_dependency_declarations_require_hs2p_4_4_3_with_consistent_extras():
     ]
 
     assert hs2p_dependencies == [
-        "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
-        "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.3",
+        "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0",
+        "hs2p[asap,cucim,openslide,sam2,vips]>=5.0.0",
     ]
 
 

{slide2vec-6.0.1 → slide2vec-6.1.0}/tests/test_regression_core.py

@@ -1535,6 +1535,22 @@ def test_masks_boundary_accepts_distinct_integer_value_255():
     assert sampling.pixel_mapping["tumor"] == 255
 
 
+def test_masks_boundary_forwards_list_valued_pixel_mapping():
+    from slide2vec.runtime.tiling import build_hs2p_configs
+
+    preprocessing = _masks_preprocessing(
+        {
+            "pixel_mapping": {"tumor": [2, 3]},
+            "colors": {"tumor": [255, 0, 0]},
+            "min_coverage": {"tumor": 0.5},
+        }
+    )
+
+    sampling = build_hs2p_configs(preprocessing)[-3]
+
+    assert list(sampling.pixel_mapping["tumor"]) == [2, 3]
+
+
 @pytest.mark.parametrize(
     ("pixel_mapping", "message"),
     [