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

package/lib/implementations/plotly/plotly-layouts.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Plotly layout builders for every plot type the Plotly backend renders. Pure:
+ * the live service state they need (screen height, aspect lock, drag mode, the
+ * current region shapes and colours) comes in through {@link ImageLayoutContext}.
+ */
+/** Plotly shape dicts, as `layout.shapes` takes them. */
+export type PlotlyShapeDict = Record<string, unknown>;
+/** The service state an image-aligned layout depends on. */
+export interface ImageLayoutContext {
+    screenHeight: number;
+    /** Lock the y axis to x (square image pixels). */
+    scaleratio: boolean;
+    /** The active Plotly drag mode, or '' for none. */
+    dragMode: string;
+    /** The region shapes to draw over the image. */
+    shapes: PlotlyShapeDict[];
+    /** The active (selected) shape's fill colour. */
+    fillColor: string;
+    /** The outline colour of a newly drawn shape. */
+    shapeColor: string;
+}
+/** One slider step per z-plane, each showing only its own trace. */
+export declare function sliderSteps(sliceCount: number): Array<{
+    label: number;
+    method: string;
+    args: unknown[];
+}>;
+/** The heatmap / RGB image layout: image axes, the z-plane slider, the region shapes. */
+export declare function heatmapLayout(ctx: ImageLayoutContext, xRange: number[], yRange: number[], sliceCount: number): {
+    margin: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    height: number;
+    sliders: {
+        pad: {
+            t: number;
+        };
+        currentvalue: {
+            visible: boolean;
+            prefix: string;
+            xanchor: string;
+        };
+        steps: {
+            label: number;
+            method: string;
+            args: unknown[];
+        }[];
+    }[];
+    autosize: boolean;
+    shapes: PlotlyShapeDict[];
+    activeshape: {
+        fillcolor: string;
+    };
+    dragmode: string | boolean;
+    newshape: {
+        line: {
+            color: string;
+            width: number;
+        };
+    };
+    xaxis: {
+        constrain: string;
+        constraintoward: string;
+        side: string;
+        ticks: string;
+        range: number[];
+    };
+    yaxis: {
+        constrain: string;
+        constraintoward: string;
+        range: number[];
+        ticks: string;
+        ticksuffix: string;
+        autorange: boolean;
+        scaleanchor: string | boolean;
+    };
+};
+/** Image-aligned 2D axes without the z-plane slider (region scatter). */
+export declare function overlayLayout(ctx: ImageLayoutContext, xRange: number[], yRange: number[]): {
+    margin: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    height: number;
+    autosize: boolean;
+    shapes: PlotlyShapeDict[];
+    dragmode: string | boolean;
+    xaxis: {
+        constrain: string;
+        constraintoward: string;
+        side: string;
+        ticks: string;
+        range: number[];
+    };
+    yaxis: {
+        constrain: string;
+        constraintoward: string;
+        range: number[];
+        ticks: string;
+        ticksuffix: string;
+        autorange: boolean;
+        scaleanchor: string | boolean;
+    };
+};
+/** Plain 2D chart axes (intensity profile / line plots). */
+export declare function chartLayout(screenHeight: number): {
+    margin: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    height: number;
+    autosize: boolean;
+    xaxis: {
+        title: string;
+    };
+    yaxis: {
+        title: string;
+    };
+    dragmode: boolean;
+};
+/** 3D scene for volumetric plot types (scatter3d, isosurface). */
+export declare function volumeLayout(screenHeight: number): {
+    margin: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    height: number;
+    autosize: boolean;
+    scene: {
+        xaxis: {
+            title: string;
+        };
+        yaxis: {
+            title: string;
+        };
+        zaxis: {
+            title: string;
+        };
+        aspectmode: string;
+    };
+};
+/**
+ * Scene layout for the surface plot: light-grey axis planes and a manual
+ * aspect ratio whose z extent is `zRatio` of the x/y extent.
+ */
+export declare function surfaceLayout(zRatio: number): {
+    margin: {
+        t: number;
+        b: number;
+        l: number;
+        r: number;
+    };
+    scene: {
+        xaxis: {
+            gridcolor: string;
+            zerolinecolor: string;
+            showbackground: boolean;
+            backgroundcolor: string;
+        };
+        yaxis: {
+            backgroundcolor: string;
+            gridcolor: string;
+            zerolinecolor: string;
+            showbackground: boolean;
+        };
+        zaxis: {
+            gridcolor: string;
+            zerolinecolor: string;
+            showbackground: boolean;
+            backgroundcolor: string;
+        };
+        aspectratio: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        aspectmode: string;
+    };
+};

