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

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

@@ -0,0 +1,111 @@
+/**
+ * Mean expression per group, for the gene × class heatmap.
+ *
+ * A scatter coloured by one gene answers "where is this gene". It cannot answer
+ * "which classes express which genes", which is the question a marker panel is
+ * actually read for — and the standard object for that is the mean-expression
+ * matrix per cluster (scanpy's `matrixplot`/`dotplot`), genes against classes.
+ *
+ * Deliberately NOT cells × genes at the full dataset: 374k columns is not a
+ * heatmap. Cells become columns only inside a selection, where a few thousand
+ * of them render and the question changes to "what is in this region".
+ *
+ * Two things this has to get right to be readable:
+ *
+ *  - A cell with no measurement for a gene (`NaN`) is SKIPPED, not counted as
+ *    zero. Counting it would drag a group's mean towards absence for a reason
+ *    that has nothing to do with the biology.
+ *  - Z-scoring is per GENE, across groups. Without it a gene expressed an order
+ *    of magnitude above the others saturates the colour scale and the rest of
+ *    the panel reads as uniformly blank — the matrix would show which gene is
+ *    loudest rather than which class expresses what.
+ *
+ * Pure — no Angular, no Plotly, no renderer — like `spatial-density.ts`, and
+ * tested the same way.
+ */
+/** One gene's values, with the name to label its row. */
+export interface HeatmapGene {
+    name: string;
+    /** One value per observation; `NaN` where the gene was not measured. */
+    values: Float32Array;
+}
+/** The columns to aggregate into: a categorical column's categories. */
+export interface HeatmapGroups {
+    /** Per-observation category index, or {@link NO_CATEGORY}. */
+    codes: Uint16Array;
+    categories: readonly string[];
+}
+export interface HeatmapMatrixOptions {
+    /** Observations to include; every one when absent (an ROI selection). */
+    indices?: Uint32Array;
+    /**
+     * Z-score each gene across the groups, so one loud gene cannot flatten the
+     * panel. On by default — the raw means are only readable when every gene is
+     * on a comparable scale.
+     */
+    zScore?: boolean;
+    /** Drop groups with fewer than this many measured cells. A mean over one or
+     *  two cells is noise presented with the same weight as a real one. */
+    minCells?: number;
+    /**
+     * Keep at most this many columns, chosen by the STRONGEST signal any picked
+     * gene shows in them.
+     *
+     * `subclass` has 338 categories. Drawn in full that is a texture rather than a
+     * panel — every column a couple of pixels wide, every label unreadable — and
+     * the question being asked ("which groups express my genes") is answered by
+     * the handful of groups where a gene actually stands out. Ranking by
+     * max |value| across the rows surfaces exactly those; ranking by cell count
+     * would instead surface the biggest groups, which is a different question.
+     *
+     * Unset keeps every column that cleared `minCells`.
+     */
+    maxCols?: number;
+}
+export interface HeatmapMatrix {
+    /** Gene names, one per row, in the order given. */
+    rows: string[];
+    /** Columns dropped by `maxCols`, so the caller can say how many are hidden
+     *  rather than silently showing a subset as if it were everything. */
+    hiddenCols: number;
+    /** Group labels, one per column — only the groups that survived `minCells`. */
+    cols: string[];
+    /**
+     * `rows.length × cols.length`, row-major: `values[r * cols.length + c]`.
+     * `NaN` where a group had nothing measured for that gene, which the caller
+     * draws as a gap rather than as a zero.
+     */
+    values: Float32Array;
+    /** Measured cells behind each column, index-aligned with {@link cols}. */
+    counts: Uint32Array;
+    /** Finite range of `values`, for a symmetric or absolute colour scale. */
+    range: [number, number];
+}
+/** Default floor for a group to earn a column. */
+export declare const HEATMAP_MIN_CELLS = 3;
+/**
+ * Mean expression of each gene in each group.
+ *
+ * Null when nothing survives — no genes, no groups, or every group filtered
+ * out — so the caller draws no chart rather than an empty grid.
+ */
+export declare function heatmapMatrix(genes: readonly HeatmapGene[], groups: HeatmapGroups, opts?: HeatmapMatrixOptions): HeatmapMatrix | null;
+/**
+ * Groups standing in for individual cells, for the in-selection view.
+ *
+ * Inside an ROI, "which classes express what" is often the wrong question and
+ * "what is in front of me" is the right one — so each cell becomes its own
+ * column. Capped: past a few hundred columns a heatmap is a texture, not a
+ * readable panel, and the cap is applied by even thinning so the selection is
+ * still represented across its whole extent rather than truncated to its first
+ * cells.
+ *
+ * NOTE: every column here holds exactly ONE cell, so the caller must pass
+ * `minCells: 1` to {@link heatmapMatrix}. The default floor of
+ * {@link HEATMAP_MIN_CELLS} exists to suppress noisy group means and would
+ * filter out every column of this view, returning null.
+ */
+export declare function cellsAsGroups(indices: Uint32Array, observationCount: number, max?: number): {
+    groups: HeatmapGroups;
+    indices: Uint32Array;
+};

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

