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

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

@@ -0,0 +1,38 @@
+/**
+ * Loads in flight, per layer label ("Transcripts", "Cells"…), for the canvas loading badge.
+ * Shared by every plan: a label stays reported while any plan still loads it.
+ */
+export declare class LoadTracker {
+    private readonly changed;
+    private readonly loading;
+    constructor(changed: (labels: string[]) => void);
+    /** Report `label` loading while `work` is in flight. */
+    track<T>(label: string, work: Promise<T>): Promise<T>;
+    /** Forget every load (the viewer went away) and report none. */
+    clear(): void;
+}
+/**
+ * One run of `NapariSpatialTileLayers.plan()`. Completeness belongs to the run that did the
+ * fetching: on the instance, a superseded run's failed tile marked the CURRENT run incomplete,
+ * which then skipped caching its keys and retried for nothing (review NAPARI-BOUNDARY-9).
+ */
+export declare class PlanContext {
+    private readonly isStale;
+    private readonly loads;
+    private failed;
+    /** `isStale` turns true once a newer plan started or the viewer changed. */
+    constructor(isStale: () => boolean, loads: LoadTracker);
+    /** True once a newer plan started or the viewer changed. */
+    stale(): boolean;
+    /** Set when a fetch of this run failed (see fetchAll): don't cache it as done; retry. */
+    get incomplete(): boolean;
+    /** A request of this run failed: what it drew must not be cached as done. */
+    markIncomplete(): void;
+    /** Report `label` loading while `work` is in flight. */
+    track<T>(label: string, work: Promise<T>): Promise<T>;
+    /**
+     * Fetch every tile, drawing what arrived. A failure does not fail the view, but it marks this
+     * run incomplete: the caller must not cache it as done, and `plan()` retries it.
+     */
+    fetchAll<K, T>(keys: K[], load: (k: K) => Promise<T>): Promise<T[]>;
+}

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

