slide2vec 5.6.0

Live dense encoding after augmentation

Model.prepare_dense_encoder now returns a shareable DenseEncodeKit for training and inference loops that already own paired reading and augmentation. Its pickle-safe item preprocessor accepts one CPU RGB uint8 (3, H, W) tensor and returns the normalized, bottom/right-padded (3, Henc, Wenc) tensor. encode accepts the collated CPU batch and returns an on-device (B, D, Gh, Gw) grid with the frozen encoder in evaluation/no-grad/autocast mode and the resolved output dtype.

The immutable geometry records target, patch, encoded and grid sizes, padding, and the top-left crop box. Whole/sliding patch features and CLS attention use the same implementation as persisted dense extraction. This live path performs no source reading, caching, persistence, sidecar, artifact, or output-directory work. DenseImageOptions and DenseOptions are both accepted; their spacing, backend, and tolerance fields are outside the augmented-pixel handoff and therefore ignored.

Dense-image migration

soma can replace its private dense image reader and extraction loop with Model.embed_images_dense. Keep the encoder, reader backend, batch size, precision, output dtype, inputs, dense options, and model output variant fixed while validating the migration. PNG/JPEG sources use hs2p 4.4.1’s one-level PIL reader: exact-spacing reads preserve Pillow RGB pixels, while coarser requests may area-downsample. Pyramidal sources use the same parent-resolved hs2p contract. Finer image requests remain forbidden.

Both ImageSpec and SlideRegions accept the optional finite positive spacing_at_level_0 caller declaration. Dense image and region sidecars keep that declaration distinct from resolved source_spacing_um, requested declared_spacing_um, and encoded-grid effective_spacing_um. Those values and the full resolved read plan participate in resume compatibility.

One-GPU and multi-GPU extraction preserve input order, artifact shapes and dtypes, metadata, and finite outputs. Corresponding grids are compared in float32 and must reach cosine similarity of at least 0.9999. Cross-GPU bit identity is not part of the contract.

Resume and provenance boundary

Resume trusts only a compatible artifact: both payload and sidecar must exist, and the sidecar must match the normalized source identity and complete extraction recipe. The recipe includes the encoder/output, reader regime, declared and effective spacing, resolved backend and read plan, target size, padding/window/attention settings, precision, and stored dtype. GPU count, batch size, worker count, prefetching, and output directory are execution mechanics and do not change compatibility.

Legacy or incomplete dense-image sidecars remain readable as files but are not resume proof; slide2vec recomputes them. Artifacts written with hs2p 4.3 remain loadable, while resume and read_coordinates_from still validate provenance. Because hs2p 4.4 changed auto backend priority to cucim → vips → openslide → asap, an older artifact may resolve to a different decoder and be rejected or recomputed. Pin the original explicit backend when reuse across that boundary is required.

Scope

This release does not add supervision-mask I/O, spacing-aware Model.embed_images, per-image requested spacing, fit-to-target resize, upsampling, a new backend priority, source hashing, heterogeneous target sizes, or cross-GPU bit identity.