nd-embedding-atlas

Explore and annotate n-dimensional (TCZYX) microscopy images with precomputed embeddings. nd-embedding-atlas links embedding space to source images so researchers can review, select, and annotate examples for downstream model training. It does not train models or include model-training code.

nd-embedding-atlas runs locally with linked scatter plots, tables, filters, charts, image viewers, and annotation tools. Your data remains on your machine.

Project status: Active development. APIs, file-format support, and behaviour may change between releases.

Quick start

Install the latest release on macOS with Apple silicon, or on Linux with x64 or arm64:

curl -fsSL https://raw.githubusercontent.com/czbiohub-sf/nd-embedding-atlas/main/scripts/install.sh | sh

Launch an AnnData Zarr store:

ndea view path/to/data.zarr

Open http://localhost:5055 in Chrome or Edge. The scatter renderer requires WebGPU.

For multiple datasets or linked OME-Zarr images, launch a project file:

ndea view project.yaml

settings:
  port: 5055

datasets:
  - name: experiment-a
    path: ./experiment-a.zarr
    plate_path: ./experiment-a-images.zarr

See Install, Launch ndea, and Prepare data for the complete workflow.

What it does

• Links points in precomputed embedding space to their source images.
• Supports image review, selection, and annotation for downstream model-training workflows.
• Streams local AnnData, a supported MuData subset, and mounted OME-Zarr HCS images.
• Uses DuckDB and Mosaic for server-side queries and cross-filtering.
• Renders large scatter plots and selections with WebGPU.
• Opens the fixed annotate preset with linked views for exploration and annotation.

Data compatibility

nd-embedding-atlas implements specific parts of the upstream formats rather than every valid variant.

Input	Current support
AnnData Zarr	Primary tabular and embedding input; obs is required and var is optional
MuData Zarr	axis=0 stores with one-to-one observations across modalities
OME-Zarr	Mounted HCS plates using OME-NGFF 0.4/Zarr v2 or 0.5/Zarr v3
Project YAML	Multiple dataset mounts, image linkage, channel metadata, and launch settings

Read the supported formats reference before preparing production data.

Update and recover

ndea update                       # latest stable release
ndea update --channel pre-release # latest active pre-release
ndea rollback                     # return to the previous installed version
ndea doctor                       # inspect installation health

The installer verifies the release checksum and stores versioned binaries under ~/.ndea/versions/. See the CLI reference for channels, environment variables, completions, garbage collection, and exit codes.

Documentation

• Install
• Launch ndea
• Supported formats
• CLI reference
• WebGPU on HPC
• Contributing

Development

This repository uses Bun and Vite+. The monorepo contains the application and shared packages; docs/ is an independent Fumapress/Waku application.

vp install
vp run dev path/to/data.zarr
vp run -r check
vp run -r test
vp run build

See CONTRIBUTING.md for package-level commands and repository conventions.

Community and security

Ask questions in GitHub Discussions. Report bugs and request features in the issue tracker. Follow the Code of Conduct when participating.

Report vulnerabilities privately according to SECURITY.md; do not open a public issue.

Citation

Citation guidance will be published with the first stable research release.

Licence

nd-embedding-atlas is available under the MIT License. See LICENSE.md.