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

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

@@ -0,0 +1,142 @@
+import { ChangeDetectorRef, EventEmitter, NgZone, OnChanges, SimpleChanges } from '@angular/core';
+import type { ISpatialControls } from '../../contracts/visualizer.contract';
+import type { SpatialDataset } from '../../contracts/spatial-dataset.contract';
+import { ColormapNode, SpatialViewState, TranscriptGlyphName } from '../../contracts/display-types';
+import { PanelOption } from '../../spatial/spatial-panel-model';
+import type { GenePickerModel } from '../spatial-gene-picker';
+import * as i0 from "@angular/core";
+/** One item of the gene list's '⋮' menu. */
+export interface GeneMenuItem {
+    label: string;
+    icon: string;
+    command: () => void;
+    disabled?: boolean;
+}
+/**
+ * The Transcripts section, as Xenium Explorer's: the on/off switch, the transcript genes
+ * (with "All genes", the '⋮' menu and gene-group import), the
+ * {@link SpatialMarkerGenesFormComponent marker-genes form}, the
+ * {@link SpatialGeneTreeComponent gene tree}, how transcripts are drawn — the points
+ * estimate against its budget, colouring, icon, size, opacity and quality — and the
+ * density map's opacity, bin size, threshold window and colormap.
+ *
+ * Writes only through `controls.setViewState`.
+ */
+export declare class SpatialTranscriptsPanelComponent implements OnChanges {
+    private readonly zone;
+    private readonly cdr;
+    /** 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 transcript genes are picked from, shared with the other gene dropdowns. */
+    genes: GenePickerModel | null;
+    /** Estimated transcripts in view, against the budget — Explorer's points bar. */
+    estimate: {
+        points: number;
+        max: number;
+    } | null;
+    /** The density window in use and its densest bin, for the threshold control. */
+    densityStats: {
+        lo: number;
+        hi: number;
+        max: number;
+    } | null;
+    /** Transcripts of each selected gene in the current view, from the renderer. */
+    geneCounts: Record<string, number> | null;
+    /** Colormap tree for the density map's colouring. */
+    colormapOptions: ColormapNode[];
+    /** 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 (see the cells panel's gene dropdown). */
+    protected readonly geneVirtualScrollFrom = 200;
+    protected readonly transcriptColorOptions: PanelOption<SpatialViewState['transcriptColorBy']>[];
+    protected readonly glyphOptions: import("../../spatial/spatial-panel-model").GlyphOption[];
+    protected readonly budgetOptions: {
+        label: string;
+        value: number;
+    }[];
+    protected readonly densityBins: number[];
+    /**
+     * Transcript modes on offer. Built once per dataset rather than in a getter: 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 transcriptModeOptions: PanelOption<SpatialViewState['transcriptMode']>[];
+    /** The '⋮' menu, rebuilt when what enables its items changes. */
+    protected geneMenu: GeneMenuItem[];
+    protected editingMax: boolean;
+    /** Whether the marker-genes form is shown. */
+    protected markersOpen: boolean;
+    protected geneGroupError: string | null;
+    /**
+     * The threshold window shown: the one set, else the one derived. A stored array, not a
+     * getter: a range slider's `ngModel` given a fresh array every change-detection pass
+     * schedules another pass, forever — which hung the page the moment the density
+     * controls appeared.
+     */
+    protected densityWindow: [number, number];
+    protected densitySliderMax: number;
+    protected densityStep: number;
+    protected selectedDensityColormapNode: ColormapNode | null;
+    /** Built once per density colormap: a 256-entry LUT per change-detection pass is waste. */
+    protected densityColorBarCss: string;
+    private densityBarFor;
+    /** The mode the section header's switch turns back on. */
+    private lastTranscriptMode;
+    /** Whether any column can supply marker genes' clusters. */
+    private hasMarkerColumns;
+    /** The hidden file input the menu's import opens. */
+    private geneGroupFileRef?;
+    constructor(zone: NgZone, cdr: ChangeDetectorRef);
+    ngOnChanges(changes: SimpleChanges): void;
+    protected onTranscriptsOn(on: boolean): void;
+    protected onTranscriptMode(mode: SpatialViewState['transcriptMode']): void;
+    protected onTranscriptGenes(genes: string[] | null): void;
+    /** Real genes in the panel — the tree's denominator. */
+    protected get geneTotal(): number;
+    /** "All genes" needs the grouping pyramid, or at least tiles to draw individually. */
+    protected get canShowAllGenes(): boolean;
+    /** Why "All genes" is not offered yet, while the server builds its pyramid. */
+    protected get allGenesPreparing(): string | null;
+    protected get showingAllGenes(): boolean;
+    onTranscriptAllGenes(on: boolean): void;
+    /** '±': every gene, or back to the chosen list. */
+    protected onToggleAllGenes(): void;
+    get canAddMarkers(): boolean;
+    /** Open the marker-genes form (from the '⋮' menu). */
+    openMarkers(): void;
+    onNewGeneGroup(): void;
+    /**
+     * Import gene groups: CSV/TSV with a group and a gene column (header optional), e.g.
+     * marker genes per cell type. The genes are added to the selection.
+     */
+    protected onImportGeneGroups(input: HTMLInputElement): Promise<void>;
+    protected get estimatePercent(): number;
+    protected get estimateOverMax(): boolean;
+    protected onTranscriptBudget(n: number): void;
+    protected onTranscriptColorBy(by: SpatialViewState['transcriptColorBy']): void;
+    protected onTranscriptScale(value: number | undefined): void;
+    protected onTranscriptOpacity(value: number | undefined): void;
+    protected onTranscriptQuality(includeLow: boolean): void;
+    protected glyphOf(gene: string, slot: number): TranscriptGlyphName;
+    protected onGlyph(gene: string, glyph: TranscriptGlyphName): void;
+    protected get densityOpacityPercent(): number;
+    protected onDensityOpacity(value: number | undefined): void;
+    protected onDensityOpacityPercent(v: number | null): void;
+    protected get densityBinIndex(): number;
+    protected onDensityBinIndex(i: number | undefined): void;
+    protected onDensityRange(range: [number, number] | number[] | undefined): void;
+    protected onDensityRangeEnd(which: 0 | 1, v: number | null): void;
+    protected onDensityAuto(): void;
+    protected onDensityColormap(node: ColormapNode | null): void;
+    private refreshDensityWindow;
+    /** '⋮' menu. */
+    private buildGeneMenu;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpatialTranscriptsPanelComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpatialTranscriptsPanelComponent, "spatial-transcripts-panel", never, { "controls": { "alias": "controls"; "required": false; }; "dataset": { "alias": "dataset"; "required": false; }; "view": { "alias": "view"; "required": false; }; "genes": { "alias": "genes"; "required": false; }; "estimate": { "alias": "estimate"; "required": false; }; "densityStats": { "alias": "densityStats"; "required": false; }; "geneCounts": { "alias": "geneCounts"; "required": false; }; "colormapOptions": { "alias": "colormapOptions"; "required": false; }; "open": { "alias": "open"; "required": false; }; }, { "openChange": "openChange"; }, never, never, true, never>;
+}

