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

package/lib/intensity/intensity-profile.service.d.ts

@@ -0,0 +1,108 @@
+import { OnDestroy } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { IIntensityControls, IntensityProfile } from '../contracts/visualizer.contract';
+import { IImageInfo } from '../contracts/image.contract';
+import { TileAccessPort } from '../contracts/ports/tile-access.port';
+import { ImageStatePort } from '../contracts/ports/image-state.port';
+import { Region } from '../models/region';
+import { RegionStore } from '../store/region-store.service';
+import { ProfileLine } from './intensity-profile';
+import * as i0 from "@angular/core";
+/** The pixels the profiles are sampled from, and the image they belong to. */
+export interface IntensityFrames {
+    /** Per-z-plane pixel matrices (grayscale numbers or `[r, g, b]` cells). */
+    frames: any[];
+    /** [xRatio, yRatio]: image units per frame pixel. */
+    ratios: number[];
+    /** Image coordinate of the frames' pixel (0,0); [0,0] unless a zoom crop. */
+    origin?: [number, number];
+}
+/** The image the frames come from: its extent (for line placement) and its
+ *  metadata (pixel size, grayscale). */
+export interface IntensityImage {
+    imageInfo: IImageInfo;
+    /** [x0, x1, y0, y1] in image units. */
+    extent: number[];
+    /** The displayed z-plane, when the frames hold a stack. */
+    frameIndex?: () => number;
+}
+/**
+ * Intensity profiles along line ROIs (PlotType.LINE), for every backend.
+ *
+ * Profile lines are ordinary RegionStore regions tagged `kind: 'profile'`; any
+ * region change re-samples and re-emits every line's profile. The service owns
+ * its OWN sampling frames — a backend's tool readback never doubles as the
+ * profile source (OSD-PLOTLY-2) — filled by Plotly when it renders or high-def
+ * zooms, and fetched here for the other backends: the displayed slice
+ * ({@link ensureIntensitySampling}) and, on zoom/pan, a display-resolution
+ * crop of the visible region ({@link refreshIntensitySamplingForRoi}). Every
+ * sampling write supersedes the async ones before it.
+ *
+ * Per viewer: listed in `provideVisualization()` with the RegionStore it
+ * listens to.
+ */
+export declare class IntensityProfileService implements IIntensityControls, OnDestroy {
+    private readonly http;
+    private readonly tiles;
+    private readonly regionStore;
+    private frames;
+    private image;
+    /** The last visible image-pixel rect a backend reported (new lines go there). */
+    private lastVisibleRoi;
+    /** Palette cursor (never reset on delete, so colours keep cycling). */
+    private colorSeq;
+    /** Bumped by every sampling write request: an async fetch lands only if no
+     *  newer one was requested meanwhile. */
+    private gen;
+    /** The element whose parent sizes a crop request (the viewer's plot div). */
+    private elementId;
+    /** The host's selected file, so a crop for a previous file is dropped. */
+    private fileName;
+    private readonly profiles$;
+    private readonly subs;
+    private readonly utils;
+    constructor(http: HttpClient, tiles: TileAccessPort, state: ImageStatePort, regionStore: RegionStore);
+    ngOnDestroy(): void;
+    /** Every profile line's profile, re-emitted whenever one is added, moved or removed. */
+    getIntensityProfile$(): Observable<IntensityProfile[]>;
+    /** The element (by id) whose size a crop request is made for. */
+    setSamplingElement(id: string): void;
+    /** Supersede every sampling fetch in flight; returns the new generation. */
+    supersede(): number;
+    /** Whether `gen` (from {@link supersede}) is still the latest sampling request. */
+    isCurrent(gen: number): boolean;
+    /** Sample from these frames from now on — of `image`, or of the image already set. */
+    setFrames(frames: IntensityFrames, image?: IntensityImage): void;
+    /**
+     * Fetch the displayed slice's preview for sampling (the same pixels a heatmap
+     * would sample), for a backend that has no frames of its own (OpenSeadragon,
+     * napari-js). Re-emits the profiles once loaded.
+     */
+    ensureIntensitySampling(imageInfo: IImageInfo, zIndex: number): Promise<void>;
+    /**
+     * Re-fetch the given image-pixel ROI at the display resolution and sample from
+     * it, so the profile reflects the data at the current zoom level. Also
+     * remembers the ROI, so a new line is placed inside it.
+     */
+    refreshIntensitySamplingForRoi(x: number, y: number, width: number, height: number, zIndex: number): void;
+    /**
+     * Add another profile line: a horizontal open 2-point polyline in the next
+     * palette colour, placed by {@link placeProfileLine}, added to the shared
+     * store so every backend renders and drags it (and excluded from the Regions
+     * tab and exports by its kind). Null until an image extent is known.
+     */
+    addProfileLine(): Region | null;
+    /** Recompute and broadcast every profile line's profile (tagged with the
+     *  line's id and colour, so the inset trace matches its line). */
+    emitProfiles(): void;
+    /** Sample the active frame along `line` (see sampleLine). */
+    computeIntensityProfile(line: ProfileLine): IntensityProfile;
+    /** The profile-line regions in the store. */
+    private profileRegions;
+    /** Fetch one slice through HttpClient (auth interceptors apply) and decode it. */
+    private loadSlice;
+    private toMatrix;
+    static ɵfac: i0.ɵɵFactoryDeclaration<IntensityProfileService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<IntensityProfileService>;
+}

