@jax-data-science/sci-image-visualizer 0.6.0 → 0.8.0

package/lib/implementations/napari-js/napari-spatial-tiles.d.ts

@@ -0,0 +1,315 @@
+import type { Layer, Viewer } from 'napari-js';
+import type { Rgb } from '../../contracts/colormap-lut';
+import { type SpatialDataPort } from '../../contracts/ports/spatial-data.port';
+import type { SpatialViewState } from '../../contracts/display-types';
+import { SpatialDataset, SpatialDensityRaster, SpatialImageRef, SpatialPolygonTile, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
+import { SpatialSelectionMask } from '../../spatial/spatial-selection';
+import { DataRect } from '../../spatial/spatial-tiles';
+/**
+ * Level-of-detail cell outlines, transcripts and transcript density for the 2D spatial view.
+ *
+ * WHY A SEPARATE CLASS
+ * --------------------
+ * Everything else the spatial view draws is built once per (dataset, view) and only
+ * restyled afterwards. These layers also depend on the CAMERA: which tiles are on screen
+ * and which level of detail the zoom calls for. Keeping that loop — plan on camera idle,
+ * fetch tiles, merge, draw — out of the visualizer service keeps both readable.
+ *
+ * LAYER ORDER
+ * -----------
+ * napari-js's layer list is append-only (add / remove / clear), so order is kept by
+ * re-adding: cell fill, cell outline, the transcript density, then transcripts on top.
+ * The service's observation markers sit under all of them; while outlines are drawn the
+ * markers are hidden (a cell is its outline then, not a dot), so the cells never have to
+ * be ordered against them. The density goes OVER the markers on purpose: under 10^5
+ * dots it would only show in the gaps between cells. {@link afterObservations} restores
+ * the order after the service re-adds its markers.
+ *
+ * ONE LAYER PER GROUP
+ * -------------------
+ * Each group is one merged layer over every visible tile, rebuilt when the tile set or
+ * level changes. Recolouring (a new cell-type column, a selection) only rewrites the
+ * per-shape values — the geometry is not re-expanded.
+ */
+export interface SpatialTileHost {
+    /** Latest dataset/view/selection, as the spatial subscription saw them. */
+    latest(): [SpatialDataset | null, SpatialViewState, SpatialSelectionMask] | null;
+    /** Canvas size in CSS pixels. */
+    canvasSize(): [number, number];
+    /** The continuous LUT the view is using (so cells coloured by a gene match the markers). */
+    continuousLut(view: SpatialViewState): Rgb[];
+    /** Outlines appeared or disappeared: the markers' visibility follows. */
+    polygonsShownChanged(shown: boolean): void;
+    /** The density window changed (auto-derived or set). */
+    densityChanged?(stats: {
+        lo: number;
+        hi: number;
+        max: number;
+    }): void;
+    /** Estimated transcripts in view for the current selection, against the budget. */
+    estimateChanged?(estimate: TranscriptEstimate | null): void;
+    /** Transcripts of each selected gene inside the view, or null when not known. */
+    geneCountsChanged?(counts: Record<string, number> | null): void;
+    /** The layers whose data is in flight now ("Transcripts", "Cells"…); empty when none. */
+    loadingChanged?(layers: string[]): void;
+}
+/** Xenium Explorer's "Estimated Transcript Points". */
+export interface TranscriptEstimate {
+    /** Transcripts of the visible genes estimated to be in view. */
+    points: number;
+    /** The marker budget. */
+    max: number;
+}
+/** A transcript fetch the planner can key before running. */
+interface TranscriptJob {
+    /** What one entry is — decides what hovering it says. */
+    kind: 'genes' | 'individual' | 'bins';
+    /** For bins: their size and grid origin, so a hovered bin's square can be recovered. */
+    bin?: {
+        size: number;
+        origin: [number, number];
+    };
+    /** Identifies what will be drawn, so an unchanged plan is a no-op. */
+    key: string;
+    /** Fetch and merge; `px` is each entry's marker diameter in screen pixels. A job may
+     *  switch to another kind once it sees the data (individual → bins); it then says so. */
+    load(): Promise<TranscriptLoad>;
+}
+interface TranscriptLoad {
+    merged: SpatialTranscriptTile;
+    px: Float32Array;
+    /** For a gene selection: group it on this bin ladder once hidden genes are dropped. */
+    ladder?: {
+        baseBin: number;
+        levels: number;
+        start: number | null;
+    };
+    /** Already one marker per cluster per bin (zoomed out, from the density grids): no cells. */
+    clustered?: {
+        group: Int32Array;
+        names: string[];
+        genes: string[][];
+        bin: number;
+        origin: [number, number];
+    };
+    kind?: TranscriptJob['kind'];
+    bin?: TranscriptJob['bin'];
+}
+export declare class NapariSpatialTileLayers {
+    private readonly port;
+    private readonly host;
+    private viewer;
+    private cameraOff;
+    private timer;
+    /** Set when a tile of the current plan failed to load (see fetchAll). */
+    private planIncomplete;
+    /** Consecutive retries of an incomplete view. */
+    private tileRetries;
+    private token;
+    private readonly layers;
+    /** What each group currently shows, so an unchanged plan is a no-op. */
+    private readonly keys;
+    private polygonsShown;
+    /** Rings currently drawn and the (dataset, set, tiles) they came from. */
+    private currentRings;
+    private cellGeometryKey;
+    private currentNuclei;
+    private cellStyleKey;
+    /** Selection identity → revision, so a change key can name a selection cheaply. */
+    private lastSelection;
+    private selectionRevision;
+    constructor(port: SpatialDataPort, host: SpatialTileHost);
+    attach(viewer: Viewer): void;
+    /**
+     * Group a gene selection for the zoom: one marker per gene-tree cluster (a gene in no
+     * cluster is its own) per bin of the pyramid ladder, starting at the finest bin whose
+     * markers are 14 px apart and stepping up while the markers would exceed the budget.
+     * Null to draw every transcript: zoomed in, with the selection within the budget.
+     */
+    private groupSelection;
+    /** µm per observation unit of the drawn dataset, for describing a grouped marker's area. */
+    private micronsPerUnit;
+    /** Loads in flight, per layer label, for the loading badge. */
+    private readonly loading;
+    /** Report `label` loading while `work` is in flight. */
+    private track;
+    /** The loaded per-gene transcripts the in-view counts are taken from. */
+    private countSource;
+    /**
+     * Transcripts of each selected gene inside `rect`: each entry counts for the transcripts it
+     * stands for (an aggregate at a coarse level holds several). Null without per-gene data.
+     */
+    geneCountsIn(rect: DataRect): Record<string, number> | null;
+    /** Whether `layer` is one of the overlays drawn here (density, cells, transcripts). */
+    owns(layer: Layer): boolean;
+    detach(): void;
+    /** True while outlines are on screen — the service hides its dots then. */
+    get outlinesShown(): boolean;
+    /** Dataset, view or selection changed: re-plan now rather than on camera idle. */
+    refresh(): void;
+    /** Called right after the service adds its marker layer: everything goes back on top. */
+    afterObservations(): void;
+    private schedule;
+    private plan;
+    private planCells;
+    private selectionRev;
+    /** Per-shape values + colormap for the rings' owners. */
+    /**
+     * Per-shape values + colormap for the rings' owners, by the view's cell-colour mode
+     * (Xenium Explorer's "Cell Color"). A selection mutes what it leaves out.
+     */
+    private cellColors;
+    /** Codes of the group column that are switched off, or null when none are. */
+    private hiddenCodes;
+    private cellTypeColumnName;
+    private categoricalCodes;
+    private categoricalColormap;
+    /**
+     * The cell rings (and, for "both", the nucleus rings) covering `rect` at `level`, minus
+     * the hidden groups — reused when nothing that decides them changed. Null when the
+     * view went stale or the dataset has no set to draw.
+     */
+    private cellGeometry;
+    private planTranscripts;
+    /** One sized circle per entry, the size saying how many transcripts it stands for. */
+    private drawTranscriptCircles;
+    private drawTranscriptGlyphs;
+    private drawn;
+    private hoverTypes;
+    /** Details already fetched, by hovered entry. */
+    private readonly hoverCache;
+    private hoverKey;
+    private hoverTimer;
+    /**
+     * Tooltip lines for the transcript marker under world point `(wx, wy)`, or null.
+     *
+     * Returns what is known at once (gene, count, cell type); anything that needs the
+     * server — distinct genes in a group, its top genes and cells, the cell's display id —
+     * arrives through `onDetails` once the pointer has rested on the marker briefly.
+     */
+    hoverAt(wx: number, wy: number, radiusWorld: number, onDetails: (lines: string[]) => void): string[] | null;
+    private fetchDetails;
+    /** The tooltip text for entry `i`, with the server's details when they have arrived. */
+    private describe;
+    /** Physical marker size needs µm; null when the dataset's unit is unknown. */
+    private pxPerMicron;
+    /**
+     * The chosen genes, at the level the zoom calls for — or coarser, while the markers in
+     * view would exceed the budget.
+     */
+    private geneJob;
+    /**
+     * A gene selection from the pyramid's per-gene levels: starting at the level whose bins are
+     * `startBin`, fetch the view's tiles for the selected genes and step to a coarser level while
+     * one marker per cluster per bin would exceed the max. Hidden genes are fetched too (their
+     * counts in view still show) and dropped before drawing; grouping by cluster happens there.
+     */
+    private geneBinsJob;
+    /** The selection's clusters: each gene-tree group's visible genes, then each ungrouped gene. */
+    private selectionClusters;
+    /**
+     * Per-gene density grids summed for `genes`, cached (a cluster is asked for once per bin).
+     * Keyed by dataset too: this manager outlives a dataset, and another may share gene names.
+     */
+    private densityFor;
+    private readonly densityCache;
+    /**
+     * A gene selection zoomed out: one marker per cluster per bin, from the per-gene density
+     * grids. The bin starts where markers are 14 px apart and doubles until the markers fit the
+     * max; each marker sits at the count-weighted centre of the finer grid inside it, so markers
+     * follow the tissue rather than a lattice.
+     */
+    private clusterDensityJob;
+    /**
+     * Every gene: the transcripts themselves once they fit the budget, else bins of the
+     * all-gene pyramid sized by how many transcripts each holds.
+     */
+    private allGenesJob;
+    /** Bins of the all-gene pyramid at `level`, sized by how many transcripts each holds. */
+    private binsJob;
+    /** Per-entry colours both as RGBA (points) and as colormap values (glyph shapes). */
+    private transcriptColors;
+    private planDensity;
+    private countsCache;
+    /**
+     * Transcripts in view for the visible genes: each gene's dataset total times the share
+     * of the tissue on screen. An estimate — expression is not uniform — which is also what
+     * Xenium Explorer shows; it tells the user whether the budget will force grouping.
+     */
+    private planEstimate;
+    /** The density window in use and the densest bin, for the panel's threshold control. */
+    densityStats: {
+        lo: number;
+        hi: number;
+        max: number;
+    } | null;
+    /**
+     * Fetch every tile, drawing what arrived. A failure does not fail the view, but it marks the
+     * plan incomplete: the caller must not cache it as done, and `plan()` retries it.
+     */
+    private fetchAll;
+    /**
+     * Put a shapes layer in place for `group`: a geometry change builds a new layer, a
+     * colour-only change mutates values/colormap on the existing one.
+     */
+    private upsertShapes;
+    /**
+     * Install `layer` as `group`'s layer and restore the order of the groups above it.
+     * The layer was just added by the caller (so it is on top); groups that belong above
+     * it are removed and re-added.
+     */
+    private replace;
+    private drop;
+    private dropCells;
+    private setPolygonsShown;
+}
+/** What the transcript layer currently shows — what hovering needs to name a marker. */
+interface DrawnTranscripts {
+    kind: TranscriptJob['kind'];
+    bin?: TranscriptJob['bin'];
+    merged: SpatialTranscriptTile;
+    /** Marker radius per entry, in observation units. */
+    radius: Float32Array;
+    genes: string[];
+    ref: SpatialImageRef | null;
+    /** For a grouped gene selection: each entry's group, and the groups' names. */
+    entryGroup?: Int32Array;
+    groupNames?: string[];
+    /** Each group's genes, when the markers came from the density grids (for the hover). */
+    groupGenes?: string[][];
+    /** Lazily built spatial index: bucket → entry indices. */
+    grid: {
+        size: number;
+        buckets: Map<number, number[]>;
+    } | null;
+}
+/** Index of the entry under `(x, y)` — within its own radius or `tolerance` — or -1. */
+export declare function pickNearest(d: Pick<DrawnTranscripts, 'merged' | 'radius' | 'grid'>, x: number, y: number, tolerance: number): number;
+/** Rings whose owning cell is in a switched-off group removed. */
+export declare function filterRings(rings: SpatialPolygonTile, hidden: {
+    codes: Uint16Array;
+    hidden: Uint8Array;
+} | null): SpatialPolygonTile;
+/** Entries in a hidden group's cell, or of a hidden gene, removed (with their sizes). */
+export declare function filterTranscripts(t: SpatialTranscriptTile, px: Float32Array, hidden: {
+    codes: Uint16Array;
+    hidden: Uint8Array;
+} | null, hiddenGenes: Uint8Array | null): {
+    merged: SpatialTranscriptTile;
+    px: Float32Array;
+};
+/** Concatenate tiles' rings into one set, dropping rings already seen (a cell straddling
+ *  two tiles may be listed by both). */
+export declare function mergePolygonTiles(tiles: SpatialPolygonTile[]): SpatialPolygonTile;
+/** Concatenate transcript tiles, stopping at `limit` entries. */
+export declare function mergeTranscriptTiles(tiles: SpatialTranscriptTile[], limit?: number): SpatialTranscriptTile;
+/**
+ * One marker per (cluster, `bin` square) from per-cluster density grids: the counts of the grid
+ * cells inside `area` summed per square, at their count-weighted centre. `slots[c]` is the gene
+ * slot whose icon cluster c's markers take.
+ */
+export declare function clusterMarkers(rasters: SpatialDensityRaster[], slots: number[], bin: number, area: DataRect): {
+    tile: SpatialTranscriptTile;
+    group: Int32Array;
+};
+export {};

package/lib/implementations/napari-js/napari-visualizer.service.d.ts

@@ -1,8 +1,9 @@
-import { Observable } from 'rxjs';
+import { Observable, BehaviorSubject } from 'rxjs';
 import { Image } from 'image-js';
 import { IImageInfo } from '../../contracts/image.contract';
 import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
 import { SpatialObservations } from '../../contracts/spatial-dataset.contract';
+import { TranscriptEstimate } from './napari-spatial-tiles';
 import { SpatialSelectionStore } from '../../store/spatial-selection.service';
 import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
 import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from '../../contracts/visualizer.contract';
@@ -162,6 +163,18 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     /** Dataset the 3D scale bar was built for. */
     private spatialScaleBarKey;
     private spatialSub;
+    /** Level-of-detail cell outlines, transcripts and density over the 2D view — created on
+     *  first use, and only when a spatial port is bound. */
+    private spatialTilesMgr;
+    /** For the panel: the transcripts-in-view estimate and the density window in use. */
+    readonly transcriptEstimate$: BehaviorSubject<TranscriptEstimate | null>;
+    /** Transcripts of each selected gene in view (see NapariSpatialTileLayers.geneCountsIn). */
+    readonly geneCountsInView$: BehaviorSubject<Record<string, number> | null>;
+    readonly densityStats$: BehaviorSubject<{
+        lo: number;
+        hi: number;
+        max: number;
+    } | null>;
     /** Latest (dataset, view, selection) the spatial subscription saw, so a slice
      *  change can rebuild the markers for the new plane. */
     private spatialLatest;
@@ -172,6 +185,10 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
      *  round-trip, so a fast sequence of colour-by changes can resolve out of
      *  order. Only the newest rebuild is allowed to touch the layer. */
     private spatialRebuildToken;
+    /** "x reloading…" at the bottom of the canvas: the tile layers' loads and the observations'. */
+    private loadingBadge;
+    private tileLoading;
+    private observationsLoading;
     /** Monotonic load generation. Bumped by {@link reset} and {@link cancelLoading}; the frame-loading
      *  loops (volume assembly, surface preload) capture it and bail when it changes, so a Cancel (or a
      *  new plot) actually stops fetching frames instead of running to completion in the background. */
@@ -219,6 +236,12 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private invertEnabled;
     /** Physical scale bar overlay for the 2D image (null when 3D or the image has no µm/pixel). */
     private scaleBar;
+    /** Overview minimap (bottom-right), as OSD's navigator. */
+    private navigator;
+    /** Whether the navigator is shown — the same host setting OSD's navigator honours. */
+    private navigatorVisible;
+    /** Bumped per thumbnail request, so a slow one cannot overwrite a newer slice's. */
+    private navigatorToken;
     /** SVG region-drawing overlay for the 2D image (null until a 2D image is plotted). */
     private regionOverlay;
     /** Pixel-tool plumbing: the plot div id, coord transform, and bound tool hosts. */
@@ -331,6 +354,20 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     /** (Re)install the physical scale bar over the 2D image, sized from the image's µm/pixel
      *  (`/tiles/info` mppX, falling back to the image metadata). No-op without a physical size. */
     private installScaleBar;
+    /**
+     * The overview navigator for a 2D view with an image: a coarse thumbnail of the whole
+     * image with the viewport on it; click or drag to pan at the current zoom (as OSD).
+     */
+    private showLoading;
+    private installNavigator;
+    /**
+     * Draw the navigator's thumbnail from the coarsest pyramid level. A multichannel image
+     * is composited from its channels in their display colours, so the overview looks like
+     * the view rather than like channel 0 in grey.
+     */
+    private refreshNavigatorImage;
+    /** Show/hide the overview navigator (same setting as OSD's). */
+    setNavigatorVisible(visible: boolean): void;
     /** Convert a napari-js `Histogram` (bin count + min/max) to the pane's `IHistogram` (bin edges). */
     private toIHistogram;
     /**
@@ -421,6 +458,17 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
      * driven by drawn ROIs, so without the overlay there is no way to make a selection at all.
      */
     private mountSpatialOmics;
+    /**
+     * Whether the 2D observation markers are drawn: when the user wants them, and not while
+     * cell outlines are on screen — then a cell IS its outline, and a circle on top of it is
+     * noise. Zoomed out past the outline threshold, the circles stand in for the cells.
+     */
+    private spatialPointsVisible;
+    /**
+     * The tiled-geometry manager, built on first use. Its host callbacks read this
+     * service's live state, so it never holds a stale dataset or colormap.
+     */
+    private spatialTiles;
     /**
      * Region drawing for the 3D cloud.
      *
@@ -838,7 +886,6 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     zoomIn(): void;
     zoomOut(): void;
     setDragMode(_mode: string | false): void;
-    setNavigatorVisible(_visible: boolean): void;
     setImageSmoothingEnabled(enabled: boolean): void;
     setShowStack(_showstack: boolean): void;
     setZIndex(zIndex: number): void;

package/lib/implementations/spatial-data-http/spatial-data-http.service.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from '@angular/common/http';
 import { Observable } from 'rxjs';
-import { SpatialDataPort } from '../../contracts/ports/spatial-data.port';
-import { SpatialColumn, SpatialDataset, SpatialEmbedding, SpatialPolygons } from '../../contracts/spatial-dataset.contract';
+import { SpatialDataPort, TranscriptTileQuery } from '../../contracts/ports/spatial-data.port';
+import { SpatialColumn, SpatialDataset, SpatialDensityRaster, SpatialEmbedding, SpatialPolygonTile, SpatialPolygons, CategoricalColumnMeta, SpatialMarkerGenes, SpatialTranscriptCounts, SpatialTranscriptSummary, SpatialTranscriptTile } from '../../contracts/spatial-dataset.contract';
 import { SpatialDatasetSummary, SpatialManifest } from './spatial-wire';
 import * as i0 from "@angular/core";
 /**
@@ -58,6 +58,12 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     private static readonly CACHE_LIMIT;
     /** In-flight requests, so double-clicking a gene issues one fetch. */
     private readonly inFlight;
+    /**
+     * Tiles get their own, larger cache: panning revisits them constantly, and one screen
+     * of a zoomed-out section is dozens of them — far past the vector cache's limit.
+     */
+    private readonly tileCache;
+    private static readonly TILE_CACHE_LIMIT;
     private volumePromise;
     private polygonsPromise;
     constructor(http: HttpClient);
@@ -89,6 +95,26 @@ export declare class SpatialDataHttpService implements SpatialDataPort {
     getFeatureVector(name: string): Promise<Float32Array>;
     searchFeatures(query: string, limit?: number): Promise<string[]>;
     getPolygons(): Promise<SpatialPolygons>;
+    getPolygonTile(set: string, level: number, gx: number, gy: number): Promise<SpatialPolygonTile>;
+    getTranscriptTile(level: number, gx: number, gy: number, query: TranscriptTileQuery): Promise<SpatialTranscriptTile>;
+    getTranscriptGeneBins(level: number, tx: number, ty: number, genes: string[]): Promise<SpatialTranscriptTile>;
+    getTranscriptBins(level: number, tx: number, ty: number): Promise<SpatialTranscriptTile>;
+    /** Small JSON answers, keyed by URL — hovering back and forth must not refetch. */
+    private readonly summaryCache;
+    getTranscriptSummary(query: {
+        box?: [number, number, number, number];
+        genes?: string[];
+        cells?: number[];
+    }): Promise<SpatialTranscriptSummary>;
+    getDensity(genes: string[], binSize?: number): Promise<SpatialDensityRaster>;
+    importGroups(label: string, table: string): Promise<{
+        column: CategoricalColumnMeta;
+        matched: number;
+    }>;
+    getMarkerGenes(column: string, perGroup?: number): Promise<SpatialMarkerGenes>;
+    getTranscriptCounts(genes: string[]): Promise<SpatialTranscriptCounts>;
+    /** LRU over tile promises, so concurrent asks share one request and a failure is not kept. */
+    private cachedTile;
     /**
      * The reference volume's voxels, single-flighted like the polygons.
      *

package/lib/implementations/spatial-data-http/spatial-wire.d.ts

@@ -1,4 +1,4 @@
-import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialEmbedding, SpatialEmbeddingMeta, SpatialFeatureMeta, SpatialImageRef, SpatialObservations, SpatialPolygons, SpatialVolumeMeta } from '../../contracts/spatial-dataset.contract';
+import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialDensityMeta, SpatialDensityRaster, SpatialEmbedding, SpatialEmbeddingMeta, SpatialFeatureMeta, SpatialImageRef, SpatialObservations, SpatialPolygonTile, SpatialPolygonTilesMeta, SpatialPolygons, SpatialTranscriptBinsMeta, SpatialTranscriptGeneBinsMeta, SpatialTranscriptBinsStatus, SpatialTranscriptTile, SpatialTranscriptTilesMeta, SpatialVolumeMeta } from '../../contracts/spatial-dataset.contract';
 /**
  * The wire format the bundled example server speaks, and its decoders.
  *
@@ -33,7 +33,18 @@ import { SpatialColumn, SpatialColumnMeta, SpatialDataset, SpatialEmbedding, Spa
  * GET {base}/spatial/{id}/feature/{name}   -> f32[N]
  * GET {base}/spatial/{id}/features?q=&limit= -> { names: string[] }
  * GET {base}/spatial/{id}/polygons         -> u32 count, u32[count+1] offsets, f32[2*rings] coords
+ * GET {base}/spatial/{id}/polygon-tile/{set}/{level}/{gx}/{gy}
+ *                                          -> u32 count, u32[count] obs, u32[count+1] offsets, f32 coords
+ * GET {base}/spatial/{id}/transcript-tile/{level}/{gx}/{gy}?genes=A,B&quality=high|all
+ *                                          -> see decodeTranscriptTile
+ * GET {base}/spatial/{id}/density?genes=A,B -> f32[rows*cols]
+ * GET {base}/spatial/{id}/transcript-bins/{level}/{tx}/{ty}
+ *                                          -> transcript-tile layout, one entry per bin
  * ```
+ *
+ * The three tiled routes are optional and advertised in the manifest
+ * (`polygonTiles`, `transcriptTiles`, `density`); a server without them never
+ * sees them requested.
  */
 /** Bumped when the layout changes incompatibly; the client refuses anything else. */
 export declare const SPATIAL_WIRE_VERSION = 1;
@@ -63,6 +74,12 @@ export interface SpatialManifest {
     volume?: SpatialVolumeMeta;
     embeddings?: SpatialEmbeddingMeta[];
     micronsPerUnit?: number;
+    polygonTiles?: SpatialPolygonTilesMeta;
+    transcriptTiles?: SpatialTranscriptTilesMeta;
+    density?: SpatialDensityMeta;
+    transcriptBins?: SpatialTranscriptBinsMeta;
+    transcriptBinsStatus?: SpatialTranscriptBinsStatus;
+    transcriptGeneBins?: SpatialTranscriptGeneBinsMeta;
 }
 /** `GET /spatial/datasets` */
 export interface SpatialDatasetSummary {
@@ -104,6 +121,23 @@ export declare function decodeColumn(buf: ArrayBuffer, meta: SpatialColumnMeta,
  * field is 4-byte wide so each typed-array view stays aligned.
  */
 export declare function decodePolygons(buf: ArrayBuffer): SpatialPolygons;
+/**
+ * `GET /polygon-tile/...` → one tile of rings with their owning observations. Layout
+ * `[u32 count][u32 obs × count][u32 offsets × (count+1)][f32 coords × 2·offsets[count]]`.
+ */
+export declare function decodePolygonTile(buf: ArrayBuffer): SpatialPolygonTile;
+/**
+ * `GET /transcript-tile/...` → transcripts or aggregates. Layout, 4-byte aligned:
+ * `[u32 n][u32 flags][f32 x·n][f32 y·n][f32 z·n][u32 weight·n][u32 obs·n][u16 gene·n, padded]`;
+ * flags bit 0 marks an aggregated level.
+ */
+export declare function decodeTranscriptTile(buf: ArrayBuffer): SpatialTranscriptTile;
+/**
+ * `GET /density?genes=&bin=` → the summed raster. Layout
+ * `[u32 rows][u32 cols][f32 cellW][f32 cellH][f32 originX][f32 originY][f32 rows·cols]`:
+ * the geometry travels with the values because re-binning changes it.
+ */
+export declare function decodeDensity(buf: ArrayBuffer, genes: string[]): SpatialDensityRaster;
 /**
  * Fold a manifest plus its fetched coordinate/id/radius vectors into the
  * library-facing {@link SpatialDataset}. Column and feature *values* are not