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 should make use of WASM with safe and ergonomic TypeScript interfaces where appropriate.

The bundle should be tree-shakeable and avoid loading heavy dependencies before they are needed (please raise an issue if this is found not to be the case - it's not something that's been given much attention in the initial implementation).

Installation​

:::info alpha prerelease

The first npm line is an MDV-targeted alpha prerelease. Install from the next tag until the public API is declared stable.

You're more than welcome to clone the git repo and do what you will with it.

Known risks and release-readiness notes 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 today use targeted obs-column loaders; the roadmap is a unified AnnData.js / zarrita DataLoader surface for richer obs / var / X / obsm access (see MDV integration — tables).

Design Philosophy​

The library follows several key principles:

  1. Read-Only (for now): The current API is focused on reading and representing SpatialData stores as essentially immutable. You can load stores, access elements, query transformations, and load data—but not create or modify stores. Write operations may be added in a future revision.

  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
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​