6.1.0

This release gives hs2p's annotation-mask vocabulary a single typed home: MaskSamplingConfig. Pixel mapping, colors, per-label coverage, output mode and sampling strategy now live in one validated dataclass, so downstream tools (slide2vec, soma) can compose it instead of keeping their own drifting copies. The change breaks the API: read the migration notes below before upgrading. For the same inputs, sampling outputs are byte-identical to 6.0.0.

Added

• MaskSamplingConfig and DEFAULT_MASK_SAMPLING, both exported from hs2p. MaskSamplingConfig is a frozen, keyword-only dataclass with the fields pixel_mapping, min_coverage, colors, output_mode ("merged" | "per_annotation") and strategy ("joint" | "independent"). It checks its own fields when built: label values in [0, 255], each value under one label only, coverages in [0, 1] that name declared labels, and colors covering every label. DEFAULT_MASK_SAMPLING is the default {background, tissue} block, and its min_coverage["tissue"] (0.01) is now the only place the tissue threshold is set. (#272)
• resolve_mask_sampling_config(cfg) builds a MaskSamplingConfig from a loaded YAML config. (#272)

Changed (breaking)

• tile_slide(...) and tile_slides(...) now take masks=MaskSamplingConfig(...) (default DEFAULT_MASK_SAMPLING). The sampling=, selection_strategy= and output_mode= arguments are removed, with no alias. (#272)
• TilingConfig.min_coverage and TilingConfig.independent_sampling are removed. Set the tissue threshold via masks.min_coverage["tissue"] and the strategy via masks.strategy. CompatibilitySpec now requires masks. (#272)
• resolve_sampling_request(*, masks) replaces the cfg-based resolvers. resolve_sampling_spec, resolve_sampling_strategy, resolve_output_mode and build_default_sampling_spec are removed. (#272)
• YAML: tiling.independent_sampling: true|false becomes tiling.masks.strategy: independent|joint. Configs that still use the old key fail with a message that names the replacement. (#272)
• output_mode is no longer lowercased, so MERGED is rejected; use merged or per_annotation. (#272)
• Label values are normalized to tuples, so tissue: [1] now counts as the default vocabulary and does binary tissue tiling. Before, it triggered annotation sampling. Through the Python API, the default {background, tissue} vocabulary always means tissue tiling, as it already did in the CLI. (#272)

Migration

# before (6.0.0)
tile_slide(..., tiling=TilingConfig(..., min_coverage=0.05), sampling=spec, output_mode="merged")

# after (6.1.0)
from hs2p import MaskSamplingConfig
masks = MaskSamplingConfig(
    pixel_mapping={"background": (0,), "tissue": (1,)},
    min_coverage={"tissue": 0.05},
    output_mode="merged",
)
tile_slide(..., tiling=TilingConfig(...), masks=masks)