package/lib/implementations/plotly/plotly-readback.d.ts

@@ -0,0 +1,41 @@
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { PixelData } from '../../contracts/visualizer.contract';
+import { PlotType } from '../../contracts/plot-type';
+import { IChannelState } from '../../contracts/channel-histogram-api.contract';
+/**
+ * Pure reads of what the Plotly backend has on screen or in memory: a trace's
+ * pixels, a frame's histogram, the image rect the axes show, and the restyle
+ * that applies the channel display state.
+ */
+/** A plotted trace's `z` grid as flat pixels: an RGB `image` trace keeps its
+ *  channels (3 or 4), a heatmap is one rounded channel. Null when empty. */
+export declare function tracePixels(trace: {
+    type?: string;
+    z?: any[][];
+} | undefined): PixelData | null;
+/** 256-bin histogram of one channel of a frame (raw, pre-LUT). Grayscale cells
+ *  are numbers; RGB cells `[r,g,b]` give channel `channelIndex`, or the BT.601
+ *  luminance for an index past their channels. */
+export declare function frameHistogram(frame: any[], channelIndex: number): IHistogram;
+/** 256-bin histogram of a one-byte-per-pixel plane (a channel's raw pixels). */
+export declare function planeHistogram(plane: ArrayLike<number>): IHistogram;
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * The image rect the plot shows, from the live axis ranges — after a high-def
+ * zoom the axes are relaid out to the crop's bounds, so the ranges ARE the
+ * crop — else the whole image `[x0, x1, y0, y1]`, else null.
+ */
+export declare function axesSourceRect(xr: number[] | undefined, yr: number[] | undefined, trueImgSize: number[] | undefined): Rect | null;
+/**
+ * The restyle that live-applies the channel display: the colour scale, reverse
+ * (reverse-scale and invert each flip the ramp; both together cancel) and the
+ * Intensity channel's window — cmin/cmax for the 3D plot types, zmin/zmax for
+ * heatmap/contour. A trace without a colour scale ignores these attributes.
+ */
+export declare function channelDisplayRestyle(channels: IChannelState[], reverse: boolean, invert: boolean, colorscale: unknown, plotType: PlotType): Record<string, unknown>;
+export {};

package/lib/implementations/plotly/plotly-region-overlay.d.ts

@@ -16,8 +16,8 @@ export declare class PlotlyRegionOverlay implements IRegionOverlay {
     constructor(plotly: PlotlyService);
     setMode(mode: RegionToolMode): void;
     redraw(): void;
-    /** Bezier regions are an OpenSeadragon-only feature (Plotly has no native
-     *  curved-shape rendering), so this is a no-op here. */
+    /** Bezier regions are drawn by the SVG overlays (OpenSeadragon, napari-js);
+     *  Plotly has no native curved-shape rendering, so this is a no-op here. */
     setSelectedBezier(_bezier: boolean): void;
     destroy(): void;
 }

package/lib/implementations/plotly/plotly-shape-projection.d.ts

