@jax-data-science/sci-image-visualizer 0.3.3 → 0.4.0

package/index.d.ts

@@ -11,6 +11,8 @@ export * from './lib/contracts/ports/image-state.port';
 export * from './lib/contracts/ports/tile-access.port';
 export * from './lib/contracts/ports/region-io.port';
 export * from './lib/contracts/ports/preferences.port';
+export * from './lib/contracts/ports/spatial-data.port';
+export * from './lib/contracts/spatial-dataset.contract';
 export * from './lib/contracts/channel-histogram-api.contract';
 export * from './lib/contracts/viz-config';
 export * from './lib/contracts/image.contract';
@@ -23,6 +25,14 @@ export * from './lib/contracts/display-types';
 export * from './lib/contracts/sam.contract';
 export * from './lib/contracts/cell-segmenter.contract';
 export { CellposeSegmenterService } from './lib/toolbar/segmentation/cellpose-segmenter.service';
+export { SpatialDataHttpService, SupersededError } from './lib/implementations/spatial-data-http/spatial-data-http.service';
+export { SPATIAL_WIRE_VERSION, isLittleEndian, assertManifestVersion, datasetFromManifest, decodeCoords, decodeRadius, decodeColumn, decodeFeatureVector, decodePolygons, } from './lib/implementations/spatial-data-http/spatial-wire';
+export type { SpatialManifest, SpatialDatasetSummary, SpatialRadiusSpec, } from './lib/implementations/spatial-data-http/spatial-wire';
+export { encodeCategorical, encodeContinuous, resolveCategoryColors, contrastWindow, markerDiameters, toRgbaTuples, lutFor, DEFAULT_CATEGORICAL_PALETTE, DEFAULT_MUTED_OPACITY, MISSING_COLOR, } from './lib/spatial/spatial-encoding';
+export type { RGBA, CategoricalEncodingOptions, ContinuousEncodingOptions, } from './lib/spatial/spatial-encoding';
+export { selectInRegions, selectByCategory, mutedFromSelection, pointInRing, emptySelection, countMask, maskToIndices, } from './lib/spatial/spatial-selection';
+export type { SpatialSelectionMask } from './lib/spatial/spatial-selection';
+export { SpatialSelectionStore } from './lib/store/spatial-selection.service';
 export * from './lib/contracts/instance-segmenter.contract';
 export * from './lib/contracts/semantic-segmenter.contract';
 export { ProcessingImage } from './lib/processing/processing-image';
@@ -40,3 +50,8 @@ export { VisualizerComponent } from './lib/visualizer.component';
 export { RegionEditorComponent } from './lib/region-editor/region-editor.component';
 export { HexColorPickerComponent } from './lib/hex-color-picker/hex-color-picker.component';
 export { ChannelHistogramComponent } from './lib/channel-histogram/channel-histogram.component';
+export { SpatialControlsComponent, } from './lib/spatial-controls/spatial-controls.component';
+export type { SpatialLegendEntry } from './lib/spatial-controls/spatial-controls.component';
+export { SpatialChartsComponent } from './lib/spatial-controls/spatial-charts/spatial-charts.component';
+export { buildOmicsTraces, omicsLayout, benefitsFromGrouping, } from './lib/implementations/plotly/omics-trace-builders';
+export type { OmicsChartKind, OmicsGrouping, OmicsTraceInput, } from './lib/implementations/plotly/omics-trace-builders';

package/lib/contracts/display-types.d.ts

@@ -39,3 +39,134 @@ export interface IBrushOptions {
     /** Brush diameter in matrix (image) pixels. */
     size?: number;
 }
