How the viewer detects and reads a SpatialData Zarr store. The table is read with the same AnnData code as H5AD, and the image uses the shared OME-Zarr loader described in Image sources. For hosting requirements see Host your own data.
SpatialData is detected in one of two places in detectSpatialDataset
(src/datasets/datasetFactory.ts):
- Zarr-looking URL (path ends in
.zarr,.ome.zarr,/zarr.json, or/.zattrs, or names a group inside a.zarrstore, such assample.zarr/images/he). The URL is reduced to the store root, andzarr.jsonand/or.zattrsare probed withHEAD. This happens before the Xenium probe. - Any other folder URL, after the
experiment.xeniumprobe fails. The samezarr.json/.zattrsprobes run against the folder.
For each metadata file that answered, probeSpatialDataRoot downloads it and
calls isSpatialDataRootMetadata (src/datasets/spatialDataCatalog.ts). A
store is SpatialData when:
spatialdata_attrsis present inattributes(Zarr v3) or at the top level (Zarr v2), and- none of
coordinateTransformations,encoding-type,multiscales, oromeis present. Those keys mark an element, not the root, so a URL pointing at…/images/heloads as a plain OME-Zarr image.
A Zarr store without spatialdata_attrs falls through to the
OME-Zarr image path.
A URL whose path ends in .icechunk is an Icechunk
repository; it is SpatialData when its root group has spatialdata_attrs (see
AnnData in Icechunk for how it is opened).
A URL whose path ends in .zip (usually .zarr.zip) is a zipped store
(detectZarrZip). After a HEAD probe, the zip's central directory is read
by range (openZippedZarrStore, src/zarr/zarrZipStore.ts) and the store
root is the shallowest folder holding zarr.json, .zgroup, .zattrs, or
zmetadata: the top of the zip, or the sample.zarr/ folder that zipping a
store folder keeps. __MACOSX/ is ignored, and a zip with no store or with
two side by side is an error. The store is SpatialData when its root
metadata passes isSpatialDataRootMetadata, or, since some writers (for
example the STHELAR exports) leave root attributes out, when the root holds
images, labels, points, shapes, or tables groups and its attributes
do not mark an image or AnnData. A zip holding any other Zarr store is an
error, since only SpatialData is read from zips.
A dataset manifest with "platform": "spatialdata"
names the store in files.store and skips the metadata check. Its
options (table, coordinateSystem, image, micrometersPerUnit) are the
starting selection: spatialDataSelectionFor returns them until a choice in the info
drawer's View options replaces them.
openSpatialDataStore (src/datasets/spatialDataCatalog.ts) wraps the root in
stores from src/zarr/zarrStores.ts:
- Consolidated metadata is required.
readConsolidatedZarrMetadatafetcheszarr.json(v3,consolidated_metadata),zmetadata, and.zmetadata(v2,zarr_consolidated_format: 1) in parallel and uses the first valid one. Without it the load fails withSpatialDataConsolidatedMetadataError, because the browser cannot list object-store prefixes. An Icechunk repository's snapshot lists every node's metadata, so it stands in for consolidated metadata. - 403 for missing metadata.
createZarrFetchStoretreats403as missing only for metadata keys (.zarray,.zgroup,.zattrs,.zmetadata,zmetadata,zarr.json). Chunk403s are still errors. - Chunk cache.
consolidatedZarrStoreanswers metadata keys from memory and keeps every otherget(matrix chunks, obs arrays, image tiles) in a 256 MiB LRU (CHUNK_CACHE_MAX_BYTES). Range reads (getRange) bypass it. - Zipped stores. For a
.zipURL the base store is zarrita'sZipFileStoreoverCachedHttpRangeReader(src/zarr/cachedZipStore.ts), with keys relative to the store root inside the zip. Each entry is read with two ranges, its local header and its data; ranges up to 8 MiB go through the persistent byte-range cache. Entries stored without compression are read by range; deflated entries are read and inflated whole. The opened zip is returned aszipand kept in a four-entry cache, so detection, the dataset, and diagnostics share one central-directory read; diagnostics check every table, image, and labels chunk and eachshapes.parquetagainst the zip directory instead of with requests. Consolidated metadata is still required.
readSpatialDataCatalog lists every group exactly <kind>/<name> deep, where
kind is images, labels, points, shapes, or tables, and reads each
element's coordinate transforms (src/datasets/spatialDataTransforms.ts).
selectSpatialDataView then chooses what to show:
- Table (
primaryTable): the first table by name whoseregionnames a shapes element, else one that names a labels element, else the first table. Among Visium HD bin tables (named or annotatingsquare_NNNum, as spatialdata-io writes them), only the coarsest bin counts, so a Visium HD store opens onsquare_016umrather than its millions of 2 µm bins. TheTableselect in the info drawer's View options overrides it (sdTablein the shareable URL); one table is read at a time, and the others are listed among the skipped elements.region,region_key, andinstance_keycome fromspatialdata_attrs. - Coordinate system (
bestCoordinateSystem): candidates are ranked by number of the table's region elements placed in the system, then whether it holds an image, then total elements, then whether it is namedglobal, then declaration order. TheCoordinate systemselect in the info drawer's View options overrides it (sdCsin the shareable URL). - Region shapes / labels: region elements placed in that system.
- Image: images placed with an affine that only scales, flips, or swaps
x and y (
axisPermutingAffine); rotated and sheared images are skipped. Off-axis terms under 1e-4 of the scale are dropped first, so STHELAR's H&E, an x/y swap and flip with a 1.9e-5 rad registration turn, is shown. The one with the smallest pixel (highest resolution) wins unless the View optionsImageselect picks another (sdImage). - Boundary candidates: non-region shapes whose name matches
/(?:^|[_-])cell[_-]?(?:boundar|segmentation|polygon)/i, for examplecell_boundaries. - Nucleus candidates: non-region shapes whose name matches
/(?:^|[_-])nucle(?:us|i)[_-]?(?:boundar|segmentation|polygon)/i, for example spatialdata-io's Xeniumnucleus_boundaries. A table that annotates the nuclei itself (STHELAR'stable_nuclei) draws them as its cells instead. - Everything else, including images other than the one shown, is reported
as
skippedElementsin the activity log.
transformationToAffine converts each transform to a 2D affine:
| Type | Notes |
|---|---|
identity |
|
scale |
Uses the x and y axis values |
translation |
Two values are read as (x, y); otherwise trailing (…, y, x) |
affine |
Rows picked by output axes |
mapAxis |
x/y swaps only |
sequence |
Composed in order |
Any other type, or a non-finite value, raises
SpatialDataTransformUnsupportedError and that element is dropped from that
coordinate system.
| Store path | Read by | Library | Used for |
|---|---|---|---|
zarr.json / .zattrs (root) |
probeSpatialDataRoot |
fetch + JSON | Detection |
zarr.json / zmetadata / .zmetadata |
readConsolidatedZarrMetadata |
fetch + JSON | Element discovery |
tables/<table>/obs, var, X, obsm |
AnnDataH5adDataset (readAnnDataZarr) |
zarrita + decode worker (codecs) |
Cells, genes, annotations, embeddings |
shapes/<name>/shapes.parquet |
readSpatialDataShapes (src/datasets/spatialDataShapes.ts) |
hyparquet in a worker (range reads, or zip slices) |
Cell positions, cell and nucleus boundaries |
images/<name>/<level>/… |
openOmeZarrImageWithOptions (src/zarr/omeZarrLoader.ts) |
zarrita |
Morphology layer |
labels/<name>/<level>/… |
SpatialDataLabelsReader (src/datasets/spatialDataLabels.ts) |
zarrita + decode worker |
Cell outlines |
points (transcripts), extra images, and extra tables are not read. Label
chunks in view are decoded and traced into cell outlines in the Zarr decode
worker when you zoom in below Boundary limit.
SpatialDataDataset.readState (src/datasets/spatialDataDataset.ts) creates
an AnnDataH5adDataset with a zarrSource over the consolidated store. The
table's obs, var, X, and obsm follow exactly the
H5AD layout rules: index and gene-name
selection, categorical annotations, dense/CSR/CSC expression, and obsm
embeddings.
Coordinates come from resolveTableCoordinates instead of obsm when the
table annotates regions in the chosen coordinate system:
- Each row's
instance_keyvalue (or obs name) andregion_keyvalue (or the single region) select a shape. The row is placed at the shape's centroid. Tables usually list rows in shape order, so the shape after the last match is tried first; an idMapis built only when that misses (ShapeLookup). - Rows annotating a labels region use their
obsmspatial point mapped through the labels element's affine. - Rows that match nothing get
NaNcoordinates and are hidden. If no row is placed, the load fails. - Without region elements in the chosen system, the H5AD
obsmkey order is used.
The Plots panel reads the table's X as for AnnData over HTTP.
A store without a table says Plots have nothing to read. The Visium example's
CSR table (4,992 spots, 29.7 million stored values) is 227 MiB of values and
indices, so the panel asks before reading it; it downloads 16 MB and plots in
about 7 s.
readSpatialDataShapes reads the whole shapes.parquet with
parquetReadObjects and hyparquet-compressors, in a shapes worker started
by readSpatialDataShapesInWorker (src/datasets/spatialDataShapesWorker.ts).
The worker fetches a plain URL itself. In a zipped store the file is the zip
entry, read on the main thread and handed to the worker slice by slice; a
custom fetcher is handled the same way. Without a Worker, or if the worker
fails to start, the file is read on the main thread.
The shapes come back as transferred columns (SpatialDataShapes): per shape
an instance id, a kind (circle or polygon), centroid, radius, ring area, and
bounds, plus every outer ring in one Float32Array with offsets. The main
thread keeps no object or typed array per shape.
- Geometry column:
geo.primary_column, elsegeometry. hyparquet's GeoJSON decoding is replaced (WKB_PARSERS) so the WKB bytes are read straight into typed rings (Point, Polygon, MultiPolygon; ISO and EWKB, 2D to 4D). GeoJSON-shaped values are still accepted. - Instance ids: the first pandas
index_columnsentry, or aRangeIndexstart/step. - Points become circles with diameter from the
radiuscolumn (default 1) times the affine scale. - Polygons keep only the outer ring of their largest polygon, as interleaved
x, y in the shared ring buffer. A 598,222-cell Xenium
cell_boundaries(about 15 million vertices) holds about 120 MB. - Centroid: area-weighted centroid of the transformed outer ring.
boundaryElement chooses which shapes are drawn as cell boundaries:
- If every region shape is already a polygon, or no boundary candidate exists, the region shapes are drawn (circles as 32-segment polygons).
- Otherwise (for example Xenium
cell_circlesas the region) the first boundary candidate is drawn, matched to cells through the region instance ids. If no id matches, it falls back to the region geometry.
readBoundaryIndex keeps, per cell, the index of its shape in the shape
columns and its bounds in µm; elements(bbox) is a linear bounds filter over
them that builds polygon elements, scaled to µm, only for the cells it
returns, reusing the previous request's elements for cells still in view.
The first nucleus candidate is drawn as the nucleus layer behind the
Nucleus boundaries checkbox, which the Cells section offers only for a
store that has one. segmentationElements('nucleus', bbox) reads the whole
shapes.parquet the first time the checkbox is on, in the shapes worker, and
filters it by bounds like the cell outlines. Nuclei are matched to table
rows through the region shapes that share their index (spatialdata-io indexes
cell_boundaries and nucleus_boundaries by cell id), or by the table's
cell ids when the table annotates labels. A cell's first nucleus keeps its
id and later ones get <id>#nucleus-N, as on Xenium; each matched nucleus
names its cell (segmentation metadata cellId), so hovering it shows the
cell, a click selects it, and the Cell card lists the cell's nuclei in view.
Nuclei that match no row are left out; when none match, every nucleus is
drawn and the log says so. meta().segmentations lists the cell and nucleus
outlines. Cell and nucleus outlines are separate viewport requests, and cell
outlines are read only while Cell boundaries is on, so neither waits for
the other. On STHELAR bone marrow all 225,906 nuclei matched; in one run on
2026-11-17 the cell outlines were drawn 0.1 s after the view opened and the
nuclei 6.8 s later, most of it the 19.4 MB compressed zip entry from
the BioImage Archive.
The chosen image element is opened with openOmeZarrImageWithOptions using
the store and a planar transform from the element's affine. Per-level dataset
scales are kept; the affine supplies the base scale and origin. Extra channels
open as #c=N loaders through openChannelLoader, and other planes of a
z-stack as #z=N loaders.
A flipped or axis-swapped affine (planarTransformFromAffine) gives the
loader the absolute scales and a placement, an ImageFramePlacement in
src/data/coords.ts: a signed axis permutation and translation from the
loader's frame (x along image columns, y along rows) to the coordinate
system. Tiles keep their frame bounds. The morphology canvas
(MorphologyCanvas, the minimap included) selects and caches tiles for the
viewport mapped into the frame (unplaceFrameBbox), snaps each tile's placed
bounds to whole pixels, and draws the tile turned into place about its
centre. The extent uses the placed image bounds. STHELAR's he (37,252 ×
11,024 px) lands landscape over the DAPI morpho image, with nuclei on the
hematoxylin.
Native RGB images (exactly three channels with no omero metadata, or channels
labelled/coloured red, green, blue) keep their 0–255 window: the lifecycle
passes skipNativeRgbAutoContrast and enables all channels. Other images
start with their first six channels on.
- Coordinates are scaled to micrometers by a factor per coordinate system
(
src/datasets/spatialDataUnits.ts): the View optionsµm per unitoverride (sdUm), else the x/y axis unit the elements declare, else an estimate (cell_areaagainst segmentation areas, the Visium 100 µm spot pitch, or Visium HDsquare_NNNumbin names). When none applies the factor is 1 and distances are labelled as units. spatialdata-io stores usually declareunit, for example full-resolution pixels for Visium. extentis the union of the table points' bounding box and the image.capabilities.cellBoundariesis true when there is a table and at least one region shapes or labels element. Boundary loading readsmeta()first, andmeta()treats an image that fails to open as no image, so a broken image does not block outlines; its error is shown by the morphology layer.
useDatasetLifecycle (src/features/app-shell/useDatasetLifecycle.ts):
- Sets the platform to
spatialdata; cell boundaries default to on and nucleus boundaries to off, unless the link says otherwise (nucleusBounds). - Logs
summary(): coordinate system, image, table, skipped elements. - Runs the shared
loadAnnDataOverview(cells, gene panel, annotation sets, embedding options). - If
Morphology imageis enabled, loads the image in the background.
Gating is in SPATIALDATA_PLATFORM_ADAPTER
(src/features/app-shell/platformAdapter.ts): boundaries come from
dataset.elements(bbox) and nuclei from segmentationElements, with the
nucleus checkbox shown only when summary().nuclei names an element
(nucleusBoundaryControlsVisibleFor); transcripts and Magic Lens are off.
| File | Role |
|---|---|
src/datasets/datasetFactory.ts |
Root probes, probeSpatialDataRoot |
src/datasets/spatialDataCatalog.ts |
Root check, store opening, catalog, view and table selection |
src/datasets/spatialDataTransforms.ts |
Transform parsing and affine maths |
src/datasets/spatialDataShapes.ts |
GeoParquet / WKB shapes reader and shape columns, run in a worker by spatialDataShapesWorker.ts (src/workers/) |
src/datasets/spatialDataLabels.ts |
Label outline tracing and caching (spatialDataLabelTrace.ts) |
src/datasets/spatialDataUnits.ts |
µm-per-unit override, declared units, and estimates |
src/datasets/spatialDataDataset.ts |
SpatialDataDataset: coordinates, boundaries, image, delegation to the table |
src/datasets/h5adDataset.ts |
AnnData table reader (readAnnDataZarr) |
src/zarr/zarrStores.ts |
Fetch store, consolidated store, chunk LRU |
src/zarr/zarrZipStore.ts |
Zipped stores: central directory, store root, Parquet entries |
src/zarr/omeZarrLoader.ts |
Image pyramid |
src/data/datasetDiagnostics.ts |
Diagnostics: store, catalog, table chunks, image and labels chunks, drawn shapes.parquet and nucleus shapes |
- An Icechunk repository holds only Zarr arrays and groups, so a SpatialData
store copied into one keeps its images, labels, and tables but not its
shapes and points, which are Parquet files. Copy every Zarr key
(
zarr.jsonand chunk keys) into the repository's store; tested with spatialdata'sblobsexample (labels, image, table). points(transcripts), additional images, and additional tables are not shown. Labels elements are shown only as traced cell outlines, not as a raster layer, and nucleus labels (nucleus_labels) are not traced.pointscould be read by viewport only coarsely. In the 460-plex example (503.5 million transcripts, 8.8 GB in 190 Parquet parts, stored in the zip) every row group carries x/y min/max: parts are x strips 250-1,000 µm wide and row groups are y bands of about a million rows within them. There is no page index, so a 100 µm view still reads 6 row groups (4.7 million rows, 23 MB of x, y, gene, and QV), a 500 µm view 45 MB, and the whole slide 2.35 GB. STHELAR'spoints/stis one deflated zip entry (156 MB) that would be read whole. Checked 2026-11-17 by reading every footer.- Only one coordinate system and one image are shown at a time. They are
chosen automatically; the
Coordinate systemandImageselects in View options override the choice and reload the store. - Only one table is read at a time. Every table is offered in the
Tableselect, including tables that annotate no region (such as STHELAR'sfeatures_*embeddings). Those place rows fromobsmas an H5AD would, so they fail to load whenobsmhas none of the coordinate keys. - Images placed with a rotated or sheared affine are skipped; they are listed only among the skipped elements in the activity log. Flips, x/y swaps, and turns by multiples of 90° are shown, and turns under 1e-4 rad are dropped.
- Labels read only
z = 0, and neither images nor labels have atchoice. Images open onomero.rdefs.defaultZ, else the middle plane, and have theZ planecontrol like other z-stacks. - Polygon holes, and every part of a MultiPolygon but the largest, are dropped.
- Shapes are read whole, not by viewport. spatialdata-io writes
shapes.parquetas one row group with no per-shape bounding boxes (598,222 rows in the 460-plex example), so a range read cannot skip cells out of view. The 97 MB download and decode run in a worker. - A zipped store needs consolidated metadata like any other. Deflated zip
entries are read whole, so a compressed
shapes.parquetis downloaded in full before any of it is parsed. - Over HTTP, diagnostics send a
HEADfor the first 2,000 table chunks and check only the first chunk of the coarsest level of the image and of each labels region. A zipped store has every chunk checked against its directory; image and labels chunks absent only from finer levels pass with a note, as writers such as zarr-python 3 skip empty chunks (304 of 1,148 in the 460-plex image).