@@ -0,0 +1,92 @@
+import { Subscription } from 'rxjs';
+import { RegionStore } from '../../store/region-store.service';
+/** The service state the projection reads. */
+export interface ShapeProjectionHost {
+    /** The plot div's id ('' before the first plot); it may be another backend's now. */
+    plotDiv(): string;
+    /** The image on screen (shapes are tagged with it). */
+    fileName(): string | undefined;
+}
+/**
+ * Plotly's render projection of the shared RegionStore: `shapes` is the dict
+ * array `Plotly.relayout` consumes, kept beside the store. Shapes edited or
+ * drawn on the Plotly canvas are mirrored INTO the store ({@link commitToStore});
+ * every other change — wherever it was made — arrives as a store update event
+ * and is projected back OUT and redrawn ({@link connect}). Also maps the store's
+ * selection onto Plotly's `_activeShapeIndex` (the shape with the edit handles)
+ * and back.
+ */
+export declare class PlotlyShapeProjection {
+    private readonly host;
+    private readonly regionStore;
+    /** The render projection: one Plotly shape dict per store region. */
+    shapes: any[];
+    /** Nesting depth of {@link quietly}: region updates are not redrawn while > 0. */
+    private muted;
+    private readonly utils;
+    constructor(host: ShapeProjectionHost, regionStore: RegionStore);
+    /** The plot div, live Plotly graph or not (null when none is set). */
+    private gd;
+    /** The plot div while it hosts a live Plotly graph, else null: the div stays
+     *  set after it was handed to another backend, and Plotly throws on it then. */
+    private liveGd;
+    /** Rebuild the dict working-set from the store (after an image switch, or when
+     *  regions changed while another backend was rendering). */
+    syncFromStore(): void;
+    /**
+     * Make the shared store authoritative for the current dict working-set: convert
+     * the dicts to neutral regions and replace the store's list (the store mints
+     * ids, applies class colours, syncs its per-image cache and emits the
+     * region-update event). Store-minted ids are written back onto the dicts so the
+     * two representations stay aligned. Profile-line ROIs are ordinary regions
+     * (tagged `kind: 'profile'`) and round-trip through here too.
+     */
+    commitToStore(): void;
+    /**
+     * Apply a `plotly_relayout` event's shape part: in-place edits
+     * (`shapes[i].x0`, `shapes[i].path`, …, rounded to whole pixels) and a shape
+     * drawn natively on the canvas (a lone `shapes` key — snapped, tagged with
+     * the file and, when labels are on, a label object), mirrored into the store.
+     */
+    applyRelayout(event: Record<string, any>): void;
+    /** Push the dict working-set to Plotly (a no-op when another backend owns the div). */
+    render(): void;
+    /** The shapes of the image on screen, labelled (or not) for display, as fresh dicts. */
+    shapesToRedraw(showLabel?: boolean): any[];
+    /**
+     * Follow the shared store: redraw the shapes on every region update and move
+     * the edit handles on every selection change, whoever made the change (the
+     * router, an undo, the Region Editor, another backend's overlay, a canvas
+     * tool). Plotly is not on the store's write path any more — it listens, like
+     * the OpenSeadragon and napari-js overlays do. Service-lifetime: both
+     * callbacks no-op while no live Plotly graph holds the div.
+     */
+    connect(): Subscription;
+    /**
+     * Run `write` — a store write this projection already reflects (a shape edited
+     * on the canvas, an image switch the next plot draws) — without redrawing from
+     * the update event it causes.
+     */
+    quietly(write: () => void): void;
+    /**
+     * A region update. The stored set re-projects and redraws; a transient set
+     * (`setRegions(…, isRegionSaveOn = false)`, which the store emits without
+     * storing) is drawn as-is and leaves the working-set alone.
+     */
+    private onRegionUpdate;
+    /**
+     * A selection change: Plotly's `_activeShapeIndex` points at the last selected
+     * shape so it gets the edit handles (Plotly's own active-shape rendering is the
+     * only highlight). Skipped when the plot already shows it — the change came
+     * from a click on the plot ({@link syncSelectionFromPlot}).
+     */
+    private onSelection;
+    /**
+     * Read Plotly's `_activeShapeIndex` and push it as the selection. Plotly fires
+     * no dedicated active-shape event for clicks, so this is sampled after a
+     * relayout and a click. The store no-ops when the selection is unchanged.
+     */
+    syncSelectionFromPlot(): void;
+    /** The shapes-relayout payload: the shapes plus the active-shape fill colour. */
+    private relayoutPayload;
+}

