Visualization packages

This document describes how @spatialdata/vis fits into the wider visualization story and how we plan to split responsibilities across packages.

Today: @spatialdata/vis

2D only — no 3D orbit/volume rendering yet (see SpatialCanvas status).

• SpatialCanvas — Main React surface: coordinate system, layer toggles, pan/zoom, OME-Zarr images (Viv) with labels, shapes and points (deck.gl).
• SpatialCanvasViewer — The same render path as a headless, controlled component (guide).
• ImageView — Deprecated; use SpatialCanvas with an image layer. Removal is tracked in #215.
• Sketch / demo app — Prototyping and docs examples.

Dependencies include @hms-dbmi/viv, deck.gl, @spatialdata/avivatorish, @spatialdata/layers, and @spatialdata/core / @spatialdata/react.

See SpatialCanvas + images — status and roadmap. For the current boundary between demo UI behaviour and reusable feature/table semantics, see Feature table associations and annotation columns.

@spatialdata/layers

• SpatialLayer CompositeLayer and versioned SpatialLayerProps (Zod + schemaVersion + migrateSpatialLayerProps).
• The canonical home for RenderStack saved/render order, including SpatialData entries, host overlay descriptors, and reserved group entries.
• Deck renderers for shapes, labels and points. SpatialLayer itself renders shapes sublayers only; vis composes the rest.
• No MobX; plain TypeScript and deck APIs.

Details: Layers package overview.

@spatialdata/avivatorish

• Viv-centric loaders (createLoader, loadOmeZarrMultiscalesData), channel statistics, and Zustand stores (Avivator lineage).
• Intended for MDV and others to replace duplicated avivatorish code.
• Deck composition stays in @spatialdata/layers / @spatialdata/vis; this package focuses on loaders + channel state.

@spatialdata/core

• Semantic SpatialData-on-Zarr: elements, transforms, tables, metadata, and the renderer-agnostic Resource Resolver that vis consumes.
• Not responsible for GPU buffer layouts; layers owns those.

API tiers (summary)

Tier	Typical use
RenderStack / Deck / SpatialLayer	Non-React or custom DeckGL apps; ordered stack, host overlay descriptors, versioned props
Headless avivatorish	Loaders, cache, getSingleSelectionStats
Zustand + VivProvider	MDV-style embeds
SpatialCanvas	Batteries-included SpatialData React UI

For MDV-specific migration notes, see MDV integration.