+/** What drives point colour in the spatial-omics mode: an annotation column
+ *  from the dataset, or one feature (gene) vector fetched on demand. */
+export interface SpatialColorBy {
+    kind: 'column' | 'feature';
+    name: string;
+}
+/** Display state for the spatial-omics plot mode. Lives in `VisualizerStore`
+ *  alongside the colormap/channel state so the renderer reacts to edits the
+ *  same way it does for an image. */
+export interface SpatialViewState {
+    /** Colour source; `null` renders every observation in one neutral colour
+     *  (useful on its own — it shows where the tissue actually is). */
+    colorBy: SpatialColorBy | null;
+    /** Multiplier on the dataset's physical marker size. 1 = true size, which for
+     *  a 55 µm Visium spot is correct but can be invisible when zoomed out. */
+    pointScale: number;
+    /** Alpha for points that are not muted. */
+    opacity: number;
+    /** Log-scale continuous values before mapping them onto the colormap. Seeded
+     *  from the column's `logScaleHint` — count data needs it. */
+    logScale: boolean;
+    /** Percentile clip for the contrast window as `[lo, hi]` fractions, so a
+     *  handful of saturated observations don't flatten the rest. */
+    percentileClip: [number, number];
+    /**
+     * Colormap for CONTINUOUS spatial colouring — a gene, a numeric column — as a
+     * {@link ColormapValue}, the same shape the display colormap carries: a scale
+     * NAME for the built-ins, or an inline `[stop, colour]` array for the rest.
+     * Null follows the display colormap.
+     *
+     * Its own setting because the display colormap belongs to the tissue image and
+     * is usually a grey ramp, which is the wrong thing to read a measurement
+     * through: grey over grey cannot be told apart from the anatomy. Following it
+     * (with a Viridis fallback for exactly that case) is a reasonable default and a
+     * poor ceiling, since which gradient reads best is a judgement about the data.
+     *
+     * One setting for the markers, the 2D gene map and the 3D gene map together, so
+     * the field under the cells and the cells over it cannot disagree about what a
+     * colour means — and the panel's own colour bar is built from it too.
+     */
+    continuousColormap: ColormapValue | null;
+    /**
+     * What the 3D scene draws. The three things in it — the reference volume, the
+     * observation cloud and the cluster density volumes — occupy the same space, so
+     * any two of them hide each other to some degree. These are independent because
+     * the useful views are the combinations: the volumes alone to read an estimated
+     * distribution, one section's cells over them to check that estimate against the
+     * measurement, the anatomy alone to find a landmark.
+     *
+     * Visibility only — the layers stay built, so toggling one back on is immediate
+     * and does not re-run a rasterisation. {@link densityVolume} is the exception and
+     * genuinely gates construction, because building six volumes is not free.
+     */
+    showVolume: boolean;
+    /**
+     * The reference volume's opacity.
+     *
+     * Its own, not {@link opacity} (which belongs to the markers): the volume is a
+     * BACKDROP, and reading the cloud or a density field through it means turning
+     * the anatomy down without touching the data drawn over it. Ranges lower than
+     * the markers' slider for the same reason — a faint anatomical hint is a useful
+     * setting for a backdrop and a useless one for the measurement.
+     */
+    volumeOpacity: number;
+    /** Draw the observation cloud (3D). */
+    showPoints: boolean;
+    /**
+     * Restrict the cloud to ONE imaged section, by index into the dataset's sampled
+     * sections; null draws every section.
+     *
+     * The whole cloud is a stack of discs that hides whatever is drawn between them.
+     * One section at a time is the view that answers "does the estimated field
+     * actually follow the cells I measured" — and it is only offered for data that
+     * really is sectioned (see `sampledSections`).
+     */
+    pointSection: number | null;
+    /**
+     * Draw each cluster as a translucent DENSITY volume alongside the 3D cloud.
+     *
+     * Serial sections hundreds of microns apart make a cloud hard to read as an
+     * anatomical distribution — the eye cannot integrate discs into a shape. A
+     * density field can be estimated between the imaged planes (a continuous
+     * estimate, unlike individual cells, which have no correspondence to
+     * interpolate along) and renders as a cloud that reads as an estimate.
+     */
+    densityVolume: boolean;
+    /** Multiplier on the default kernel bandwidth. Above 1 is smoother and less
+     *  committal; below 1 exposes the individual sections. */
+    densitySmoothing: number;
+    /**
+     * Draw the active GENE as a continuous field under the observations (2D).
+     *
+     * Colouring the markers by a gene says which cells express it; it cannot say
+     * where, because the eye will not integrate thousands of dots into a territory.
+     * The field is an estimate — a kernel-weighted mean per cell, transparent where
+     * no cell was measured — and it is drawn beneath the cells, not instead of them,
+     * so the measurement stays on screen next to the interpolation.
+     *
+     * Ignored unless the colour source is a gene: there is nothing else to map.
+     */
+    geneMap: boolean;
+    /**
+     * Restrict the 3D gene map to ONE imaged section, by index into the dataset's
+     * sampled sections; null draws every section's sheet.
+     *
+     * Separate from {@link pointSection} so the combinations stay open: all the
+     * sheets with one section's cells over them is a useful view, and so is one
+     * sheet inside the whole cloud. Ignored while {@link geneMapVolume} is set —
+     * interpolating a single section along z would smear one slide through the
+     * specimen's whole depth and call it an estimate.
+     */
+    geneMapSection: number | null;
+    /**
+     * Smooth the per-section gene maps along z into a continuous VOLUME (3D).
+     *
+     * The sheets are what was measured — one field per imaged slide, with the gaps
+     * between them empty. This turns them into an estimate defined between the
+     * slides, the same move the cluster density volumes make and with the same
+     * caveat: a field may be interpolated between sections, individual cells may
+     * not, and the result is drawn as a translucent cloud so it cannot be mistaken
+     * for measurement.
+     */
+    geneMapVolume: boolean;
+    /** Multiplier on the gene map's kernel bandwidth. */
+    geneMapSmoothing: number;
+    /** The gene map's own opacity. Separate from {@link opacity}, which belongs to
+     *  the markers: turning the cells down to read the field underneath must not
+     *  turn the field down with them. */
+    geneMapOpacity: number;
+}
+export declare const DEFAULT_SPATIAL_VIEW: SpatialViewState;