@@ -0,0 +1,49 @@
+/**
+ * What is under the cursor, and what to say about it.
+ *
+ * A coloured cloud answers "how is this annotation distributed"; it cannot answer
+ * "which class is THAT" — the legend has 34 entries, several of them similar
+ * colours, and matching a dot to a swatch by eye is exactly the task a tooltip
+ * exists to remove.
+ *
+ * Pure — no DOM, no camera, no data access. The renderer supplies screen
+ * positions (it owns the projection) and the active colour source; everything
+ * here is arithmetic and string formatting, so it is tested directly.
+ */
+/** The colour source a tooltip describes, as the renderer already has it. */
+export type HoverSource = {
+    kind: 'categorical';
+    /** Column name, for the tooltip's first line. */
+    name: string;
+    categories: readonly string[];
+    /** Per-observation category index, or `NO_CATEGORY`. */
+    codes: Uint16Array;
+} | {
+    kind: 'continuous';
+    /** Column or gene name. */
+    name: string;
+    values: Float32Array;
+    /** Unit for the value, when the dataset declares one. */
+    unit?: string;
+};
+/**
+ * Index of the drawn observation nearest `(x, y)` within `maxDist` screen pixels,
+ * or -1.
+ *
+ * `screen` is `[x0, y0, x1, y1, …]` indexed BY OBSERVATION, with NaN for anything
+ * not currently drawn — off screen, behind the eye, or on a hidden section. NaN
+ * fails every comparison, so those are skipped without a special case.
+ *
+ * Ties go to the LATER observation, which is the one drawn on top and therefore
+ * the one the user believes they are pointing at.
+ */
+export declare function nearestObservation(screen: Float32Array, x: number, y: number, maxDist: number): number;
+/**
+ * The tooltip's lines for one observation: what it is, then which column said so.
+ *
+ * Null when the source cannot describe this observation — a code outside the
+ * category list, or a value that was never measured. Saying nothing is better
+ * than a tooltip that reads "undefined", and better than inventing a label for a
+ * cell whose annotation is genuinely missing.
+ */
+export declare function hoverText(source: HoverSource | null, index: number): string[] | null;

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