package/lib/implementations/plotly/plotly-trace-builders.d.ts

@@ -6,19 +6,19 @@ import { PlotType } from '../../contracts/plot-type';
  * DESIGN / EXTRACTION ALIGNMENT
  * -----------------------------
  * Every function here is **pure** — it takes a `TraceBuildInput` and returns
- * Plotly trace dicts. There is no Angular, no RxJS, no host-state coupling
- * (`MainState`, `FilesService`, …). That keeps the module relocatable into the
- * future `@jax-data-science/image-visualization` library core (see the
- * `sketch/jit-plotting-extraction` SOW) without port surgery.
+ * Plotly trace dicts. There is no Angular, no RxJS and no service state, so
+ * the builders are unit-testable on plain fixtures.
  *
- * Layout building stays in `PlotlyService` (it needs live service state such
- * as screen height, scale ratio and the current shapes); only TRACE building
- * is pluggable here. To add a new plot type: write a builder, register it in
- * `PLOTLY_PLOT_TYPE_IMPLS`, and add a descriptor in `contracts/plot-type.ts`.
+ * Layouts are built in `plotly-layouts.ts` (from a context of live service
+ * state); only TRACE building is pluggable here. To add a new plot type: write
+ * a builder, register it in `PLOTLY_PLOT_TYPE_IMPLS`, and add a descriptor in
+ * `contracts/plot-type.ts`.
  *
- * The original HEATMAP/SURFACE/RGB types intentionally keep their dedicated
- * renderers in `PlotlyService` (they are also reused by the high-def zoom
- * re-fetch path), so they are NOT registered here.
+ * The original HEATMAP/SURFACE/RGB types have their own builders at the end of
+ * this file ({@link buildHeatmapTraces}, {@link buildSurfaceTraces},
+ * {@link buildRgbImageTraces}) — used by the initial render and the high-def
+ * zoom re-render alike — but are NOT registered: they take the raw frames and
+ * the active colormap, not a {@link TraceBuildInput}.
  */
 /** Normalised input for a trace builder. Frames are per-z-plane matrices:
  *  grayscale cells are scalars, RGB cells are `[r, g, b]`. */
@@ -57,4 +57,15 @@ export interface PlotlyPlotTypeImpl {
 }
 /** Registry of the pluggable (non-original) plot types. */
 export declare const PLOTLY_PLOT_TYPE_IMPLS: Partial<Record<PlotType, PlotlyPlotTypeImpl>>;
-export declare function getPlotTypeImpl(type: PlotType): PlotlyPlotTypeImpl | undefined;
+/**
+ * One grayscale heatmap trace per z-plane, only the first visible (the layout's
+ * slider switches them). `trueImgSize` is [x0, x1, y0, y1]; `ratios` the data
+ * units per pixel. No per-cell hover text: building it for every pixel is too slow.
+ */
+export declare function buildHeatmapTraces(frames: any[], trueImgSize: number[], ratios: number[], colorscale: unknown, reversescale: boolean): any[];
+/** One grayscale surface trace per frame, coloured by the active colormap. */
+export declare function buildSurfaceTraces(frames: any[], colorscale: unknown, reversescale: boolean): any[];
+/** One RGB `image` trace per z-plane (width × height pixels), only the first visible. With
+ *  `sources`, each plane draws its PNG data URI instead of its `z` cells (the browser draws it;
+ *  Plotly paints `z` one rectangle per pixel). */
+export declare function buildRgbImageTraces(frames: any[], trueImgSize: number[], ratios: number[], width: number, height: number, sources?: string[]): any[];

package/lib/implementations/plotly/plotly-zoom-controller.d.ts