package/lib/contracts/image.contract.d.ts

@@ -31,6 +31,13 @@ export interface IImageMetadata {
     /** Physical pixel size in µm; null/undefined when the format reports none. */
     mppX?: number | null;
     mppY?: number | null;
+    /** Physical spacing BETWEEN slices in µm — the z counterpart of `mppX`/`mppY`,
+     *  for a stack that knows it (a resampled volume, a confocal stack). It is what
+     *  lets the 3D volume view render true anisotropy: with all three present the
+     *  world box is the image's real physical extent, so 40 x 40 x 200 µm voxels
+     *  read as a brain and not as a cube-aspect brick. Absent, the view falls back
+     *  to its resolution-invariant reference box, which is shape-only. */
+    mppZ?: number | null;
     /** Per-channel name/color/LUT for multichannel (non-RGB) images, when known. */
     channelInfo?: IChannelInfo[] | null;
 }

package/lib/contracts/plot-type.d.ts

@@ -31,7 +31,16 @@ export declare enum PlotType {
     /** WebGPU 2D scatter of region centroids (napari-js analog of Plotly SCATTER). */
     NAPARI_SCATTER = "napari-scatter",
     /** WebGPU 3D scatter of the downsampled voxel cloud (napari-js analog of Plotly SCATTER3D). */
-    NAPARI_SCATTER3D = "napari-scatter3d"
+    NAPARI_SCATTER3D = "napari-scatter3d",
+    /** Spatial-omics observations (Visium spots, segmented cells) drawn over the tissue image and
+     *  coloured by an annotation column or a gene. Needs a `SpatialDataset` on `SPATIAL_DATA_PORT`,
+     *  so it is gated by `requiresSpatialData` and never appears for an image-only host. */
+    SPATIAL_OMICS = "spatial-omics",
+    /** Spatial-omics observations as a 3D point cloud, for assays whose observations carry a z —
+     *  serial sections registered into a common frame (e.g. the Allen CCF), or a genuinely
+     *  volumetric assay. Gated by `requiresSpatial3d`, a strictly narrower gate than
+     *  {@link SPATIAL_OMICS}: a single-plane dataset has no z to render. */
+    SPATIAL_OMICS_3D = "spatial-omics-3d"
 }
 /** How many spatial dimensions a plot type renders in. */
 export type PlotDimensions = '2d' | '3d';
@@ -39,8 +48,11 @@ export type PlotDimensions = '2d' | '3d';
  * Where a plot type pulls its data from:
  *  - `image`   — the loaded pixel matrices / z-stack (HEATMAP, SURFACE, …)
  *  - `regions` — the drawn/derived regions (SCATTER of region centroids, …)
