Files and interoperability

A slide keeps its original image. Derived data lives beside it:

case.svs
case.svs.microscope/
  slide.json
  projects/default/
    annotations.json
    annotations.previous.json
    layers/
      overlays.json
      overlays.previous.json
      assets/<sha256>.npy
      assets/<sha256>.mpoly
      assets/<sha256>.geojson

Project rosters point to slides; project IDs select independent namespaces. The browser and Python use the same files. Annotation V1 and overlay V1 retain their existing contracts. Extended geometry/raster sources use overlay V2; both updated readers accept V1/V2. Old viewers reject V2 rather than silently misinterpret it. See annotation format, overlay V1, and overlay V2.

Assets are immutable and fully byte-hashed; the small index describes source kind, shape/counts, compatible renderer and appearance. Assets commit before the index. Revision conflicts, backups, and single-writer limits are shared between Python and the browser. Removing layers retains their files. Existing V1 sources may coexist in a V2 index. Associated images/WSI bytes are not embedded in generated layers.

This is local storage interoperability, not a streaming server or geographic tile service. Limits, float precision, and topology expectations are documented in the layer guide.

Sparse raster extension (overlay manifest version 3)

An ordinary raster source may contain chunks (1–1024). Each chunk has mode, level-0 bounds, shape, content-addressed NPY path/hash and byte length. Its ordinary source fields anchor the first chunk, which is also included in chunks. Core rectangles must not overlap; assets total at most 128 MiB per slide. Masks use |u1, probabilities <f4, and labels <u4 (lossless uint32). Existing v1/v2 manifests remain supported.

Use slide.layers.read_raster_chunks(id) to iterate (source, shape, values) and array_paths(id) to locate assets. read_array/array_path reject sparse layers rather than silently returning a first core. Static rendering samples chunk fields into the bounded output image; appearance saves validate/retain all cores. No full-slide dense allocation is required. Viewer currently loads bounded chunk assets on reconnect and draws a deck.gl composite; true out-of-core visible-chunk loading is future work.