@@ -0,0 +1,86 @@
+import * as Plotly from 'plotly.js-dist-min';
+import { MessageService } from 'primeng/api';
+import { IImageInfo } from '../../contracts/image.contract';
+import { TileAccessPort } from '../../contracts/ports/tile-access.port';
+import { ImageStatePort } from '../../contracts/ports/image-state.port';
+/** The service state and render hooks the zoom drives. */
+export interface PlotlyZoomHost {
+    plotDiv(): string;
+    /** [x0, x1, y0, y1] of the plotted image, or undefined before one. */
+    trueImgSize(): number[] | undefined;
+    imageInfo(): IImageInfo | undefined;
+    fileName(): string | undefined;
+    imageCached(): boolean;
+    zIndex(): number;
+    /** Start a render generation; a newer one supersedes a crop in flight. */
+    nextRenderGen(): number;
+    isCurrentRender(gen: number): boolean;
+    heatmapLayout(xRange: number[], yRange: number[]): Plotly.Layout;
+    setScreenHeight(height: number): void;
+    /** Called at request time: returns the hook that samples the crop's pixels
+     *  (tools + intensity profiles), or drops them when sampling moved on. */
+    cropSampler(): (frame: any[], ratios: number[], origin: [number, number]) => void;
+    /** Re-render the crop in the plot type on screen; `reapplyRange` when the
+     *  layout is image-aligned (the heatmap range must be re-applied). */
+    renderCrop(frame: any[], ratios: number[], size: [number, number], imageSize: number[], fileName?: string): {
+        rendered: Promise<unknown>;
+        reapplyRange: boolean;
+    };
+    /** Clear the plot after a failed relayout. */
+    reset(): void;
+}
+/**
+ * Plotly zoom: the step and box zooms, autoscale, and the HIGH-DEF zoom — a
+ * zoomed-in range is re-fetched from the server at screen resolution and
+ * re-rendered in place, so the user sees the data at the zoom level rather
+ * than the upscaled preview. Owns the current zoom box.
+ */
+export declare class PlotlyZoomController {
+    private readonly host;
+    private readonly state;
+    private readonly tiles;
+    private readonly messages;
+    /** The zoomed range [x0, x1, y0, y1], or [] when not zoomed. */
+    zoomCoordinates: number[];
+    /** Whether a 2D drag-zoom re-fetches at high definition. */
+    isRealZoom: boolean;
+    private readonly utils;
+    constructor(host: PlotlyZoomHost, state: ImageStatePort, tiles: TileAccessPort, messages: MessageService);
+    private gd;
+    /** The axis-range part of a `plotly_relayout` event: remember the drag-zoom
+     *  box and, outside stack mode, re-fetch it at high definition. */
+    onRelayout(event: Record<string, any>): void;
+    /** Autoscale the plot (and forget the zoom box). */
+    autoscale(): void;
+    /** Back to the whole image. */
+    resetAxes(): void;
+    /**
+     * Re-apply the image layout at the current DOM height: over the zoom box when
+     * zoomed, else over `trueImageSize` (default: the plotted image). A failed
+     * relayout clears the plot and tells the user to reopen the image.
+     */
+    relayout(trueImageSize?: number[]): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Scale the visible range about its centre by `factor` (< 1 zooms in). */
+    private stepZoom;
+    /** Overlay pixel → data coords via the axis objects (minus the plot margin);
+     *  the zoom-to-box tool calls this through its host. */
+    pixelToData(px: number, py: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Apply a zoom-to-box selection: stack mode does a pure axis-range relayout;
+     * otherwise the high-def pipeline re-fetches the box at the new resolution.
+     */
+    applyZoomToBox(coordinates: number[]): void;
+    /**
+     * The high-def zoom: fetch `coordinates` from the server at screen resolution
+     * and re-render it in place (in the plot type on screen), unless the user
+     * moved on meanwhile — another file, another render of the div (a new zoom or
+     * plot, or the div handed to another backend). A box covering the whole image
+     * autoscales instead.
+     */
+    triggerZoom(coordinates: number[]): void;
+}