@@ -0,0 +1,71 @@
+import type { PointsLayer } from 'napari-js';
+import type { SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
+import { SpatialTranscriptTile } from '../../../contracts/spatial-dataset.contract';
+import type { CategoricalCodes } from './categorical-lookup';
+/** What one transcript entry is — decides what hovering it says. */
+export type TranscriptKind = 'genes' | 'individual' | 'bins';
+/** A bin grid: its size and origin, so a hovered bin's square can be recovered. */
+export interface TranscriptBin {
+    size: number;
+    origin: [number, number];
+}
+/**
+ * Tooltips for the transcript markers of the 2D spatial view.
+ *
+ * Reads only what the transcript layer last drew — handed over one way through
+ * {@link setDrawn} / {@link setTypes} — and asks the server for the slower details (distinct
+ * genes in a group, its top genes and cells, the cell's display id) once the pointer has
+ * rested on a marker, caching them until the next draw.
+ */
+export declare class TranscriptHover {
+    private readonly port;
+    private readonly layerShown;
+    /** What the transcript layer currently shows (written by drawing, read by hover). */
+    private drawn;
+    /** The cell-type column, to name the cell a marker is in. */
+    private types;
+    /** µm per observation unit of the drawn dataset, for describing a grouped marker's area. */
+    private micronsPerUnit;
+    /** Details already fetched, by hovered entry. */
+    private readonly cache;
+    private key;
+    private timer;
+    /** `layerShown` says whether the transcript layer is on screen now (it may have been dropped). */
+    constructor(port: SpatialDataPort, layerShown: () => boolean);
+    /** The transcript layer was redrawn: hover names these entries now (cached details are dropped). */
+    setDrawn(drawn: DrawnTranscripts, micronsPerUnit: number | null): void;
+    /** The cell-type column the drawn entries' cells are named by, or null. */
+    setTypes(types: CategoricalCodes | null): void;
+    /** Nothing is drawn any more. */
+    clear(): void;
+    /** Stop a pending details request and forget what was drawn. */
+    dispose(): void;
+    /**
+     * Tooltip lines for the transcript marker under world point `(wx, wy)`, or null.
+     *
+     * The marker is napari-js's pick on the drawn layer: hit anywhere on it, or within
+     * `radiusWorld` of its centre when it is smaller than that, the NEAREST centre winning
+     * among several (an exact tie, such as two genes' groups on one bin centre, goes to the one
+     * drawn on top). 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;
+}
+/** What the transcript layer currently shows — what hovering needs to name a marker. */
+export interface DrawnTranscripts {
+    kind: TranscriptKind;
+    bin?: TranscriptBin;
+    merged: SpatialTranscriptTile;
+    /** The layer the entries are drawn in, one marker per entry in the same order. */
+    layer: PointsLayer;
+    genes: string[];
+    /** 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[][];
+}

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

@@ -0,0 +1,105 @@
+import { type SpatialDataPort } from '../../../contracts/ports/spatial-data.port';
+import type { SpatialViewState } from '../../../contracts/display-types';
+import { SpatialDataset, SpatialTranscriptTile } from '../../../contracts/spatial-dataset.contract';
+import { DataRect } from '../../../spatial/lod';
+import type { PlanContext } from './plan-context';
+import type { TranscriptBin, TranscriptKind } from './transcript-hover';
+/** A transcript fetch the planner can key before running. */
+export interface TranscriptJob {
+    /** What one entry is — decides what hovering it says. */
+    kind: TranscriptKind;
+    /** For bins: their size and grid origin, so a hovered bin's square can be recovered. */
+    bin?: TranscriptBin;
+    /** 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(ctx: PlanContext): Promise<TranscriptLoad>;
+}
+export 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'];
+}
+/**
+ * Decides which transcripts the 2D spatial view fetches, at which level, for the current
+ * camera and selection: a {@link TranscriptJob} that can be keyed before it runs (so an
+ * unchanged plan is a no-op) and that fetches and merges when run.
+ *
+ * Pure apart from the port, so the level policy is testable without a viewer. Owns the
+ * cache of summed per-cluster density grids a zoomed-out gene selection is drawn from.
+ */
+export declare class TranscriptJobPlanner {
+    private readonly port;
+    /** Summed per-cluster density grids (see densityFor). */
+    private readonly densityCache;
+    constructor(port: SpatialDataPort);
+    /**
+     * The job that draws the view's transcripts as markers (circles or icons), or null when the
+     * view draws none or the port cannot serve them.
+     */
+    jobFor(dataset: SpatialDataset, view: SpatialViewState, rect: DataRect, pxPerUnit: number): TranscriptJob | null;
+    /**
+     * 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.
+     * Least-recently-USED eviction, so the clusters in view stay cached; a failed request is
+     * dropped so the next plan asks again.
+     */
+    private densityFor;
+    /**
+     * 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;
+}
+/**
+ * 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.
+ */
+export declare function groupSelection(t: SpatialTranscriptTile, view: SpatialViewState, ladder: NonNullable<TranscriptLoad['ladder']>, pxPerUnit: number): {
+    merged: SpatialTranscriptTile;
+    px: Float32Array;
+    bin: number;
+    group: Int32Array;
+    names: string[];
+} | null;

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

@@ -0,0 +1,56 @@
+import type { PointSymbol } from 'napari-js';
+import type { SpatialViewState } from '../../../contracts/display-types';
+import { SpatialDataset } from '../../../contracts/spatial-dataset.contract';
+import { DataRect } from '../../../spatial/lod';
+import { TranscriptGlyph } from '../../../spatial/glyphs';
+import type { CategoricalLookup } from './categorical-lookup';
+import type { OrderedLayerGroups, TileGroup } from './layer-groups';
+import type { PlanContext } from './plan-context';
+import type { TranscriptHover } from './transcript-hover';
+import { type TranscriptJobPlanner } from './transcript-jobs';
+/**
+ * The napari-js point symbol each transcript icon is drawn as. Every icon has a counterpart of
+ * the same outline (`circle` is napari's `disc`); see {@link GLYPH_SIZE} for the one whose size
+ * differs.
+ */
+export declare const GLYPH_SYMBOLS: Readonly<Record<TranscriptGlyph, PointSymbol>>;
+/**
+ * The transcript markers of the 2D spatial view: runs the planner's job, drops hidden groups
+ * and genes, groups a selection under the marker budget, colours the entries and draws them as
+ * one points layer: sized circles, or gene icons as per-point symbols (with a dark rim while
+ * there are few enough).
+ *
+ * Hands what it drew to the hover one way ({@link TranscriptHover.setDrawn}), and keeps the
+ * loaded per-gene transcripts the in-view gene counts are taken from.
+ */
+export declare class TranscriptLayers {
+    private readonly groups;
+    private readonly jobs;
+    private readonly lookup;
+    private readonly hover;
+    /** The loaded per-gene transcripts the in-view counts are taken from. */
+    private countSource;
+    constructor(groups: OrderedLayerGroups<TileGroup>, jobs: TranscriptJobPlanner, lookup: CategoricalLookup, hover: TranscriptHover);
+    /**
+     * 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;
+    /** The viewer went away: no counts until the next plan. */
+    detached(): void;
+    /** Draw the view's transcript markers (or drop them); an unchanged plan key is a no-op. */
+    plan(dataset: SpatialDataset, view: SpatialViewState, rect: DataRect, pxPerUnit: number, ctx: PlanContext): Promise<void>;
+    /**
+     * Gene icons: each entry drawn as its gene's napari-js point symbol, in the same one points
+     * layer as the circles. With every gene drawn there is one icon for all of them — 18,000
+     * shapes would say nothing.
+     */
+    private drawTranscriptGlyphs;
+    /**
+     * The one transcripts layer: a marker per entry, `size` saying how many transcripts it stands
+     * for, drawn as the layer's disc or as each entry's `symbols` code.
+     */
+    private drawTranscripts;
+    /** Per-entry colours, as packed RGBA. */
+    private transcriptColors;
+}

package/lib/implementations/osd/display-pipeline.d.ts

@@ -4,8 +4,8 @@ import { Rgb } from '../../contracts/colormap-lut';
  * The OSD pixel display pipeline (refactoring plan, Step 4 — a pure move of
  * the recolor math out of the visualizer service). Stateless: every call reads
  * the current display state through the host closures, exactly like the moved
- * code read the service's fields. Shared by tile recoloring and the composite
- * export so they stay identical.
+ * code read the service's fields. Shared by tile recoloring, the serverless
+ * multichannel compositor and the composite export so they stay identical.
  */
 export interface DisplayPipelineHost {
     /** Grayscale image (colormap LUT path) vs RGB/multichannel (additive tint). */
@@ -23,25 +23,54 @@ export declare class DisplayPipeline {
     /**
      * Apply the current display pipeline to an RGBA buffer in place; returns
      * whether any opaque pixel was written.
-     *  - Grayscale: intensity → window + gamma + invert → colormap LUT.
+     *  - Grayscale: intensity → window → invert → gamma → colormap LUT.
      *  - RGB/multichannel: additive pseudo-colour merge — each visible channel's
-     *    windowed intensity is tinted by its assigned colour and summed (Fiji
-     *    "Merge Channels"). Defaults (R=red, G=green, B=blue) are the identity.
+     *    intensity (window → invert → gamma, see {@link channelIntensity}) is
+     *    tinted by its assigned colour and summed (Fiji "Merge Channels"), then
+     *    clamped. Invert is per channel, before the merge, as napari-js inverts
+     *    each additive layer (NAPARI-BOUNDARY-2) — not the composite. Defaults
+     *    (R=red, G=green, B=blue) are the identity.
      */
     applyToRgba(d: Uint8ClampedArray): boolean;
-    /** Precomputed lum(0..255) → tinted-RGB lookup for a channel's window/gamma/
-     *  colour. Building it costs 256 channelIntensity() calls; using it makes a
+    /** Precomputed lum(0..255) → tinted-RGB lookup for a channel's window/invert/
+     *  gamma/colour. Building it costs 256 channelIntensity() calls; using it makes a
      *  full-tile recolor ~262k array lookups instead of ~262k Math.pow() calls. */
     channelRgbLut(st?: IChannelState): {
         r: Uint8ClampedArray;
         g: Uint8ClampedArray;
         b: Uint8ClampedArray;
     };
-    /** Windowed + gamma intensity (0..255) for a channel, ignoring tint/invert. */
-    channelIntensity(val: number, c?: IChannelState): number;
+    /**
+     * Additive ('lighter') merge of single-band channel planes into one opaque
+     * RGBA image — what OSD's drawer shows for a per-channel image, where each
+     * channel tile is tinted by {@link channelRgbLut}. Hidden channels, missing
+     * planes and planes of another size contribute nothing. A plane is RGBA
+     * (`bands` 4, R=G=B, transparent pixels skipped) or one byte per pixel
+     * (`bands` 1). Used by the serverless multichannel compositor, the
+     * multichannel composite export and the Plotly image's channel display.
+     */
+    compositeChannels(planes: ReadonlyArray<Uint8ClampedArray | Uint8Array | null | undefined>, states: ReadonlyArray<IChannelState | undefined>, bands?: 1 | 4): Uint8ClampedArray;
+    /** Add one single-band plane (RGBA or one byte per pixel, see
+     *  {@link compositeChannels}), tinted by its channel state, onto `out`
+     *  (Uint8ClampedArray clamps → additive 'lighter'). */
+    addChannel(out: Uint8ClampedArray, plane: Uint8ClampedArray | Uint8Array, st?: IChannelState, bands?: 1 | 4): void;
+    /**
+     * A channel's display intensity (0..255, before its tint): window → invert →
+     * gamma, the order of napari-js's `windowGamma`, which every additive napari
+     * layer applies on its own before the layers are summed (NAPARI-BOUNDARY-2).
+     * The gamma exponent is the ImageJ one (t^(1/γ)). An empty window span maps to
+     * 0 before the invert; with no channel state the value passes through.
+     */
+    channelIntensity(val: number, c?: IChannelState, invert?: boolean): number;
     /** A channel's pseudo-colour tint as [r,g,b] in 0..1 (default white). */
     tint01(c?: IChannelState): [number, number, number];
     /** True when any RGB channel is windowed/hidden/gamma'd/re-tinted or the
      *  background is inverted — otherwise the tile passes through unchanged. */
     rgbNeedsRecolor(): boolean;
 }
+/**
+ * Whether an RGB image's channel states (R, G, B) change how it looks: any band windowed, hidden,
+ * gamma'd or re-tinted, or the image inverted. False means the RGB pixels pass through as they
+ * are — every backend's cue to keep drawing the image directly.
+ */
+export declare function rgbNeedsRecolor(channelStates: ReadonlyArray<IChannelState | undefined>, invert: boolean): boolean;

package/lib/implementations/osd/histogram-sampler.d.ts

@@ -30,9 +30,10 @@ export interface HistogramSamplerHost {
     /** Histograms landed — nudge the pane to re-read (its retry window may have
      *  lapsed). */
     onChannelHistogramsSampled(): void;
-    /** A grayscale auto-window was measured from full-res tiles — seed the
-     *  Intensity channel (or re-invalidate if the user already windowed). */
-    onGrayWindowSampled(min: number, max: number): void;
+    /** A grayscale auto-window was measured from slice `z`'s full-res tiles —
+     *  seed the Intensity channel (or re-invalidate if the user already
+     *  windowed). Background-preloaded slices report too; the host decides. */
+    onGrayWindowSampled(min: number, max: number, z: number): void;
 }
 export declare class HistogramSampler {
     private http;
@@ -40,18 +41,25 @@ export declare class HistogramSampler {
     private host;
     /** 256-bin intensity histogram per z-slice, from sampled tiles. */
     private sliceHistograms;
-    /** Native-bit-depth histograms from `/histogram`, keyed `${z}|${channel}`. */
+    /** Native-bit-depth histograms from `/histogram`, keyed
+     *  `${infoB64}|${z}|${channel}|${bins}`. */
     private nativeHistograms;
-    /** Per-app-load cache-buster for `/histogram` — the server marks the
-     *  response cacheable for 24h, and a hard refresh can't bust a post-load
-     *  XHR. A token stable within a session but new on each full load keeps the
-     *  in-session dedup (via `nativeHistograms`) while always reflecting the
-     *  live backend after a reload. */
-    private readonly histCacheBuster;
+    /** Bumped by {@link clear}. Every async sampler captures it before its first
+     *  `await` and drops its result if it changed: tile sampling and the native
+     *  fetch can take tens of seconds, and a run for the previous image must not
+     *  write that image's histogram, auto-window or native histogram into the
+     *  next one. */
+    private generation;
+    /** Slices whose tile sampling is in flight, so a scrub back to one (or a
+     *  background preload of it) doesn't fetch its tiles again. */
+    private readonly inFlight;
     constructor(http: HttpClient, api: string, host: HistogramSamplerHost);
     /** The sampled histogram for one channel of slice z, or null until the
      *  async sampling resolves (or if it was skipped). */
     get(z: number, channelIndex: number): IHistogram | null;
+    /** Whether slice z is already sampled or being sampled (tile samplers only
+     *  run once per slice until {@link clear}). */
+    private sampledOrPending;
     /** Drop everything (teardown / image switch). */
     clear(): void;
     /**
@@ -94,9 +102,11 @@ export declare class HistogramSampler {
     /**
      * Native-bit-depth histogram for >8-bit images, from the server `/histogram`
      * endpoint (the 8-bit canvas tiles can't carry 16-bit values). Cached per
-     * slice+channel for the session.
+     * image+slice+channel+bin count until {@link clear}.
      */
     native$(infoB64: string, z: number, channel: number, bins: number): Observable<IHistogram | null>;
-    /** Fetch + cache one channel's native histogram from `GET /histogram`. */
+    /** Fetch + cache one channel's native histogram from `GET /histogram`
+     *  (the shared jit-service client, which adds the per-app-load cache-buster
+     *  that defeats the server's 24 h cache). */
     private fetchNative;
 }

package/lib/implementations/osd/openseadragon-viewer-options.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Quiet OpenSeadragon's "[Viewport.*] is not accurate with multi-image" advisories.
+ * A multichannel image is composited from one TiledImage per channel — a legitimate
+ * multi-image world — and OSD logs that advisory (at error level) from its own
+ * navigator/overview rendering on every animation frame, flooding the console. Our
+ * own image<->viewport conversions already route through world item 0 (see
+ * osd-coords), so the remaining advisories are OSD-internal and only affect the
+ * minimap's box accuracy (cosmetic). This wraps OSD's logger in a Proxy that drops
+ * only that one message string and forwards every other log untouched. Idempotent.
+ */
+export declare function silenceOsdMultiImageAdvisory(): void;
+/** What {@link buildViewerOptions} needs to know about the viewer being mounted. */
+export interface ViewerOptionsInput {
+    /** The DOM id OSD mounts into. */
+    id: string;
+    /** Show the overview navigator (minimap). */
+    navigatorVisible: boolean;
+    /** Bilinear smoothing; false gives crisp nearest-neighbour pixels. */
+    smoothing: boolean;
+    /** Bearer token for OSD's own tile fetches (its loader bypasses HttpClient). */
+    authHeaders: Record<string, string>;
+    /** Slices in the image (1 for a single image). */
+    sliceCount: number;
+    /** How many slices the slice cache keeps resident (see SliceCache.maxSlices). */
+    maxSlices: number;
+}
+/**
+ * The options object handed to the OpenSeadragon factory. Pure: every value
+ * that depends on the service comes in through `input`.
+ *
+ * These are OSD config keys, not library code: OSD silently falls back to its
+ * own default when one is misspelled or renamed upstream, so the values we rely
+ * on are pinned by `openseadragon-viewer-options.spec.ts`.
+ */
+export declare function buildViewerOptions(input: ViewerOptionsInput): Record<string, unknown>;