@@ -0,0 +1,59 @@
+import { SpatialObservations } from '../contracts/spatial-dataset.contract';
+/**
+ * The planes a **serially sectioned** dataset was actually imaged at.
+ *
+ * A 3D spatial-omics dataset of this kind is not a cloud that happens to have a z:
+ * it is a stack of thin sections, hundreds of microns apart, each one a separate
+ * slide. Every observation on a given slide shares that slide's registered z
+ * exactly, so the distinct z values ARE the sections — no binning, no tolerance,
+ * and no need for a dataset-specific section-label column.
+ *
+ * That matters for the 3D view, where the cloud reads as a stack of discs and the
+ * discs hide the density volumes drawn between them. Being able to show one
+ * section's cells against the estimated field is how you check the estimate against
+ * the measurement; being able to hide them is how you see the field at all.
+ *
+ * Deliberately NOT a binning of a continuous z (that is
+ * `observationsInSlice`'s job, against a volume's voxel planes). If the z is
+ * continuous rather than sectioned there are no sections to offer, and
+ * {@link sampledSections} says so by returning null rather than inventing some.
+ *
+ * Pure — no Angular, no GPU — like `spatial-density.ts`, and tested the same way.
+ */
+/**
+ * Distinct z values beyond which the data is treated as continuous rather than
+ * sectioned. Serial sectioning runs to tens or low hundreds of slides (53 for the
+ * ABC whole-brain MERFISH atlas); a z that keeps producing new values is a
+ * measurement axis, and a "pick one section" control over it would be a lie.
+ */
+export declare const MAX_SAMPLED_SECTIONS = 512;
+/**
+ * The dataset's sampled section positions, ascending — or null when it has no z,
+ * no observations, or a z too finely divided to be sections at all.
+ *
+ * Bails out as soon as the distinct count passes `max`, so a continuous z costs one
+ * partial pass rather than a set with one entry per observation.
+ */
+export declare function sampledSections(obs: SpatialObservations, max?: number): Float32Array | null;
+/**
+ * Indices of the observations lying on one sampled section.
+ *
+ * Exact equality on purpose: `z` comes from {@link sampledSections}, which read the
+ * values out of this same array, so the comparison cannot drift. Passing a z that
+ * is not one of the sampled positions yields nothing, which is the honest answer.
+ */
+export declare function observationsInSection(obs: SpatialObservations, z: number): Uint32Array;
+/**
+ * {@link sampledSections} for a dataset's observations, computed once.
+ *
+ * Both the renderer (which filters the cloud's geometry to one section) and the
+ * control panel (which offers the sections to pick from) need this list, and the
+ * scan reads the z of up to 3.7M observations — so it is memoized on the
+ * observations object itself rather than each caller keeping its own copy keyed by
+ * a dataset id it has to remember to invalidate. Still referentially transparent:
+ * the same observations always give the same sections.
+ *
+ * Default `max` only; a caller wanting a different cap should call
+ * {@link sampledSections} directly and cache it itself.
+ */
+export declare function sectionsOf(obs: SpatialObservations): Float32Array | null;

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

