@jax-data-science/sci-image-visualizer 0.8.3 → 0.9.0

package/lib/spatial/spatial-tiles.d.ts

@@ -1,259 +1,12 @@
 /**
- * Level-of-detail planning for tiled spatial geometry — cell outlines and transcripts.
+ * Spatial tile helpers, re-exported from the modules they now live in.
  *
- * The renderer knows its camera (a world-space centre, a zoom in canvas pixels per world
- * unit, a canvas size); a tiled dataset knows its grids (one per level, in observation
- * units). This module is the bridge: which level the zoom calls for, which tiles are on
- * screen, how big a transcript marker should be. Everything here is pure, so the policy
- * — the part that decides whether the view is fast and legible — is testable without a
- * GPU.
- *
- * Observation units map onto world units through the dataset's `imageRef` affine
- * (`world = data · scale + translate`), so "pixels per observation unit" is
- * `zoom · scale`. For a Xenium bundle the data unit is the micron and the world unit the
- * morphology pixel.
- */
-import type { SpatialBounds, SpatialImageRef, SpatialTileLevel, SpatialTranscriptTile } from '../contracts/spatial-dataset.contract';
-import type { SpatialViewState } from '../contracts/display-types';
-import type { SpatialDataset } from '../contracts/spatial-dataset.contract';
-/** A rectangle in observation coordinates. */
-export interface DataRect {
-    x0: number;
-    y0: number;
-    x1: number;
-    y1: number;
-}
-/** Tile address. */
-export interface TileKey {
-    level: number;
-    gx: number;
-    gy: number;
-}
-/** Whether cell outlines are drawn: the user's choice, else on when the dataset has any. */
-export declare function cellsShown(dataset: Pick<SpatialDataset, 'polygonTiles' | 'polygons'> | null, view: Pick<SpatialViewState, 'showCells'>): boolean;
-/** A column holding a hand-curated cell-type annotation, by naming convention. */
-export declare function isCuratedColumn(name: string): boolean;
-/**
- * The categorical column that names each cell's type: the view's choice when it is a
- * column of this dataset, else the first categorical column that is not a curated
- * annotation (a pipeline's clustering is the default; curation is opted into), else
- * any categorical column.
- */
-export declare function cellTypeColumnFor(dataset: SpatialDataset, view: Pick<SpatialViewState, 'cellTypeColumn'>): string | null;
-export declare function tileId(k: TileKey): string;
-/** Canvas pixels per observation unit along x, for a camera zoom and a data→world affine. */
-export declare function pixelsPerDataUnit(zoom: number, ref?: SpatialImageRef | null): number;
-/**
- * The part of observation space the camera shows, padded by `margin` (a fraction of the
- * viewport) so tiles just off screen are already there when a pan brings them in.
- */
-export declare function visibleDataRect(center: readonly [number, number], zoom: number, canvasW: number, canvasH: number, ref?: SpatialImageRef | null, margin?: number): DataRect | null;
-/**
- * Tiles of one level intersecting `rect`, clipped to the dataset's `bounds` (so zooming
- * out over empty canvas does not ask for tiles that cannot exist). Ordered from the
- * rectangle's centre outward, so the middle of the screen fills in first.
- */
-export declare function tilesInRect(rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
-/**
- * Typical cell diameter, in observation units, used to judge how large cells appear.
- * Derived from the per-observation radius when there is one; 12 µm otherwise.
- */
-export declare function typicalCellDiameter(radius: Float32Array | number | undefined, fallback?: number): number;
-/**
- * On-screen cell diameter (px) at or above which each polygon level is used. A level
- * halves the vertices of the one below, so each should take over when the cell is about
- * half as large on screen. Below the last finite threshold outlines are not drawn at
- * all — a cell a few pixels wide is a dot, and the observation markers already draw it
- * as one.
- *
- * Xenium's fourth level (3 vertices per cell) is deliberately never used: seen on
- * screen it is a field of triangles, which reads as an artefact rather than as cells.
- * The dots below 8 px say the same thing more honestly.
- */
-export declare const POLYGON_LEVEL_MIN_CELL_PX: number[];
-/**
- * Which polygon level suits this zoom, or -1 for "too small to outline".
- * `detail` > 1 prefers finer levels (sharper, slower); < 1 coarser.
- */
-export declare function polygonLevelFor(pxPerUnit: number, cellDiameter: number, levelCount: number, detail?: number): number;
-/**
- * Which transcript level suits this zoom: the one whose tiles come out closest to
- * `targetTilePx` on screen. Coarser levels aggregate more, so this keeps the number of
- * markers per screen roughly constant however far out the camera is — the property that
- * keeps the view fast.
- */
-export declare function transcriptLevelFor(pxPerUnit: number, levels: readonly SpatialTileLevel[], targetTilePx?: number): number;
-/**
- * The bin a selection of genes is grouped into at this zoom, in observation units, or null
- * to draw every transcript. Bins follow the all-gene pyramid's ladder (`baseBin` × 2^m) so a
- * gene selection and "all genes" group alike: the finest bin whose markers land at least
- * `spacingPx` apart on screen. Once the finest bin is that wide, transcripts are drawn as
- * themselves.
- */
-export declare function geneBinSize(pxPerUnit: number, baseBin: number, levels?: number, spacingPx?: number): number | null;
-/** The entries of `t` inside `rect` (observation units). */
-export declare function clipTranscripts(t: SpatialTranscriptTile, rect: DataRect): SpatialTranscriptTile;
-/**
- * Group transcripts into `bin`-wide squares of a grid anchored at the origin (so a pan does
- * not move them), one entry per (group, square): `groupOf(gene slot)` says which group a gene
- * is in — its cluster in the gene tree, or itself. Each entry sits at its transcripts'
- * centroid, weighted by how many each stands for; it takes the gene and the cell holding most
- * of them, each summed over all its transcripts in the entry. `group[i]` is entry i's group.
- */
-export declare function groupTranscripts(t: SpatialTranscriptTile, bin: number, groupOf?: (geneSlot: number) => number): {
-    tile: SpatialTranscriptTile;
-    group: Int32Array;
-};
-/**
- * The colour of each gene-tree cluster of a selection, for colouring transcripts by cluster: a
- * cluster named like a group of the cells' grouping takes that group's colour (its cells and its
- * transcripts agree); the others take palette colours in tree order. Clusters are the tree's
- * groups holding a selected gene, then each ungrouped selected gene on its own. Every gene of a
- * cluster gets the same colour — the tree's swatches and the markers use this one map.
- */
-export declare function clusterColorMap(genes: readonly string[], groups: readonly {
-    name: string;
-    genes: readonly string[];
-}[], cellColors: ReadonlyMap<string, string>, palette: readonly string[]): Map<string, string>;
-/** The cluster a selected gene is in: its first gene-tree group holding it, else itself. */
-export declare function clusterOfGene(gene: string, groups: readonly {
-    name: string;
-    genes: readonly string[];
-}[]): string;
-/** Smallest and largest transcript marker, in canvas pixels. */
-export declare const TRANSCRIPT_MIN_PX = 4;
-export declare const TRANSCRIPT_MAX_PX = 32;
-/**
- * Physical diameter a single transcript is drawn at, in µm — clearly larger than the
- * imaged spot (~0.3 µm) so it stays legible, and small enough that neighbouring
- * molecules inside one cell stay apart.
- */
-export declare const TRANSCRIPT_PHYSICAL_UM = 1.2;
-/**
- * Marker diameter in canvas pixels for an entry standing for `weight` transcripts.
- *
- * The convention spatial viewers share (deck.gl's `radiusMinPixels`/`radiusMaxPixels`,
- * Xenium Explorer's transcript size): a PHYSICAL size, clamped to a screen-pixel range.
- * Zoomed out, markers sit at the minimum and never vanish; zoomed in, they grow with the
- * tissue instead of shrinking to specks next to cells hundreds of pixels wide. A fixed
- * screen size does the opposite at high zoom, which is what made transcripts disappear
- * at pixel-level zoom.
- *
- * Aggregates grow with the cube root of their count: area ∝ count would let one dense
- * aggregate swallow its neighbours, the cube root keeps a 1000-transcript cluster clearly
- * larger than a 10-transcript one without covering the tile.
- *
- * `pxPerMicron` is omitted for data with no known physical unit; the marker is then
- * screen-sized only.
- */
-export declare function transcriptMarkerPx(weight: number, scale?: number, pxPerMicron?: number): number;
-/** Marker shapes for the transcript "icon" mode. All star-convex, so a fan fills them. */
-export declare const TRANSCRIPT_GLYPHS: readonly ["circle", "star", "triangle", "square", "diamond", "cross", "hexagon", "triangle-down", "pentagon", "x"];
-export type TranscriptGlyph = typeof TRANSCRIPT_GLYPHS[number];
-/** Unit outline of a glyph, radius ≈ 1, centred on the origin, as `[x0, y0, x1, y1, …]`. */
-export declare function glyphOutline(glyph: TranscriptGlyph): Float32Array;
-/** The glyph a gene gets by default: by its position in the selected list. */
-export declare function defaultGlyphFor(slot: number): TranscriptGlyph;
-/**
- * Expand point markers into glyph rings for a shapes layer: entry `i` becomes a copy of
- * `glyphs[gene[i]]` scaled to `radius[i]` and centred on `(x[i], y[i])`.
- */
-export declare function glyphRings(x: Float32Array, y: Float32Array, radius: Float32Array, glyphOf: (i: number) => Float32Array): {
-    coords: Float32Array;
-    offsets: Uint32Array;
-};
-/**
- * A shapes layer colours through a colormap LUT, not per-shape RGBA. A categorical
- * palette becomes a piecewise-constant colormap: category `c` of `n` owns the band
- * `[c/n, (c+1)/n)`, and a shape takes the value at its band's centre, so the LUT's
- * linear filtering never blends two categories.
- *
- * Returns the stops (linear 0..1 RGB) and a function mapping a category code to the
- * value to hand the layer. `missing` is the colour of the extra band used for "no
- * category".
- */
-export declare function discreteColormapStops(rgb: readonly (readonly [number, number, number])[], missing: readonly [number, number, number]): {
-    stops: {
-        t: number;
-        color: [number, number, number];
-    }[];
-    valueOf: (code: number) => number;
-};
-/**
- * Separable Gaussian blur of a row-major raster, `sigma` in raster cells.
- *
- * A per-gene count raster at 10 µm is mostly zeros and ones — drawn as-is it is speckle,
- * not a density. A σ of one to two cells (10–20 µm, about a cell diameter) turns it into
- * a field that reads as territory while keeping structures a few cells wide.
- */
-export declare function smoothRaster(values: Float32Array, rows: number, cols: number, sigma: number): Float32Array;
-/**
- * Colour a density raster as RGBA bytes: log-scaled, windowed at a high percentile of the
- * non-zero values, and faded in from transparent so empty tissue shows what is under it.
- */
-export declare function colorDensity(values: Float32Array, lut: readonly (readonly [number, number, number])[], opacity: number, { log, percentile }?: {
-    log?: boolean | undefined;
-    percentile?: number | undefined;
-}): Uint8Array;
-/** Smallest on-screen spacing between groups, in px — below it groups read as noise. */
-export declare const GROUP_MIN_SPACING_PX = 14;
-/** Area of `rect` inside `bounds` (the whole rect when there are none). */
-export declare function visibleArea(rect: DataRect, bounds?: SpatialBounds | null): number;
-export type AllGenesPlan = {
-    kind: 'individual';
-} | {
-    kind: 'bins';
-    level: number;
-} | {
-    kind: 'none';
-};
-/**
- * How to draw every transcript in view without exceeding `budget` markers.
- *
- * - The transcripts themselves, once the estimated count in view fits the budget.
- * - Otherwise the finest pyramid level whose bins are at least `minSpacingPx` apart on
- *   screen and number no more than the budget — groups big enough to read, few enough
- *   to draw.
- *
- * The count in view is estimated from the average density, which over- or under-shoots
- * locally; the renderer still caps what it draws, so an estimate is enough to choose.
- */
-export declare function allGenesPlan(o: {
-    rect: DataRect;
-    bounds: SpatialBounds;
-    total: number;
-    pxPerUnit: number;
-    levels: readonly {
-        binSize: number;
-    }[];
-    budget: number;
-    canIndividual: boolean;
-    minSpacingPx?: number;
-}): AllGenesPlan;
-/**
- * Diameter in px of a group of `count` transcripts in a bin `binPx` wide, where
- * `refCount` is a typical busy bin in view (its 95th percentile).
- *
- * Area grows with the count — a bin with a quarter of the transcripts gets half the
- * diameter — between a third of the bin (so a sparse bin is still visible) and a little
- * over the full bin (so dense neighbours just touch rather than pile up).
- */
-export declare function groupedMarkerPx(count: number, refCount: number, binPx: number, scale?: number): number;
-/** The `p` quantile (0..1) of a count vector — a sample of it for large vectors. */
-export declare function quantileOf(values: ArrayLike<number>, p: number): number;
-/** {@link tilesInRect} for a grid whose tile (0, 0) starts at `origin`. */
-export declare function tilesInRectFrom(origin: readonly [number, number], rect: DataRect, level: number, levels: readonly SpatialTileLevel[], bounds?: SpatialBounds | null, limit?: number): TileKey[];
-/** A density window from the non-empty bins: 1st to 99th percentile. */
-export declare function densityAutoRange(values: ArrayLike<number>): [number, number];
-/**
- * Colour density bins through `lut` over the window `[lo, hi]` — Xenium Explorer's
- * "scale threshold". Bins at or below `lo` are transparent, so empty tissue shows the
- * image under it; bins at or above `hi` saturate.
- */
-export declare function colorDensityWindow(values: ArrayLike<number>, lut: readonly (readonly [number, number, number])[], opacity: number, lo: number, hi: number): Uint8Array;
-/**
- * Inferno (matplotlib), as an inline `[stop, colour]` scale: the density map's default,
- * as in Xenium Explorer. Inline because the colormap tree's `INFERNO_LUT` key is resolved
- * at runtime by the store, which the renderer does not see.
+ * @deprecated Kept for one release so existing imports keep working. Import from
+ * `./lod` (level of detail, tiles in view), `./transcript-grouping` (grouping, marker
+ * sizing, cluster colours), `./glyphs` (transcript icons) or `./density-raster` (density
+ * window and scale) instead.
  */
-export declare const INFERNO_SCALE: [number, string][];
+export * from './lod';
+export * from './transcript-grouping';
+export * from './glyphs';
+export * from './density-raster';

package/lib/spatial/stats.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Percentiles for the spatial code: one "collect, sort, index" routine instead of one per
+ * caller.
+ *
+ * The callers used to differ in rounding (`round(p·(n-1))` against `floor(p·n)`), in
+ * sampling and in filtering, so windows computed for the same data in different views
+ * could disagree. Here there is one rule for each:
+ *
+ *  - **Rank**: `round(p·(n-1))` — the nearest rank. `floor(p·n)` is biased upward and
+ *    hands back the maximum for `p = 0.99` on a hundred values, outlier included.
+ *  - **Sort**: a typed-array sort, which is native and numeric — several times faster
+ *    than a comparator sort of a boxed `number[]`, and far lighter on the heap.
+ *  - **Sample**: past `2·sampleSize` qualifying values, every `floor(count/sampleSize)`-th
+ *    one, which is plenty for a display window and keeps a 3.7M-cell recolour from
+ *    sorting 3.7M values.
+ */
+export interface QuantileOptions {
+    /** Which values count: every finite one (the default), or only those above zero. */
+    filter?: 'finite' | 'positive';
+    /** Count index `i` only where `where[i] > 0` — e.g. a field's support. */
+    where?: ArrayLike<number>;
+    /** Sample down to about this many values (see the module doc); unsampled when absent. */
+    sampleSize?: number;
+}
+/**
+ * The `ps` quantiles (each 0..1, clamped) of the values that qualify, or null when none do.
+ */
+export declare function quantiles(values: ArrayLike<number>, ps: readonly number[], opts?: QuantileOptions): number[] | null;
+/** One quantile; see {@link quantiles}. */
+export declare function quantile(values: ArrayLike<number>, p: number, opts?: QuantileOptions): number | null;
+/** Sample size for a contrast window: a display window does not need every value. */
+export declare const WINDOW_SAMPLE_SIZE = 65536;
+/**
+ * A `[lo, hi]` percentile window over the qualifying values, never flat or inverted
+ * (a flat window would divide by zero downstream, so it is widened by one), and `[0, 1]`
+ * when nothing qualifies, so callers always get a usable window.
+ */
+export declare function percentileWindow(values: ArrayLike<number>, lo: number, hi: number, opts?: QuantileOptions): [number, number];

package/lib/spatial/transcript-grouping.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Transcript grouping and marker sizing: how many transcripts one marker stands for at the
+ * current zoom, how big it is drawn, and which colour each gene-tree cluster takes. Pure, so
+ * the budget policy is testable without a viewer.
+ */
+import type { SpatialBounds, SpatialTranscriptTile } from '../contracts/spatial-dataset.contract';
+import { DataRect } from './lod';
+/** Smallest on-screen spacing between groups, in px — below it groups read as noise. */
+export declare const GROUP_MIN_SPACING_PX = 14;
+/**
+ * The bin a selection of genes is grouped into at this zoom, in observation units, or null
+ * to draw every transcript. Bins follow the all-gene pyramid's ladder (`baseBin` × 2^m) so a
+ * gene selection and "all genes" group alike: the finest bin whose markers land at least
+ * `spacingPx` apart on screen. Once the finest bin is that wide, transcripts are drawn as
+ * themselves.
+ */
+export declare function geneBinSize(pxPerUnit: number, baseBin: number, levels?: number, spacingPx?: number): number | null;
+/** The entries of `t` inside `rect` (observation units). */
+export declare function clipTranscripts(t: SpatialTranscriptTile, rect: DataRect): SpatialTranscriptTile;
+/**
+ * Group transcripts into `bin`-wide squares of a grid anchored at the origin (so a pan does
+ * not move them), one entry per (group, square): `groupOf(gene slot)` says which group a gene
+ * is in — its cluster in the gene tree, or itself. Each entry sits at its transcripts'
+ * centroid, weighted by how many each stands for; it takes the gene and the cell holding most
+ * of them, each summed over all its transcripts in the entry. `group[i]` is entry i's group.
+ */
+export declare function groupTranscripts(t: SpatialTranscriptTile, bin: number, groupOf?: (geneSlot: number) => number): {
+    tile: SpatialTranscriptTile;
+    group: Int32Array;
+};
+/**
+ * The colour of each gene-tree cluster of a selection, for colouring transcripts by cluster: a
+ * cluster named like a group of the cells' grouping takes that group's colour (its cells and its
+ * transcripts agree); the others take palette colours in tree order. Clusters are the tree's
+ * groups holding a selected gene, then each ungrouped selected gene on its own. Every gene of a
+ * cluster gets the same colour — the tree's swatches and the markers use this one map.
+ */
+export declare function clusterColorMap(genes: readonly string[], groups: readonly {
+    name: string;
+    genes: readonly string[];
+}[], cellColors: ReadonlyMap<string, string>, palette: readonly string[]): Map<string, string>;
+/** The cluster a selected gene is in: its first gene-tree group holding it, else itself. */
+export declare function clusterOfGene(gene: string, groups: readonly {
+    name: string;
+    genes: readonly string[];
+}[]): string;
+/** Smallest transcript marker, in canvas pixels. */
+export declare const TRANSCRIPT_MIN_PX = 4;
+/** Largest transcript marker, in canvas pixels. */
+export declare const TRANSCRIPT_MAX_PX = 32;
+/**
+ * Physical diameter a single transcript is drawn at, in µm — clearly larger than the
+ * imaged spot (~0.3 µm) so it stays legible, and small enough that neighbouring
+ * molecules inside one cell stay apart.
+ */
+export declare const TRANSCRIPT_PHYSICAL_UM = 1.2;
+/**
+ * Marker diameter in canvas pixels for an entry standing for `weight` transcripts.
+ *
+ * The convention spatial viewers share (deck.gl's `radiusMinPixels`/`radiusMaxPixels`,
+ * Xenium Explorer's transcript size): a PHYSICAL size, clamped to a screen-pixel range.
+ * Zoomed out, markers sit at the minimum and never vanish; zoomed in, they grow with the
+ * tissue instead of shrinking to specks next to cells hundreds of pixels wide. A fixed
+ * screen size does the opposite at high zoom, which is what made transcripts disappear
+ * at pixel-level zoom.
+ *
+ * Aggregates grow with the cube root of their count: area ∝ count would let one dense
+ * aggregate swallow its neighbours, the cube root keeps a 1000-transcript cluster clearly
+ * larger than a 10-transcript one without covering the tile.
+ *
+ * `pxPerMicron` is omitted for data with no known physical unit; the marker is then
+ * screen-sized only.
+ */
+export declare function transcriptMarkerPx(weight: number, scale?: number, pxPerMicron?: number): number;
+/**
+ * How "all genes" is drawn at the current zoom: individual transcripts, a bin level, or nothing.
+ */
+export type AllGenesPlan = {
+    kind: 'individual';
+} | {
+    kind: 'bins';
+    level: number;
+} | {
+    kind: 'none';
+};
+/**
+ * How to draw every transcript in view without exceeding `budget` markers.
+ *
+ * - The transcripts themselves, once the estimated count in view fits the budget.
+ * - Otherwise the finest pyramid level whose bins are at least `minSpacingPx` apart on
+ *   screen and number no more than the budget — groups big enough to read, few enough
+ *   to draw.
+ *
+ * The count in view is estimated from the average density, which over- or under-shoots
+ * locally; the renderer still caps what it draws, so an estimate is enough to choose.
+ */
+export declare function allGenesPlan(o: {
+    rect: DataRect;
+    bounds: SpatialBounds;
+    total: number;
+    pxPerUnit: number;
+    levels: readonly {
+        binSize: number;
+    }[];
+    budget: number;
+    canIndividual: boolean;
+    minSpacingPx?: number;
+}): AllGenesPlan;
+/**
+ * Diameter in px of a group of `count` transcripts in a bin `binPx` wide, where
+ * `refCount` is a typical busy bin in view (its 95th percentile).
+ *
+ * Area grows with the count — a bin with a quarter of the transcripts gets half the
+ * diameter — between a third of the bin (so a sparse bin is still visible) and a little
+ * over the full bin (so dense neighbours just touch rather than pile up).
+ */
+export declare function groupedMarkerPx(count: number, refCount: number, binPx: number, scale?: number): number;
+/** The `p` quantile (0..1) of a count vector — a sample of it for large vectors. */
+export declare function quantileOf(values: ArrayLike<number>, p: number): number;

package/lib/spatial-controls/spatial-cells-panel/spatial-cells-panel.component.d.ts

@@ -0,0 +1,64 @@
+import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import type { ISpatialControls } from '../../contracts/visualizer.contract';
+import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { SpatialViewState } from '../../contracts/display-types';
+import { PanelOption } from '../../spatial/spatial-panel-model';
+import type { GenePickerModel } from '../spatial-gene-picker';
+import * as i0 from "@angular/core";
+/**
+ * The Cells section, as Xenium Explorer's: the outlines' on/off switch, which boundary set
+ * is drawn, how cells are coloured (with the gene, the colour, or the colour bar that
+ * goes with it), the {@link SpatialGroupsPanelComponent groups}, and how cells are drawn.
+ *
+ * Writes only through `controls.setViewState`.
+ */
+export declare class SpatialCellsPanelComponent implements OnChanges {
+    /** The spatial controls this panel reads and writes through; null without a `SPATIAL_DATA_PORT`. */
+    controls: ISpatialControls | null;
+    /** The dataset on offer, or null. */
+    dataset: SpatialDataset | null;
+    /** The current spatial view state: what is drawn, and how. */
+    view: SpatialViewState;
+    /** The gene list the "Gene Expression" colouring picks from, shared with the other
+     *  gene dropdowns. */
+    genes: GenePickerModel | null;
+    /** The observations' continuous colour bar, shown for the gene colouring while it has one. */
+    colorBarCss: string | null;
+    /** Whether the section is expanded. */
+    open: boolean;
+    /** Asks to open or close it; two-way with `open`. */
+    readonly openChange: EventEmitter<boolean>;
+    /** Virtual-scrolled only past this many options: the scroller earns its complexity for
+     *  a few thousand names, and for eight it adds only overhead — a virtual viewport that
+     *  short swallows the clicks it is meant to forward. */
+    protected readonly geneVirtualScrollFrom = 200;
+    protected readonly cellDrawOptions: PanelOption<SpatialViewState['cellDraw']>[];
+    /**
+     * Option lists for the cell controls. Built once per dataset rather than in getters: a
+     * getter returns a fresh array on every change-detection pass, and PrimeNG re-renders
+     * its buttons whenever the array identity changes — which made them impossible to click.
+     */
+    protected cellSetOptions: PanelOption<string>[];
+    /** Cell colour modes on offer (Xenium Explorer's "Cell Color"). */
+    protected cellColorOptions: PanelOption<SpatialViewState['cellColorMode']>[];
+    /** The density colour bar, rebuilt only when its colormap changes (a 256-entry LUT). */
+    protected densityColorBarCss: string;
+    private densityBarFor;
+    ngOnChanges(changes: SimpleChanges): void;
+    /** Whether outlines are on — the explicit choice, or automatically for data that has them. */
+    protected get cellsOn(): boolean;
+    /** The boundary set drawn: the view's choice, else the dataset's default, else its first. */
+    protected get activeCellSet(): string | null;
+    /** Fill opacity as a 0–100 number, for the box beside the slider. */
+    protected get cellOpacityPercent(): number;
+    protected onShowCells(on: boolean): void;
+    protected onCellSet(set: string): void;
+    protected onCellDraw(draw: SpatialViewState['cellDraw']): void;
+    protected onCellOpacity(value: number | undefined): void;
+    protected onCellOpacityPercent(v: number | null): void;
+    protected onCellColorMode(mode: SpatialViewState['cellColorMode']): void;
+    protected onCellColorGene(gene: string | null): void;
+    protected onCellSingleColor(hex: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialCellsPanelComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialCellsPanelComponent, "spatial-cells-panel", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; "genes": { "alias": "genes"; "required": false; }; "colorBarCss": { "alias": "colorBarCss"; "required": false; }; "open": { "alias": "open"; "required": false; }; }, { "openChange": "openChange"; }, never, never, true, never>;
+}

package/lib/spatial-controls/spatial-charts/chart-data-model.d.ts

@@ -0,0 +1,153 @@
+import type { ISpatialControls } from '../../contracts/visualizer.contract';
+import type { SpatialDataset, SpatialEmbedding, SpatialEmbeddingMeta } from '../../contracts/spatial-dataset.contract';
+import type { SpatialColorBy } from '../../contracts/display-types';
+import type { OmicsGrouping } from '../../implementations/plotly/omics-trace-builders';
+/** What a colour-source load came to. */
+export type ValueLoad = 
+/** Nothing to chart: no colour source, or no port. */
+'none'
+/** A categorical column: its counts per category are loaded. */
+ | 'categorical'
+/** A gene or numeric column: its values are loaded. */
+ | 'continuous'
+/** The load failed; {@link ChartDataModel.notice} says why. */
+ | 'failed'
+/** A newer load (or a dataset switch) overtook this one: nothing to do. */
+ | 'superseded';
+/** What the renderer draws from: everything loaded for the current dataset. */
+export interface ChartData {
+    /** The colour source's values, when it is continuous. */
+    values: Float32Array | null;
+    /** The colour source's categories, when it is a categorical column. */
+    categorical: OmicsGrouping | null;
+    /** The grouping column the violin, box and heatmap split by. */
+    grouping: OmicsGrouping | null;
+    groupBy: string | null;
+    /** The heatmap's genes that have their vectors, in row order. */
+    heatmapRows: {
+        name: string;
+        values: Float32Array;
+    }[];
+    /** The drawn embedding's coordinates, once loaded. */
+    embeddingCoords: SpatialEmbedding | null;
+}
+/**
+ * The data the spatial charts draw, and its loading: the colour source's vector (or its
+ * categories), the grouping column, the heatmap's gene vectors, and the embedding's
+ * coordinates.
+ *
+ * Each load has its OWN {@link Supersede}: on one shared counter a redraw for a selection
+ * change dropped a pending colour-source load (SPATIAL-2), and a busy flag per load, since
+ * a shared one was left set by whichever load lost its race. A dataset switch
+ * ({@link onDatasetChanged}) cancels all of them together and drops every vector, because
+ * each is indexed by the previous dataset's observations (SPATIAL-1).
+ *
+ * Plain class: the component asks it to load, then renders {@link snapshot}.
+ */
+export declare class ChartDataModel {
+    /** Categorical column the violin/box (and heatmap) split by; null = one trace for all. */
+    groupBy: string | null;
+    groupOptions: {
+        label: string;
+        value: string | null;
+    }[];
+    /**
+     * Genes the heatmap's rows are. Local rather than in `SpatialViewState`, as the chart
+     * kind is: this is what the panel is charting, not what the map is drawing.
+     */
+    heatmapGenes: string[];
+    geneOptions: {
+        label: string;
+        value: string;
+    }[];
+    /** Embeddings to offer, and which of them is drawn. */
+    embeddings: SpatialEmbeddingMeta[];
+    embedding: SpatialEmbeddingMeta | null;
+    embeddingCoords: SpatialEmbedding | null;
+    /** Set when something cannot be charted, for an inline hint. */
+    notice: string | null;
+    private values;
+    /** Set instead of `values` when the colour source is a categorical column: its
+     *  distribution is counts per category, not a histogram of its codes. */
+    private categorical;
+    private grouping;
+    /** Every gene the dataset inlined. `geneOptions` is only ever the best few hundred of
+     *  these — see `gene-search.ts` for why a whole-transcriptome list cannot be handed to
+     *  the control whole. */
+    private geneNames;
+    /** What is typed in the picker's filter box, so the options can be rebuilt when the
+     *  selection changes without losing the query. */
+    private geneQuery;
+    /** Fetched vectors by gene name, so adding a fourth gene does not refetch the first
+     *  three — each is a full per-observation Float32Array. */
+    private readonly geneCache;
+    private valueBusy;
+    private heatmapBusy;
+    private embeddingBusy;
+    /** Guards the colour-source fetch: a fast colour-source change can resolve out of order,
+     *  and a stale vector would be charted against the new label. */
+    private readonly valueLoad;
+    /** The same for the grouping, which the user can change as fast. */
+    private readonly groupLoad;
+    private readonly heatmapLoad;
+    private readonly embeddingLoad;
+    /** The dataset the loaded vectors belong to; `undefined` before the first. */
+    private datasetId;
+    /** A load is in flight. */
+    get busy(): boolean;
+    /** Whether the colour source is a categorical column (with its categories loaded). */
+    get isCategorical(): boolean;
+    /** Whether a grouping column's categories are loaded. */
+    get hasGrouping(): boolean;
+    /** What the renderer draws from. */
+    snapshot(): ChartData;
+    /**
+     * A dataset emission: its grouping columns, gene names and the embeddings to offer.
+     *
+     * @returns true when this is a SWITCH from another dataset. Every vector loaded so far is
+     *   then dropped and every load still running for the old dataset cancelled; the caller
+     *   must reload the colour source (and the grouping), because a port may go straight from
+     *   one dataset to the next with a colour source of the same name, so the view need not
+     *   re-emit.
+     */
+    onDatasetChanged(dataset: SpatialDataset | null, categoricalColumns: readonly string[], embeddings: SpatialEmbeddingMeta[]): boolean;
+    /** Fetch the colour source's vector — or, for a categorical column, its categories. */
+    loadValues(controls: ISpatialControls | null, source: SpatialColorBy | null): Promise<ValueLoad>;
+    /**
+     * Group by `name` (null for none), fetching its categories.
+     *
+     * @returns false when a later choice overtook this one — sequenced, because picking A
+     *   then B with a slower A would otherwise chart A's categories under a dropdown that
+     *   says B. A failure falls back to no grouping.
+     */
+    loadGrouping(controls: ISpatialControls | null, name: string | null): Promise<boolean>;
+    /** The heatmap's rows. Chosen genes stay among the options, or the control cannot label
+     *  its chips. */
+    setHeatmapGenes(names: string[] | null): void;
+    /** The gene picker's filter box changed: search the resident names, show the best. */
+    filterGenes(query: string | null): void;
+    /**
+     * Fetch any gene the heatmap needs and does not already hold.
+     *
+     * Sequenced: each vector is a separate request, and a slower one must not paint rows
+     * for a gene list the user has already moved on from — nor land in the cache of a
+     * dataset it was not fetched for.
+     */
+    loadHeatmapGenes(controls: ISpatialControls | null): Promise<void>;
+    /** Draw `name` next, when the dataset offers it. @returns whether the choice changed. */
+    selectEmbedding(name: string): boolean;
+    /**
+     * The coordinates for `meta`: kept when already loaded, else fetched — sequenced, as a
+     * slower round-trip must not paint over an embedding the user has already moved on from.
+     *
+     * @returns whether they are ready to draw ('failed' has set {@link notice}).
+     */
+    loadEmbedding(getEmbedding: (name: string) => Promise<SpatialEmbedding>, meta: SpatialEmbeddingMeta): Promise<'ready' | 'failed' | 'superseded'>;
+    /**
+     * Supersede any embedding load in flight without starting one — for a draw that needs
+     * no fetch (computed here, or still to be computed), which a slower fetch must not
+     * overwrite.
+     */
+    supersedeEmbeddingLoad(): void;
+    private refreshGeneOptions;
+}