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

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

@@ -58,7 +58,9 @@ export declare class SpatialHover {
      * Listen on `el` (the plot host) rather than the canvas, so it keeps working over the region
      * overlay (an SVG covering the canvas, which would otherwise swallow every move), and throttle
      * to one hit-test per animation frame: a pointermove can fire far more often than that, and
-     * the first test after an orbit re-projects the cloud.
+     * the first test after an orbit re-projects the cloud. None while a button is held: that is an
+     * orbit or a pan moving the camera every frame, and a test per frame re-projected all of a 3.7M
+     * cloud each time (≈150 ms a frame); the first move after the drag pays for one.
      */
     install(el: HTMLElement): void;
     /** Hide the tooltip (the navigator is being dragged, say). */

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

@@ -23,6 +23,9 @@ import { CellSegmentToolService } from '../../toolbar/segmentation/cell-segment-
 import { BaseStoreVisualizer } from '../base-store-visualizer';
 import { SimpleSliceAccessService } from '../simple-slice-access.service';
 import { TranscriptEstimate } from './napari-spatial-tiles';
+import { VolumeVoxelsOnScreen } from './napari-scene';
+import type { PlaneAxis, SlicePlanes } from './napari-volume-slice-planes';
+import type { RegionMesh3D } from './napari-volume-region-meshes';
 import * as i0 from "@angular/core";
 /** Opaque handle from {@link NapariVisualizerService.load}, passed back to plot(). */
 interface NapariLoaded {
@@ -90,6 +93,20 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private lifetime;
     /** What {@link plot} mounted, while it is mounted. */
     private scene;
+    /** Region reconstructions to show in a volume view, kept across re-plots of their image. */
+    private regionMeshes;
+    /** The image (file name) {@link regionMeshes} were built from. */
+    private regionMeshesImage;
+    /** The keys of the reconstructions highlighted. */
+    private regionHighlight;
+    /** The keys of the reconstructions hidden. */
+    private regionHidden;
+    /** The planes of the sections beside a volume view, or none. */
+    private slicePlanes;
+    /** A section's plane dragged in the volume (see {@link getSlicePlaneMove$}). */
+    private readonly slicePlaneMove$;
+    /** Clicks on the reconstructions (see {@link getRegionMeshPick$}). */
+    private readonly regionMeshPick$;
     /** Spatial state that outlives a scene (latest data, windows, estimated gene-map fields). */
     private readonly spatial;
     /** Viewer settings that outlive a scene. */
@@ -136,12 +153,43 @@ export declare class NapariVisualizerService extends BaseStoreVisualizer impleme
     private fitCameraSoon;
     /** @deprecated Plotly-specific; host re-drives plot() from its image stream. */
     reloadAndPlot(): void;
+    /** Show `message` on the canvas's loading badge until the returned function is called. */
+    beginTask(message: string): () => void;
+    /** Show these region reconstructions of `image` in the volume view (kept for its next volume plot). */
+    setRegionMeshes(meshes: readonly RegionMesh3D[], image: string | undefined): void;
+    /** Highlight the reconstructions of these keys (none: all as usual). */
+    setRegionHighlight(keys: readonly string[]): void;
+    /** Hide the reconstructions of these keys (kept for the next volume plot). */
+    setRegionHidden(keys: readonly string[]): void;
+    /** Draw the reconstructions through the volume rather than hidden behind it (kept across plots). */
+    setRegionsThroughVolume(through: boolean): void;
+    private regionsThroughVolume;
+    /** Show the planes of the sections beside a volume view (null: hide one); kept across plots. */
+    setSlicePlanes(planes: SlicePlanes): void;
+    /** A section's plane dragged in the volume view, to `value` along its axis (image px, or a slice). */
+    getSlicePlaneMove$(): Observable<{
+        axis: PlaneAxis;
+        value: number;
+    }>;
+    /** The volume on screen, as assembled (see VolumeScene.volumeVoxels); null outside a volume view. */
+    volumeVoxels(): VolumeVoxelsOnScreen | null;
+    /** A reconstruction clicked with the selection tool (its key), or the volume beside them (null). */
+    getRegionMeshPick$(): Observable<{
+        key: string | null;
+        additive: boolean;
+    }>;
+    /** Image px per voxel of the volume on screen, in-plane; null outside a volume view. */
+    regionVoxelStep(): number | null;
     /**
      * End the mounted scene: abort its lifetime (its descriptor poll, tile counts, frame loading and
      * awaits) and dispose it — its layers, keys, subscriptions and listeners go with it, so the next
      * plot can never inherit an "already built" key (NAPARI-SVC-1) — then tear the viewer down.
      */
     reset(): void;
+    /**
+     * The plot area changed size (the slice editor split it, a divider moved): fit the canvas, whose
+     * height was fixed at plot time, to it again.
+     */
     relayout(_trueImageSize?: number[]): void;
     /** @deprecated Plotly-specific axis reset. */
     resetAxes(): void;

package/lib/implementations/napari-js/napari-volume-region-meshes.d.ts

@@ -0,0 +1,66 @@
+import type { Viewer } from 'napari-js';
+/** A region's 3D reconstruction to show in the volume: a mesh in image px (x, y) and slices (z). */
+export interface RegionMesh3D {
+    /** Identity (a class name): a mesh with the same key and arrays is kept, not rebuilt. */
+    key: string;
+    /** `#rrggbb`. */
+    color: string;
+    /** What hovering it shows ("HPF · Hippocampal formation"); default: the key. */
+    label?: string;
+    vertices: Float32Array;
+    faces: Uint32Array;
+}
+/** Where the stack sits in the volume's world: its full size, and the centred world box it fills. */
+export interface VolumeFrame {
+    /** Image width, height (px) and slice count. */
+    size: [number, number, number];
+    /** The world box (centred on the origin), Z as currently stretched. */
+    world: [number, number, number];
+}
+/** Opacity of a region's surface in the volume. */
+export declare const REGION_MESH_OPACITY = 0.55;
+/** While some surfaces are highlighted: theirs (near opaque, so their shape reads) … */
+export declare const REGION_MESH_HIGHLIGHT_OPACITY = 0.9;
+/** … and the others' (ghosted: still there for context, not in the way). */
+export declare const REGION_MESH_DIMMED_OPACITY = 0.12;
+/**
+ * The region reconstructions shown in a volume view: one translucent surface per region, in its
+ * colour, placed in the volume's world box (pixel x, y and slice z mapped onto it the way the
+ * volume maps its voxels) and re-placed when the volume's Z is stretched. A surface is updated in
+ * place (`setData`, `color`) rather than added again, and picked by napari-js (`pickSurface`).
+ *
+ * Highlighting is focus + context: the highlighted surfaces turn near opaque and the others fade
+ * to a ghost, so the selection stands out while staying in place among its neighbours.
+ */
+export declare class VolumeRegionMeshes {
+    private readonly viewer;
+    private readonly layers;
+    private highlighted;
+    private hidden;
+    /** The meshes to show (kept while the volume has no frame yet). */
+    private wanted;
+    private frame;
+    constructor(viewer: Viewer);
+    /** Show exactly `meshes` (adding, keeping or removing surfaces). */
+    set(meshes: readonly RegionMesh3D[]): void;
+    /** Follow the volume's frame (it opened, or its Z was stretched): re-place every surface. */
+    setFrame(frame: VolumeFrame): void;
+    /** Highlight the surfaces of these keys (none: every surface as usual). */
+    setHighlight(keys: Iterable<string>): void;
+    /** Hide the surfaces of these keys (they are kept, so showing them again is instant). */
+    setHidden(keys: Iterable<string>): void;
+    /** The front-most surface under screen point (`x`, `y`) (canvas CSS px), or null. */
+    pickAt(x: number, y: number): RegionMesh3D | null;
+    /** The meshes shown. */
+    get shown(): RegionMesh3D[];
+    clear(): void;
+    private sync;
+    private add;
+    private opacityOf;
+    private remove;
+}
+/**
+ * Image px / slice coordinates → the volume's centred world box: pixel x of a `w`-wide image
+ * spans the box's width, slice k sits at the middle of its share of the box's depth.
+ */
+export declare function toWorld(vertices: Float32Array, frame: VolumeFrame): Float32Array;

package/lib/implementations/napari-js/napari-volume-scene.d.ts

@@ -4,7 +4,9 @@ import { IImageInfo } from '../../contracts/image.contract';
 import { IHistogram } from '../../contracts/channel-histogram-api.contract';
 import { IIsosurfaceControls, ISurface3dControls } from '../../contracts/visualizer.contract';
 import { Axes3dGizmo, Box3 } from './napari-axes-gizmo';
-import type { NapariScene, SceneContext } from './napari-scene';
+import type { NapariScene, SceneContext, VolumeVoxelsOnScreen } from './napari-scene';
+import { RegionMesh3D } from './napari-volume-region-meshes';
+import { SlicePlanes } from './napari-volume-slice-planes';
 /**
  * NAPARI_VOLUME / NAPARI_ISOSURFACE (review Appendix B, cluster F): the stack assembled into a
  * decimated volume — one additive, tinted `VolumeLayer` per channel for a multichannel image, a
@@ -29,7 +31,49 @@ export declare class VolumeScene implements NapariScene {
     gizmo: Axes3dGizmo | null;
     private zHandle;
     private displaySub;
+    /** Regions' 3D reconstructions shown in the volume (see {@link setRegionMeshes}). */
+    private readonly regionMeshes;
+    /** The planes of the sections shown beside the volume, marked and draggable in it. */
+    private readonly slicePlanes;
+    /** The image's full size (px, px, slices), which reconstructions are in. */
+    private fullSize;
+    /** Clicks and hover on the reconstructions (with the selection tool). */
+    private meshPointer;
+    private toolSub;
+    private selecting;
     constructor(ctx: SceneContext, info: IImageInfo | undefined, rendering: 'iso' | 'mip');
+    /** Show these region reconstructions in the volume (replacing the ones shown). */
+    setRegionMeshes(meshes: readonly RegionMesh3D[]): void;
+    setRegionHighlight(keys: readonly string[]): void;
+    setRegionHidden(keys: readonly string[]): void;
+    /** Whether the volume lets every region through (see {@link setRegionsThroughVolume}). */
+    private regionsThrough;
+    /**
+     * The volume hides the region reconstructions behind what it shows (its brightest sample along
+     * each ray, napari-js's `'translucent'` depth) — the perspective of a region behind the
+     * cerebellum — or, `through`, hides none (`'translucent_no_depth'`): surfaces traced inside its
+     * bright structures, an OCT's layer boundaries in its bright bands, which that depth speckles
+     * or hides. A multichannel volume's channels add up and hide nothing either way.
+     */
+    setRegionsThroughVolume(through: boolean): void;
+    private applyVolumeDepth;
+    /** Show the planes of the sections beside the volume where they are (null: hide one). */
+    setSlicePlanes(planes: SlicePlanes): void;
+    /**
+     * The assembled volume's voxels per channel (key 0: the grayscale one), its frame, and whether
+     * it is a multichannel composite — what the sections beside it are cut from. Null before it is
+     * assembled.
+     */
+    volumeVoxels(): VolumeVoxelsOnScreen | null;
+    /**
+     * Picking the reconstructions: with the selection tool armed, a click on one selects its class
+     * (null beside them); resting over one names it, whatever the tool.
+     */
+    private listenToRegionMeshes;
+    /** Image px per voxel of the assembled volume (in-plane), or null before it is assembled. */
+    voxelStep(): number | null;
+    /** Place the region reconstructions in the volume's world box as it is now. */
+    private frameRegionMeshes;
     /**
      * Assemble and render the volume, then add the axes gizmo + labels and the Z handle and follow
      * the display state.

package/lib/implementations/napari-js/napari-volume-slice-planes.d.ts

@@ -0,0 +1,43 @@
+import type { Viewer } from 'napari-js';
+import type { VolumeFrame } from './napari-volume-region-meshes';
+/** A plane across the volume: x = const, y = const (image px) or z = const (a slice). */
+export type PlaneAxis = 'x' | 'y' | 'z';
+/** Where each plane is (image px for x and y, the slice for z); null: not shown. */
+export type SlicePlanes = Record<PlaneAxis, number | null>;
+/** Each plane's colour: its axis's, as the axes gizmo draws them. */
+export declare const SLICE_PLANE_COLORS: Readonly<Record<PlaneAxis, string>>;
+/** A plane's opacity: enough to read where it is, not to hide the volume behind it … */
+export declare const SLICE_PLANE_OPACITY = 0.22;
+/** … and while it is dragged. */
+export declare const SLICE_PLANE_DRAG_OPACITY = 0.4;
+export interface SlicePlanesOptions {
+    /** A plane dragged to `value` along its axis (image px, or a fractional slice). */
+    onMove(axis: PlaneAxis, value: number): void;
+}
+/**
+ * The planes of the sections shown beside a volume view: napari-js's {@link SlicePlanesWidget}
+ * (translucent quads in their axis's colour, each with a grip that drags it along its axis) over
+ * the stack's frame. It works in the frame's image px and slices: the widget's box is the image,
+ * one voxel per px, so a px position is the widget's shifted by half a pixel (pixel i spans
+ * [i, i + 1) here, is centred on i there); a slice is the same in both.
+ */
+export declare class VolumeSlicePlanes {
+    private readonly viewer;
+    private readonly host;
+    private readonly opts;
+    private widget;
+    private frame;
+    private planes;
+    /** Set while the planes are moved from here, so the widget's echo is not reported as a drag. */
+    private applying;
+    constructor(viewer: Viewer, host: HTMLElement, opts: SlicePlanesOptions);
+    /** Follow the volume's frame (it opened, or its Z was stretched). */
+    setFrame(frame: VolumeFrame): void;
+    /** Show the planes where they are now (null: hide one). */
+    set(planes: SlicePlanes): void;
+    clear(): void;
+    destroy(): void;
+    /** The widget over the current frame, made when there is one and a plane to show. */
+    private rebuild;
+    private apply;
+}

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

@@ -23,6 +23,8 @@ export interface ViewerOptionsInput {
     sliceCount: number;
     /** How many slices the slice cache keeps resident (see SliceCache.maxSlices). */
     maxSlices: number;
+    /** Tiled images per slice: the channel count when channels are drawn per channel, else 1. */
+    channelImages?: number;
 }
 /**
  * The options object handed to the OpenSeadragon factory. Pure: every value

package/lib/implementations/osd/openseadragon-visualizer.service.d.ts

@@ -53,6 +53,8 @@ export declare class OpenSeadragonVisualizerService extends BaseStoreVisualizer
     private viewer;
     private overlay;
     private scaleBar;
+    /** "Image reloading…" while the view fetches its tiles. */
+    private tileLoading;
     private descriptor;
     /** Base64 RawFileInfo + current z-slice, kept so setZIndex can rebuild the
      *  tile source and swap slices live (stack navigation). */

package/lib/implementations/osd/osd-region-overlay-draw.d.ts

@@ -1,5 +1,6 @@
 import { Region } from '../../models/region';
 import { ScreenLayer } from '../../region-overlay/svg-region-renderer';
+import { RegionStyle } from '../../region-overlay/region-style';
 /**
  * The OpenSeadragon region overlay's look: region stroke/fill, labels, the
  * selected region's handles, the marquee and the in-progress drawing. Pure SVG
@@ -12,14 +13,14 @@ type Pt = {
 };
 /** `color` with `alpha`; a colour that doesn't parse (a named one) is used as-is. */
 export declare function rgba(color: string, alpha: number): string;
-/** Stroke/fill for a region shape (drawn in image coordinates by the renderer). */
-export declare function styleRegionShape(el: SVGElement, region: Region, selected: boolean, shapeColor: string): void;
+/** Stroke/fill for a region shape (drawn in image coordinates by the renderer), in `style`. */
+export declare function styleRegionShape(el: SVGElement, region: Region, selected: boolean, shapeColor: string, style?: RegionStyle): void;
 /**
  * The class label (legend) just above the region's top-left — mirrors Plotly's
  * per-shape label, drawn in the region's colour. region.label is restored from
  * the shape's legend in getRegion().
  */
-export declare function drawRegionLabel(layer: ScreenLayer, region: Region, shapeColor: string): void;
+export declare function drawRegionLabel(layer: ScreenLayer, region: Region, shapeColor: string, style?: RegionStyle): void;
 /** A small vertex handle (filled when emphasised, hollow otherwise) at an image point. */
 export declare function vertexMarker(layer: ScreenLayer, x: number, y: number, emphasised: boolean, color: string): void;
 /**

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

@@ -1,5 +1,5 @@
 import { IRegionStore } from '../../contracts/visualizer.contract';
-import { IRegionEditApi } from '../../contracts/region-store.contract';
+import { IRegionEditApi, IRegionSourceApi } from '../../contracts/region-store.contract';
 import { IRegionOverlay, RegionToolMode } from '../../contracts/region-overlay.contract';
 import { OsdViewerLike } from './osd-viewer-like';
 /**
@@ -8,9 +8,10 @@ import { OsdViewerLike } from './osd-viewer-like';
  * {@link IRegionEditApi} (add/move/resize/vertex edits). The shared RegionStore
  * satisfies both. The overlay edits through these typed operations on the
  * neutral Region model — it never touches a backend's own shape representation
- * (e.g. Plotly's `x0/y0/x1/y1` / `M…L…Z` dicts).
+ * (e.g. Plotly's `x0/y0/x1/y1` / `M…L…Z` dicts). With {@link IRegionSourceApi}
+ * (optional) it also draws and picks the image's region source.
  */
-export type RegionEditStore = IRegionStore & IRegionEditApi;
+export type RegionEditStore = IRegionStore & IRegionEditApi & Partial<IRegionSourceApi>;
 /**
  * OpenSeadragon implementation of {@link IRegionOverlay}.
  *
@@ -62,6 +63,8 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
      *  projection, and so the DOM, untouched. */
     private readonly cameraHandler;
     private readonly renderer;
+    /** The image's region source, drawn under the regions at the zoom's level of detail. */
+    private readonly sourceLayer;
     /** OSD's MouseTracker drops a cancelled pointer (touch interrupted, pointer
      *  capture lost to the browser) without calling releaseHandler, so the
      *  gesture is ended here instead. */
@@ -152,8 +155,12 @@ export declare class OsdRegionOverlay implements IRegionOverlay {
      */
     private applyEdit;
     private selectAt;
+    /** Take the region-source features the band meets into the regions, adding them to the selection. */
+    private selectSourceIn;
     /** Index of the topmost region under an image point, or -1. */
     private regionIndexAt;
+    /** Whether a region's class is hidden (not drawn, not picked). */
+    private hidden;
     /** Whether the element-pixel `position` lands on `region` (see `regionContains`). */
     private containsPoint;
     /** Abandon whatever pointer gesture is in progress (drawing, edit drag,

package/lib/implementations/osd/osd-tile-loading.d.ts

@@ -0,0 +1,43 @@
+/** What it needs of the viewer. */
+interface LoadingViewer {
+    element: HTMLElement;
+    world: {
+        getItemCount(): number;
+        getItemAt(i: number): unknown;
+        addHandler(event: 'add-item' | 'remove-item', handler: (e: {
+            item: unknown;
+        }) => void): unknown;
+        removeHandler(event: 'add-item' | 'remove-item', handler: (e: {
+            item: unknown;
+        }) => void): unknown;
+    };
+}
+/**
+ * "Image reloading…" over the OpenSeadragon view while it fetches the tiles of what it shows, as
+ * napari's views show it for their image, cells and transcripts (the same badge). Driven by each
+ * world item's own `fully-loaded-change` (an image, a stack slice, a channel), so it covers every
+ * tile source alike, and shown only after a short delay, so tiles served from cache never flash it.
+ *
+ * Only items on screen count (opacity above 0): a hidden channel loads nothing by design (it is
+ * not preloaded), so it never becomes fully loaded, and a slice cached or loading in the
+ * background is not what the view shows. An item is weighed again when its opacity changes.
+ */
+export declare class OsdTileLoading {
+    private readonly viewer;
+    private readonly state;
+    /** Each item still loading, with the function that un-counts it. */
+    private readonly loading;
+    private readonly watched;
+    private readonly onAdd;
+    private readonly onRemove;
+    constructor(viewer: LoadingViewer);
+    /** The badge's text (shown, or about to be). */
+    get text(): string;
+    destroy(): void;
+    private watch;
+    private unwatch;
+    /** Whether the item is on screen and still fetching its tiles. */
+    private isLoading;
+    private set;
+}
+export {};

package/lib/implementations/osd/osd-viewer-like.d.ts

@@ -48,6 +48,18 @@ export interface OsdViewerLike {
     /** OSD's own pan/zoom (drag + wheel); region tools switch it off. */
     setMouseNavEnabled(enabled: boolean): unknown;
     isMouseNavEnabled(): boolean;
+    /** OSD's tile request queue: the jobs not started yet (see OsdQueuedTileJob). */
+    imageLoader?: {
+        jobQueue?: unknown[];
+    };
+}
+/** A tile request waiting in OSD's queue: `abort` (before it starts) only marks the tile as
+ *  not loading, so it is requested again when it is needed. */
+export interface OsdQueuedTileJob {
+    tile?: {
+        tiledImage?: unknown;
+    };
+    abort?: () => void;
 }
 /** A point in any OSD space (viewer-element px, viewport units or image px —
  *  the method it comes from says which). */
@@ -70,6 +82,8 @@ export interface OsdTiledImageLike {
     imageToViewportRectangle(r: OpenSeadragon.Rect): OpenSeadragon.Rect;
     viewportToImageRectangle(r: OsdRectLike): OsdRectLike;
     setOpacity(opacity: number): void;
+    /** Load tiles even while hidden (opacity 0); without it a hidden item loads nothing. */
+    setPreload?(preload: boolean): void;
     /** False while any of the image's tiles are still loading. */
     getFullyLoaded(): boolean;
     /** Re-run the tile pipeline (restore + re-process) for this image's tiles;

package/lib/implementations/osd/slice-cache.d.ts

@@ -106,14 +106,22 @@ export declare class SliceCache {
     /**
      * Add slice z's channel group: one additively-composited ('lighter' = Fiji
      * "Composite") TiledImage per channel, hidden (opacity 0) until revealed.
-     * Each is preloaded so the background loader can pre-fill every slice.
+     * The visible channels' are preloaded, so the background loader can pre-fill
+     * every slice; a hidden channel's loads nothing until it is shown (a 22-channel
+     * plate fetched and decoded every channel's tiles, overflowing the tile cache:
+     * tiles evicted mid-conversion failed to decode).
      * Cached so a revisit is an instant opacity toggle — no re-fetch, no
      * white-flicker. Mirrors addSlice for the composite path.
      */
     addChannelSlice(z: number): void;
     /** Reveal slice z's channel group (each visible channel → opacity 1) and
-     *  hide every other cached slice's group. Instant; no fetch/decode. */
+     *  hide every other cached slice's group. Instant; no fetch/decode. Only the
+     *  visible channels keep loading (preload): a hidden channel's tiles are not
+     *  fetched or decoded until it is shown. */
     revealChannelSlice(z: number): void;
+    /** Drop the tile requests still waiting in OSD's queue for `items` (channels just hidden), so
+     *  the visible channels' tiles are not stuck behind them. A request already sent completes. */
+    private dropQueuedTiles;
     /** Show the given composite slice (opacity 1) and hide all other cached slices. */
     private showOnlySlice;
     /** Re-tint after a display change: invalidate ONLY the visible slice's
@@ -154,7 +162,9 @@ export declare class SliceCache {
     private sliceCacheHas;
     /** The cached TiledImage(s) for slice z (0–1 for composite, N for multichannel). */
     private sliceGroup;
-    /** Whether slice z's tiles are still streaming (any cached image not fully loaded). */
+    /** Whether slice z's tiles are still streaming (any cached image not fully loaded). A hidden
+     *  channel loads nothing, so it never becomes fully loaded: only the visible channels count, or
+     *  the background loader would wait on it forever. */
     private sliceTilesLoading;
     /** Remove slice z's cached image(s) from the world and the active cache. */
     private removeCachedSlice;

package/lib/implementations/tile-server/tile-protocol.d.ts

@@ -38,6 +38,9 @@ export interface TileDescriptor {
     /** Physical pixel size in µm (0 when the format doesn't report it). */
     mppX?: number;
     mppY?: number;
+    /** Spacing between z slices in µm (0 or absent when the format doesn't report it): what
+     *  lets a z-stack be drawn as a volume to scale. */
+    mppZ?: number;
 }
 /** Tile coordinates for one `/tile` request. `channel == null` (or omitted)
  *  requests the server-composited tile; an index (including 0) requests that

package/lib/models/class-preset.d.ts

@@ -38,6 +38,13 @@ export interface PresetSet {
     autoPromote: boolean;
     /** Label matching against `Region.label` (default `'exact'`). */
     matchMode: MatchMode;
+    /**
+     * Class colours that imported GeoJSON carried for classes with no preset, keyed by the
+     * match mode's key (see `presetKey`). They come before the fallback palette, so an imported
+     * file keeps its own colours. Session-only: never persisted, and absent from a set a caller
+     * saves or exports.
+     */
+    importedColors?: Readonly<Record<string, string>>;
 }
 /**
  * Fallback palette for classes not present in the preset set — reasonably distinct hues.

package/lib/models/polygon-factory.d.ts

@@ -38,3 +38,8 @@ export declare function replaceBounds(existing: Region, bounds: Region['bounds']
  * are rounded to whole pixels.
  */
 export declare function regionPolygons(region: Region): Polygon[];
+/**
+ * The open polylines a region traces (a polyline, or a multi-polygon's open parts), as interleaved
+ * `x, y` image px; a bézier polyline as its flattened curve. Closed shapes yield nothing.
+ */
+export declare function regionPolylines(region: Region): Float64Array[];

package/lib/models/region-geojson.d.ts

@@ -5,13 +5,53 @@ import { Region } from './region';
  * coordinates.
  */
 export declare function regionsFromGeoJson(geoJsonStr: string): Region[];
+/** A feature's `classification`: QuPath's `{name, color}`, or a bare name. */
+type Classification = string | {
+    name?: string;
+    color?: number[];
+};
+/** The parts of a GeoJSON feature the reader looks at, JIT's bezier extras
+ *  included. Parsed from a file, so nothing here is guaranteed. */
+export interface GeoJsonFeature {
+    id?: string | number;
+    geometry: {
+        type?: string;
+        coordinates?: unknown;
+        plane?: {
+            z?: number;
+        };
+    };
+    properties?: {
+        id?: string | number;
+        classification?: Classification;
+        isBezier?: boolean;
+        bezierAnchors?: number[][];
+        bezierHandlesIn?: number[][];
+        bezierHandlesOut?: number[][];
+        holes?: number[][][];
+        holeHandlesIn?: number[][][];
+        holeHandlesOut?: number[][][];
+    };
+}
+/**
+ * One GeoJSON feature as the region `shape<idx>`. Throws on a feature without coordinates.
+ * The feature's id becomes {@link Region.sourceId} (or `sourceId`, when given: a region source's
+ * id for the feature) and its other properties {@link Region.properties}.
+ */
+export declare function regionFromGeoJsonFeature(feature: GeoJsonFeature, idx: number, sourceId?: string): Region;
 /**
  * Serialise regions as a GeoJSON FeatureCollection string (QuPath-compatible),
  * leaving out intensity-profile lines.
  */
 export declare function regionsToGeoJson(rois: readonly Region[]): string;
+/**
+ * A region as a GeoJSON feature; null for a region without bounds. Its {@link Region.sourceId}
+ * is the feature's `id` and its {@link Region.properties} come along beside the classification.
+ */
+export declare function featureFromRegion(roi: Region): object | null;
 /**
  * Download a GeoJSON string as `<baseName without extension>.geojson`
  * (`rois.geojson` without a base name).
  */
 export declare function downloadGeoJson(jsonString: string, baseName?: string): void;
+export {};

package/lib/models/region.d.ts

@@ -35,6 +35,25 @@ export declare class Region {
      * through the store, so the marker has to travel with the data.
      */
     source?: string;
+    /**
+     * The id of the GeoJSON feature this region was read from (the feature's `id`, else
+     * `properties.id`; for a tiled region source, else its position in the file). Written back
+     * as the feature's `id` on export, so a region keeps its identity through a save. A region
+     * taken out of a region source for editing carries it, and the source stops drawing that
+     * feature while it does.
+     */
+    sourceId?: string;
+    /**
+     * A region source feature's area (image px²) while it stands in for the feature in the Region
+     * Editor's table: such a row has no geometry until the feature is taken.
+     */
+    sourceArea?: number;
+    /**
+     * The feature's other GeoJSON properties (everything but the ones SIV reads and writes:
+     * `classification`, `id` and the bézier fields), carried through untouched so a save keeps
+     * them, e.g. an atlas structure's acronym and id.
+     */
+    properties?: Readonly<Record<string, unknown>>;
     color?: string;
     label?: string;
     /** True when the user set this region's colour explicitly (Region Editor Color

package/lib/region-editor/class-tree/class-tree.component.d.ts

@@ -0,0 +1,78 @@
+import { ElementRef, EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import type { RegionClassNode } from '../../region-source/region-tiles';
+import { ClassTree, ClassTreeRow } from './class-tree';
+import * as i0 from "@angular/core";
+/** A pick in the tree: the class, and it with every class under it. */
+export interface ClassTreePick {
+    name: string;
+    classes: string[];
+    additive: boolean;
+}
+/** Whether a class is shown: it and its subclasses all, none ('hidden'), or only some ('partial'). */
+export type ClassVisibility = 'shown' | 'hidden' | 'partial';
+/**
+ * The Region Editor's classes as a hierarchy (a brain atlas's ontology), as the Allen atlas viewer
+ * shows it: collapsible, each class with its colour, name and long name, and the regions it and
+ * its subclasses have on this slice; a class with none is greyed. Picking a class selects all its
+ * regions and its subclasses' (the editor does the selecting). Search by name or long name. A
+ * class's swatch recolours it, as the class list's does; its eye hides it and its subclasses.
+ */
+export declare class ClassTreeComponent implements OnChanges {
+    private readonly el;
+    /** The hierarchy. */
+    nodes: readonly RegionClassNode[];
+    /** Regions per class on this slice (the regions and the region source's). */
+    counts: ReadonlyMap<string, number>;
+    /** A class's colour (a new function when the colours change, so the rows repaint). */
+    colorOf: (name: string) => string;
+    /** The class picked last (highlighted, its path expanded, scrolled into view). */
+    picked: string | null;
+    /** Classes with a selected region (marked). */
+    marked: ReadonlySet<string>;
+    /** Whether a volume view is on screen: each class can then be shown in 3D. */
+    volume: boolean;
+    /** The classes shown in 3D. */
+    shown3d: ReadonlySet<string>;
+    /** The classes hidden from view. */
+    hidden: ReadonlySet<string>;
+    pick: EventEmitter<ClassTreePick>;
+    /** A class's swatch picked a new colour. */
+    recolor: EventEmitter<{
+        name: string;
+        color: string;
+    }>;
+    /** A class's 3D toggle: it with every class under it. */
+    toggle3d: EventEmitter<{
+        name: string;
+        classes: string[];
+    }>;
+    /** A class's eye: hide (or show) it with every class under it. */
+    toggleHidden: EventEmitter<{
+        classes: string[];
+        hidden: boolean;
+    }>;
+    protected tree: ClassTree;
+    protected rows: ClassTreeRow[];
+    /** Each row's visibility (a row absent: shown). */
+    protected visibility: Map<string, ClassVisibility>;
+    protected query: string;
+    private expanded;
+    constructor(el: ElementRef<HTMLElement>);
+    ngOnChanges(changes: SimpleChanges): void;
+    protected node(name: string): RegionClassNode | undefined;
+    protected total(name: string): number;
+    protected toggle(row: ClassTreeRow, event: Event): void;
+    protected choose(name: string, event: Event): void;
+    /** The eye: a class hidden (wholly) is shown again with its subclasses; otherwise they are hidden. */
+    protected flipHidden(name: string, event: Event): void;
+    protected flip3d(name: string, event: Event): void;
+    protected onQuery(value: string): void;
+    /** Enter in the search box picks the first match. */
+    protected pickFirstMatch(event: Event): void;
+    protected readonly trackRow: (_: number, r: ClassTreeRow) => string;
+    private refresh;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ClassTreeComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ClassTreeComponent, "region-class-tree", never, { "nodes": { "alias": "nodes"; "required": false; }; "counts": { "alias": "counts"; "required": false; }; "colorOf": { "alias": "colorOf"; "required": false; }; "picked": { "alias": "picked"; "required": false; }; "marked": { "alias": "marked"; "required": false; }; "volume": { "alias": "volume"; "required": false; }; "shown3d": { "alias": "shown3d"; "required": false; }; "hidden": { "alias": "hidden"; "required": false; }; }, { "pick": "pick"; "recolor": "recolor"; "toggle3d": "toggle3d"; "toggleHidden": "toggleHidden"; }, never, never, true, never>;
+}
+/** Scroll the row matching `selector` inside `host` into view, if it is out of it. */
+export declare function scrollToPicked(host: HTMLElement, selector: string): void;