Skip to main content

Core Package Overview

The @spatialdata/core package provides a TypeScript/JavaScript interface for reading and working with SpatialData Zarr stores. It mostly mirrors the Python library's API design while adapting to TypeScript idioms and the asynchronous nature of browser-based data loading. Hot paths (parquet decode) use WASM behind TypeScript interfaces.

Installation​

info

Known risks are tracked in the MDV release checklist.

npm install @spatialdata/core
# or
pnpm add @spatialdata/core

Quick Start​

import { readZarr, loadFeatureRowIndexByFeatureIndex } from '@spatialdata/core';

// Load a SpatialData store from a URL
const sdata = await readZarr('https://example.com/my-spatialdata.zarr');

// View a representation of what's in the store
console.log(sdata.toString());

// Access elements by type
const images = sdata.images;    // Record<string, ImageElement>
const shapes = sdata.shapes;    // Record<string, ShapesElement>
const tables = sdata.tables;    // Record<string, TableElement>
const labels = sdata.labels;    // Record<string, LabelsElement>
const points = sdata.points;    // Record<string, PointsElement>

// Get coordinate systems
const coordinateSystems = sdata.coordinateSystems; // ['global', ...]

// Table-backed shape association (see also @spatialdata/layers encoders)
const shapesEl = sdata.shapes.cell_shapes;
const renderData = await shapesEl.loadRenderData();
const rowIndexByFeatureIndex = await loadFeatureRowIndexByFeatureIndex({
  spatialData: sdata,
  kind: 'shapes',
  key: 'cell_shapes',
  featureIds: renderData.featureIds,
});

Tables load through anndata.js on zarrita stores. Association helpers use targeted obs-column loaders rather than anndata.js; see Element classes.

Design Philosophy​

The library follows several key principles:

  1. Read-only: You can load stores, access elements, query transformations, and load data, but not create or modify stores.

  2. Python API Familiarity: Method and class names mirror the Python spatialdata library where practical, making it easy to translate workflows.

  3. Type Safety: Full TypeScript types with Zod schema validation for metadata, giving you confidence in the data structures.

  4. Lazy Loading of Heavy Data: Data is loaded on-demand rather than all at once, critical for working with large datasets in the browser.

  5. Eager Loading of Metadata: Consolidated metadata from the zarr store is loaded up-front and used to build a representation of the object structure such that it can be programmatically exposed without async leaking where it isn't needed, which can lead to a lot of fiddly state management.

  6. Explicit Error Handling: Uses a Rust-inspired Result type for operations that can fail, allowing you to handle errors gracefully without exceptions.

Public API Surface​

The main entry points for application code are:

ExportPurpose
readZarr(url)Load a SpatialData store from a URL
SpatialDataThe loaded store object with element collections
Element classesImageElement, ShapesElement, LabelsElement, PointsElement, TableElement
Result utilitiesOk, Err, isOk, isErr, unwrap, unwrapOr
getTransformMatrix()Convenience function for getting Matrix4 transforms
Points and shapes loadingPointsElement.loadPoints() / streamPoints(), ShapesElement.loadRenderData(); see Loading points and shapes
Resource ResolverSpatialEntryStore, PointsResolver, ShapesResolver, Resolution, SpatialEntryError, EntryNotice; see Resource Resolver
Table association helpersTableElement.getTableKeys(), SpatialData.getAssociatedTable(s), loadAssociatedTableFeatureRows, loadFeatureRowIndexByFeatureIndex, createFeatureTableAlignment

The table association helpers follow Python spatialdata semantics: regions are matched through region, region_key, and instance_key (when present), with feature ids coming from SpatialElement instances such as GeoDataFrame.index for shapes. getTableKeys() normalizes the attrs contract and treats missing association metadata as "no region links". Visual encoders in @spatialdata/layers consume the row alignment produced here rather than reimplementing association rules.

For internal architecture details, module organization, and APIs intended for contributors or advanced tooling, see Internals & Architecture.

Element Types​

SpatialData stores contain different types of elements:

Spatial Elements​

These have coordinate transformations and can be rendered in shared coordinate systems:

  • Images (ImageElement): Multiscale raster images following OME-NGFF
  • Labels (LabelsElement): Segmentation label images (also OME-NGFF)
  • Shapes (ShapesElement): Vector geometries (polygons, circles)
  • Points (PointsElement): Point cloud data (transcripts, etc.)

Non-Spatial Elements​

  • Tables (TableElement): AnnData tables with region annotations

Next Steps​