@@ -0,0 +1,113 @@
+import { Region } from '../models/region';
+import { SpatialImageRef, SpatialObservations } from '../contracts/spatial-dataset.contract';
+/**
+ * Which observations fall inside a set of drawn regions.
+ *
+ * Pure, like `spatial-encoding.ts` — no store, no renderer — so the geometry is
+ * testable on its own.
+ *
+ * WHY THIS IS THE WHOLE SELECTION MECHANISM
+ * -----------------------------------------
+ * Regions already come from every on-canvas tool the library has: rectangle,
+ * polygon, freehand, magic wand, brush. Testing observations against them turns
+ * all of those into spatial-omics selection tools without adding a single new
+ * canvas interaction — which is why there is no bespoke marquee here.
+ *
+ * COORDINATE FRAMES
+ * -----------------
+ * Regions are drawn in WORLD (image) coordinates. Observations live in the
+ * dataset's own frame and reach the world through `imageRef` — so they are
+ * transformed forward before testing, matching exactly what the renderer draws.
+ */
+/** A selection over N observations: `mask[i] === 1` when i is selected. */
+export interface SpatialSelectionMask {
+    mask: Uint8Array;
+    count: number;
+}
+/** An empty selection over `count` observations. */
+export declare function emptySelection(count?: number): SpatialSelectionMask;
+/** Number of set entries in a mask. */
+export declare function countMask(mask: Uint8Array): number;
+/** Selected indices, for export or a downstream query. */
+export declare function maskToIndices(mask: Uint8Array): Uint32Array;
+/**
+ * Renderer-facing inverse: which observations to MUTE. With nothing selected
+ * nothing is muted (the whole tissue reads normally); with a selection, every
+ * unselected observation is muted — the CosMx highlight-vs-mute rule.
+ */
+export declare function mutedFromSelection(selection: SpatialSelectionMask): Uint8Array | null;
+/** Even-odd ray cast: is (px, py) inside the closed ring xs/ys? */
+export declare function pointInRing(xs: readonly number[], ys: readonly number[], px: number, py: number): boolean;
+/** Axis-aligned bounds of a ring, for a cheap reject before the ray cast. */
+interface Bounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+/** A region flattened to something testable: bounds + a hit test. */
+interface Shape {
+    bounds: Bounds;
+    hit(px: number, py: number): boolean;
+}
+/**
+ * Flatten a region to testable shapes. Returns an empty array for anything that
+ * encloses no area — an open polyline, an intensity-profile line, a degenerate
+ * rectangle — so those never contribute to a selection.
+ */
+export declare function regionShapes(region: Region): Shape[];
+/**
+ * Observations inside ANY of `regions` (union). Coordinates are transformed by
+ * `imageRef` first, so the test happens in the same world space the regions were
+ * drawn in.
+ *
+ * `candidates`, when given, restricts the test to those observation indices — how
+ * a 2D view of a 3D dataset keeps a drawn region meaning what it looks like it
+ * means: the shape was drawn over ONE section, so it selects that section's cells
+ * rather than the whole depth of the specimen behind them. The returned mask stays
+ * indexed by observation, so every consumer (charts, legend, the 3D cloud) reads it
+ * the same way.
+ */
+/**
+ * A selection from an explicit list of observation indices.
+ *
+ * What a lasso in a linked plot produces: the plot knows which points the user drew
+ * around, and the map needs that as a mask over ALL observations. Out-of-range and
+ * duplicate indices are ignored rather than rejected — a plot may hand back the same
+ * point twice, and a stale index from a plot drawn before a dataset change must not
+ * throw in the middle of a selection gesture.
+ */
+export declare function selectByIndices(indices: Iterable<number>, observationCount: number): SpatialSelectionMask;
+export declare function selectInRegions(observations: SpatialObservations, imageRef: SpatialImageRef | undefined, regions: readonly Region[], candidates?: Uint32Array): SpatialSelectionMask;
+/**
+ * Select observations whose SCREEN projection falls inside the drawn regions.
+ *
+ * This is how a region selection works in the 3D cloud. There is no data-space
+ * affine to map a drawn shape through, because the shape was drawn on a 2D screen
+ * against a perspective camera — so the observations come the other way, already
+ * projected to canvas pixels by the renderer (which owns the camera), and the
+ * regions are tested in that same screen space.
+ *
+ * The consequence is worth being explicit about: a screen-space lasso selects
+ * through the WHOLE DEPTH of the cloud, like a cookie cutter, not a slab at some
+ * chosen z. That is inherent to drawing on a flat screen, and it is what napari
+ * and every other orbit-camera point picker do. Orbit and draw again to cut from
+ * another angle.
+ *
+ * `screen` is `[x0, y0, x1, y1, …]` in canvas pixels, `count` entries long. An
+ * observation the camera puts behind the eye is given NaN by the projector and
+ * never selected.
+ */
+export declare function selectInRegionsProjected(screen: Float32Array, count: number, regions: readonly Region[]): SpatialSelectionMask;
+/** Every observation whose categorical code equals `code` — the legend click. */
+/**
+ * Whether two selections hold exactly the same observations.
+ *
+ * Lets a click toggle against the SELECTION rather than against a remembered
+ * click: picking a class in the legend and then clicking that same class on the
+ * canvas should clear it, and a remembered click cannot know about the legend.
+ * Counts are compared first, so two different selections usually cost nothing.
+ */
+export declare function sameSelection(a: SpatialSelectionMask, b: SpatialSelectionMask): boolean;
+export declare function selectByCategory(codes: Uint16Array, code: number): SpatialSelectionMask;
+export {};

