Browser-based explorer for hosted spatial-omics and image data. The app loads
10x Xenium and Atera output folders, standard Visium (55 µm spots) and Visium
HD Space Ranger output folders, Vizgen MERSCOPE region folders, AnnData
.h5ad files and AnnData Zarr stores (including Visium AnnData with
uns/spatial), SpatialData Zarr stores, and image-only
OME-TIFF/TIFF/QPTIFF/SVS/NDPI/OME-Zarr URLs from object storage, and dataset
collections that list several of them to browse together.
It renders spatial cells, spots, bins, image pyramids, morphology channels, expression
overlays, transcript density/exact overlays, annotations, ROI queries,
shareable view state, and dataset diagnostics without a server-side data
service. Browse Store and Browse File show what a Zarr store or Parquet
file holds without opening it as a dataset.
The implementation is a Vite + React application. It uses deck.gl for spatial rendering, DuckDB WASM and Hyparquet for browser-side Parquet queries, GeoTIFF, OME-Zarr, and JPEG2000 decoding for image tiles, and Zarr/HDF5 readers for cell-feature matrices, Feature Slice H5, H5AD, and native transcript LOD access.
npm ci
npm run devUseful development commands:
npm run typecheck
npm run lint
npm run test
npm run build
npm run previewnpm run test:coverage runs the unit tests with V8 coverage, writes an HTML
report to coverage/, and fails below the thresholds in vitest.config.ts. CI
runs it on every pull request in a separate job that reports but does not block;
npm test is the required check.
End-to-end tests use the built app through Vite preview:
npm run build
npm run test:e2eOne smoke test runs the axe accessibility rules (WCAG 2.2 A and AA) on the
layer sections, the info drawer, the dataset menu, Help, Settings and the
Embedding panel, empty and with a fixture loaded. Known violations are
listed in tests/e2e/axe-baseline.json, and any other violation fails the
test. When you fix one, the test fails until you remove it from the list; to
rewrite the list, run:
UPDATE_AXE_BASELINE=1 npx playwright test --grep "axe baseline"The Vite dev and preview servers are configured with cross-origin isolation headers needed by the browser-side WASM and decoding paths.
To measure main-thread work and load times, or to serve datasets locally with byte ranges, see Profiling.
To cut a release, open Releases > Draft a new release, create a new vX.Y.Z
tag on main, generate the release notes, and publish. The
Release workflow then type-checks the tag,
runs the unit and E2E smoke tests, builds the app, and attaches it to the
release as explorer-<tag>.zip. Pre-releases get a zip too. To retry, or to
attach a zip to an older release, run the workflow manually with the tag.
The zip holds one explorer-<tag>/ folder with index.html, assets/,
LICENSE, and a version.json that records the tag and commit. Asset paths are relative, so
the folder works when served from a domain root or any subpath. It has to be
served over HTTP; opening index.html from disk does not work. See
Deploy to S3 for hosting it.
src/App.tsxcoordinates dataset loading, controls, diagnostics, URL hash state, ROI workflows, and the viewer shell.src/components/contains the spatial viewer, morphology canvas, error boundary, and viewer model helpers.src/data/contains browser data access for Parquet, Zarr, HDF5, analysis outputs, annotations, ROI queries, diagnostics, range checks, telemetry, and shareable state.src/datasets/defines the spatial dataset interface and platform implementations for Xenium, Atera, standard Visium, Visium HD, MERSCOPE, H5AD, SpatialData, and image-only sources.src/features/contains domain UI and workflow modules for the app shell, genes, transcripts, annotations, ROI, morphology, cells, diagnostics, dataset collections, the store and file browser, and platform-specific behaviour.src/rendering/contains deck.gl layer creation, styling, aggregation, viewport logic, opacity handling, and morphology canvas helpers.src/tiff/,src/codecs/,src/zarr/, andsrc/workers/handle tiled OME-TIFF and OME-Zarr loading, JPEG2000 decoding, byte-range chunk access, tile caching, and worker-backed decode concurrency.tests/e2e/contains Playwright coverage; colocated*.test.tsand*.test.tsxfiles cover the data, rendering, component, and store modules.
Enter a source in the Dataset or image URL field:
- Xenium: output folder with
experiment.xenium,cells.parquet, and a readablecell_feature_matrix.zarr.ziporcell_feature_matrix.h5. - Atera: Atera Onboard Analysis output folder with
experiment.spatial,cell_feature_matrix.zarr.zip,csc_cell_feature_matrix.zarr.zip, andcells.zarr.zip, plus themorphology_2d/OME-TIFFs for the image. - Standard Visium (v1/v2, 55 µm spots): Space Ranger
outs/folder withspatial/tissue_positions.csv(or the 1.xtissue_positions_list.csv),spatial/scalefactors_json.json, andfiltered_feature_bc_matrix.h5, plus the hires or lowres tissue PNG; or a.h5adwith the scanpy/CELLxGENEuns/spatial/<library>layout. A dataset manifest loads GEO samples, whose files are renamed and gzipped, in place. - MERSCOPE: Vizgen region folder with
cell_by_gene.csvandcell_metadata.csv(each read whole, up to 300 MB), pluscell_boundaries.parquetfor cell outlines, and the run's.vzgfor the image (one stain and z plane at a time). A dataset manifest loads vpt re-segmentations and GEO deposits in place. Transcripts are not read. - Visium HD: Space Ranger
outs/folder with at least onebinned_outputs/square_*umtier containing positions, scalefactors, and a filtered feature-barcode matrix, plus rootfeature_slice.h5for gene overlays. - H5AD: direct
.h5adfile URL withobs,var,/X, and a supported 2Dobsmcoordinate matrix. Files over 64 MiB are read by range, without a.h5ad.jsonreference or.h5ad.icechunkrepository; one next to the file is read only when it is over 300 MiB and cannot be read by range. An AnnData Zarr store (v2 or v3, asadata.write_zarrwrites it) needs neither, as it is read chunk by chunk; its root metadata must sayencoding-type: anndata. - SpatialData: Zarr store root (v2 or v3) with consolidated metadata, an AnnData
table annotating a shapes or labels element, and optionally image elements;
or the same store zipped as one
.zarr.zipfile. - Image-only: direct OME-TIFF, TIFF, QPTIFF, SVS (Aperio H&E), NDPI (Hamamatsu), or OME-Zarr URL. NDPI files over 4 GB are not read.
- Icechunk: a
.icechunkrepository URL holding AnnData, SpatialData (images, labels, and tables), or an OME-Zarr image.
Files do not have to keep these names. A dataset manifest, explorer.json in
the dataset folder (or any .json URL entered directly), can name the
platform, point to renamed or moved files, and set the genes, layers, and image
channels shown on first load. See Dataset manifest.
A dataset collection is a JSON file that lists datasets to browse together,
such as the sections of one study. Open it with ?collection=<url> in the
viewer's address: a bar under the canvas lists its datasets with previews of
their cells, and choosing one opens it with the same genes and cell
colouring. Sections registered to each other can be shown side by side with
one view. See Dataset collections.
Because data is read directly by the browser, hosted datasets must support CORS
and HTTP byte-range requests for large binary assets. The in-app
Diagnose Dataset action checks the detected platform and the key assets for
the active source.
When the address is a Zarr store (a .zarr folder or a group inside one, a
zipped store, or an Icechunk repository), Browse Store next to
Load Dataset lists its groups and arrays with their shapes, data types,
chunking, codecs and attributes. For a Parquet file, Browse File shows
its schema, row groups, metadata and first rows, read from the footer and the
first pages. Neither loads the dataset, so both work for stores and files the
viewer cannot open.
examples/ lists public datasets from data repositories
(BioImage Archive, CELLxGENE, IDR, and others) with links that open them in
the hosted viewer. Each is a dataset manifest pointing at the repository's own
files; add one with npm run examples to refresh the list. The viewer's start
screen reads the same list from main at runtime, so a new example appears
there without a release.
The full index is in docs/README.md.
- User guide: loading supported sources, navigation, layers, genes, transcript overlays, annotations, ROI tools, embeddings, diagnostics, and shareable URLs.
- UI reference: every panel, control, default, viewer interaction, and shareable URL parameter, with platform availability.
- Architecture: detection order, load pipeline, platform gating, coordinates, caching, workers, and error handling.
- Modality read paths: Xenium, Atera, standard Visium, Visium HD, MERSCOPE, H5AD, SpatialData, and image sources. Each lists the files read, the libraries used, the source modules involved, and known limitations.
- Deploy the React app to S3-compatible object storage: download a release zip or build the Vite app, upload it to AWS S3 or Ceph RGW-style storage, configure edge headers, and validate production.
- Host your own data: required and optional files for Xenium, Atera, standard Visium, Visium HD, MERSCOPE, H5AD, SpatialData, and image-only sources, plus HTTP requirements, serving data from your own computer, and quick validation commands.
- Dataset manifest: the optional
explorer.jsonthat maps renamed files and sets first-load display defaults, with a JSON Schema inpublic/schemas/. - Dataset collections: a JSON file listing
datasets to browse together, opened with
?collection=, with previews and registered sections side by side. - Image-only and GeoJSON annotations: direct image URL support, platform gating, and GeoJSON shape import/export rules.
- TIFF tile-offset sidecars: the optional
.zchunkstorenext to a pyramidal OME-TIFF, and how to generate one. - Large H5AD files: how large H5AD files are read
by range, and the optional
.h5ad.jsonkerchunk reference or.h5ad.icechunkrepository, and how to generate one. - S3/CORS hosting playbook: exact CORS headers, object serving rules, byte-range validation, and CDN considerations.
- Cell-feature matrix compatibility: the key decision to prefer native CSC Zarr for fast ROI gene statistics and fall back to HDF5 for older Xenium output, instead of generating custom cell-major sidecars.
- Visium HD 2 µm strategy: why 2 µm first
paint uses filtered matrix barcodes and a derived affine grid instead of the
full
tissue_positions.parquet. - Plan: the build plan, with each phase's status. Phase records,
architecture decisions, refactor history, and open items are in
docs/plan/.
MIT. Copyright (c) 2026 Genome Research Ltd.