package/lib/store/class-color.util.d.ts

@@ -8,12 +8,20 @@
  *      so the same unknown class always gets the same colour with no stored state.
  *
  * These functions are pure (no mutation); opt-in promotion of unknown classes into the
- * set is handled by the store, which owns persistence.
+ * set is reported to the caller (see {@link applyPresetColors}), which owns persistence.
  */
 import { ClassPreset, PresetSet } from '../models/class-preset';
+import { Region } from '../models/region';
 export declare function normalizeLabel(s: string): string;
 /** Stable, non-negative 32-bit string hash (identical across runs and machines). */
 export declare function hashString(s: string): number;
+/**
+ * The key two class names are compared by under the set's match mode: the name
+ * itself for `exact`, trimmed and lower-cased for `normalized`.
+ */
+export declare function presetKey(set: Pick<PresetSet, 'matchMode'>, label: string): string;
+/** `#RRGGBB` (upper-case) for an HSL colour: hue in degrees, saturation and lightness in %. */
+export declare function hslToHex(hDeg: number, sPct: number, lPct: number): string;
 /** Find the preset matching `label` under the set's match mode. */
 export declare function findPreset(label: string, set: PresetSet): ClassPreset | undefined;
 /**
@@ -22,5 +30,34 @@ export declare function findPreset(label: string, set: PresetSet): ClassPreset |
  * HSL hue. Same name -> same colour, every run.
  */
 export declare function fallbackColorFor(label: string, palette: string[]): string;
-/** Resolve a colour for `label`: a matching preset's colour, else the deterministic fallback. */
+/**
+ * Resolve a colour for `label`: a matching preset's colour, else the colour an imported file
+ * gave the class, else the deterministic fallback.
+ */
 export declare function colorForLabel(label: string, set: PresetSet): string;