+ *  - `spatial` — a `SpatialDataset` supplied through `SPATIAL_DATA_PORT`: N
+ *    observations (spots/cells) with categorical + continuous columns and a
+ *    lazily-fetched feature matrix, drawn over the tissue image they came from.
  */
-export type PlotDataSource = 'image' | 'regions';
+export type PlotDataSource = 'image' | 'regions' | 'spatial';
 /**
  * Backend-neutral metadata about a plot type. Drives UI affordances (which
  * types are 3D, which need an image stack, how to label them in a dropdown)
@@ -75,6 +87,17 @@ export interface PlotTypeDescriptor {
      *  surface, intensity profile, isosurface) — only meaningful for grayscale.
      *  Image/Heatmap render RGB fine; Scatter uses regions. */
     requiresGrayscale?: boolean;
+    /** True when the type renders a `SpatialDataset` (`source: 'spatial'`) and is
+     *  therefore meaningless without one. The selector hides it until a dataset is
+     *  published on `SPATIAL_DATA_PORT` — the same shape of gate as
+     *  {@link requiresStack} for a z-stack, so a host with no spatial data never
+     *  sees the mode. */
+    requiresSpatialData?: boolean;
+    /** True when the type needs observations with a z coordinate, not merely a
+     *  `SpatialDataset`. Narrower than {@link requiresSpatialData}: most spatial
+     *  assays are a single plane, so this hides the 3D mode unless the published
+     *  dataset actually carries `observations.z`. */
+    requiresSpatial3d?: boolean;
 }
 /**
  * Single source of truth for plot-type metadata. LINE is intentionally absent —
@@ -95,6 +118,23 @@ export declare function isNapariSurface(type: PlotType): boolean;
 export declare function isNapariScatter(type: PlotType): boolean;
 /** napari-js 3D scatter (voxel point cloud). */
 export declare function isNapariScatter3d(type: PlotType): boolean;
+/** Spatial-omics observations over the tissue image. */
+export declare function isSpatialOmics(type: PlotType): boolean;
+/** Spatial-omics observations as a 3D point cloud. */
+export declare function isSpatialOmics3d(type: PlotType): boolean;
+/**
+ * Whether the renderer, rather than the shell, should handle wheel zoom.
+ *
+ * The shell's wheel listener applies a FIXED step per event, which is far too sensitive for a
+ * renderer that reads the scroll delta: it works out at 30% per event against napari-js's 3%, and
+ * ignores the device normalization and easing the renderer does. So every plot type drawn by a
+ * renderer that owns the wheel has to opt out here.
+ *
+ * The image view always did. The spatial-omics modes did NOT, despite being drawn by the same
+ * napari-js viewer — the shell gated on an `isHeatmap` flag that defaults to true and only goes
+ * false for the 3D Plotly scenes, so it silently took the wheel for them too.
+ */
+export declare function rendererOwnsWheel(type: PlotType): boolean;
 /** Any napari-js 3D plot type (volume, isosurface, surface, or 3D scatter). Resolution is a runtime
  *  decimate factor (Full / ½ / ¼ / ⅛) — see the service's `resolutionScale`. */
 export declare function isNapari3d(type: PlotType): boolean;

package/lib/contracts/ports/spatial-data.port.d.ts

