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

package/lib/implementations/napari-js/napari-tile-client.d.ts

@@ -0,0 +1,214 @@
+import { Observable } from 'rxjs';
+import type { TiledSource } from 'napari-js';
+import { IImageInfo } from '../../contracts/image.contract';
+import { IChannelState, IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { TileAccessPort } from '../../contracts/ports/tile-access.port';
+import { SimpleSliceAccessService } from '../simple-slice-access.service';
+import { TileDescriptor } from '../tile-server';
+import { LumaPlane } from './napari-helpers';
+/** What the navigator draws: a whole-slice picture (a canvas read from the pyramid, or a bitmap). */
+export type OverviewImage = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+/** An assembled uint8 (luminance) volume, x-fastest then y then z. */
+export interface AssembledVolume {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    depth: number;
+}
+/** Decode an `ImageBitmap` to a single-channel uint8 luminance plane with napari-js's
+ *  `bitmapToScalar` (server bands are grey, R=G=B, and decode exactly; a colour composite
+ *  becomes its BT.601 luminance). `maxSide` caps the longest side (downscaling on the canvas
+ *  draw) — used to keep pre-loaded surface slice planes small. Closes the bitmap. */
+export declare function bitmapToLuminance(bmp: ImageBitmap, maxSide?: number): LumaPlane;
+/**
+ * The napari-js backend's client of the jit-service tile server (review Appendix B, step 2), on
+ * the shared `tile-server/` protocol: the `/tiles/info` descriptor (polled, cached per source,
+ * shared between concurrent callers), whole-slice reads from the pyramid (napari-js `readLevel`), the pyramidal
+ * {@link TiledSource}s the 2D image draws, volume assembly, surface planes, the native `/histogram`
+ * and the `/export/tiff` download.
+ *
+ * The image is always passed in — the client never reads which image the service has loaded —
+ * so a descriptor can only ever describe the image a caller asked about (NAPARI-SVC-2).
+ *
+ * Scene-scoped state (the poll in flight, the sources that answered "no", the native histograms)
+ * lives until {@link startScene}; the descriptor cache itself survives scenes, keyed by source.
+ */
+export declare class NapariTileClient {
+    private readonly tiles;
+    private readonly simpleStack;
+    private readonly api;
+    /** Cached `/tiles/info` pyramid descriptor + the infoB64 it was fetched for. */
+    private descriptor;
+    private descriptorKey;
+    /** The poll in flight, shared by every caller asking for the same `infoB64`. */
+    private descriptorPoll;
+    /** `infoB64`s this scene's poll got no descriptor for (non-202 status, empty body, timeout).
+     *  Scene-scoped, so a re-plot retries a slow or flaky server once. */
+    private readonly descriptorMisses;
+    /** Native-bit-depth histograms from `/histogram`, keyed `${z}|${channel}` (>8-bit images). */
+    private readonly nativeHistograms;
+    /** The current scene's lifetime: a poll started under it ends when it is aborted. */
+    private scene;
+    constructor(tiles: TileAccessPort, simpleStack: SimpleSliceAccessService, api: string);
+    /** Whether `info` is a self-contained stack (`tiled:false`: each slice its own file, no
+     *  server pyramid). */
+    isSimple(info: IImageInfo | undefined): boolean;
+    /** A new scene: forget the scene-scoped state and poll under `signal` from now on. */
+    startScene(signal: AbortSignal): void;
+    /**
+     * Fetch + cache the server pyramid descriptor (`GET /tiles/info`): the REAL per-level tile grid,
+     * tile size, channel metadata and physical pixel size. The backend returns 202 while the source
+     * is still caching, so we poll ({@link pollDescriptor}). Cached per `infoB64`; returns null if it
+     * never becomes ready, or the server will not describe the source (callers fall back to a
+     * single-tile fetch). Read it back through {@link currentDescriptor}. This is the authoritative
+     * grid — guessing level dims from `trueImageSize` overshoots the real grid and the server 400s
+     * out-of-range tiles.
+     */
+    ensureDescriptor(info: IImageInfo | undefined): Promise<TileDescriptor | null>;
+    /**
+     * The `/tiles/info` loop behind {@link ensureDescriptor}: the shared jit-service poll
+     * (`tile-server/pollDescriptor`). Re-polls only on 202 (the server is still caching the source);
+     * any other status means this server will not describe it, so the answer is null at once. Each
+     * request gives up after its own timeout — a hung request would otherwise never reach the
+     * deadline check — and the whole poll ends (null) as soon as `scene` is aborted.
+     */
+    private pollDescriptor;
+    /**
+     * The pyramid descriptor of `info`, or null when it has none.
+     *
+     * The cache is keyed by `infoB64` and survives image switches and failed polls, so reading it
+     * directly would hand a `tiled:false` stack (or an image whose poll never answered) the
+     * PREVIOUS image's size, µm/pixel, tile size and bit depth. Every read site goes through here.
+     */
+    currentDescriptor(info: IImageInfo | undefined): TileDescriptor | null;
+    /** µm per pixel along x for `info`: the descriptor's, else the image metadata's; 0 when
+     *  neither declares it. */
+    mppX(info: IImageInfo | undefined): number;
+    /**
+     * Slice `z` as ONE image, for a source with no pyramid to read: a `tiled:false` stack's own
+     * file for `z`, else (no descriptor) the server's single top-left tile — correct for
+     * small/simple images.
+     *
+     * A self-contained multi-slice stack's `z` indexes a completely different file's own preview
+     * URL, not an internal slice of one server-tiled file, so it is resolved and fetched via
+     * SimpleSliceAccessService (shared with OSD; see its docs for why this can't be a bare fetch())
+     * rather than as a /tile?info=...&z= request against whichever single file
+     * getSelectedInfoB64() points at (which would 400/mismatch for any z beyond that one file's own
+     * extent). `channel` selects a band: a serverless multichannel stack's own plane
+     * (`channelUrls[z][channel]`, the client-side analog of the server's per-channel
+     * `/tile?channel=c`), else the server's.
+     */
+    fetchImage(info: IImageInfo | undefined, z: number, channel?: number): Promise<ImageBitmap>;
+    /**
+     * Slice `z` as a single-channel uint8 luminance plane. With a pyramid, napari-js's `readLevel`
+     * reads it from the same {@link tiledSource} the 2D view draws: the finest level whose tile grid
+     * fits `maxTiles` and whose longest side fits the GPU texture limit (no finer than `maxSide`
+     * needs, when given), stitched with bounded concurrency and area-averaged down to `maxSide`.
+     * Without one, the single image of {@link fetchImage}. `channel` selects a band (real levels
+     * only); omit it for the composite, whose overview levels let a large image read a small level.
+     * `compositeFallback`: see {@link planeSource}. `signal` cancels the read (it rejects).
+     */
+    readPlane(info: IImageInfo | undefined, z: number, channel: number | undefined, opts: {
+        maxTiles: number;
+        maxSide?: number;
+        compositeFallback?: boolean;
+        signal?: AbortSignal;
+    }): Promise<LumaPlane>;
+    /**
+     * The scalar source for one decimated plane of band `channel`. A band has tiles only at the
+     * (few, large) real Bio-Formats levels; when none of them fits the budget — e.g. the coarsest
+     * real level is still 14982×18670, ~1100 full-res tiles — stitching it per slice floods the
+     * server (504s) and stalls the load. The composite pyramid has small overview levels, so the
+     * plane is read from the composite instead (its luminance). Only for a caller that wants one
+     * decimated plane (the surface height): for a multichannel VOLUME every channel would then read
+     * the same composite and the channels would collapse into one, so volumes keep each band.
+     */
+    private planeSource;
+    /**
+     * A small picture of the whole slice for the navigator: the composite (or band `channel`) at the
+     * finest level a single tile holds, else the coarsest level, as an RGBA canvas. Without a
+     * pyramid, the single image of {@link fetchImage}.
+     */
+    overviewImage(info: IImageInfo | undefined, z: number, channel?: number): Promise<OverviewImage>;
+    /**
+     * Slice `z`'s R, G and B bands, as three uint8 planes: the composite read as RGBA at the
+     * finest level within `maxTiles` (as {@link readPlane} picks it; 1 for a cheap overview
+     * sample), else the single image of {@link fetchImage}. The raw bands of an RGB image, for the
+     * per-band layers and their histograms.
+     */
+    readRgbBands(info: IImageInfo | undefined, z: number, maxTiles?: number): Promise<LumaPlane[]>;
+    /** Fetch slice `z` and read it back as a single-channel uint8 plane (see {@link readPlane}),
+     *  within `budgetTiles`: the 2D stitch fallback reads at the full budget, the histogram samples
+     *  at 1 for a cheap overview tile. */
+    fetchChannelData(info: IImageInfo | undefined, z: number, channel?: number, budgetTiles?: number): Promise<LumaPlane>;
+    /** Tile budget to stitch a whole slice at ~`targetPx` resolution from the pyramid. Shared by the
+     *  surface plane fetch and the volume assembly, so both cap their reads by the decimate factor. */
+    tileBudgetFor(info: IImageInfo | undefined, targetPx: number): number;
+    /**
+     * Build a pyramidal TiledSource backed by the server `/tile` endpoint. `channel` selects a band
+     * (grayscale luminance, real levels only); omit it for the composite (RGBA, all levels).
+     *
+     * For the 2D view, `scene` is the signal of the render that asked for it, taken before that
+     * render's awaits, and `onTile` is told of each tile request and handed back the tile's end. A
+     * request issued once `scene` is aborted (a disposed source still fetching after a reset) is not
+     * reported, and one that settles after it does not end, so it can never count toward the next
+     * scene. A tile request's own `signal` (napari-js aborts a read it no longer needs) aborts the
+     * HTTP request.
+     */
+    tiledSource(desc: TileDescriptor, channel: number | undefined, channels: 1 | 4, scene?: AbortSignal, onTile?: () => () => void): TiledSource;
+    /**
+     * The composite pyramid's R, G and B bands as three scalar {@link TiledSource}s — one per
+     * additive layer, so each band takes its own window, gamma, invert, tint and visibility — that
+     * share ONE `/tile` request per tile. The three layers ask for a tile in the same frame: the
+     * first fetches the RGBA tile and splits it, the other two take their band from the same
+     * promise, and the split tile is dropped once all three have it. A band that asks later (one
+     * shown again after being hidden) finds it in a small LRU, else fetches it again. `scene` and
+     * `onTile` as {@link tiledSource}: the loading badge counts the one request.
+     */
+    rgbBandSources(desc: TileDescriptor, scene?: AbortSignal, onTile?: () => () => void): TiledSource[];
+    /**
+     * Assemble a downsampled uint8 volume (luminance) of `info`'s stack with napari-js's
+     * `assembleVolume`: every `sliceStep`th slice, read from the band's (or composite's) pyramid at
+     * the level that `maxSlice` needs, within its tile budget, and area-averaged to `maxSlice` on
+     * the longest side. Slices are read with bounded concurrency (the connection pool stays full
+     * without flooding it on a deep stack), each reporting `progress` (0–100) as it lands so the host
+     * shows a determinate progress bar. Null when `signal` aborts (a Cancel or a new plot), which
+     * also aborts the tile requests in flight — a partial volume is never returned.
+     */
+    assembleVolume(info: IImageInfo | undefined, opts: {
+        maxSlice?: number;
+        sliceStep?: number;
+    }, channel: number | undefined, hooks: {
+        signal: AbortSignal;
+        progress(percent: number): void;
+    }): Promise<AssembledVolume | null>;
+    /**
+     * The scalar source a volume reads: the band's (or composite's) pyramid; without one, one whole
+     * image per slice ({@link fetchImage}) as a single-tile level sized by the first slice, which is
+     * fetched here and served again as that slice's tile.
+     */
+    private volumeSource;
+    /**
+     * Slice `z` as a single WHOLE-image luminance plane (decimated to `maxGrid`), for the surface.
+     * Prefers the server pyramid, read at the level the grid needs ({@link readPlane}, which may
+     * drop a band to the composite overview); without a descriptor, the app's complete per-slice
+     * image (`urls`/`smallUrls`, as the Plotly surface) — never a lone top-left tile, which would be
+     * a corner of the slice — and only as a last resort the single-tile fetch.
+     */
+    fetchPlane(info: IImageInfo | undefined, z: number, channel: number | undefined, maxGrid: number): Promise<LumaPlane>;
+    /**
+     * Channel `channel`'s native-bit-depth histogram at slice `z` when `info` is a >8-bit image —
+     * the displayed pixels are 8-bit, so a client histogram would be clipped — cached per
+     * `(z, channel)`; null for an 8-bit channel, which the caller bins from the client data.
+     */
+    nativeHistogram$(info: IImageInfo | undefined, z: number, channel: number, bins: number): Observable<IHistogram | null> | null;
+    /** Fetch + cache one channel's native-bit-depth histogram from `GET /histogram` (>8-bit),
+     *  through the shared jit-service client — whose URL carries the per-app-load cache-buster
+     *  this backend used to omit, so a reload showed the server's 24 h-cached histogram. */
+    fetchNativeHistogram(channel: number, bins: number, z: number, key: string): Promise<IHistogram | null>;
+    /** Native-bit-depth (16/32-bit) multi-band TIFF export of slice `z` via the server
+     *  `/export/tiff` endpoint — the displayed PNG is an 8-bit figure, this preserves the true pixel
+     *  values. Visible channels only (omitted when all are visible → server default). Mirrors the
+     *  OSD backend. */
+    exportTiff(z: number, states: IChannelState[], fileName: string | undefined): Promise<void>;
+}

package/lib/implementations/napari-js/napari-tool-bridge.d.ts

@@ -0,0 +1,179 @@
+import type { Viewer } from 'napari-js';
+import { CanvasToolId } from '../../contracts/display-types';
+import { ICoordinateTransform } from '../../contracts/coordinate-transform.contract';
+import { PixelData } from '../../contracts/visualizer.contract';
+import { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
+import { RegionStore } from '../../store/region-store.service';
+import { CachedImageData, CanvasToolHost } from '../../toolbar/tool-kit/canvas-tool';
+import { CanvasToolManager } from '../../toolbar/tool-kit/canvas-tool-manager';
+import { WandService } from '../../toolbar/wand/wand.service';
+import { SamToolService } from '../../toolbar/segmentation/sam-tool.service';
+import { SamPointToolService } from '../../toolbar/segmentation/sam-point-tool.service';
+import { CellSegmentToolService } from '../../toolbar/segmentation/cell-segment-tool.service';
+import { NapariRegionOverlay, OverlayViewer } from './napari-region-overlay';
+/** A world-space rectangle (x, y = top-left). */
+export interface WorldRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** ICoordinateTransform over the napari camera: pointer client coords ↔ image/world coords. */
+export declare class NapariCoordinateTransform implements ICoordinateTransform {
+    private readonly viewer;
+    private readonly ready;
+    constructor(viewer: {
+        canvasToWorld(clientX: number, clientY: number): [number, number];
+        readonly camera: {
+            zoom: number;
+        };
+    }, ready: () => boolean);
+    clientToData(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
+    dataLengthToScreen(dataLength: number): number;
+    isReady(): boolean;
+}
+/** What the bridge reads from the service: the live viewer and its DOM, the image on screen, and
+ *  where the viewport and zone-crossing output go. */
+export interface ToolBridgeHost {
+    viewer(): Viewer | null;
+    host(): HTMLElement | null;
+    canvas(): HTMLCanvasElement | null;
+    /** The image's full-resolution size, or null before one is drawn. */
+    imageSize(): {
+        width: number;
+        height: number;
+    } | null;
+    frameIndex(): number;
+    fileName(): string | undefined;
+    /** The visible region changed (clamped to the image); called outside the Angular zone. */
+    viewportChanged(rect: WorldRect): void;
+    /** Run `fn` outside / inside the Angular zone. */
+    outsideZone<T>(fn: () => T): T;
+    inZone<T>(fn: () => T): T;
+}
+/** The services the pixel tools and segmentation runs need. */
+export interface ToolBridgeDeps {
+    regionStore: RegionStore;
+    wandService: WandService;
+    samTool: SamToolService;
+    samPointTool: SamPointToolService;
+    cellSegmentTool: CellSegmentToolService;
+    cellSegmenter: ICellSegmenter | null;
+}
+/**
+ * The napari backend's side of the shared canvas tools (review Appendix B, step 4): the region
+ * overlay, the {@link CanvasToolManager} and its host, the coordinate transform, and the
+ * displayed-pixel readback the wand, brush, eraser and SAM/cellpose read — kept current as the
+ * camera moves, but only paid for while a pixel tool needs it (NAPARI-SVC-26).
+ *
+ * One per service; {@link teardown} ends a scene's interaction (overlay, camera hook, timers,
+ * pixels) and an `install…Interaction` starts the next one's.
+ */
+export declare class NapariToolBridge {
+    private readonly host;
+    private readonly deps;
+    /** What this backend's canvas tools read and write (one host for every tool). */
+    readonly toolHost: CanvasToolHost;
+    /** This backend's own wand, brush, eraser, zoom-to-box and SAM point tools. */
+    readonly canvasTools: CanvasToolManager;
+    /** SVG region-drawing overlay (null until a 2D/3D interaction is installed). */
+    regionOverlay: NapariRegionOverlay | null;
+    /** The pixel tools' pointer ↔ world transform for the current viewer. */
+    coordTransform: ICoordinateTransform | null;
+    /** The last readback of the displayed composite (the pixel tools' source). */
+    lastPixels: PixelData | null;
+    /** Visible world rect captured AT the last readback — must pair with `lastPixels` so the pixel
+     *  tools' ratios/origin match the matrix's camera (using the live rect after a pan/zoom would
+     *  mis-scale the region). */
+    lastPixelsRect: WorldRect | null;
+    /** Active tools that read the displayed pixels; a pan/zoom re-reads them only while non-empty. */
+    readonly pixelTools: Set<CanvasToolId>;
+    /** The camera moved since {@link lastPixels} was read. */
+    pixelsStale: boolean;
+    /** Cached CachedImageData built from the last readback (rebuilt when lastPixels changes). */
+    private cachedImage;
+    private cachedImageSource;
+    /** Debounced readback timer + camera-change unsubscribe (keep lastPixels current for tools). */
+    private readbackTimer;
+    /** Debounced viewport emission for a camera change that needs no pixels. */
+    private viewportTimer;
+    private cameraOff;
+    constructor(host: ToolBridgeHost, deps: ToolBridgeDeps);
+    /**
+     * The interaction stack every 2D mode needs: the region overlay (draw/select/edit), the pixel
+     * tools that read back displayed pixels (wand, brush, vertex eraser, zoom-to-box, SAM/cellpose),
+     * and a camera hook that keeps that readback current as the view pans/zooms and tiled levels
+     * load.
+     *
+     * One call for all of it because forgetting it is invisible: the toolbar gates its region buttons
+     * on 2D-vs-3D rather than on plot type, so a 2D mode that skips this shows every tool and silently
+     * does nothing. That is exactly what happened to the spatial and region-centroid scatter modes.
+     */
+    install2dInteraction(viewer: Viewer, host: HTMLElement): void;
+    /**
+     * Region drawing for the 3D cloud.
+     *
+     * Reuses {@link NapariRegionOverlay} verbatim by handing it a SCREEN-SPACE viewer: the drawn
+     * shape is a lasso in canvas pixels, so "world" is the canvas and both transforms are identity
+     * (bar the client→canvas offset). Every existing tool — rectangle, polygon, freehand — therefore
+     * works in 3D with no new drawing code.
+     *
+     * A screen-space shape stops meaning anything the moment the camera moves, so an orbit clears
+     * the regions drawn in this view (and only those). The SELECTION they produced is kept: that is
+     * the durable artefact, and the highlighted points stay highlighted from every angle.
+     */
+    install3dInteraction(viewer: Viewer, host: HTMLElement): void;
+    /**
+     * The {@link OverlayViewer} the 3D region overlay draws through: "world" is the canvas, in
+     * canvas-local CSS pixels. A pointer arrives in CLIENT pixels, so `canvasToWorld` subtracts the
+     * canvas's client offset (without it the lasso was drawn offset from the cursor whenever the
+     * canvas was not at the page origin); drawing is then the identity, with no layout read.
+     */
+    screenSpaceViewer(viewer: Viewer): OverlayViewer;
+    /** End the scene's interaction: the overlay, the camera hook, the pending timers and the
+     *  pixels read from the old canvas. The armed tool and the pixel-tool set persist. */
+    teardown(): void;
+    /** Read the displayed composite into `lastPixels` (the pixel-tools' source) + emit the clamped
+     *  visible region. A fresh PixelData object means cachedImageData() rebuilds automatically. */
+    runReadback(): Promise<void>;
+    /** A readback on the next frame — after a plot or a scene change drew something new. */
+    scheduleReadback(): void;
+    /** Debounced readback — armed on camera changes while a pixel tool is active, so `lastPixels`
+     *  tracks the current view after a pan/zoom settles, which the on-canvas pixel tools
+     *  (wand/brush/SAM) read synchronously. Coalesces rapid changes. */
+    armReadback(delayMs?: number): void;
+    /** Emit the visible region, clamped to the image. */
+    private emitViewport;
+    /**
+     * A 2D pan/zoom. The full-canvas GPU readback is paid for only while a pixel tool reads it
+     * ({@link pixelTools}); otherwise only the viewport rect is emitted (debounced), and the pixels
+     * are marked stale for whoever next needs them (a tool arms a fresh readback as it activates).
+     */
+    private onViewChanged;
+    /** Build the pixel tools' coordinate transform for the current viewer. */
+    private buildCoordinateTransform;
+    /** Zoom/pan the camera to fit a data-space rectangle `[xMin, xMax, yMax, yMin]`. */
+    private applyZoomToBox;
+    /** Build CachedImageData from the most recent readback — its RGBA device pixels are the frame
+     *  as-is (packed, no per-pixel arrays: NAPARI-SVC-23) — with ratios/origin mapping image coords
+     *  ↔ readback pixels. Cached until the readback changes. */
+    cachedImageData(): CachedImageData | null;
+    /**
+     * The service's `beforeToolChange`: track the pixel-reading tool (see {@link onViewChanged}),
+     * gate the camera, and arm a fresh readback for a pixel tool. Nothing is armed without a
+     * viewer, nor a pixel tool before a plot built its coordinate transform.
+     *
+     * Control gating: a tool that ACTIVATES disables the camera controls; deactivation is a no-op
+     * because the host always calls the region overlay's setMode FIRST in each toggle (which sets
+     * the baseline enabled/disabled), so re-enabling here would fight a freshly-activated draw mode.
+     */
+    beforeToolChange(next: CanvasToolId | null): boolean;
+    /** SAM over the drawn rectangles — a server round-trip that reads the rectangles from the
+     *  RegionStore and the image from a fresh readback. Returns the regions added. */
+    segmentRectangles(): Promise<number>;
+    /** Cellpose over the drawn rectangles (see {@link segmentRectangles}). */
+    segmentRectanglesCellpose(): Promise<number>;
+}