+/** Options for {@link applyPresetColors}. */
+export interface ApplyPresetColorsOptions {
+    /**
+     * True for a region the caller owns outright (fresh, not yet stored, so in no
+     * undo snapshot): its colour is set in place. Every other region whose
+     * colour changes is copied. Default: never in place.
+     */
+    inPlace?: (r: Region) => boolean;
+    /**
+     * Called once per unknown class when `set.autoPromote` is on, with the
+     * preset to add (name trimmed in `normalized` match mode, `source: 'auto'`).
+     */
+    onPromote?: (preset: ClassPreset) => void;
+}
+/**
+ * Resolve each labelled region's colour from the preset set (jit-ui#70). The
+ * presets are the source of truth: a matching preset gives the class colour,
+ * an unknown class the colour an imported file gave it (`importedColors`) or else
+ * its deterministic fallback, **overriding any colour already on the region**. Unlabelled regions and
+ * ones the user recoloured (`colorOverridden`) are left untouched. Unknown
+ * classes are reported through `onPromote` when `autoPromote` is on.
+ *
+ * Returns a new array; regions whose colour is already right are the same
+ * instances.
+ */
+export declare function applyPresetColors(regions: Region[], set: PresetSet, opts?: ApplyPresetColorsOptions): Region[];

package/lib/store/class-signatures.d.ts

@@ -0,0 +1,11 @@
+import { Region } from '../models/region';
+/**
+ * A fingerprint of each class's regions (by label): their ids and geometry folded into one number
+ * per class. Two sets give the same fingerprint for a class when its regions did not change, so
+ * comparing a slice's fingerprints before and after an edit names the classes the edit touched
+ * (a recoloured or relabelled region touches its old class and its new one). Profile lines and
+ * unlabelled regions are left out: they are in no class.
+ */
+export declare function classSignatures(regions: readonly Region[]): Map<string, number>;
+/** The classes whose fingerprints differ between `before` and `after` (added and removed included). */
+export declare function changedClasses(before: ReadonlyMap<string, number>, after: ReadonlyMap<string, number>): Set<string>;

package/lib/store/region-history.d.ts

@@ -0,0 +1,66 @@
+import { Observable } from 'rxjs';
+/**
+ * Bounded undo/redo history of immutable snapshots (review RT-13, RegionStore
+ * split "RegionHistory").
+ *
+ * Holds snapshots by reference. That is only sound because the store never
+ * changes a snapshot after recording it — `RegionStore` is copy-on-write: each
+ * edit replaces the edited region (and the array) rather than mutating them —
+ * so a snapshot costs one array of pointers, not a deep clone of every vertex.
+ *
+ * Recording: call {@link record} with the state just BEFORE a change. Commits
+ * coalesce into one step:
+ *  - between {@link beginGesture} and {@link endGesture} every commit folds into
+ *    the step its first commit opened, however long the pauses, and a gesture
+ *    never merges with a commit before or after it (RT-12);
+ *  - outside a gesture, each commit within `coalesceMs` of the previous one
+ *    folds into the same step.
+ * A fresh step drops the redo future. Up to `limit` steps are kept each way.
+ */
+export declare class RegionHistory<T> {
+    private readonly limit;
+    private readonly coalesceMs;
+    private undoStack;
+    private redoStack;
+    /** True while a coalescing burst is open (further commits fold into it). */
+    private burstOpen;
+    /** Open gestures (nested begin/end); while > 0 the burst stays open with no timer. */
+    private gestureDepth;
+    private burstTimer;
+    /** True while a snapshot is being restored, so the restore records nothing. */
+    private restoring;
+    private readonly canUndoSubject;
+    private readonly canRedoSubject;
+    constructor(limit?: number, coalesceMs?: number);
+    /** Whether an undo step is available (drives the toolbar's Undo button). */
+    readonly canUndo$: Observable<boolean>;
+    /** Whether a redo step is available. */
+    readonly canRedo$: Observable<boolean>;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /**
+     * Record `before` — the state just before a change — unless the change
+     * folds into the step already open, or a restore is in progress.
+     */
+    record(before: T): void;
+    /**
+     * Step back: returns the state to restore (and keeps `current` for redo), or
+     * undefined when there is nothing to undo. Restore it inside {@link restore}.
+     */
+    undo(current: T): T | undefined;
+    /** Step forward again: the mirror of {@link undo}. */
+    redo(current: T): T | undefined;
+    /** Run `fn` (applying an undo/redo snapshot) without recording anything it triggers. */
+    restore(fn: () => void): void;
+    /** Forget every step (an image load/switch: history never crosses images). */
+    reset(): void;
+    /** Start one user gesture: every commit until the matching {@link endGesture} is one step. Nests. */
+    beginGesture(): void;
+    /** End the gesture opened by {@link beginGesture}; the next commit starts a new step. */
+    endGesture(): void;
+    private push;
+    /** (Re)arm the idle timer that closes the current coalescing burst. */
+    private armBurst;
+    private closeBurst;
+    private emit;
+}