package/lib/intensity-inset/intensity-inset.component.d.ts

@@ -0,0 +1,58 @@
+import { ChangeDetectorRef, DestroyRef, NgZone, OnDestroy, OnInit } from '@angular/core';
+import { IImageInfo } from '../contracts/image.contract';
+import { IVisualizer } from '../contracts/visualizer.contract';
+import { Region } from '../models/region';
+import { FloatingPos } from '../visualizer/floating-drag.directive';
+import * as i0 from "@angular/core";
+/**
+ * The floating, draggable intensity-profile inset: shown while any intensity line
+ * exists, charting one trace per line as lines are added, moved or removed.
+ *
+ * Owns the profile and viewport-change subscriptions, the window-resize reflow, the
+ * drag and the per-instance chart div id it is given. The chart itself is drawn by the
+ * backend (`IVisualizer.renderIntensityInset`) so this never reaches a charting
+ * library. Fixed to the viewport, outside the plot div, so it is not clipped to the
+ * canvas.
+ *
+ * OnPush, with its view state in signals: the profile stream may fire outside the zone.
+ */
+export declare class IntensityInsetComponent implements OnInit, OnDestroy {
+    private readonly visualizer;
+    private readonly cdr;
+    private readonly zone;
+    private readonly destroyRef;
+    /** Id of the chart div — unique per viewer: the backend resolves it by id. */
+    divId: string;
+    /** Id of the viewer's plot div: the inset parks near its top-right corner. */
+    plotDivName: string;
+    /** The displayed slice, re-sampled at when the view settles. */
+    zIndex: number;
+    /** The Image view (OSD), whose line sampling is fed from preview frames. */
+    imageView: boolean;
+    /** The image shown (the Image view samples its lines from it). */
+    imageInfo: IImageInfo | undefined;
+    /** True whenever any intensity-profile line exists (whatever the plot type). */
+    protected readonly hasProfiles: import("@angular/core").WritableSignal<boolean>;
+    protected readonly pos: import("@angular/core").WritableSignal<FloatingPos>;
+    /** Where a header drag starts from. */
+    protected readonly dragOrigin: () => FloatingPos;
+    private profiles;
+    private readonly onResize;
+    constructor(visualizer: IVisualizer, cdr: ChangeDetectorRef, zone: NgZone, destroyRef: DestroyRef);
+    ngOnInit(): void;
+    /** Removes the window resize listener; the streams end through `takeUntilDestroyed`. */
+    ngOnDestroy(): void;
+    /** The canvas was resized: reflow the chart a tick later, once the panel has settled. */
+    reflow(): void;
+    /** A slice was committed: keep the lines sampled from it (Image view). */
+    sliceCommitted(z: number): void;
+    /**
+     * Add another line ROI (next bright colour) and select it on the active backend so
+     * it is ready to move or delete. The first line parks the inset near the plot's
+     * top-right. Resolves the new line, or null when no image extent is known yet.
+     */
+    addProfileLine(): Promise<Region | null>;
+    private render;
+    static ɵfac: i0.ɵɵFactoryDeclaration<IntensityInsetComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<IntensityInsetComponent, "viz-intensity-inset", never, { "divId": { "alias": "divId"; "required": false; }; "plotDivName": { "alias": "plotDivName"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "imageView": { "alias": "imageView"; "required": false; }; "imageInfo": { "alias": "imageInfo"; "required": false; }; }, {}, never, never, true, never>;
+}

package/lib/models/bezier.d.ts

@@ -52,8 +52,3 @@ export declare function resolveHandles(xs: number[], ys: number[], closed: boole
  * closed ring returns to its first point.
  */
 export declare function bezierCurveFromHandles(xs: number[], ys: number[], handles: AnchorHandle[], closed: boolean): CurvePoints;
-/**
- * Flatten the smooth Catmull-Rom bezier through the anchors (no custom handles).
- * Falls back to the anchors when there are too few to form a curve.
- */
-export declare function bezierCurve(xs: number[], ys: number[], closed: boolean): CurvePoints;

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

@@ -5,7 +5,12 @@
  * The `PresetSet` is the per-user, server-persisted source of truth for region colours;
  * see `class-color.util.ts` for the deterministic colour-resolution engine.
  */
+/** Where a preset class came from: added by the user, one of the built-in
+ *  defaults, or auto-promoted from an unknown region label. */
 export type PresetSource = 'user' | 'default' | 'auto';
+/** One annotation class and its colour: regions whose `label` matches
+ *  `name` (per the set's {@link MatchMode}) draw in `color` unless their colour
+ *  was overridden by hand. */
 export interface ClassPreset {
     /** The class name — matched against `Region.label`. */
     name: string;
@@ -16,7 +21,14 @@ export interface ClassPreset {
     /** Provenance; `'auto'` = added by opt-in fallback promotion. */
     source?: PresetSource;
 }
+/** How a region label is matched to a preset name: `'exact'` compares the
+ *  strings as is; `'normalized'` trims and lower-cases both first. */
 export type MatchMode = 'exact' | 'normalized';
+/**
+ * The per-user class-colour configuration (server-persisted through the
+ * preferences port): the preset classes, the palette for labels outside them,
+ * and the matching rules. Resolved into region colours by `class-color.util.ts`.
+ */
 export interface PresetSet {
     /** Ordered list of preset classes. */
     classes: ClassPreset[];
@@ -26,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.
@@ -37,3 +56,9 @@ export declare const DEFAULT_FALLBACK_PALETTE: string[];
 export declare function defaultPresetSet(): PresetSet;
 /** True when the set has no usable classes (e.g. the server returned an empty/blank record). */
 export declare function isEmptyPresetSet(set: PresetSet | null | undefined): boolean;
+/**
+ * Validate an untrusted value (e.g. an imported JSON file) as a preset set.
+ * Returns a clean copy — only well-formed `{ name, color }` classes, defaults
+ * for missing optional fields — or null when it has no usable classes.
+ */
+export declare function parsePresetSet(value: unknown): PresetSet | null;

package/lib/models/geometry.d.ts

@@ -1,66 +1,32 @@
 /**
- * Pure geometry helpers extracted from PlotlyService.
+ * Pure SVG-path helpers (build and parse a vertex ring as a Plotly path).
  *
- * No DOM access, no service state, no `this` — every function is testable
- * in isolation. Keep it that way: this module is the dumping ground for
- * shape/mask/SVG-path utilities the wand, vertex eraser, and region editor
- * share. If a helper grows a `this.shapes` reference, it doesn't belong here.
+ * No DOM access, no service state, no `this`. Mask and ring geometry (the
+ * rasterizer, mask set operations, point-in-ring, simplification, contour
+ * tracing) lives in `src/lib/geometry/`.
  */
-/** A bbox-relative binary mask (1 = filled, 0 = empty). */
-export interface BBoxMask {
-    bx: number;
-    by: number;
-    bw: number;
-    bh: number;
-    mask: Uint8Array;
-}
 /** Parsed single-subpath polygon vertices. */
 export interface PolygonVertices {
     xpoints: number[];
     ypoints: number[];
 }
 /**
- * Parse a single-subpath `M x,y L x,y ... Z` path into vertex arrays.
+ * Split a single-subpath `M x,y L x,y ... [Z]` path into vertex arrays, plus
+ * whether it is closed (ends in `Z`). No validation: a coordinate that doesn't
+ * parse comes back as NaN. See {@link parseSvgPathPolygon} for the checked form.
+ */
+export declare function parseSvgPath(path: string): PolygonVertices & {
+    closed: boolean;
+};
+/**
+ * Parse a single-subpath `M x,y L x,y ... [Z]` path into vertex arrays.
  *
  * Returns null for paths we can't safely round-trip (multi-subpath, curves,
- * fewer than three vertices). The wand only adopts shapes it produced or
- * that Plotly's drawclosedpath produces, both of which are single-subpath
- * polygons.
+ * non-numeric coordinates, fewer than three vertices).
  */
 export declare function parseSvgPathPolygon(path: string): PolygonVertices | null;
-/**
- * Build a closed SVG path string `M x,y L x,y L ... Z` from vertex arrays.
- * Returns '' for fewer than three vertices (degenerate).
- */
-export declare function polygonToSvgPath(xpoints: number[], ypoints: number[]): string;
 /**
  * Build an SVG path string from vertex arrays. Closed polygons end with `Z`,
  * open polylines do not. Returns '' for fewer than two vertices (degenerate).
  */
 export declare function verticesToSvgPath(xs: number[], ys: number[], closed: boolean): string;
-/**
- * Compare two Plotly shape objects for "same region" — used by the wand to
- * avoid appending duplicates when the user pushes the same find result more
- * than once. Polygons compare by SVG path string, rectangles compare by
- * (x0, y0, x1, y1).
- */
-export declare function shapesEqual(a: any, b: any): boolean;
-/** Returns true if the two bbox-relative masks share at least one set pixel. */
-export declare function masksOverlap(a: BBoxMask, b: BBoxMask): boolean;
-/**
- * Allocate a fresh accumulator covering both masks and OR them in. The
- * resulting mask's bbox is the smallest rectangle containing both inputs.
- */
-export declare function unionMasks(a: BBoxMask, b: BBoxMask): BBoxMask;
-/**
- * Simplify a closed ring with the Douglas–Peucker algorithm (jit-ui#85):
- * drop every vertex that lies within `epsilon` pixels (the "altitude
- * threshold") of the line between its kept neighbours. Anchored at vertex 0
- * (the ring is closed by appending it). Rings of ≤ 3 vertices, or a
- * non-positive epsilon, are returned unchanged. Output keeps the closed-ring
- * convention (no repeated closing point).
- */
-export declare function simplifyRing(xs: number[], ys: number[], epsilon: number): {
-    xs: number[];
-    ys: number[];
-};

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

@@ -0,0 +1,72 @@
+/**
+ * Copy-on-write polygon edits (review RT-13, RegionStore split "polygon-edit").
+ *
+ * Every function takes a polygon and returns a NEW {@link Polygon} with the
+ * edit applied — or null when the edit does not apply (an index out of range,
+ * a vertex delete that would degenerate the ring, …), so a caller can skip its
+ * undo step. The input is never mutated: arrays the edit does not touch are
+ * shared with it (structural sharing), arrays it does touch are copied. That
+ * is what lets `RegionStore` keep shallow undo snapshots instead of deep
+ * clones: an instance in a snapshot is never changed after the fact.
+ *
+ * Pure: no DOM, no store. Coordinates are image pixels; bézier handle offsets
+ * are relative to their anchor, as on {@link Polygon}.
+ */
+import { MultiPolygon, Polygon, Rectangle } from './region';
+/** Move exterior vertex `index` to (x, y). Null when `index` is out of range. */
+export declare function moveVertex(p: Polygon, index: number, x: number, y: number): Polygon | null;
+/**
+ * Insert a vertex at (x, y) after `segIndex` (the start vertex of the edge),
+ * clamped to the ring. A bézier polygon with stored handles gives the new
+ * vertex smooth handles from its neighbours and keeps the others' (possibly
+ * hand-edited) handles.
+ */
+export declare function addVertex(p: Polygon, segIndex: number, x: number, y: number): Polygon;
+/**
+ * Delete exterior vertex `index`. Null when out of range, or when it would
+ * leave fewer than 3 vertices (2 for an open polyline).
+ */
+export declare function deleteVertex(p: Polygon, index: number): Polygon | null;
+/** Move vertex `index` of hole `holeIndex` to (x, y). Null when either is out of range. */
+export declare function moveHoleVertex(p: Polygon, holeIndex: number, index: number, x: number, y: number): Polygon | null;
+/**
+ * Insert a vertex at (x, y) on hole `holeIndex`, after `segIndex`. A bézier
+ * polygon re-seeds its hole handles so they stay parallel to the rings. Null
+ * for an out-of-range hole.
+ */
+export declare function addHoleVertex(p: Polygon, holeIndex: number, segIndex: number, x: number, y: number): Polygon | null;
+/**
+ * Delete vertex `index` of hole `holeIndex`. Taking a ring below 3 vertices
+ * drops the whole hole (it would bound no area). Null when out of range.
+ */
+export declare function deleteHoleVertex(p: Polygon, holeIndex: number, index: number): Polygon | null;
+/**
+ * Per-hole bézier handles seeded from the Catmull-Rom default, parallel to
+ * `holes` (both undefined without holes).
+ */
+export declare function seededHoleHandles(holes: number[][][] | undefined): Pick<Polygon, 'holeHandlesIn' | 'holeHandlesOut'>;
+/**
+ * Turn bézier on — seeding editable handles (holes included) from the smooth
+ * default — or off, dropping every handle. The anchors never move. Null when
+ * the polygon is already in that state.
+ */
+export declare function setBezier(p: Polygon, bezier: boolean): Polygon | null;
+/**
+ * Move the `side` control point of exterior vertex `index` to the absolute
+ * point (x, y). Handles missing from a bézier polygon are seeded from the
+ * default first. Null for a non-bézier polygon or an out-of-range index.
+ */
+export declare function moveBezierHandle(p: Polygon, index: number, side: 'in' | 'out', x: number, y: number): Polygon | null;
+/**
+ * Move the `side` control point of vertex `index` on hole `holeIndex` to the
+ * absolute point (x, y), seeding the hole handles first when missing. Null for
+ * a non-bézier polygon or an out-of-range hole/index.
+ */
+export declare function moveHoleBezierHandle(p: Polygon, holeIndex: number, index: number, side: 'in' | 'out', x: number, y: number): Polygon | null;
+/**
+ * A polygon moved by (dx, dy): its vertices and holes (bézier offsets are
+ * relative, so they carry over). `round` snaps the moved coordinates.
+ */
+export declare function translatePolygon(p: Polygon, dx: number, dy: number, round?: (v: number) => number): Polygon;
+/** Any region geometry moved by (dx, dy) (see {@link translatePolygon}). */
+export declare function translateBounds(b: Rectangle | Polygon | MultiPolygon, dx: number, dy: number, round?: (v: number) => number): Rectangle | Polygon | MultiPolygon;

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

@@ -0,0 +1,45 @@
+import { MultiPolygon, Polygon, Rectangle, Region } from './region';
+/**
+ * Polygon / Region construction and cloning in one place, so callers stop
+ * hand-filling `npoints`, `xpoints`, `ypoints`, `coordinates` and `closed`
+ * (three redundant views of one ring that every mutator must keep in sync).
+ */
+/** Options for {@link makePolygon}. */
+export interface MakePolygonOptions {
+    /** false for an open polyline; default true. */
+    closed?: boolean;
+    /** Interior rings; omitted when absent or empty. */
+    holes?: number[][][];
+    bezier?: boolean;
+}
+/** A Polygon over the given vertex arrays (taken by reference). */
+export declare function makePolygon(xs: number[], ys: number[], opts?: MakePolygonOptions): Polygon;
+/** The four corners of a rectangle as a closed ring (clockwise from top-left). */
+export declare function rectToRing(r: Pick<Rectangle, 'x' | 'y' | 'width' | 'height'>): {
+    xs: number[];
+    ys: number[];
+};
+/** A deep copy of a polygon: vertices, holes and every bézier handle. */
+export declare function clonePolygon(p: Polygon): Polygon;
+/** A deep copy of any region geometry. */
+export declare function cloneBounds(bounds: Rectangle | Polygon | MultiPolygon): Rectangle | Polygon | MultiPolygon;
+/**
+ * A copy of `existing` (id, name, label, colour, colour override, source,
+ * file name, kind, z, …) with new geometry and optional extra fields. Use it
+ * whenever a tool edits a region's shape, so the edit never drops metadata and
+ * never mutates the store's instance.
+ */
+export declare function replaceBounds(existing: Region, bounds: Region['bounds'], patch?: Partial<Region>): Region;
+/**
+ * The closed polygons a region covers, for image-processing consumers (crop,
+ * segmentation requests): a rectangle's four corners, a closed polygon with its
+ * holes (a bézier region as its flattened curve), one polygon per part of a
+ * multi-polygon. Open polylines cover no area and yield nothing. Coordinates
+ * 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-clone.d.ts

@@ -0,0 +1,20 @@
+import { Polygon, Region } from './region';
+/**
+ * Copy-on-write region copies and geometry equality (RT-13). Stored regions
+ * are shared with the undo history, so a change is always a copy; these
+ * helpers return the input unchanged when the patch would not change it.
+ * (Deep geometry copies are `cloneBounds` / `clonePolygon` in `polygon-factory`.)
+ */
+/** A shallow copy of `r` with `patch` applied; `r` itself is never changed. */
+export declare function withRegionPatch(r: Region, patch: Partial<Region>): Region;
+/** `r` tagged with slice `z`: itself when it already is, else a copy. */
+export declare function withRegionZ(r: Region, z: number): Region;
+/**
+ * True when two regions have the same geometry: equal rectangles, or polygons
+ * (each part of a multi-polygon, in order) with the same vertices, open/closed
+ * state and holes. Bézier handles, labels and colours are not compared. Mixed
+ * kinds are never equal.
+ */
+export declare function regionsEqual(a: Region, b: Region): boolean;
+/** Same vertices, open/closed state and holes (see {@link regionsEqual}). */
+export declare function polygonsEqual(pa: Polygon, pb: Polygon): boolean;

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

@@ -0,0 +1,57 @@
+import { Region } from './region';
+/**
+ * Parse a GeoJSON FeatureCollection string (QuPath-compatible) into regions.
+ * Throws on invalid JSON, a missing `features` key, or a feature without
+ * 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

@@ -1,9 +1,20 @@
 import { ShapeSelection } from './shape';
+/**
+ * One annotation region — the backend-neutral model every renderer (Plotly,
+ * OpenSeadragon, napari-js), the RegionStore, the Region Editor and the
+ * GeoJSON/QuPath import/export share.
+ *
+ * Geometry lives in {@link bounds}, in full-resolution image-pixel
+ * coordinates (x right, y down) of slice {@link z}. A region with no bounds
+ * (`null`/absent) is kept but draws nowhere. Regions that arrive as JSON are
+ * rebuilt into class instances by {@link hydrateBounds} on their way into the
+ * store, so `bounds instanceof Rectangle` etc. can be relied on downstream.
+ */
 export declare class Region {
-    /** Stable, unique identity for selection and equality. Minted by
-     *  PlotlyService when a region first enters the system. Never derived
-     *  from array index — name collisions across delete/add cycles must
-     *  not break PrimeNG row selection. */
+    /** Stable, unique identity for selection and equality. Minted by the
+     *  RegionStore when a region first enters it. Never derived from array
+     *  index — name collisions across delete/add cycles must not break PrimeNG
+     *  row selection. */
     id: number;
     name: string;
     bounds?: Rectangle | Polygon | MultiPolygon | null;
@@ -24,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
@@ -37,6 +67,7 @@ export declare class Region {
      *  or a region drawn without a slice context (jit-ui#93). */
     z: number;
     shapeColor?: string | undefined;
+    /** @deprecated Unused by the library; will be removed in the next minor release. */
     bytesPerPixel: number;
     /**
      * resolution is the resolution at which the region
@@ -49,13 +80,19 @@ export declare class Region {
      * at resolution = 0
      */
     resolution: number;
+    /** @deprecated Unused by the library; will be removed in the next minor release. */
     cropped: boolean;
+    /** @deprecated Unused by the library; will be removed in the next minor release. */
     tileNumber: number;
     tileCoordinates: number[] | null;
     /** True for intensity-profile line ROIs (the intensity tool's lines). These are
      *  NOT annotation regions: they never appear in the Region Editor and editor
      *  operations (select/save/delete) must never touch them. */
     isProfile(): boolean;
+    /**
+     * A debug string: the rectangle's box, or the polygon's SVG path.
+     * @deprecated Unused by the library; will be removed in the next minor release.
+     */
     toString(): string;
     /**
      * Returns a ShapeSelection object that can be used to
@@ -67,12 +104,23 @@ export declare class Region {
     isRectangle(bnds: any): bnds is Rectangle;
     isPolygon(bnds: any): bnds is Polygon;
 }
+/** An axis-aligned box in image-pixel coordinates: (`x`, `y`) is the top-left
+ *  (minimum) corner, `width`/`height` extend right/down. */
 export declare class Rectangle {
     x: number;
     y: number;
     width: number;
     height: number;
 }
+/**
+ * A polygon or open polyline in image-pixel coordinates, optionally with holes
+ * and smoothed into a bézier curve.
+ *
+ * The vertices are stored twice and must agree: as the parallel `xpoints` /
+ * `ypoints` arrays (length `npoints`; the Java/JIT wire shape) and as
+ * `coordinates` `[x, y]` pairs (what GeoJSON export reads). The ring is
+ * implicitly closed — the first vertex is not repeated at the end.
+ */
 export declare class Polygon {
     npoints: number;
     xpoints: number[];
@@ -132,6 +180,13 @@ export declare class MultiPolygon {
     /** One or more disjoint closed polygons (each may have holes). */
     polygons: Polygon[];
 }
+/**
+ * A region's geometry as a host may supply it: a {@link Rectangle} or
+ * {@link Polygon} instance, or a plain object with the same fields (e.g. parsed
+ * JSON, possibly with only some of them). Image-pixel coordinates. Plain objects
+ * become class instances via {@link hydrateBounds} when they enter the store;
+ * {@link Region.bounds} itself is always an instance (or a {@link MultiPolygon}).
+ */
 export type Bounds = Rectangle | Polygon | {
     x?: number;
     y?: number;

package/lib/models/shape.d.ts

@@ -1,5 +1,13 @@
 import { Region } from './region';
 import { Datum, Font, Shape, ShapeLabel, ShapeLine, XAxisName, YAxisName } from 'plotly.js-dist-min';
+/**
+ * A {@link Region} projected to a Plotly layout shape (`rect` or SVG `path`),
+ * carrying the region's identity, class label and file name along so it
+ * round-trips through Plotly's relayout. Coordinates are the plot's data
+ * coordinates, which are the region's image pixels. Built by
+ * {@link Region.getShape}; {@link getRegion} converts back (only `rect` and
+ * `path` shapes — anything else throws).
+ */
 export declare class ShapeSelection implements Shape {
     /** Stable, unique identity carried alongside the shape so it round-trips
      *  through Plotly's relayout untouched. Plotly preserves unknown