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

package/lib/region-overlay/svg-region-renderer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * World-space SVG region renderer shared by the OpenSeadragon and napari
+ * overlays (review NAPARI-BOUNDARY-10, OSD-PLOTLY-11).
+ *
+ * The overlays used to delete and rebuild every region element on every camera
+ * frame, projecting every vertex to screen pixels (napari also read the layout
+ * once per vertex). Here region geometry is drawn ONCE, in world coordinates,
+ * inside a single `<g transform="matrix(a b c d e f)">`, with
+ * `vector-effect: non-scaling-stroke` so strokes keep their pixel width. A
+ * camera change rewrites that one attribute and re-positions the few
+ * screen-sized elements (labels, the selected region's handles, a draft) —
+ * nothing is created or removed. Region nodes are rebuilt only when the
+ * regions or the selection change ({@link render}).
+ *
+ * Layers, bottom to top, each attached only while it has content:
+ *  1. world   — region shapes, in world coordinates (transformed group);
+ *  2. labels  — screen-space text pinned to world anchors, rebuilt with the regions;
+ *  3. overlay — screen-space handles/drafts, rebuilt by the overlay on demand
+ *     ({@link renderOverlay}).
+ */
+import { Region } from '../models/region';
+/** An SVG affine `matrix(a b c d e f)`: x' = a·x + c·y + e, y' = b·x + d·y + f. */
+export type Affine = readonly [number, number, number, number, number, number];
+/** World → svg-local pixel projection. */
+export type Project = (x: number, y: number) => [number, number];
+export declare const IDENTITY_AFFINE: Affine;
+/**
+ * The affine of a projection that is affine (pan/zoom/rotate/flip), read from
+ * where it sends (0,0), (1,0) and (0,1) — how the OSD overlay gets its matrix
+ * from the viewport transform without depending on viewer internals. (napari-js
+ * hands the napari overlay its matrix directly: `Viewer.canvasTransform()`.)
+ */
+export declare function affineFromProjection(project: (x: number, y: number) => readonly [number, number]): Affine;
+/** Apply an affine to a point. */
+export declare function applyAffine(m: Affine, x: number, y: number): [number, number];
+/** How a placed screen element is (re)positioned for the current camera. */
+export type Placement<T extends SVGElement> = (el: T, project: Project) => void;
+/** Options for {@link SvgRegionRenderer}. */
+export interface SvgRegionRendererOptions {
+    /** Draw a {@link Rectangle} as a `<rect>` or as a four-point `<polygon>`. Default polygon. */
+    rectElement?: 'rect' | 'polygon';
+    /** Stroke and fill for one region's shape element. */
+    styleShape(el: SVGElement, region: Region, selected: boolean): void;
+    /** Add a region's screen-space decorations (its label) — once per {@link render}. */
+    decorate?(region: Region, index: number, selected: boolean, layer: ScreenLayer): void;
+    /** Leave a region out entirely (it keeps its index). */
+    skip?(region: Region): boolean;
+}
+/**
+ * A screen-space layer: elements positioned from world anchors through the
+ * current camera, re-positioned (not rebuilt) on every camera change.
+ */
+export declare class ScreenLayer {
+    readonly group: SVGGElement;
+    private readonly project;
+    private readonly placed;
+    constructor(group: SVGGElement, project: Project);
+    /** Append `el`, positioned by `place` now and after every camera change. */
+    place<T extends SVGElement>(el: T, place: Placement<T>): T;
+    /** Append `el` with attributes `x`/`y` (e.g. `'cx'`/`'cy'`) at a world point, offset in pixels. */
+    at<T extends SVGElement>(el: T, wx: number, wy: number, attrs?: {
+        x?: string;
+        y?: string;
+        dx?: number;
+        dy?: number;
+    }): T;
+    /** A `<line>` between two world points. */
+    line(ax: number, ay: number, bx: number, by: number): SVGLineElement;
+    /** A `<polygon>` / `<polyline>` through world points. */
+    poly(tag: 'polygon' | 'polyline', pts: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>): SVGElement;
+    /** Re-position every element for the current camera. */
+    reproject(): void;
+    get isEmpty(): boolean;
+    clear(): void;
+}
+/** Create an SVG element. */
+export declare function svgEl<K extends keyof SVGElementTagNameMap>(tag: K): SVGElementTagNameMap[K];
+export declare class SvgRegionRenderer {
+    private readonly svg;
+    private readonly opts;
+    private camera;
+    private readonly world;
+    private readonly labels;
+    private readonly overlay;
+    /** World → svg-local pixels through the current camera. */
+    readonly project: Project;
+    constructor(svg: SVGSVGElement, opts: SvgRegionRendererOptions);
+    /** The current world → svg-local affine. */
+    get affine(): Affine;
+    /**
+     * Move the camera: rewrite the world group's transform and re-position the
+     * screen-space elements. No element is created or removed. Returns false
+     * (and touches nothing) when the affine did not change.
+     */
+    setCamera(affine: Affine): boolean;
+    /** Rebuild the region shapes (world space) and their decorations. */
+    render(regions: ReadonlyArray<Region>, selected: ReadonlyArray<number>): void;
+    /** Rebuild the overlay layer (the selected region's handles, drafts). */
+    renderOverlay(build: (layer: ScreenLayer) => void): void;
+    /** Remove every layer from the svg. */
+    destroy(): void;
+    private applyCamera;
+    /** Attach the layers that have content (in order) and detach the empty ones. */
+    private sync;
+    /** The world-space element for a region's geometry, or null when it has none. */
+    private shapeOf;
+}

package/lib/region-source/http-region-source.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A {@link RegionSource} served over HTTP, by a server that tiles a region set as `region-tiles`
+ * does (the example tile server's `/regions/…` routes). Relative to the source's base URL:
+ *
+ *  - `GET  info`                       → {@link RegionSourceInfo}
+ *  - `GET  tile/{z}/{level}/{gx}/{gy}` → `{ features: WireTileFeature[] }`
+ *  - `POST features` `{ ids }`         → `{ features: SourceFeature[] }`
+ *  - `POST index` `{ z, ...query }`    → {@link RegionIndexPage}
+ *  - `POST classes` `{ z, exclude }`    → features per class on plane z
+ *  - `POST outlines` `{ classes, level, exclude }` → `{ slices: [{ z, rings }] }`
+ *  - `POST export` `{ exclude, extra }`→ a GeoJSON FeatureCollection
+ *
+ * Tile rings travel as flat `[x, y, x, y, …]` arrays, label points as flat `[x, y, room, …]`.
+ *
+ * Given the host's Angular `HttpClient` (as the visualizer passes it), every request goes through
+ * it, so the host's interceptors apply — its auth header above all — as for the image tiles and
+ * the spatial data. The library itself knows nothing of authentication.
+ */
+import type { HttpClient } from '@angular/common/http';
+import { RegionSource } from './region-source';
+import type { Bbox } from './region-tiles';
+/** A tile feature on the wire: rings as plain arrays. */
+export interface WireTileFeature {
+    id: string;
+    label: string | null;
+    color: string | null;
+    bbox: Bbox;
+    rings: number[][];
+    open?: boolean;
+    labels?: number[];
+}
+/** Options of {@link openHttpRegionSource}. */
+export interface HttpRegionSourceOptions {
+    /**
+     * The host's `HttpClient`: requests then go through it and its interceptors (the host's auth),
+     * not `fetch`, and `init` and `fetch` are not used.
+     */
+    http?: HttpClient;
+    /** Extra request options (credentials, headers) for every `fetch` request. */
+    init?: RequestInit;
+    /** The fetch to use (default the global one). */
+    fetch?: typeof fetch;
+}
+/** Open the region source at `baseUrl` (its `info` is fetched first). */
+export declare function openHttpRegionSource(baseUrl: string, options?: HttpRegionSourceOptions): Promise<RegionSource>;

package/lib/region-source/region-source-ops.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The region-source worker's protocol and the tables it holds, shared by the worker and the
+ * main-thread fallback (which runs the very same {@link RegionSourceTables} where no worker can
+ * start).
+ *
+ * Protocol: `{ id, op, ...args }` → `{ id, ok: true, result }` | `{ id, ok: false, error }`.
+ */
+import { ReconstructOptions, SliceOutlines } from '../geometry/reconstruct';
+import type { Mesh } from 'napari-js/geometry';
+import { ClassOutlines, RegionIndexPage, RegionIndexQuery, RegionSourceInfo, RegionTile } from './region-tiles';
+import type { SourceFeature } from './region-source';
+export type RegionSourceRequest = {
+    op: 'open';
+    text: string;
+    tileSize?: number;
+} | {
+    op: 'tile';
+    handle: number;
+    z: number;
+    level: number;
+    gx: number;
+    gy: number;
+} | {
+    op: 'features';
+    handle: number;
+    ids: readonly string[];
+} | {
+    op: 'index';
+    handle: number;
+    z: number;
+    query: RegionIndexQuery;
+} | {
+    op: 'classes';
+    handle: number;
+    z: number | null;
+    exclude?: readonly string[];
+} | {
+    op: 'outlines';
+    handle: number;
+    classes: readonly string[] | null;
+    level: number;
+    exclude?: readonly string[];
+} | {
+    op: 'mesh';
+    slices: readonly SliceOutlines[];
+    options?: ReconstructOptions;
+} | {
+    op: 'export';
+    handle: number;
+    exclude: readonly string[];
+    extra: readonly object[];
+} | {
+    op: 'close';
+    handle: number;
+};
+export interface RegionSourceResults {
+    open: {
+        handle: number;
+        info: RegionSourceInfo;
+    };
+    tile: RegionTile;
+    features: SourceFeature[];
+    index: RegionIndexPage;
+    classes: Record<string, number>;
+    outlines: ClassOutlines[];
+    mesh: Mesh;
+    export: string;
+    close: null;
+}
+export type RegionSourceMessage = RegionSourceRequest & {
+    id: number;
+};
+export type RegionSourceReply = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/** The open tables, by handle. */
+export declare class RegionSourceTables {
+    private readonly tables;
+    private nextHandle;
+    run<R extends RegionSourceRequest>(request: R): RegionSourceResults[R['op']];
+    private dispatch;
+    private table;
+}

package/lib/region-source/region-source-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Factory for the region-source Web Worker, isolated in its own module so the `import.meta.url`
+ * reference — which the bundler needs in order to locate the worker — is never pulled into the
+ * ts-jest CommonJS compile of anything that uses it. Same arrangement as
+ * `workers/spatial-math-worker.ts`.
+ */
+export declare function createRegionSourceWorker(): Worker;

package/lib/region-source/region-source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A tiled region source: one image's large region set, served as level-of-detail tiles so a view
+ * never holds or draws the whole set (see `region-tiles` for the levels and tiles).
+ *
+ * Two implementations behind {@link RegionSource}: a GeoJSON source parsed and tiled in a Web
+ * Worker (`openGeoJsonRegionSource`, the main thread only ever sees tiles), and an HTTP source
+ * for a server that serves the same tiles (`openHttpRegionSource`).
+ */
+import type { ClassOutlines, GeoJsonFeatureLike, RegionIndexPage, RegionIndexQuery, RegionSourceInfo, RegionTile, RegionTileKey, TileFeature } from './region-tiles';
+import type { RegionStyle } from '../region-overlay/region-style';
+/** A feature's exact GeoJSON with the source's id for it. */
+export interface SourceFeature {
+    id: string;
+    feature: GeoJsonFeatureLike;
+}
+/** One image's tiled region set. */
+export interface RegionSource {
+    /** What the source holds; known once it is open. */
+    readonly info: RegionSourceInfo;
+    /** One tile of plane `z`. Cached: asking again for a tile in view costs nothing. */
+    getTile(z: number, key: RegionTileKey, signal?: AbortSignal): Promise<RegionTile>;
+    /** The exact features with these ids (unknown ids are skipped). */
+    getFeatures(ids: readonly string[]): Promise<SourceFeature[]>;
+    /** A page of plane `z`'s feature index. */
+    getIndex(z: number, query: RegionIndexQuery): Promise<RegionIndexPage>;
+    /**
+     * Every plane's outlines of the features of these classes, simplified for `level`, without the
+     * `exclude`d ids: what a 3D reconstruction of the classes stacks. `classes` null reads every
+     * class, each outline labelled with its own (what a section through the stack draws).
+     */
+    getClassOutlines(classes: readonly string[] | null, level: number, exclude?: readonly string[]): Promise<ClassOutlines[]>;
+    /**
+     * How many features of each class plane `z` has (null: every plane, the whole stack), without
+     * the `exclude`d ids.
+     */
+    getClassCounts(z: number | null, exclude?: readonly string[]): Promise<Record<string, number>>;
+    /**
+     * The whole set as a GeoJSON FeatureCollection string, through the working set: `exclude`d
+     * features (taken for editing, or deleted) left out, `extra` features appended.
+     */
+    exportGeoJson(exclude: readonly string[], extra: readonly object[]): Promise<string>;
+    /** Release the source (its worker table, its cache). */
+    dispose(): void;
+}
+/** What the store shows of the current slice's region source: what a source layer draws. */
+export interface RegionSourceView {
+    source: RegionSource;
+    /** The source plane the slice shows. */
+    plane: number;
+    /** Ids the source no longer draws: taken into the working set, or deleted. */
+    taken: ReadonlySet<string>;
+    /** The colour a feature is drawn in (its class colour, as a region of that class gets). */
+    colorOf(feature: Pick<TileFeature, 'label' | 'color'>): string;
+    /** The region look, the regions' own (so a feature looks the same once taken). */
+    style: RegionStyle;
+    /** Whether class labels are shown. */
+    labels: boolean;
+    /** Whether a class's features are hidden (see `RegionStore.setClassesHidden`); default: none is. */
+    isHidden?(label: string | null | undefined): boolean;
+}
+/**
+ * ROI GeoJSON at least this many characters long loads as a tiled region source rather than as
+ * regions (see `VizConfig.regionSourceMinChars`).
+ */
+export declare const REGION_SOURCE_MIN_CHARS = 1000000;
+/** Tiles a source keeps, most recently used last. */
+export declare const REGION_TILE_CACHE_SIZE = 384;
+/** A least-recently-used cache of tile requests. A request that fails is forgotten. */
+export declare class RegionTileCache {
+    private readonly limit;
+    private readonly tiles;
+    constructor(limit?: number);
+    /** The cached tile, else `load()`'s, cached. */
+    get(z: number, key: RegionTileKey, load: () => Promise<RegionTile>): Promise<RegionTile>;
+    clear(): void;
+}
+/** An `AbortError`, as `fetch` and the workers reject with. */
+export declare function abortError(): Error;
+/** True for the rejection of an aborted request. */
+export declare function isAbortError(err: unknown): boolean;
+/** `promise`, rejected with an `AbortError` as soon as `signal` fires (the work goes on). */
+export declare function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;

package/lib/region-source/region-tiles.d.ts

@@ -0,0 +1,289 @@
+/** An axis-aligned box `[x0, y0, x1, y1]` in image pixels. */
+export type Bbox = [number, number, number, number];
+/** Edge of a level-0 tile, in image pixels. */
+export declare const REGION_TILE_SIZE = 512;
+/**
+ * One class of a class hierarchy (e.g. a brain-atlas ontology): the class name the features use,
+ * its long name, its parent class and its colour. A region set may carry one (a GeoJSON
+ * FeatureCollection's `classHierarchy` member); the Region Editor then lists the set as a tree.
+ */
+export interface RegionClassNode {
+    /** The class name, as features use it (`classification.name`): an atlas acronym, say. */
+    name: string;
+    /** The long name, e.g. "Somatomotor areas, Layer 5". */
+    title?: string;
+    /** The parent class's name; absent for a root. */
+    parent?: string | null;
+    /** `#rrggbb`. */
+    color?: string;
+    /** Position among its siblings (an atlas's graph order); file order without one. */
+    order?: number;
+}
+/**
+ * How a region set wants to be drawn, a hint the viewer applies when the set opens (a GeoJSON
+ * FeatureCollection's `style` member): an atlas fills its structures and labels them.
+ */
+export interface RegionSourceStyle {
+    /** Fill regions in their colour at this opacity (0 = outlines only). */
+    fillOpacity?: number;
+    /** Outline colour when filled (default: the region's colour). */
+    stroke?: string;
+    /** Outline width in screen px. */
+    strokeWidth?: number;
+    /** Show class labels inside the regions. */
+    labels?: boolean;
+    /** Fill colour of selected regions. */
+    highlight?: string;
+}
+/** What a region source holds, known once it is open. */
+export interface RegionSourceInfo {
+    /** Features in the source, over every plane. */
+    featureCount: number;
+    /** The box around every feature's geometry; null when none has any. */
+    bounds: Bbox | null;
+    /** Edge of a level-0 tile, in image pixels. */
+    tileSize: number;
+    /** Number of levels; the last one's tiles cover {@link bounds} in a few tiles. */
+    levels: number;
+    /** The z planes features are on (QuPath's `geometry.plane.z`, 0 without one), ascending. */
+    planes: number[];
+    /** The colour the file gives each class (its first feature's), by class name. */
+    classColors: Record<string, string>;
+    /** The set's class hierarchy, when it has one. */
+    hierarchy?: RegionClassNode[];
+    /** How the set wants to be drawn, when it says. */
+    style?: RegionSourceStyle;
+}
+/** One feature as a tile carries it: identity, class and outline at the tile's level. */
+export interface TileFeature {
+    id: string;
+    /** The class name. */
+    label: string | null;
+    /** The feature's own colour (`#rrggbb`), from its classification. */
+    color: string | null;
+    /** The box around the exact geometry. */
+    bbox: Bbox;
+    /** Rings as interleaved `x, y` (no repeated closing vertex): exteriors and holes of every
+     *  part, drawn and hit-tested even-odd. For an open feature, its polylines. */
+    rings: Float32Array[];
+    /** A polyline (LineString) rather than an area. */
+    open: boolean;
+    /**
+     * Where to label the feature, per part big enough: `x, y, room` triples, `room` the distance
+     * from the point to the part's nearest edge (image px), so a label shows once it fits.
+     */
+    labels?: Float32Array;
+}
+/**
+ * A class's outlines on one plane: rings as interleaved `x, y` image px (holes included), and its
+ * open features' polylines, likewise (absent from a server that predates them). Read for every
+ * class at once, each ring's and line's class comes with it (`ringLabels`, `lineLabels`).
+ */
+export interface ClassOutlines {
+    z: number;
+    rings: Float32Array[];
+    /**
+     * The feature each ring is part of (see SliceOutlines.ringGroups): a feature's rings fill
+     * even-odd, the features as their union. Absent from a server that predates them.
+     */
+    ringGroups?: number[];
+    lines?: Float32Array[];
+    ringLabels?: string[];
+    lineLabels?: string[];
+}
+/** One tile of one level of one plane. */
+export interface RegionTile {
+    z: number;
+    level: number;
+    gx: number;
+    gy: number;
+    features: TileFeature[];
+}
+/** A tile's address. */
+export interface RegionTileKey {
+    level: number;
+    gx: number;
+    gy: number;
+}
+/** One row of a source's feature index (the Region Editor's table). */
+export interface RegionIndexRow {
+    id: string;
+    label: string | null;
+    color: string | null;
+    bbox: Bbox;
+    /** The area inside the exact outline (holes left out), image px²; 0 for a polyline. Absent from a
+     *  server that predates it. */
+    area?: number;
+}
+/** A page of a plane's feature index. */
+export interface RegionIndexPage {
+    /** Rows matching the query, over the whole plane. */
+    total: number;
+    rows: RegionIndexRow[];
+}
+/** Which rows a page of the index holds. */
+export interface RegionIndexQuery {
+    offset: number;
+    limit: number;
+    /** Only rows whose class name contains this (case-insensitive). */
+    label?: string;
+    /** Leave these ids out (taken into the working set, or deleted). */
+    exclude?: readonly string[];
+    /** Only rows of exactly these classes. */
+    classes?: readonly string[];
+}
+/** The parts of a GeoJSON feature the tiler reads. Parsed from a file: nothing is guaranteed. */
+export interface GeoJsonFeatureLike {
+    type?: string;
+    id?: string | number;
+    geometry?: {
+        type?: string;
+        coordinates?: unknown;
+        plane?: {
+            z?: number;
+        };
+    } | null;
+    properties?: {
+        id?: string | number;
+        classification?: unknown;
+    } & Record<string, unknown>;
+}
+/**
+ * The level whose tiles suit a zoom of `pxPerImagePx` screen pixels per image pixel: exact (0)
+ * at 1:1 and closer, else level k for zooms in [2⁻ᵏ, 2¹⁻ᵏ), where its tolerance is half to one
+ * screen pixel and the features it leaves out are under one or two.
+ */
+export declare function regionLevelFor(pxPerImagePx: number, levels: number): number;
+/** Simplification tolerance of a level, in image pixels (0 = exact). */
+export declare function levelTolerance(level: number): number;
+/** Features smaller than this (their box's longer side, image pixels) are left out of a level. */
+export declare function levelMinExtent(level: number): number;
+/** Tile edge of a level, in image pixels. */
+export declare function levelTileSize(level: number, tileSize?: number): number;
+/**
+ * Tiles of `level` that meet `rect`, clipped to `bounds` (none past the data), ordered from the
+ * rectangle's centre outward so the middle of the screen fills first. At most `limit`.
+ */
+export declare function regionTilesInRect(rect: Bbox, level: number, tileSize: number, bounds: Bbox | null, limit?: number): RegionTileKey[];
+/** `level/gx/gy`, a tile's id within one plane. */
+export declare function regionTileId(k: RegionTileKey): string;
+/** The tile of `level` holding image point (x, y). */
+export declare function tileAt(x: number, y: number, level: number, tileSize?: number): RegionTileKey;
+/** True when two boxes meet (edges included). */
+export declare function bboxesMeet(a: Readonly<Bbox>, b: Readonly<Bbox>): boolean;
+/**
+ * The feature under image point (x, y): inside an area (even-odd over its rings, so holes are
+ * outside) or within `tolerance` image pixels of a polyline. Of several, the one with the
+ * smallest box — the innermost of nested outlines. Null when none is.
+ */
+export declare function featureAt(features: Iterable<TileFeature>, x: number, y: number, tolerance?: number): TileFeature | null;
+/** Features whose box meets `rect` (the rubber band's rule for regions). */
+export declare function featuresInRect(features: Iterable<TileFeature>, rect: Readonly<Bbox>): TileFeature[];
+/** Even-odd containment over interleaved rings. */
+export declare function insideRings(rings: readonly ArrayLike<number>[], x: number, y: number): boolean;
+/** Douglas–Peucker over an open polyline (both ends kept). */
+export declare function simplifyPolyline(xs: number[], ys: number[], epsilon: number): {
+    xs: number[];
+    ys: number[];
+};
+/**
+ * Rings simplified for a level: every ring through Douglas–Peucker at the level's tolerance,
+ * rings whose box is under the level's minimum extent dropped, and rings left with too few
+ * vertices to draw (3 for a closed ring, 2 for a polyline) dropped. Level 0 returns the rings
+ * as they are.
+ */
+export declare function simplifyRings(rings: readonly Float64Array[], open: boolean, level: number): Float32Array[];
+/**
+ * A parsed GeoJSON region set, indexed for tiles. Holds the raw features (for the exact
+ * geometry and the export), each feature's rings, box, plane and class, and builds a level's
+ * tile buckets the first time that level of a plane is asked for.
+ */
+export declare class RegionFeatureTable {
+    readonly raw: GeoJsonFeatureLike[];
+    readonly tileSize: number;
+    readonly ids: string[];
+    readonly labels: Array<string | null>;
+    readonly colors: Array<string | null>;
+    readonly planes: number[];
+    readonly boxes: Bbox[];
+    readonly rings: Float64Array[][];
+    readonly open: boolean[];
+    /** Per feature, its parts as ring indices (the exterior first, then its holes). */
+    readonly parts: number[][][];
+    private readonly labelPoints;
+    /** Each feature's area, worked out the first time its row is asked for. */
+    private readonly areas;
+    private hierarchy?;
+    private style?;
+    private readonly byId;
+    private readonly buckets;
+    private readonly simplified;
+    private readonly bounds;
+    private readonly levels;
+    constructor(raw: GeoJsonFeatureLike[], tileSize?: number);
+    /** Parse a GeoJSON FeatureCollection string. Throws on invalid JSON or no `features`. */
+    static fromGeoJson(text: string, tileSize?: number): RegionFeatureTable;
+    /** Attach a class hierarchy and a style hint (each ignored when not well formed). */
+    describe(hierarchy?: unknown, style?: unknown): void;
+    /**
+     * The outlines of every feature of these classes, plane by plane, simplified for `level` (what a
+     * 3D reconstruction of the classes stacks), without the `exclude`d ids: closed features' rings,
+     * open features' polylines as `lines`, each ring with its feature (`ringGroups`). Planes without
+     * one are left out. `classes` null reads every labelled feature, each outline with its class
+     * (`ringLabels`, `lineLabels`).
+     */
+    classOutlines(classes: readonly string[] | null, level: number, exclude?: readonly string[]): ClassOutlines[];
+    /** Features per class on plane `z` (null: on every plane), without the `exclude`d ids. */
+    classCounts(z: number | null, exclude?: readonly string[]): Record<string, number>;
+    info(): RegionSourceInfo;
+    /** One tile of plane `z`. */
+    tile(z: number, level: number, gx: number, gy: number): RegionTile;
+    /** The raw GeoJSON features with these ids, in the order asked (unknown ids skipped). */
+    features(ids: readonly string[]): Array<{
+        id: string;
+        feature: GeoJsonFeatureLike;
+    }>;
+    /** Feature `i`'s area in px² (0 for a polyline). */
+    private areaOf;
+    /** A page of plane `z`'s features, in file order. */
+    index(z: number, query: RegionIndexQuery): RegionIndexPage;
+    /**
+     * The source as a GeoJSON FeatureCollection string, through the working set: features whose
+     * id is in `exclude` (taken for editing, or deleted) are left out, `extra` (the working set's
+     * features) appended. Every feature keeps an `id`; the set keeps its hierarchy and style.
+     */
+    exportGeoJson(exclude: readonly string[], extra: readonly object[]): string;
+    /**
+     * Feature `i`'s label points (one per part with room for a label at `level`: a part under the
+     * level's minimum extent is not drawn there), from the exact geometry, computed once.
+     */
+    private labelsAt;
+    /** Feature `i`'s rings at `level`, simplified once and cached. */
+    private ringsAt;
+    /** Entries in plane `z`'s level-`level` index: cell listings plus wide features (tests). */
+    indexEntries(z: number, level: number): number;
+    /**
+     * Plane `z`'s level-`level` index, built on first use: features by tile cell (`gx/gy` → feature
+     * indices), and the wide ones (more than {@link MAX_CELLS_PER_FEATURE} cells, or past the
+     * number range), tested against a tile when it is asked for.
+     */
+    private bucketsFor;
+}
+/**
+ * A feature spanning more tiles than this is not listed in each of them but kept aside and tested
+ * against a tile when one is asked for: one huge box (an outline around a whole slide, or a corrupt
+ * coordinate) must not make a plane's index millions of entries.
+ */
+export declare const MAX_CELLS_PER_FEATURE = 64;
+/** A feature's own id (`id`, else `properties.id`) as a string. */
+export declare function featureIdOf(feature: GeoJsonFeatureLike): string | undefined;
+/**
+ * A FeatureCollection string of `features` (each a feature's JSON), with the set's class hierarchy
+ * and style as its `classHierarchy` and `style` members when it has them: what
+ * {@link RegionFeatureTable.fromGeoJson} reads back.
+ */
+export declare function featureCollectionJson(features: readonly string[], hierarchy?: readonly RegionClassNode[], style?: RegionSourceStyle): string;
+/** A well-formed class hierarchy from a file (colours as `#rrggbb` or `[r, g, b]`), else undefined. */
+export declare function readHierarchy(raw: unknown): RegionClassNode[] | undefined;
+/** A well-formed style hint from a file, else undefined. */
+export declare function readStyle(raw: unknown): RegionSourceStyle | undefined;