package/lib/store/region-scope-cache.d.ts

@@ -0,0 +1,65 @@
+import { IImageInfo } from '../contracts/image.contract';
+import { Region } from '../models/region';
+/** How a stack's regions round-trip to disk (jit-ui#93): `combined` writes one
+ *  z-indexed geojson (single-file z-stack, QuPath schema); `per-slice-file`
+ *  writes one geojson per slice-file (a folder of numbered images). */
+export type StackSaveLayout = 'combined' | 'per-slice-file';
+/**
+ * Where the region store's *live* set comes from and goes back to: a per-image
+ * cache (keyed by the image's first URL, else its file name) and, while a
+ * z-stack is loaded, a per-slice map for the current image (jit-ui#93).
+ *
+ * The owner holds the live array; every method that can change scope takes
+ * the current live array (to capture its edits) and returns the incoming
+ * live set, or null when nothing changes. It never changes a region: slice
+ * tags are applied to copies ({@link withRegionZ}).
+ */
+export declare class RegionScopeCache {
+    private byImage;
+    private imageKey;
+    private bySlice;
+    private stack;
+    private sliceZ;
+    private layout;
+    /** Slices loaded with regions: a per-slice-file save re-writes them even when
+     *  now empty, so clearing a slice and saving removes its geojson. */
+    private initialNonEmpty;
+    /** The cache key for an image: its first URL, else its file name. */
+    static imageKey(imageInfo: IImageInfo | undefined): string | undefined;
+    /** The active image's cache key (see {@link imageKey}). */
+    get activeImage(): string | undefined;
+    /** True while a z-stack is loaded and regions are held per slice. */
+    get stackMode(): boolean;
+    /** The current display slice (zero-based; 0 outside stack mode unless set). */
+    get displaySlice(): number;
+    /** How the current stack persists; meaningless outside stack mode. */
+    get saveLayout(): StackSaveLayout;
+    /** Record `live` as the current image's regions. */
+    sync(live: Region[]): void;
+    /**
+     * Make `key` the active image: ends stack mode, caches `live` under the
+     * outgoing image, and returns the incoming image's regions (or []). Null when
+     * `key` already is the active image (repeated replots keep their regions).
+     */
+    switchImage(key: string | undefined, live: Region[]): Region[] | null;
+    /**
+     * Enter per-slice mode with `slices` (already admitted by the store, each
+     * region tagged with its slice) and return `initialZ`'s slice as the live set.
+     */
+    enterStack(slices: Map<number, Region[]>, initialZ: number, layout: StackSaveLayout): Region[];
+    /** Leave stack mode; a no-op outside it. */
+    exitStack(): void;
+    /**
+     * Show slice `z`: capture `live` into the current slice and return slice
+     * `z`'s regions. Null when nothing swaps — the same slice, or outside stack
+     * mode (where the index is only recorded).
+     */
+    showSlice(z: number, live: Region[]): Region[] | null;
+    /** Every slice's regions (current one from `live`), each tagged with its z,
+     *  in slice order; `live` itself outside stack mode. */
+    sliceRegions(live: Region[]): Region[];
+    /** Slices to write on a per-slice-file save: every slice with regions plus
+     *  every slice loaded non-empty (re-written empty when cleared). Empty
+     *  outside stack mode. */
+    stackSaveSlices(live: Region[]): Map<number, Region[]>;
+}

package/lib/store/region-selection.d.ts