@@ -0,0 +1,90 @@
+import { InjectionToken } from '@angular/core';
+import { Observable } from 'rxjs';
+import { SpatialColumn, SpatialDataset, SpatialEmbedding, SpatialPolygons } from '../spatial-dataset.contract';
+/**
+ * Spatial-omics data access, inverted as a port so the visualization library
+ * never learns how the data is stored or served — exactly like
+ * `TILE_ACCESS_PORT` for tiles and `REGION_IO_PORT` for annotations. The host
+ * supplies an adapter; the library consumes typed arrays.
+ *
+ * WHY A PORT AND NOT A READER
+ * ---------------------------
+ * The interchange format for this data (SpatialData Zarr v3 + AnnData
+ * conventions + GeoParquet shapes) needs three parsers, and its expression
+ * matrix is stored observation-major — so reading a single gene's column means
+ * touching every row. A server can pre-index that once; a browser cannot. So
+ * the library takes vectors it can render and leaves ingest to whoever owns the
+ * data. `SpatialDataHttpService` is a ready-made adapter for the wire format
+ * the bundled example server speaks; a host with its own backend implements
+ * this interface instead.
+ *
+ * LAZINESS IS THE POINT
+ * ---------------------
+ * `getDataset$()` yields only what is cheap to hold: coordinates plus column
+ * and feature *metadata*. Every accessor below fetches one vector at a time,
+ * for the one column or gene currently being displayed.
+ */
+export interface SpatialDataPort {
+    /**
+     * The dataset currently being visualized, or null when none is selected.
+     * Emits again when the host switches datasets, so the view can rebuild.
+     */
+    getDataset$(): Observable<SpatialDataset | null>;
+    /**
+     * Values for one annotation column, index-aligned with the observations.
+     * The column must be one advertised in `SpatialDataset.columns`; reject
+     * (don't resolve empty) when it isn't, so a typo surfaces instead of
+     * rendering as "no data".
+     *
+     * Implementations should cache — colouring by cluster, then by a gene, then
+     * back by cluster must not refetch.
+     */
+    getColumn(name: string): Promise<SpatialColumn>;
+    /**
+     * One feature's (gene's) expression vector, index-aligned with the
+     * observations. Rejects for an unknown feature.
+     */
+    getFeatureVector(name: string): Promise<Float32Array>;
+    /**
+     * One embedding's coordinates, index-aligned with the observations.
+     *
+     * The name must be one advertised in `SpatialDataset.embeddings`; rejects otherwise, for the
+     * same reason `getColumn` does — a typo should surface rather than render as an empty plot.
+     *
+     * Optional: a host with no embeddings simply omits it, and the UI offers no embedding views.
+     */
+    getEmbedding?(name: string): Promise<SpatialEmbedding>;
+    /**
+     * Typeahead over feature names, for datasets too wide to inline the list
+     * (`SpatialFeatureMeta.names` absent). Optional: a host whose panel is small
+     * enough to inline every name need not implement it — the UI falls back to
+     * filtering `names` locally.
+     */
+    searchFeatures?(query: string, limit?: number): Promise<string[]>;
+    /**
+     * Per-observation boundary geometry, when the dataset advertises
+     * `polygons`. Optional — a spot-based assay (Visium) has no segmentation.
+     */
+    getPolygons?(): Promise<SpatialPolygons>;
+    /**
+     * The reference volume's voxels: a uint8 scalar field, x-fastest, of exactly
+     * `width * height * depth` bytes as the dataset's {@link SpatialVolumeMeta}
+     * declares.
+     *
+     * Optional, and only meaningful when the dataset advertises a volume. Separate
+     * from `getDataset$()` because it is megabytes: a host that never opens the 3D
+     * mode should never pay for it.
+     */
+    getVolume?(): Promise<Uint8Array>;
+    /**
+     * Server-side "which observations fall inside this polygon", for datasets
+     * too large to hit-test client-side. Optional: without it the library
+     * point-in-polygons the resident coordinates itself, which is fine into the
+     * 10^5 range. Coordinates are in the same space as the observations.
+     */
+    queryRoi?(polygon: {
+        x: number[];
+        y: number[];
+    }): Promise<Uint32Array>;
+}
+export declare const SPATIAL_DATA_PORT: InjectionToken<SpatialDataPort>;