package/lib/spatial/spatial-volume-image.d.ts

@@ -0,0 +1,67 @@
+import { IImageInfo } from '../contracts/image.contract';
+import { SpatialDataset, SpatialImageRef, SpatialObservations, SpatialVolumeMeta } from '../contracts/spatial-dataset.contract';
+/**
+ * A dataset's reference volume, encoded as the z-stack image the 2D path renders,
+ * plus the blob URLs backing it.
+ *
+ * The URLs belong to the CALLER: nothing else can know when the image stops being
+ * displayed, and a dataset switch that forgets to revoke them leaks a volume's
+ * worth of PNGs per switch.
+ */
+export interface VolumeStackImage {
+    info: IImageInfo;
+    urls: string[];
+}
+/**
+ * Turn a spatial dataset's registered volume into a scrubbable z-stack image.
+ *
+ * A 3D omics dataset arrives as one volume and NO `imageRef`, so there is no image
+ * behind it — which left every image-shaped surface (the Image view, the slice
+ * bar, the contrast window, regions) with nothing to work on, and the Image view
+ * showing whatever slide happened to be loaded before. Encoding each z plane as a
+ * blob PNG makes the volume itself the image, so the existing stack machinery
+ * drives it unchanged: the same `urls[z]` + `isStack` shape a host emits for a
+ * multi-page TIFF, which is exactly what this volume is.
+ *
+ * Every plane is encoded up front rather than on demand, because the slice count
+ * comes from `urls.length` — the component has to know the depth before the user
+ * scrubs. The voxels are already resident (megabytes, fetched in one call), and a
+ * plane is a few KB of PNG, so the cost is bounded by the volume the host already
+ * chose to fetch.
+ *
+ * Returns null when the dataset declares no volume, or the byte count contradicts
+ * the declared geometry — a short buffer would silently produce slices of shifted
+ * anatomy, which is worse than no image at all.
+ */
+export declare function buildVolumeStackImage(dataset: SpatialDataset, voxels: Uint8Array): Promise<VolumeStackImage | null>;
+/**
+ * The data→image affine a registered volume implies.
+ *
+ * Once the volume IS the image ({@link buildVolumeStackImage}), one slice is a
+ * `width x height` pixel grid whose voxel `(i, j)` covers
+ * `[i * voxelSize[0], (i + 1) * voxelSize[0])` of the observations' coordinate
+ * space — the contract's rule that the volume's near corner sits at the
+ * coordinate origin. So observations reach pixel space by dividing out the voxel
+ * size, and nothing has to move.
+ *
+ * Shaped as a `SpatialImageRef` on purpose: the marker layer and the ROI
+ * selection then take the SAME transform they take for a dataset that ships a
+ * real `imageRef`, instead of each growing a volume special case.
+ */
+export declare function volumeImageRef(volume: SpatialVolumeMeta, micronsPerUnit?: number): SpatialImageRef;
+/** The voxel plane a coordinate falls in, clamped into the volume. */
+export declare function sliceIndexOf(z: number, volume: SpatialVolumeMeta): number;
+/**
+ * Indices of the observations that fall in one voxel plane of the volume.
+ *
+ * A 2D view of a 3D dataset shows ONE plane, so it must draw one plane's
+ * observations: without this the whole depth of the specimen piles onto a single
+ * section and reads as a solid smear rather than a section's cells. The plane is
+ * a slab `voxelSize[2]` thick, which is exactly the sampling the volume itself
+ * has — for serial sections registered into a common frame, one slab is one
+ * section.
+ *
+ * Every observation is in the plane when the dataset carries no z: a genuinely
+ * flat dataset over a volume has nothing to filter on.
+ */
+export declare function observationsInSlice(obs: SpatialObservations, volume: SpatialVolumeMeta, slice: number): Uint32Array;