@@ -0,0 +1,36 @@
+import { Observable } from 'rxjs';
+/** The part of a region the selection reads: its stable id. */
+interface HasId {
+    id: number;
+}
+/**
+ * Region selection, held by region *id* (stable across edits, reorders and
+ * delete/add cycles) and projected to array indices for the IRegionStore
+ * boundary. Changing the ids ({@link replace}, {@link retain}) is silent; the
+ * owner calls {@link sync} once the region array it projects onto is final,
+ * which prunes ids that no longer exist and emits {@link indices$} only when
+ * the index set changed.
+ */
+export declare class RegionSelection {
+    private selected;
+    private readonly indicesSubject;
+    /** The selected regions' current array indices (emits on change only). */
+    readonly indices$: Observable<number[]>;
+    /** The selected indices as last projected by {@link sync}. */
+    get indices(): number[];
+    /** The selected ids, in selection order. */
+    get ids(): readonly number[];
+    /** Replace the selected ids (no emit until {@link sync}). */
+    replace(ids: number[]): void;
+    /** Keep only the ids `keep` accepts (no emit until {@link sync}). */
+    retain(keep: (id: number) => boolean): void;
+    /**
+     * Select by array index into `regions`: invalid and duplicate indices are
+     * dropped, the given order is kept. Projects and emits.
+     */
+    selectIndices(indices: number[], regions: readonly HasId[]): void;
+    /** Project the selected ids onto `regions`, pruning ids it no longer holds,
+     *  and emit if the index set changed. */
+    sync(regions: readonly HasId[]): void;
+}
+export {};

package/lib/store/region-source-scope.d.ts

@@ -0,0 +1,68 @@
+import type { RegionSource } from '../region-source/region-source';
+/** Opens a region source on demand (and again after it was closed to save memory). */
+export type RegionSourceOpener = () => Promise<RegionSource>;
+/** Which slices a source serves: one slice (plane `plane` of the source), or every slice z
+ *  from the source's plane z (a z-indexed GeoJSON over a whole stack). */
+export type RegionSourceSlices = {
+    slice: number;
+    plane?: number;
+} | 'planes';
+/** The region source behind one slice: the source and which of its planes the slice shows. */
+export interface RegionSourceBinding {
+    source: RegionSource;
+    plane: number;
+}
+/** Sources held open, past which the least recently used one is closed (never the one shown). */
+export declare const OPEN_REGION_SOURCES = 6;
+/**
+ * The region sources of every image the store has seen, per slice, and per slice the ids of
+ * the source features taken out of the source (into the working set, or deleted) — those the
+ * source no longer draws and an export leaves out.
+ *
+ * Sources open lazily, the first time their slice is shown or read, and at most
+ * {@link OPEN_REGION_SOURCES} stay open: the least recently used are closed and re-opened from
+ * their opener when used again (a source's ids are stable, so what was taken stays taken). The
+ * source of the slice on screen ({@link show}) is never closed for another: a read across every
+ * slice must not close the source the viewer draws and takes from.
+ */
+export declare class RegionSourceScope {
+    private readonly images;
+    /** Open entries, least recently used first. */
+    private readonly openOrder;
+    /** The entry of the slice on screen: kept open. */
+    private shown;
+    /** Attach `open` to `image` for `slices`, replacing (and closing) what was there. */
+    attach(image: string, open: RegionSourceOpener, slices: RegionSourceSlices): void;
+    /** Drop every source of `image` (closing the open ones) and what was taken from them. */
+    detachImage(image: string): void;
+    /** Drop the source of one slice of `image`. */
+    detachSlice(image: string, slice: number): void;
+    /** The slice on screen (null: none): its source stays open while others are read. */
+    show(image: string | undefined, slice: number | null): void;
+    /** Whether `image` has a source for `slice`. */
+    has(image: string | undefined, slice: number): boolean;
+    /** Whether `slice` of `image` has a source of its own (not a `'planes'` source's plane). */
+    hasOwnSource(image: string | undefined, slice: number): boolean;
+    /** Every slice of `image` with a source of its own (not counting a `'planes'` source). */
+    slicesWithSource(image: string | undefined): number[];
+    /** Whether `image` has one source over all its slices. */
+    hasPlanesSource(image: string | undefined): boolean;
+    /**
+     * The source behind `slice` of `image`, opening it if needed. Resolves null when there is
+     * none, and rejects when it cannot be opened.
+     */
+    binding(image: string | undefined, slice: number): Promise<RegionSourceBinding | null>;
+    /** The ids taken from `slice`'s source. */
+    taken(image: string | undefined, slice: number): ReadonlySet<string>;
+    /** Every id taken from any slice of `image` (a `'planes'` source's ids are unique across them). */
+    allTaken(image: string | undefined): string[];
+    /** The slices of `image` with anything taken from their source. */
+    slicesWithTaken(image: string | undefined): number[];
+    /** Replace the ids taken from `slice`'s source (copy-on-write: `ids` is kept as given). */
+    setTaken(image: string | undefined, slice: number, ids: ReadonlySet<string>): void;
+    private entry;
+    private imageSources;
+    private openEntry;
+    private close;
+    private closeSource;
+}