package/lib/contracts/spatial-dataset.contract.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Backend-neutral data model for a **spatial-omics dataset**: N observations
+ * (Visium spots, segmented cells, nuclei, …) positioned in the pixel space of a
+ * tissue image, each carrying categorical and continuous annotations, plus an
+ * optional feature (gene) matrix and optional per-observation boundaries.
+ *
+ * DESIGN
+ * ------
+ * 1. **Struct-of-arrays, not object-per-cell.** Real datasets run 10^3 (Visium)
+ *    to 10^6 (Xenium/CosMx) observations. `{x, y}[]` at 500k cells is ~500k
+ *    objects the GC has to walk; two `Float32Array`s are two allocations and
+ *    upload to the GPU without a copy.
+ *
+ * 2. **Metadata is eager, values are lazy.** A dataset advertises *which*
+ *    columns and features exist ({@link SpatialColumnMeta},
+ *    {@link SpatialFeatureMeta}); the vectors themselves are fetched on demand
+ *    through {@link SpatialDataPort}. A Visium table is ~30k genes wide — the
+ *    dense matrix is ~800 MB — so "load the dataset" can never mean "load the
+ *    matrix". Only the handful of columns actually being displayed is resident.
+ *
+ * 3. **Data stays data.** No I/O, no RxJS, no Angular in this file — the same
+ *    rule `plotly-trace-builders.ts` follows. Fetching lives on the port.
+ *
+ * The shape mirrors how the field already stores this (SpatialData/AnnData:
+ * `obs` annotations, `var` features, `obsm/spatial` coordinates, shapes with a
+ * coordinate transform) so an adapter is a projection, not a translation.
+ */
+/**
+ * Observation positions. Every array is length {@link count} and index-aligned:
+ * observation `i` is at `(x[i], y[i])`, and column/feature vectors index the
+ * same way. This shared index is the join key for the whole model.
+ */
+export interface SpatialObservations {
+    /** N — number of observations. */
+    readonly count: number;
+    /** X in the reference image's pixel space (see {@link SpatialImageRef}). */
+    x: Float32Array;
+    /** Y in the reference image's pixel space. */
+    y: Float32Array;
+    /** Z, for serial sections or genuinely 3D assays. Absent for a single plane. */
+    z?: Float32Array;
+    /** Stable per-observation ids (barcodes, cell ids) for tooltips and export.
+     *  Optional — omit for large datasets where the strings cost more than they
+     *  are worth. */
+    ids?: string[];
+    /** Marker RADIUS in image pixels: one value shared by all observations (a
+     *  Visium spot is a fixed 55 µm ⇒ `27.5 / mppX` px), or one per observation
+     *  (segmented cells). Absent ⇒ the renderer picks a display default. */
+    radius?: Float32Array | number;
+}
+/** Fields common to every column descriptor. */
+interface SpatialColumnMetaBase {
+    /** Column name as the user sees it (`leiden`, `total_counts`). */
+    name: string;
+    /** Longer human-readable description for tooltips/menus. */
+    description?: string;
+}
+/**
+ * A discrete annotation — cluster, cell type, region, sample. Rendered as a
+ * palette + legend; a legend click selects the category's observations.
+ */
+export interface CategoricalColumnMeta extends SpatialColumnMetaBase {
+    kind: 'categorical';
+    /** Category labels; a value's label is `categories[codes[i]]`. */
+    categories: string[];
+    /** Authored display colours as `#rrggbb`, index-aligned with
+     *  {@link categories}. Supply these to keep the viewer's palette identical to
+     *  the figures the same analysis produced in R/Python; omit to let the viewer
+     *  derive one. */
+    colors?: string[];
+}
+/**
+ * A continuous measurement — expression, QC metric, area, density. Rendered
+ * through the shared colormap/LUT + contrast window.
+ */
+export interface ContinuousColumnMeta extends SpatialColumnMetaBase {
+    kind: 'continuous';
+    /** Unit for axis/tooltip labels (`counts`, `µm²`). */
+    unit?: string;
+    /** True when the column reads best log-scaled — count data almost always
+     *  does, and a linear scale collapses it against a few bright outliers. */
+    logScaleHint?: boolean;
+    /** Observed extremes, when the producer knows them. Lets the UI seed a
+     *  contrast window and axis range without first scanning the vector. */
+    min?: number;
+    max?: number;
+}
+export type SpatialColumnMeta = CategoricalColumnMeta | ContinuousColumnMeta;
+/**
+ * Code meaning "this observation has no category" (unassigned / filtered out /
+ * not in tissue). Renderers should draw it in the muted background style rather
+ * than as a real category, and it must never index {@link
+ * CategoricalColumnMeta.categories}.
+ */
+export declare const NO_CATEGORY = 65535;
+/** A loaded categorical column: per-observation indices into `meta.categories`,
+ *  or {@link NO_CATEGORY}. */
+export interface CategoricalColumn {
+    meta: CategoricalColumnMeta;
+    /** Length = {@link SpatialObservations.count}. */
+    codes: Uint16Array;
+}
+/** A loaded continuous column. `NaN` marks a missing value. */
+export interface ContinuousColumn {
+    meta: ContinuousColumnMeta;
+    /** Length = {@link SpatialObservations.count}. */
+    values: Float32Array;
+}
+export type SpatialColumn = CategoricalColumn | ContinuousColumn;
+export declare function isCategoricalColumn(c: SpatialColumn): c is CategoricalColumn;
+export declare function isContinuousColumn(c: SpatialColumn): c is ContinuousColumn;
+/**
+ * The feature (gene) matrix, described but never delivered whole. Vectors come
+ * one at a time from {@link SpatialDataPort.getFeatureVector}.
+ */
+export interface SpatialFeatureMeta {
+    /** Number of features available. */
+    count: number;
+    /**
+     * All feature names, when the producer chose to inline them. Present for
+     * targeted panels (Xenium/CosMx ship 300–5,000 genes ⇒ a few dozen KB) and
+     * absent for whole-transcriptome data (Visium ships ~31k ⇒ ~350 KB), where
+     * the UI should use {@link SpatialDataPort.searchFeatures} for typeahead
+     * instead of downloading the list. Consumers must handle both.
+     */
+    names?: string[];
+    /** What a feature value means (`log1p normalized`, `raw counts`). */
+    unit?: string;
+    /** True when feature vectors read best log-scaled (raw counts). */
+    logScaleHint?: boolean;
+}
+/**
+ * Per-observation boundaries (cell/nucleus segmentation, spot outlines) as flat
+ * rings — deliberately NOT GeoJSON objects, which cost one object + one array
+ * per cell and would dominate memory at 10^5 polygons.
+ *
+ * Ring `i` occupies `coords[2*offsets[i] .. 2*offsets[i+1])` as `x0,y0,x1,y1,…`
+ * and is implicitly closed. `offsets` has length `count + 1`.
+ */
+export interface SpatialPolygons {
+    coords: Float32Array;
+    offsets: Uint32Array;
+    /** Number of rings — `offsets.length - 1`. */
+    readonly count: number;
+}
+/** Presence/size of the boundary geometry, without loading it. */
+export interface SpatialPolygonsMeta {
+    count: number;
+}
+/**
+ * How observation coordinates relate to the tissue image they are drawn over.
+ * Applied as `world = coord * scale + translate`, matching the affine that
+ * SpatialData records per coordinate system — and the full-resolution world
+ * convention the napari-js backend already uses so pre-saved regions align on
+ * pyramidal slides.
+ */
+export interface SpatialImageRef {
+    /** Host-defined id of the image these coordinates live in, so the host can
+     *  resolve it to an `IImageInfo`. */
+    imageId?: string;
+    /** Data→world scale. Defaults to `[1, 1]` (coordinates already in
+     *  full-resolution image pixels). */
+    scale?: [number, number];
+    /** Data→world translation, in the same units as {@link scale}'s output. */
+    translate?: [number, number];
+    /** Physical pixel size in µm — drives the scale bar and physical marker
+     *  sizing (a 55 µm Visium spot). */
+    mppX?: number;
+    mppY?: number;
+}
+/**
+ * A spatial-omics dataset: everything cheap enough to hold resident. Column and
+ * feature *values*, and polygon *geometry*, are fetched through
+ * {@link SpatialDataPort} as they are displayed.
+ */
+/**
+ * A precomputed low-dimensional embedding over the SAME observations — UMAP, t-SNE, PCA.
+ *
+ * Announced in the dataset and fetched on demand, exactly like a column or a gene: the
+ * coordinates are another per-observation vector, and a dataset may carry several.
+ */
+export interface SpatialEmbeddingMeta {
+    /** Key as the source names it, e.g. `X_umap`. */
+    name: string;
+    /** Short label for menus; falls back to {@link name}. */
+    label?: string;
+    /** 2 for a plane, 3 for a cloud. */
+    dims: 2 | 3;
+    /**
+     * True when the coordinates were COMPUTED for this bundle rather than published with the
+     * dataset. Worth surfacing: a UMAP recomputed with different parameters is a different picture,
+     * and a reader comparing against a paper's figure needs to know which they are looking at.
+     */
+    derived?: boolean;
+    /**
+     * Fraction of total variance each axis accounts for, index-aligned with the dimensions.
+     *
+     * Only meaningful for a LINEAR embedding — PCA. Its axes are ordered, and each one explains a
+     * measurable share of the variance, which is the whole reason to look at a PCA rather than a
+     * UMAP: "PC1 (23%)" says something, where "UMAP 1" says nothing at all. A UMAP's coordinates
+     * are an arbitrary output of an optimisation with no variance to report, so this stays absent
+     * there rather than being faked.
+     */
+    varianceRatio?: number[];
+    /**
+     * How a derived embedding was computed, in a few words — e.g. "PCA(50) then perplexity 30,
+     * seed 0".
+     *
+     * Not decoration. A t-SNE or UMAP is stochastic, and its picture changes materially with
+     * perplexity or `n_neighbors`; two runs at different settings are different pictures of the same
+     * cells, and neither is more correct. Saying "computed here" without saying HOW leaves a reader
+     * unable to reproduce or compare it. Absent for a published embedding, whose parameters belong
+     * to whoever published it.
+     */
+    params?: string;
+}
+/**
+ * One embedding's coordinates.
+ *
+ * Deliberately shaped like {@link SpatialObservations}' `x`/`y`/`z` rather than an (N, D) matrix:
+ * the point of an embedding here is to be swapped in as the scatter's coordinate source, and
+ * matching that shape means the renderer, the hover hit-test and the selection code need no
+ * variant for it.
+ */
+export interface SpatialEmbedding {
+    meta: SpatialEmbeddingMeta;
+    x: Float32Array;
+    y: Float32Array;
+    z?: Float32Array;
+}
+export interface SpatialDataset {
+    /** Stable id — the key the port's lazy accessors are scoped to. */
+    id: string;
+    /** Human-readable name for menus. */
+    name: string;
+    observations: SpatialObservations;
+    /** Every column available, whether or not its values are loaded. */
+    columns: SpatialColumnMeta[];
+    features?: SpatialFeatureMeta;
+    polygons?: SpatialPolygonsMeta;
+    imageRef?: SpatialImageRef;
+    /** Presence + geometry of a reference volume the observations sit inside. */
+    volume?: SpatialVolumeMeta;
+    /** Embeddings available for these observations, whose coordinates are fetched on demand. */
+    embeddings?: SpatialEmbeddingMeta[];
+    /**
+     * Microns per observation coordinate unit — what makes a scale bar possible.
+     *
+     * The 2D path gets this from `imageRef.mppX`, because there the coordinates are
+     * image pixels. A 3D cloud has no image, so it has to say for itself: `1` means
+     * the coordinates are already microns.
+     *
+     * Absent means the unit is UNKNOWN, and a renderer must then draw no scale bar
+     * rather than assume one. A bar labelled in microns over pixel-space
+     * coordinates is worse than no bar: it looks like a measurement.
+     */
+    micronsPerUnit?: number;
+}
+/**
+ * A 3D scalar reference volume registered to the observation coordinates — the
+ * anatomical backdrop for a point cloud (an atlas template, or an image z-stack).
+ *
+ * Geometry only; the voxels are fetched through
+ * {@link SpatialDataPort.getVolume} when something is going to draw them. A cloud
+ * without one still renders, just in empty space.
+ *
+ * The observations' coordinate frame must be the volume's own: voxel `(i, j, k)`
+ * covers `[i * voxelSize[0], (i + 1) * voxelSize[0])` on x, and so on. That means
+ * the volume's near corner sits at the coordinate origin, so a renderer can place
+ * the two together knowing nothing else.
+ */
+export interface SpatialVolumeMeta {
+    width: number;
+    height: number;
+    depth: number;
+    /** World size of one voxel per axis, in the observations' units. */
+    voxelSize: [number, number, number];
+}
+/** Look a column's descriptor up by name. */
+export declare function findColumnMeta(dataset: SpatialDataset, name: string): SpatialColumnMeta | undefined;
+export {};