Align slide2vec with hs2p 2.3

README.md

@@ -23,7 +23,7 @@ pip install "slide2vec[models]"
 ```python
 from slide2vec import Model, PreprocessingConfig
 
-model = Model.from_pretrained("virchow2", level="region")
+model = Model.from_pretrained("virchow2", level="tile")
 preprocessing = PreprocessingConfig(
     target_spacing_um=0.5,
     target_tile_size_px=224,

docs/python-api.md

@@ -52,7 +52,7 @@ When `ExecutionOptions(num_gpus=2)` or another value greater than `1` is used:
 
 ## `PreprocessingConfig`
 
-The public preprocessing API combines tiling, segmentation, filtering, and QC into a single user-facing object.
+The public preprocessing API combines tiling, segmentation, filtering, and preview settings into a single user-facing object.
 
 Commonly overridden fields:
 
@@ -69,7 +69,7 @@ Defaults that most users can leave alone:
 - `use_padding=True`
 - `segmentation={}`
 - `filtering={}`
-- `qc={}`
+- `preview={}`
 - `read_tiles_from=None`
 - `resume=False`
 
@@ -83,7 +83,7 @@ preprocessing = PreprocessingConfig(
     tissue_threshold=0.1,
     segmentation={"downsample": 64},
     filtering={"ref_tile_size": 224},
-    qc={
+    preview={
         "save_mask_preview": False,
         "save_tiling_preview": False,
         "downsample": 32,

requirements.in

@@ -6,7 +6,7 @@ pandas
 pillow
 rich
 tqdm
-hs2p>=2.0,<3
+hs2p>=2.3.0,<3
 torch
 torchvision
 transformers

requirements.txt

@@ -1,4 +1,4 @@
-hs2p>=2.0,<3
+hs2p>=2.3.0,<3
 omegaconf>=2.3.0
 h5py
 matplotlib

setup.cfg

@@ -16,7 +16,7 @@ classifiers =
 packages =
     slide2vec
 install_requires =
-    hs2p>=2.0,<3
+    hs2p>=2.3.0,<3
     omegaconf
     h5py
     matplotlib

slide2vec/api.py

@@ -51,7 +51,7 @@ class PreprocessingConfig:
     resume: bool = False
     segmentation: dict[str, Any] = field(default_factory=dict)
     filtering: dict[str, Any] = field(default_factory=dict)
-    qc: dict[str, Any] = field(default_factory=dict)
+    preview: dict[str, Any] = field(default_factory=dict)
 
     @classmethod
     def from_config(cls, cfg: Any) -> "PreprocessingConfig":
@@ -69,10 +69,10 @@ def from_config(cls, cfg: Any) -> "PreprocessingConfig":
             resume=bool(getattr(cfg, "resume", False)),
             segmentation=dict(tiling.seg_params),
             filtering=dict(tiling.filter_params),
-            qc={
-                "save_mask_preview": bool(cfg.visualize),
-                "save_tiling_preview": bool(cfg.visualize),
-                "downsample": int(tiling.visu_params.downsample),
+            preview={
+                "save_mask_preview": bool(cfg.save_previews),
+                "save_tiling_preview": bool(cfg.save_previews),
+                "downsample": int(tiling.preview.downsample),
             },
         )
 

slide2vec/configs/models/conch.yaml

@@ -3,7 +3,7 @@ csv: "/data/pathology/projects/clement/discern/multi-center-prostate-no-mask.csv
 
 output_dir: "/data/pathology/projects/clement/discern/hs2p" # output directory
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/h-optimus-0.yaml

@@ -9,7 +9,7 @@ output_dir: "output"
 resume: true
 resume_dirname: "48juvldi"
 
-visualize: false
+save_previews: false
 
 tiling:
   params:

slide2vec/configs/models/hibou.yaml

@@ -2,7 +2,7 @@ csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/kaiko-midnight.yaml

@@ -2,7 +2,7 @@ csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/kaiko.yaml

@@ -2,7 +2,7 @@ csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/musk.yaml

@@ -2,7 +2,7 @@ csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/panda-vit-s.yaml

@@ -1,6 +1,6 @@
 csv: ""
 
-visualize: true
+save_previews: true
 
 output_dir: "output" # output directory
 

slide2vec/configs/models/pathojepa.yaml

@@ -5,7 +5,7 @@
 csv: "/data/pathology/projects/clement/leopard/csvs/brazil-slide2vec-august-2025-revision.csv"
 
 output_dir: "/data/pathology/projects/clement/discern/pathojepa/slide2vec"
-visualize: false
+save_previews: false
 
 tiling:
   params:

slide2vec/configs/models/phikonv2.yaml

@@ -2,7 +2,7 @@ csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/prism.yaml

@@ -1,7 +1,7 @@
 csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/prov-gigapath-slide.yaml

@@ -1,7 +1,7 @@
 csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/titan.yaml

@@ -1,7 +1,7 @@
 csv: # path to csv containing slide paths
 
 output_dir: "output" # output directory
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/uni.yaml

@@ -9,7 +9,7 @@ csv: "/data/temporary/clement/code/slide2vec/tmp.csv"
 
 output_dir: "output/debug"
 
-visualize: true
+save_previews: true
 
 tiling:
   params:

slide2vec/configs/models/virchow.yaml

@@ -4,7 +4,7 @@ csv: "/data/temporary/clement/dataset/tcga-brca/mutations/tcga-brca-tp53-slide2v
 
 output_dir: "output"
 
-visualize: true
+save_previews: true
 
 tiling:
   read_tiles_from:

slide2vec/configs/models/virchow2.yaml

@@ -5,7 +5,7 @@ csv: "/data/temporary/clement/leopard/csvs/brazil-slide2vec-august-2025-revision
 
 output_dir: "/data/temporary/clement/code/slide2vec/output"
 
-visualize: true
+save_previews: true
 
 tiling:
   # read_tiles_from: "/data/temporary/clement/code/slide2vec/output/vjh3hrr6/coordinates"

slide2vec/configs/preprocessing/default.yaml

@@ -4,7 +4,7 @@ output_dir: "output" # output directory
 resume: false # resume from a previous run
 resume_dirname: # directory name to resume from
 
-visualize: true # save a visualization of slide tiling in a .jpg
+save_previews: true # save preview images of slide tiling and mask overlays
 
 seed: 0 # seed for reproducibility
 
@@ -37,8 +37,8 @@ tiling:
     white_threshold: 220 # threshold for white pixels (0-255)
     black_threshold: 25 # threshold for black pixels (0-255)
     fraction_threshold: 0.9 # fraction of pixels that must be white/black to filter out the tile
-  visu_params:
-    downsample: 32 # downsample to use for tiling visualization
+  preview:
+    downsample: 32 # downsample to use for preview rendering
 
 speed:
   num_workers: 8 # number of workers for tiling slides

slide2vec/inference.py

@@ -1263,13 +1263,13 @@ def _embedding_work_dir(output_dir: Path | None):
 def _tile_slides(slides: Sequence[SlideSpec], preprocessing: PreprocessingConfig, *, output_dir: Path, num_workers: int):
     from hs2p import tile_slides
 
-    tiling_cfg, segmentation_cfg, filtering_cfg, qc_cfg, read_tiles_from, resume = _build_hs2p_configs(preprocessing)
+    tiling_cfg, segmentation_cfg, filtering_cfg, preview_cfg, read_tiles_from, resume = _build_hs2p_configs(preprocessing)
     tile_slides(
         slides,
         tiling=tiling_cfg,
         segmentation=segmentation_cfg,
         filtering=filtering_cfg,
-        qc=qc_cfg,
+        preview=preview_cfg,
         output_dir=output_dir,
         num_workers=num_workers,
         read_tiles_from=read_tiles_from,
@@ -1298,7 +1298,7 @@ def _record_slide_metadata_in_process_list(process_list_path: Path, slide_record
 
 
 def _build_hs2p_configs(preprocessing: PreprocessingConfig):
-    from hs2p import FilterConfig, QCConfig, SegmentationConfig, TilingConfig
+    from hs2p import FilterConfig, PreviewConfig, SegmentationConfig, TilingConfig
 
     tiling_cfg = TilingConfig(
         backend=preprocessing.backend,
@@ -1312,12 +1312,12 @@ def _build_hs2p_configs(preprocessing: PreprocessingConfig):
     )
     segmentation_cfg = SegmentationConfig(**dict(preprocessing.segmentation))
     filtering_cfg = FilterConfig(**dict(preprocessing.filtering))
-    qc_cfg = QCConfig(**dict(preprocessing.qc))
+    preview_cfg = PreviewConfig(**dict(preprocessing.preview))
     return (
         tiling_cfg,
         segmentation_cfg,
         filtering_cfg,
-        qc_cfg,
+        preview_cfg,
         preprocessing.read_tiles_from,
         preprocessing.resume,
     )
@@ -1747,7 +1747,7 @@ def _serialize_preprocessing(preprocessing: PreprocessingConfig) -> dict[str, An
         "resume": preprocessing.resume,
         "segmentation": dict(preprocessing.segmentation),
         "filtering": dict(preprocessing.filtering),
-        "qc": dict(preprocessing.qc),
+        "preview": dict(preprocessing.preview),
     }
 
 
@@ -1778,7 +1778,7 @@ def deserialize_preprocessing(payload: dict[str, Any]) -> PreprocessingConfig:
         resume=bool(payload.get("resume", False)),
         segmentation=dict(payload.get("segmentation", {})),
         filtering=dict(payload.get("filtering", {})),
-        qc=dict(payload.get("qc", {})),
+        preview=dict(payload.get("preview", {})),
     )
 
 

slide2vec/utils/config.py

@@ -18,6 +18,14 @@ def validate_removed_options(cfg) -> None:
         raise ValueError(
             "model.restrict_to_tissue is no longer supported in slide2vec."
         )
+    if "visualize" in cfg:
+        raise ValueError(
+            "visualize is no longer supported in slide2vec; use save_previews instead."
+        )
+    if "visu_params" in cfg.tiling:
+        raise ValueError(
+            "tiling.visu_params is no longer supported in slide2vec; use tiling.preview instead."
+        )
 
 
 def write_config(cfg, output_dir, name="config.yaml"):

slide2vec/utils/tiling_io.py

@@ -4,7 +4,7 @@
 import pandas as pd
 
 if TYPE_CHECKING:
-    from hs2p import FilterConfig, QCConfig, SegmentationConfig, SlideSpec, TilingConfig
+    from hs2p import FilterConfig, PreviewConfig, SegmentationConfig, SlideSpec, TilingConfig
 
 
 REQUIRED_MANIFEST_COLUMNS = ("sample_id", "image_path")
@@ -34,11 +34,11 @@ def _optional_float(value: Any) -> float | None:
 
 
 def _hs2p_exports() -> dict[str, Any]:
-    from hs2p import FilterConfig, QCConfig, SegmentationConfig, SlideSpec, TilingConfig, load_tiling_result
+    from hs2p import FilterConfig, PreviewConfig, SegmentationConfig, SlideSpec, TilingConfig, load_tiling_result
 
     return {
         "FilterConfig": FilterConfig,
-        "QCConfig": QCConfig,
+        "PreviewConfig": PreviewConfig,
         "SegmentationConfig": SegmentationConfig,
         "SlideSpec": SlideSpec,
         "TilingConfig": TilingConfig,

tests/test_output_consistency.py

@@ -49,8 +49,8 @@
     fraction_threshold=0.9,
 )
 
-# -- tiling.visu_params --
-TILING_VISU_PARAMS = dict(downsample=32)
+# -- tiling.preview --
+TILING_PREVIEW = dict(downsample=32)
 
 # -- model --
 MODEL_PARAMS = dict(
@@ -119,15 +119,15 @@ def test_output_consistency(wsi_path, mask_path, tmp_path):
         "output_dir": str(tmp_path),
         "resume": False,
         "resume_dirname": None,
-        "visualize": False,  # override (default: true)
+        "save_previews": False,  # override (default: true)
         "seed": 0,
         "tiling": {
             "read_tiles_from": None,
             "backend": "asap",
             "params": TILING_PARAMS,
             "seg_params": TILING_SEG_PARAMS,
             "filter_params": TILING_FILTER_PARAMS,
-            "visu_params": TILING_VISU_PARAMS,
+            "preview": TILING_PREVIEW,
         },
         "model": MODEL_PARAMS,
         "speed": SPEED_PARAMS,