@jax-data-science/sci-image-visualizer 0.1.0

package/lib/implementations/napari-js/napari-scale-bar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Physical scale bar for the napari-js WebGPU image view (jit-ui#102), mirroring the OSD
+ * backend's {@link OsdScaleBar}. napari keeps layers at pixel scale, so the camera's `zoom`
+ * (CSS px per world unit) is exactly screen px per image pixel; combined with the image's
+ * µm/pixel (`mppX`, from Bio-Formats `/tiles/info`) that gives a real-world bar length.
+ * Recomputes on every camera change and host resize. Hidden when the image has no physical size.
+ */
+/** Format a length given in micrometres, picking the unit that suits its magnitude (jit-service
+ *  normalises whatever unit Bio-Formats reports to µm). */
+export declare function formatUm(um: number): string;
+/** The slice of the napari Camera the scale bar reads (zoom = CSS px per world/image pixel). */
+interface ScaleBarCamera {
+    readonly zoom: number;
+    readonly changed: {
+        connect(listener: () => void): () => void;
+    };
+}
+export declare class NapariScaleBar {
+    private readonly host;
+    private readonly camera;
+    private readonly mppX;
+    private readonly bar;
+    private readonly line;
+    private readonly label;
+    private readonly disconnectCamera;
+    private readonly resizeObserver?;
+    constructor(host: HTMLElement, camera: ScaleBarCamera, mppX: number);
+    private update;
+    destroy(): void;
+}
+export {};

package/lib/implementations/napari-js/napari-visualizer.service.d.ts

@@ -0,0 +1,455 @@
+import { Observable } from 'rxjs';
+import { Image } from 'image-js';
+import { IImageInfo } from '../../contracts/image.contract';
+import { PlotType, PlotTypeDescriptor } from '../../contracts/plot-type';
+import { IVisualizer, PixelData, IntensityProfile, IIsosurfaceControls, IIntensityControls, ISurface3dControls } from '../../contracts/visualizer.contract';
+import { ViewerCapabilities } from '../../contracts/capabilities.contract';
+import { IRegionOverlay } from '../../contracts/region-overlay.contract';
+import { IHistogram } from '../../contracts/channel-histogram-api.contract';
+import { IWandOptions, IBrushOptions } from '../../contracts/display-types';
+import { VizConfig } from '../../contracts/viz-config';
+import { TileAccessPort } from '../../contracts/ports/tile-access.port';
+import { BaseStoreVisualizer } from '../base-store-visualizer';
+import { SimpleSliceAccessService } from '../simple-slice-access.service';
+import { VisualizerStore } from '../../store/visualizer-store.service';
+import { RegionStore } from '../../store/region-store.service';
+import { WandToolService } from '../../toolbar/wand/wand-tool.service';
+import { BrushToolService } from '../../toolbar/brush/brush-tool.service';
+import { VertexEraserToolService } from '../../toolbar/vertex-eraser/vertex-eraser-tool.service';
+import { ZoomToBoxToolService } from '../../toolbar/zoom-to-box/zoom-to-box-tool.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 { ICellSegmenter } from '../../contracts/cell-segmenter.contract';
+import * as i0 from "@angular/core";
+/** Opaque handle from {@link NapariVisualizerService.load}, passed back to plot(). */
+interface NapariLoaded {
+    imageInfo: IImageInfo;
+    z: number;
+    /** Must match `IImageInfo.fileName` — the render orchestrator drops the result if the
+     *  handle's `filename` doesn't match the requested image (guards against stale clicks). */
+    filename: string;
+}
+/**
+ * A WebGPU image backend built on the published `napari-js` library — the POC engine for
+ * jit-ui#102 (a browser-based napari shipped as a JS library, swapping image plotting with
+ * OpenSeadragon and 3D slicing/isosurfaces with Plotly).
+ *
+ * Render strategy: rather than re-implement the server's tile/pyramid protocol (which OSD
+ * already handles), this backend renders the **complete per-slice image URLs the app already
+ * produces** (`IImageInfo.urls`) — `urls[z]` for the 2D image, and the full `urls` stack
+ * assembled into a downsampled volume for the 3D types. Region state and display options
+ * delegate to the shared {@link RegionStore} / {@link VisualizerStore}, exactly as OSD does.
+ *
+ * Follow-ups (jit-ui#102): native-resolution pyramidal tiling, on-canvas tools, region
+ * overlay rendering, per-channel histograms, TIFF export.
+ */
+export declare class NapariVisualizerService extends BaseStoreVisualizer implements IVisualizer {
+    private readonly tiles;
+    private readonly wandTool;
+    private readonly brushTool;
+    private readonly eraserTool;
+    private readonly zoomToBoxTool;
+    private readonly samTool;
+    private readonly samPointTool;
+    private readonly cellSegmentTool;
+    private readonly cellSegmenter;
+    private readonly simpleStack;
+    readonly capabilities: ViewerCapabilities;
+    private readonly api;
+    private viewer;
+    private canvas;
+    private host;
+    private loaded;
+    private lastPixels;
+    private currentPlotType;
+    /** napari-js high-level view owning the 3D volume layers (one additive tinted layer per channel
+     *  for multichannel, or a single grayscale volume). Null in 2D. */
+    private volumeView;
+    /** True when the volume is composited from per-channel layers (vs a single grayscale volume). */
+    private volumeMultichannel;
+    /** napari-js height-field surface mesh (NAPARI_SURFACE plot type; null otherwise). Built from a
+     *  single grayscale slice by {@link buildSurface} via napari-js's `heightField` + `addSurface`. */
+    private surfaceLayer;
+    /** Which band the surface samples (a channel index for multichannel, else the composite). */
+    private surfaceChannel;
+    /** Pre-loaded per-slice luminance planes (already decimated to the surface grid), keyed by z,
+     *  so the stack slider rebuilds the surface instantly. Filled by {@link preloadSurfacePlanes}. */
+    private readonly surfacePlanes;
+    /** In-plane grid cap for the active surface load (full grid ÷ the decimate factor). */
+    private surfaceMaxGrid;
+    /** Contrast window [min,max] the current surface mesh was built with. A change reshapes the
+     *  mesh (pixel height = intensity within [min,max]), so it triggers a geometry rebuild. */
+    private surfaceWindow;
+    /** Persisted wireframe choice for the surface (re-applied when a new surface mounts). */
+    private surfaceWireframe;
+    /** napari-js 2D scatter points (region centroids) + its region-change subscription. */
+    private scatter2dPoints;
+    private scatterRegionSub;
+    /** napari-js 3D scatter (voxel point cloud). */
+    private scatter3dLayer;
+    /** Monotonic load generation. Bumped by {@link reset} and {@link cancelLoading}; the frame-loading
+     *  loops (volume assembly, surface preload) capture it and bail when it changes, so a Cancel (or a
+     *  new plot) actually stops fetching frames instead of running to completion in the background. */
+    private loadToken;
+    /** Decimate factor for the napari 3D types (1 = Full, 2 = ½ default, 4 = ¼, 8 = ⅛). Applied when a
+     *  volume/isosurface/surface (re)loads; changing it needs a re-plot (it changes fetched data). */
+    private resolutionScale;
+    /** 3D coordinate-axes / scale gizmo for the volume/isosurface view (null in 2D). */
+    private axesLayer;
+    /** DOM X/Y/Z + scale labels tracking the 3D axes gizmo (null in 2D). */
+    private axesLabels;
+    /** Draggable Z-height grip over the volume (null unless a volume/isosurface is mounted). */
+    private zHandle;
+    /** User Z-height factor for the volume (1 = the volume's natural proportions); driven by the
+     *  in-view drag handle. Reset per mount. */
+    private volumeZScale;
+    /** Volume world box at `volumeZScale = 1` (base) + the sampled voxel depth — enough to recompute
+     *  the Z-axis voxel scale, axes depth, and overlay anchors as the handle stretches Z. */
+    private volumeWorldBase;
+    private volumeSampledDepth;
+    /** Persisted axes on/off choice, re-applied when a new volume mounts. Defaults on. */
+    private axesVisible;
+    private volumeDims;
+    /** Assembled uint8 volume data per channel (key = channel index), kept for the volume intensity
+     *  histogram. Key 0 holds the grayscale/composite volume in the single-channel case. */
+    private readonly volumeChannelData;
+    private imageW;
+    private imageH;
+    /** Monotonic slice-request id so a slow out-of-order slice fetch can't clobber a newer one. */
+    private sliceReq;
+    /** Cached `/tiles/info` pyramid descriptor + the infoB64 it was fetched for. */
+    private descriptor;
+    private descriptorKey;
+    /** How the current 2D image is composited (drives histogram + state application). */
+    private imageMode;
+    /** napari-js high-level view that owns the per-channel layer set (build + live display
+     *  updates) for the current {@link imageMode}. Rebuilt on each (re)render. */
+    private channelView;
+    /** Live subscription applying channel-state / colormap changes to the layers. */
+    private displaySub;
+    /** Latest grayscale colormap selection from the store (applied to the single gray layer). */
+    private currentColormap;
+    private currentReverse;
+    /** Latest invert toggle from the store (flips intensity before the colormap, like OSD). */
+    private invertEnabled;
+    /** Physical scale bar overlay for the 2D image (null when 3D or the image has no µm/pixel). */
+    private scaleBar;
+    /** SVG region-drawing overlay for the 2D image (null until a 2D image is plotted). */
+    private regionOverlay;
+    /** Pixel-tool plumbing: the plot div id, coord transform, and bound tool hosts. */
+    private plotDivId;
+    private coordTransform;
+    private wandHost;
+    private eraserHost;
+    /** Cached CachedImageData built from the last readback (rebuilt when lastPixels changes). */
+    private cachedImage;
+    private cachedImageSource;
+    /** 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). */
+    private lastPixelsRect;
+    /** Image smoothing (bilinear) vs nearest-neighbour (crisp pixels, the default). */
+    private imageSmoothing;
+    /** True when the 2D image is rendered via pyramidal TiledSources (descriptor available). */
+    private tiled;
+    /** Debounced readback timer + camera-change unsubscribe (keep lastPixels current for tools). */
+    private readbackTimer;
+    private cameraReadbackOff;
+    /** Coarse per-channel luminance sample (keyed by channel index) for the histogram in tiled mode,
+     *  where the layers have no full in-memory pixels. Refreshed on plot + slice change. */
+    private readonly histSamples;
+    /** Native-bit-depth histograms from `/histogram`, keyed `${z}|${channel}` (>8-bit images). */
+    private readonly nativeHistograms;
+    private readonly stackLoading$;
+    private readonly stackLoadingProgress$;
+    private readonly autoscaleEvent$;
+    private readonly intensityProfile$;
+    private readonly viewportChange$;
+    constructor(tiles: TileAccessPort, store: VisualizerStore, regionStore: RegionStore, wandTool: WandToolService, brushTool: BrushToolService, eraserTool: VertexEraserToolService, zoomToBoxTool: ZoomToBoxToolService, samTool: SamToolService, samPointTool: SamPointToolService, cellSegmentTool: CellSegmentToolService, cellSegmenter: ICellSegmenter | null, simpleStack: SimpleSliceAccessService, config: VizConfig);
+    /**
+     * 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 briefly. Cached per `infoB64`; returns null if it never becomes
+     * ready (callers fall back to a single-tile fetch). This is the authoritative grid — guessing
+     * level dims from `trueImageSize` overshoots the real grid and the server 400s out-of-range tiles.
+     */
+    private ensureDescriptor;
+    /**
+     * Fetch a COMPLETE rendered slice as an `ImageBitmap` by stitching the server's REAL tile grid
+     * (from `/tiles/info`) — not just the top-left tile, which only ever showed a large image's
+     * corner. Picks the finest pyramid level whose grid fits `budgetTiles` and whose longest side is
+     * within the GPU texture limit, fetches that grid concurrently, and stitches it into one canvas.
+     *
+     * `channel` selects a single band as grayscale (real levels only); omit for the server composite.
+     * `budgetTiles` caps the grid: the 2D view uses the full budget for detail; the 3D volume passes
+     * 1 for a cheap overview tile per slice (it downsamples to {@link VOLUME_MAX_SLICE}). Falls back
+     * to a single `col=0,row=0` tile when no descriptor is available (small/simple images, volumes).
+     */
+    private fetchSlice;
+    load(imageInfo: IImageInfo, zIndex: number): Promise<NapariLoaded>;
+    plot(plotDiv: string, imageLoaded: unknown, imageInfo: IImageInfo, screenHeight: number, plotType: PlotType, _inPlace?: boolean): Promise<boolean>;
+    /** The grayscale display colormap from the store selection (+reverse), defaulting to gray.
+     *  Maps the jit-ui store colormap node to a napari `Colormap` via the library's LUT factory;
+     *  the multichannel tint ramps are built inside {@link MultiChannelImageView} from each
+     *  channel's hex colour. */
+    private grayscaleColormap;
+    /** Fetch a stitched slice and read it back as a single-channel uint8 plane. `channel` selects a
+     *  band (multichannel); omit it for the grayscale composite (all overview levels available, so a
+     *  large image picks a fitting downscaled level rather than only the full-res real level). */
+    private fetchChannelData;
+    /** Decode an `ImageBitmap` (server bands are grayscale, R=G=B) to a single-channel uint8 plane.
+     *  `maxSide` caps the longest side (downscaling on the canvas draw) — used to keep pre-loaded
+     *  surface slice planes small. */
+    private bitmapToLuminance;
+    /**
+     * Render the 2D image for slice `z`. With a server pyramid descriptor we use a pyramidal
+     * {@link TiledSource} per layer so the view refines to higher resolution on zoom (like OSD) and
+     * sits naturally in full-resolution coordinates; without one we fall back to the single-level
+     * stitch. Three display modes either way: multichannel additive tint, grayscale colormap, RGB.
+     */
+    private renderImage;
+    /** Single-level stitch fallback (no descriptor): the pre-tiling path. */
+    private renderImageStitched;
+    /**
+     * Render the 2D image with pyramidal {@link TiledSource}s — the view refines to higher resolution
+     * as you zoom in (the visual fetches the level whose texels ≈ screen pixels) and sits in full-res
+     * coordinates so regions align. Same three modes as the stitch path. Per-channel layers use the
+     * REAL pyramid levels (per-channel tiles only exist there); the composite uses all levels.
+     */
+    private renderImageTiled;
+    /** 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). */
+    private buildTiledSource;
+    /** (Re)fetch a coarse per-channel luminance sample for the histogram (tiled mode has no full
+     *  in-memory pixels). One cheap overview tile per channel; cached by channel index. */
+    private refreshHistogramSamples;
+    /** Subscribe channel states + grayscale colormap → live-apply to the rendered layers (no
+     *  re-fetch; only z changes re-fetch). Replaces any prior subscription. */
+    private subscribeDisplayState;
+    /** Subscribe the store colormap (+reverse), invert, and channel state → the volume/isosurface
+     *  transfer function: colour (channel tint or selected colormap), the intensity **window
+     *  (min/max → contrastLimits)** and **gamma**, mirroring the grayscale image's display controls
+     *  so the histogram pane drives the 3D render. Replaces any prior subscription. */
+    private subscribeVolumeDisplayState;
+    /** A channel's tint colormap (black→colour) with reverse-scale / invert applied by flipping. */
+    private channelTintColormap;
+    /**
+     * Colour map for the volume/isosurface. A real colormap selection (viridis/magma/…) wins;
+     * otherwise the channel's colour tints it (so the channel-dialog colour swatch recolors the 3D
+     * render). Reverse-scale and invert each flip the ramp — the `VolumeLayer` has no per-layer
+     * invert, so both are emulated by reversing the colormap.
+     */
+    private volumeColormap;
+    /** Apply the current channel states / colormap to the live layers (no re-fetch), delegating the
+     *  per-channel layer mutations to the {@link MultiChannelImageView}. */
+    private applyDisplayState;
+    /** (Re)install the physical scale bar over the 2D image, sized from the image's µm/pixel
+     *  (`/tiles/info` mppX, falling back to the image metadata). No-op without a physical size. */
+    private installScaleBar;
+    /** Convert a napari-js `Histogram` (bin count + min/max) to the pane's `IHistogram` (bin edges). */
+    private toIHistogram;
+    /**
+     * Mount the 3D volume/isosurface. A multichannel image becomes one additive, tinted
+     * {@link VolumeLayer} per channel (so each channel's colour composites into the render); a
+     * grayscale/composite image uses a single volume. Adds the axes gizmo + labels and wires the
+     * display-state subscription. The caller owns `viewer.ready`.
+     */
+    private mountVolume;
+    /**
+     * Restretch the volume's Z height live (driven by the in-view {@link NapariVolumeZHandle}). Only
+     * the per-axis `voxelSize` / axes depth change — the voxel textures are untouched — so dragging is
+     * smooth. `factor` is relative to the volume's natural proportions (1). Persists across re-mounts
+     * (resolution changes) so the chosen height sticks.
+     */
+    private setVolumeZScale;
+    /** Build the X/Y/Z axis-end label specs for the 3D gizmo. Anchors are in the volume's centred
+     *  world box (matching the AxesLayer geometry); the scale text reflects the FULL image extent —
+     *  physical µm when µm/pixel is known, else pixel (X/Y) / slice (Z) counts. */
+    private buildAxesLabels;
+    /**
+     * Assemble a downsampled uint8 volume (luminance) from the per-slice tile endpoint. Slices are
+     * fetched with bounded concurrency (keeps the connection pool full without flooding it on a deep
+     * stack) and read into the volume as each arrives, driving {@link stackLoadingProgress$} so the
+     * host shows a determinate progress bar instead of a bare spinner.
+     */
+    private assembleVolume;
+    /**
+     * Mount the NAPARI_SCATTER 2D scatter: the slice image with a points layer at each region's
+     * centroid (napari-js analog of Plotly's region-centroid scatter). Rebuilds the points live as
+     * regions change.
+     */
+    private mountScatter;
+    /** (Re)build the 2D scatter's point layer at the current region centroids. */
+    private rebuildScatterPoints;
+    /** Region centroids as flat `[x, y, …]` data coords (rectangle / polygon / multipolygon). */
+    private regionCentroids;
+    /**
+     * Mount the NAPARI_SCATTER3D 3D scatter: the downsampled voxel grid as a 3D point cloud colored
+     * by intensity (napari-js analog of Plotly's voxel scatter3d). Assembles a coarse volume, then
+     * emits a flat-strided sample of voxels (capped at {@link SCATTER3D_MAX_POINTS}) via `addPoints3D`.
+     */
+    private mountScatter3d;
+    /** Store colormap / reverse / invert / channel window → the 3D scatter's colormap + contrast. */
+    private subscribeScatter3dDisplayState;
+    /**
+     * Mount the NAPARI_SURFACE height-field surface. A height field is single-scalar, so for a
+     * multichannel image the surface follows ONE band — the first visible channel (fallback 0) —
+     * coloured by that channel's window/colormap (like the Plotly SURFACE, which is grayscale-only).
+     * Pre-loads every slice's height data with a progress bar (as the volume does) so the stack
+     * slider re-slices instantly, then builds the mesh for the current slice. All mesh + GPU work
+     * lives in napari-js (`heightField` + `Viewer.addSurface`); this backend supplies scalar slices.
+     */
+    private mountSurface;
+    /** Add the 3D axes gizmo + DOM labels around the (origin-centered) surface mesh, matching the
+     *  volume/isosurface. Installed once per mount; the box tracks the mesh bounds, X/Y show the
+     *  physical (or pixel) extent, and Z is the intensity/height axis. */
+    private installSurfaceAxes;
+    /** X/Y/Z end-labels for the surface gizmo: X/Y are the physical (µm) or pixel extent of the FULL
+     *  image; Z is the intensity/height axis. Anchors are in the centered box (matching AxesLayer). */
+    private buildSurfaceAxesLabels;
+    /**
+     * Pre-fetch every stack slice's luminance plane (decimated to the surface grid) into
+     * {@link surfacePlanes}, driving {@link stackLoadingProgress$} — the same load-with-progress UX
+     * as the volume, but keeping one 2D plane per slice rather than packing a 3D volume. Bounded
+     * concurrency keeps the connection pool busy without flooding it on a deep stack.
+     */
+    private preloadSurfacePlanes;
+    /**
+     * Fetch slice `z` as a single WHOLE-image luminance plane (decimated to `maxGrid`). Prefers the
+     * app's complete per-slice image (`smallUrls`/`urls`, exactly like the Plotly surface) so the
+     * surface always covers the FULL slice — the tile-pyramid `fetchSlice` path would fall back to a
+     * single top-left tile (a corner) for self-contained / non-`/tiles/info` images. Falls back to
+     * stitching the tile grid only when no complete-image URL is available.
+     */
+    /** Tile budget to stitch a whole slice at ~`targetPx` resolution from the pyramid: a higher target
+     *  pulls a FINER pyramid level (more real detail). Shared by the surface plane fetch and the volume
+     *  assembly so both scale their in-plane resolution with the decimate factor. */
+    private tileBudgetFor;
+    private fetchSurfacePlane;
+    /** The channel state driving the surface: the chosen band for multichannel (matched by index),
+     *  else the single grayscale channel. */
+    private surfaceState;
+    /**
+     * (Re)build the surface mesh for slice `z` from the pre-loaded plane cache (instant — this is
+     * what the stack slider calls); a slice missing from the cache is fetched on demand. napari-js's
+     * pure `heightField` builds the triangle grid (z = normalized intensity), then `addSurface`
+     * renders it. The slice plane also feeds the intensity histogram (key 0).
+     */
+    private buildSurface;
+    /** Subscribe the store colormap / reverse / invert / channel window → the surface, so histogram
+     *  & channel-dialog edits update it live without a re-fetch. **min/max reshapes the surface's
+     *  height** (a pixel's height = its intensity within [min,max]), so a window change rebuilds the
+     *  mesh geometry (from the cached slice); colour-only edits (colormap/LUT, gamma, reverse, invert)
+     *  just update the layer's uniforms. */
+    private subscribeSurfaceDisplayState;
+    private fitCameraSoon;
+    /** @deprecated Plotly-specific; host re-drives plot() from its image stream. */
+    reloadAndPlot(): void;
+    reset(): void;
+    relayout(_trueImageSize?: number[]): void;
+    /** @deprecated Plotly-specific axis reset. */
+    resetAxes(): void;
+    /** @deprecated Plotly-specific autoscale. */
+    autoscale(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    setDragMode(_mode: string | false): void;
+    setNavigatorVisible(_visible: boolean): void;
+    setImageSmoothingEnabled(enabled: boolean): void;
+    setShowStack(_showstack: boolean): void;
+    setZIndex(zIndex: number): void;
+    setStackLoading(stackLoading: boolean): void;
+    /** Cancel in-flight frame loading: bump the load generation so the volume-assembly / surface
+     *  preload workers stop fetching more frames, and clear the loading flag + progress. */
+    cancelLoading(): void;
+    isStackLoading(): Observable<boolean>;
+    getStackLoadingProgress(): Observable<number>;
+    getTrueImageSize(): {
+        width: number;
+        height: number;
+    } | null;
+    getCurrentImage(): Promise<Image | null>;
+    getDisplayedPixelData(): PixelData | null;
+    getDisplayedSourceRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    downloadImage(): void;
+    setPlotType(plotType: PlotType): void;
+    /** Map a Plotly-style 3D drag mode onto napari-js's camera drag mode. */
+    setSurfaceDragMode(mode: string): void;
+    /** Re-frame the 3D camera on the current 3D layer. A surface mesh sits in the positive octant
+     *  (not centred), so frame it by its own bounds; a volume/isosurface uses its centred box. */
+    resetSurfaceCamera(): void;
+    getAutoscaleEvent(): Observable<unknown>;
+    getPlotTypeDescriptors(): PlotTypeDescriptor[];
+    /** The napari 3D decimate factor (1 = full … 8 = ⅛). Read by the toolbar to init the control. */
+    getResolutionScale(): number;
+    /** Set the decimate factor for the napari 3D types. Takes effect on the next (re)load — the host
+     *  re-plots after calling this, since decimation changes the fetched/assembled data. */
+    setResolutionScale(scale: number): void;
+    getIntensityProfile$(): Observable<IntensityProfile[]>;
+    renderIntensityInset(_divId: string, _profiles: IntensityProfile[]): void;
+    /** Read the displayed composite into `lastPixels` (the pixel-tools' source) + emit the clamped
+     *  visible region. A fresh PixelData object means cachedImageData() rebuilds automatically. */
+    private runReadback;
+    private scheduleReadback;
+    /** Debounced readback — armed on camera changes so `lastPixels` tracks the current view after a
+     *  pan/zoom settles (and after tiled levels finish loading), which the on-canvas pixel tools
+     *  (wand/brush/SAM) read synchronously. Coalesces rapid changes. */
+    private armReadback;
+    /** Build the coordinate transform + tool hosts for the current viewer (called from plot()). The
+     *  pixel tools read displayed pixels synchronously from the last readback and convert pointer
+     *  coords via the napari camera, exactly mirroring the OSD host. */
+    private buildToolHosts;
+    private zoomBoxHost;
+    /** Zoom/pan the camera to fit a data-space rectangle `[xMin, xMax, yMax, yMin]`. */
+    private applyZoomToBox;
+    /** Build CachedImageData from the most recent readback (RGBA device pixels → [y][x]=[r,g,b]),
+     *  with ratios/origin mapping image coords ↔ readback pixels. Cached until the readback changes. */
+    private cachedImageData;
+    setWandMode(active: boolean, options?: IWandOptions): void;
+    setWandOptions(options: IWandOptions): void;
+    clearActiveWandRegion(): void;
+    setBrushMode(active: boolean, options?: IBrushOptions): void;
+    setBrushOptions(options: IBrushOptions): void;
+    setVertexEraserMode(active: boolean): void;
+    setVertexEraserRadius(radius: number): void;
+    setZoomToBoxMode(active: boolean): void;
+    segmentRectangles(): Promise<number>;
+    segmentRectanglesCellpose(): Promise<number>;
+    setSamModel(id: string): void;
+    setSamPointMode(active: boolean): void;
+    commitSamPoints(): void;
+    clearSamPoints(): void;
+    ensureIntensitySampling(_imageInfo: IImageInfo, _zIndex: number): Promise<void>;
+    refreshIntensitySamplingForRoi(_x: number, _y: number, _width: number, _height: number, _zIndex: number): void;
+    getViewportChange$(): Observable<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    getRegionOverlay(): IRegionOverlay | null;
+    getIsosurfaceControls(): IIsosurfaceControls | null;
+    getIntensityControls(): IIntensityControls | null;
+    getSurface3dControls(): ISurface3dControls | null;
+    getHistogram(channelIndex: number, bins: number): IHistogram | null;
+    getHistogram$(channelIndex: number, bins: number): Observable<IHistogram | null>;
+    /** Fetch + cache one channel's native-bit-depth histogram from `GET /histogram` (>8-bit). */
+    private fetchNativeHistogram;
+    /** Per-channel histogram of the displayed RGB composite (R/G/B byte), from the last readback. */
+    private rgbHistogram;
+    exportComposite(): void;
+    /** Native-bit-depth (16/32-bit) multi-band TIFF export 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. */
+    exportData(): Promise<void>;
+    unsubscribe(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NapariVisualizerService, [null, null, null, null, null, null, null, null, null, null, { optional: true; }, null, null]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NapariVisualizerService>;
+}
+export {};

package/lib/implementations/napari-js/napari-volume-z-handle.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Draggable Z-height handle for the napari-js WebGPU volume (jit-ui#102). A small DOM grip is drawn
+ * over the 3D canvas at the projected top-face centre of the volume box (reusing the axes-label
+ * {@link projectPoint} projection, so it tracks the box as the volume orbits). Dragging it up makes
+ * the volume taller, down makes it flatter — the host maps the drag to a Z-scale factor and
+ * restretches the volume + axes live (only the model matrix changes; the voxel texture is untouched).
+ *
+ * Direct-manipulation counterpart of {@link NapariAxesLabels}: both are absolute-positioned overlays
+ * updated on every `camera3d.changed`, but this one accepts pointer input.
+ */
+import { AxesLabelCamera3D } from './napari-axes-labels';
+export interface VolumeZHandleOptions {
+    /** Current top-face-centre world point (the box is centred at the origin, so `[0, 0, +halfZ]`). */
+    topAnchor: () => [number, number, number];
+    /** The current Z-scale factor (1 = the volume's default proportions). */
+    getScale: () => number;
+    /** Apply a new Z-scale factor — the host restretches the volume + axes and repositions overlays. */
+    setScale: (scale: number) => void;
+    /** Vertical drag (px) for one doubling/halving of the Z height. Larger = less sensitive. */
+    pixelsPerDouble?: number;
+    /** Clamp for the Z-scale factor. */
+    minScale?: number;
+    maxScale?: number;
+}
+export declare class NapariVolumeZHandle {
+    private readonly host;
+    private readonly camera3d;
+    private readonly el;
+    private readonly disconnectCamera;
+    private readonly resizeObserver?;
+    private readonly opts;
+    private visible;
+    private dragging;
+    private startY;
+    private startScale;
+    constructor(host: HTMLElement, camera3d: AxesLabelCamera3D, opts: VolumeZHandleOptions);
+    setVisible(visible: boolean): void;
+    /** Reproject the handle to the current top-face anchor. Called on camera move, resize, and after
+     *  the host applies a new scale (so the grip follows the growing/shrinking box). */
+    reposition(): void;
+    private readonly onPointerDown;
+    private readonly onPointerMove;
+    private readonly onPointerUp;
+    private readonly onDoubleClick;
+    destroy(): void;
+}

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

@@ -0,0 +1,47 @@
+import { IChannelState } from '../../contracts/channel-histogram-api.contract';
+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.
+ */
+export interface DisplayPipelineHost {
+    /** Grayscale image (colormap LUT path) vs RGB/multichannel (additive tint). */
+    isGrayscale(): boolean;
+    /** 256-entry colormap LUT (grayscale path); null while options resolve. */
+    colorLut(): Rgb[] | null;
+    /** Latest per-channel display state from the store. */
+    channelStates(): IChannelState[];
+    /** Inverted background (white = zero). */
+    invertBg(): boolean;
+}
+export declare class DisplayPipeline {
+    private host;
+    constructor(host: DisplayPipelineHost);
+    /**
+     * 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.
+     *  - 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.
+     */
+    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
+     *  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;
+    /** 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;
+}