package/lib/spatial/tsne-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Factory for the t-SNE Web Worker, isolated in its own module so the `import.meta.url`
+ * reference — which the bundler needs in order to locate the worker — is never pulled
+ * into the ts-jest CommonJS compile of anything that uses it. Unit tests `jest.mock` this
+ * module, or pass their own factory. Same arrangement as `mask-worker.ts`.
+ */
+export declare function createTsneWorker(): Worker;

package/lib/spatial/world-grid.d.ts

@@ -0,0 +1,58 @@
+/**
+ * How finely a drawn shape's vertices may be placed in world space.
+ *
+ * Region geometry has always been stored in whole world units, and for an image that is
+ * exactly right: world units ARE pixels, a region should align to them, and integers keep
+ * the stored geometry exact and tidy.
+ *
+ * It is wrong for a dataset whose coordinates are not pixels. seqFISH's observations span
+ * about 5 x 7 units in total, so snapping vertices to integers leaves roughly SIX BY EIGHT
+ * distinct positions in the whole sample — every ROI collapses to the same handful of
+ * boxes and drawing a fine shape is not possible at any zoom. Nothing errors; the tool
+ * simply cannot express what the user is drawing.
+ *
+ * So the step is chosen from the world's own extent rather than assumed to be one. An
+ * image keeps integers, because its extent is thousands of units and a finer step would
+ * buy nothing; a unitless dataset gets a step fine enough to draw with.
+ *
+ * Pure — no renderer, no store — so both region overlays can share one answer, and the
+ * napari and OSD paths cannot drift into disagreeing about what a vertex may be.
+ */
+/** One world unit: the step for a world whose units are image pixels. */
+export declare const PIXEL_WORLD_QUANTUM = 1;
+/**
+ * Distinct positions a drawn shape should be able to reach across the world's extent.
+ *
+ * Set by what a person can actually place with a pointer, not by float precision: a few
+ * thousand steps across the sample is finer than any screen it will be drawn on, so the
+ * limit stops being the grid and becomes the hand.
+ */
+export declare const WORLD_GRID_STEPS = 4096;
+/**
+ * The step size for a world of this extent, for a world whose units are NOT pixels.
+ *
+ * The caller decides which world it has, because the extent cannot say: a 2,000 unit world
+ * is a small slide if the units are pixels and an enormous one if they are microns, and
+ * only the caller knows which. An image keeps {@link PIXEL_WORLD_QUANTUM} by never asking.
+ *
+ * Never returns anything coarser than {@link PIXEL_WORLD_QUANTUM}. A non-pixel world can
+ * still be large — the Allen atlas is ~11,000 microns across — and there a finer step than
+ * one unit buys nothing.
+ *
+ * Rounded DOWN to a power of ten, so the step is a number a person reading the stored
+ * geometry can recognise — 0.001 rather than 0.0017044 — and so it does not shift when the
+ * extent changes slightly between datasets.
+ *
+ * A non-finite or empty extent falls back to the pixel grid: an unknown world is treated
+ * as the conservative, established case rather than given an invented precision.
+ */
+export declare function worldQuantumForExtent(spanX: number, spanY: number): number;
+/**
+ * Snap one world coordinate to the grid.
+ *
+ * A step of zero or less means no snapping — the caller keeps full float precision.
+ * Division and multiplication by the step leaves a float artefact (0.001 * 3 is not
+ * exactly 0.003), so the result is rounded to the step's own number of decimals; without
+ * that, "tidy" geometry acquires a trail of digits the grid was supposed to remove.
+ */
+export declare function snapToWorldGrid(value: number, quantum: number): number;