@idetik/core 0.28.0 → 0.29.0

package/dist/index.d.ts

@@ -33,6 +33,7 @@ declare abstract class Texture extends Node {
     releaseCpuData(): void;
     abstract get width(): number;
     abstract get height(): number;
+    get depth(): number;
     get type(): string;
 }
 
@@ -95,6 +96,7 @@ type SourceDimensionLod = {
     scale: number;
     translation: number;
 };
+/** @group Layer Configuration */
 type SliceCoordinates = {
     z?: number;
     c?: number[];
@@ -105,6 +107,7 @@ type ChunkSource = {
 };
 type ChunkLoader = {
     getSourceDimensionMap(): SourceDimensionMap;
+    getBytesPerElement(): number;
     loadChunkData(chunk: Chunk, signal: AbortSignal): Promise<void>;
 };
 
@@ -141,9 +144,13 @@ type ImageSourcePolicy = Readonly<{
         bias: number;
     };
 }>;
+/** @group Layer Configuration */
 declare function createImageSourcePolicy(config: ImageSourcePolicyConfig): ImageSourcePolicy;
+/** @group Layer Configuration */
 declare function createExplorationPolicy(overrides?: Partial<ImageSourcePolicyConfig>): ImageSourcePolicy;
+/** @group Layer Configuration */
 declare function createPlaybackPolicy(overrides?: Partial<ImageSourcePolicyConfig>): ImageSourcePolicy;
+/** @group Layer Configuration */
 declare function createNoPrefetchPolicy(overrides?: Partial<ImageSourcePolicyConfig>): ImageSourcePolicy;
 
 declare class ChunkStore {
@@ -251,7 +258,10 @@ declare class ChunkManager {
     private readonly queue_;
     private readonly uploadTexture_?;
     private readonly disposeTexture_?;
-    constructor(uploadTexture?: (texture: Texture) => void, disposeTexture?: (texture: Texture) => void);
+    private readonly getGpuResidentBytes_;
+    private readonly memoryLimitBytes_;
+    constructor(uploadTexture?: (texture: Texture) => void, disposeTexture?: (texture: Texture) => void, getGpuResidentBytes?: () => number, memoryLimitBytes?: number);
+    get memoryLimitBytes(): number;
     get queueStats(): QueueStats;
     get memoryStats(): {
         cpuChunkBytes: number;
@@ -259,6 +269,8 @@ declare class ChunkManager {
     };
     addView(source: ChunkSource, policy: ImageSourcePolicy): ChunkStoreView;
     update(): void;
+    private enqueueWithinBudget;
+    private chunkBytes;
     private uploadLoadedChunks;
     private disposeChunkTexture;
 }
@@ -334,7 +346,9 @@ declare class TrsTransform {
 
 type Shader = "floatScalarImage" | "floatVolume" | "intScalarImage" | "intVolume" | "labelImage" | "points" | "projectedLine" | "uintScalarImage" | "uintVolume" | "wireframe";
 
+/** @group Layer Configuration */
 type ColorLike = Color | vec3 | vec4 | string;
+/** @group Layer Configuration */
 declare class Color {
     static readonly RED: Color;
     static readonly GREEN: Color;
@@ -446,11 +460,34 @@ declare class EventDispatcher {
     private readonly handleEvent;
 }
 
+/**
+ * A camera using an orthographic (parallel) projection.
+ *
+ * Orthographic projection has no perspective foreshortening, so object size is
+ * independent of distance from the camera. This is the camera to use for 2D
+ * image viewing, where it pairs naturally with {@link PanZoomControls}. The
+ * initial frame is given in world coordinates; zoom and pan are applied as
+ * scale and translation on top of that frame.
+ *
+ * @see {@link PerspectiveCamera} for 3D scenes with perspective projection.
+ *
+ * @group Cameras & Controls
+ */
 declare class OrthographicCamera extends Camera {
     private width_;
     private height_;
     private viewportAspectRatio_;
     private viewportSize_;
+    /**
+     * Creates an orthographic camera framing the given world-space rectangle.
+     *
+     * @param left - Left edge of the view frame, in world units.
+     * @param right - Right edge of the view frame, in world units.
+     * @param top - Top edge of the view frame, in world units.
+     * @param bottom - Bottom edge of the view frame, in world units.
+     * @param near - Near clipping plane distance. Defaults to `0.0`.
+     * @param far - Far clipping plane distance. Defaults to `100.0`.
+     */
     constructor(left: number, right: number, top: number, bottom: number, near?: number, far?: number);
     get viewportSize(): [number, number];
     setAspectRatio(aspectRatio: number): void;
@@ -466,6 +503,7 @@ interface CameraControls {
     onUpdate(dt: number): void;
     onEvent(event: EventContext): void;
 }
+/** @group Cameras & Controls */
 declare class PanZoomControls implements CameraControls {
     private readonly camera_;
     private dragActive_;
@@ -519,6 +557,7 @@ declare class Viewport {
     private updateAspectRatio;
 }
 
+/** @group Layers */
 type LayerState = "initialized" | "loading" | "ready";
 type BlendMode = "none" | "normal" | "additive" | "subtractive" | "multiply" | "premultiplied";
 type StateChangeCallback = (newState: LayerState, prevState?: LayerState) => void;
@@ -526,6 +565,22 @@ interface LayerOptions {
     opacity?: number;
     blendMode?: BlendMode;
 }
+/**
+ * Abstract base class for everything that can be added to a viewport.
+ *
+ * A `Layer` owns a set of renderable objects and contributes them to the scene
+ * each frame. Subclasses (e.g. {@link ImageLayer}, {@link VolumeLayer},
+ * {@link LabelLayer}) implement {@link Layer.update} to build or refresh those
+ * objects for the current view, and may override the `attach`/`detach` hooks to
+ * acquire and release resources when the layer joins or leaves a viewport.
+ *
+ * Layers carry shared presentation state — {@link Layer.opacity} and blend mode —
+ * and expose a lifecycle {@link LayerState} (`initialized` → `loading` → `ready`)
+ * that observers can subscribe to. A layer instance may be attached to only one
+ * viewport at a time.
+ *
+ * @group Layers
+ */
 declare abstract class Layer {
     abstract readonly type: string;
     private objects_;
@@ -585,18 +640,22 @@ declare abstract class Renderer {
     set backgroundColor(color: ColorLike);
 }
 
+/** @group Runtime */
 type Overlay = {
     update(idetik: Idetik): void;
 };
+/** @inline */
 type IdetikParams = {
     canvas: HTMLCanvasElement;
     viewports?: ViewportConfig[];
     overlays?: Overlay[];
     showStats?: boolean;
+    memoryLimitMB?: number;
 };
 type IdetikContext = {
     chunkManager: ChunkManager;
 };
+/** @group Runtime */
 type MemoryStats = {
     cpuChunkBytes: number;
     cpuChunkCount: number;
@@ -605,6 +664,18 @@ type MemoryStats = {
     jsHeapUsedBytes?: number;
     jsHeapLimitBytes?: number;
 };
+/**
+ * The top-level entry point for an Idetik visualization.
+ *
+ * An `Idetik` instance owns the renderer, the shared chunk manager, and one or
+ * more viewports. Each viewport pairs a camera, its controls, and a stack of
+ * layers and draws into a region of the canvas. Call {@link Idetik.start} to
+ * begin the render loop and {@link Idetik.stop} to halt it.
+ *
+ * @see {@link Layer} for the data layers rendered within a viewport.
+ *
+ * @group Runtime
+ */
 declare class Idetik {
     private readonly chunkManager_;
     private readonly context_;
@@ -975,8 +1046,10 @@ declare class OmeZarrImageLoader {
     private readonly arrays_;
     private readonly arrayParams_;
     private readonly dimensions_;
+    private readonly bytesPerElement_;
     constructor(props: OmeZarrImageLoaderProps);
     getSourceDimensionMap(): SourceDimensionMap;
+    getBytesPerElement(): number;
     loadChunkData(chunk: Chunk, signal: AbortSignal): Promise<void>;
 }
 
@@ -1284,11 +1357,15 @@ type Version = (typeof versions)[number];
 type AdaptedOme<T> = T & {
     originalVersion: Version;
 };
+/** @group Data Loading */
 declare function loadOmeZarrPlate(url: string, version?: Version): Promise<AdaptedOme<Plate["ome"]>>;
+/** @group Data Loading */
 declare function loadOmeZarrWell(url: string, path: string, version?: Version): Promise<AdaptedOme<Well["ome"]>>;
 type OmeroMetadata = NonNullable<Image$1["ome"]["omero"]>;
 type OmeroChannel = OmeroMetadata["channels"][number];
+/** @group Data Loading */
 declare function loadOmeroChannels(source: OmeZarrImageSource): Promise<OmeroChannel[]>;
+/** @group Data Loading */
 declare function loadOmeroDefaults(source: OmeZarrImageSource): Promise<OmeroMetadata["rdefs"]>;
 
 type HttpOmeZarrImageSourceProps = {
@@ -1300,7 +1377,11 @@ type FileSystemOmeZarrImageSourceProps = {
     version?: Version;
     path?: `/${string}`;
 };
-/** Opens an OME-Zarr multiscale image Zarr group from either a URL or local directory. */
+/**
+ * Opens an OME-Zarr multiscale image Zarr group from either a URL or local directory.
+ *
+ * @group Data Loading
+ */
 declare class OmeZarrImageSource {
     readonly location: Location<Readable>;
     readonly version?: Version;
@@ -1329,6 +1410,7 @@ declare class OmeZarrImageSource {
     static fromFileSystem(props: FileSystemOmeZarrImageSourceProps): Promise<OmeZarrImageSource>;
 }
 
+/** @group Layers */
 declare class AxesLayer extends Layer {
     readonly type = "AxesLayer";
     constructor(params: {
@@ -1338,6 +1420,7 @@ declare class AxesLayer extends Layer {
     update(): void;
 }
 
+/** @group Layer Configuration */
 type ChannelProps = {
     visible?: boolean;
     color?: ColorLike;
@@ -1358,6 +1441,7 @@ interface PointPickingResult {
     value: number;
 }
 
+/** @inline */
 type ImageLayerProps = LayerOptions & {
     source: ChunkSource;
     sliceCoords: SliceCoordinates;
@@ -1365,6 +1449,20 @@ type ImageLayerProps = LayerOptions & {
     channelProps?: ChannelProps[];
     onPickValue?: (info: PointPickingResult) => void;
 };
+/**
+ * A layer that renders a 2D slice of a chunked, multi-channel image source.
+ *
+ * `ImageLayer` streams chunks from a `ChunkSource` (e.g.
+ * {@link OmeZarrImageSource}) according to the supplied `ImageSourcePolicy`,
+ * which decides which resolution levels and chunks to load for the current
+ * view. Per-channel appearance (contrast limits,
+ * color, visibility) is controlled via {@link ChannelProps}, and the visible
+ * slice is selected with {@link SliceCoordinates}.
+ *
+ * @see {@link VolumeLayer} for 3D volume rendering of the same data.
+ *
+ * @group Layers
+ */
 declare class ImageLayer extends Layer implements ChannelsEnabled {
     readonly type = "ImageLayer";
     private readonly source_;
@@ -1421,6 +1519,7 @@ type VolumeLayerProps = {
     policy: ImageSourcePolicy;
     channelProps?: ChannelProps[];
 };
+/** @group Layers */
 declare class VolumeLayer extends Layer implements ChannelsEnabled {
     readonly type = "VolumeLayer";
     private readonly source_;
@@ -1464,6 +1563,7 @@ type LabelColorMapProps = {
     lookupTable?: ReadonlyMap<number, ColorLike>;
     cycle?: ColorLike[];
 };
+/** @group Renderable Objects */
 declare class LabelColorMap {
     readonly lookupTable: ReadonlyMap<number, Color>;
     readonly cycle: ReadonlyArray<Color>;
@@ -1478,6 +1578,7 @@ type LabelLayerProps = LayerOptions & {
     onPickValue?: (info: PointPickingResult) => void;
     outlineSelected?: boolean;
 };
+/** @group Layers */
 declare class LabelLayer extends Layer {
     readonly type = "LabelLayer";
     private readonly source_;
@@ -1528,6 +1629,7 @@ type UniformValues = {
     u_valueScale: number;
     u_zTexCoord: number;
 };
+/** @group Renderable Objects */
 declare class ImageRenderable extends RenderableObject {
     private channels_;
     zTexCoord: number;
@@ -1546,6 +1648,7 @@ type LabelImageRenderableProps = {
     outlineSelected?: boolean;
     selectedValue?: number | null;
 };
+/** @group Renderable Objects */
 declare class LabelImageRenderable extends RenderableObject {
     private outlineSelected_;
     private selectedValue_;
@@ -1573,6 +1676,7 @@ type PointProperties = {
     size: number;
     marker: Marker;
 };
+/** @group Renderable Objects */
 declare class Points extends RenderableObject {
     constructor(points: PointProperties[]);
     get type(): string;
@@ -1589,6 +1693,7 @@ type LineParameters = {
     color: ColorLike;
     width: number;
 };
+/** @group Renderable Objects */
 declare class ProjectedLine extends RenderableObject {
     private color_;
     private width_;
@@ -1604,6 +1709,7 @@ declare class ProjectedLine extends RenderableObject {
     };
 }
 
+/** @group Renderable Objects */
 declare class VolumeRenderable extends RenderableObject {
     voxelScale: vec3;
     private channels_;
@@ -1632,6 +1738,7 @@ type PerspectiveCameraOptions = {
     far?: number;
     position?: vec3;
 };
+/** @group Cameras & Controls */
 declare class PerspectiveCamera extends Camera {
     private fov_;
     private aspectRatio_;
@@ -1650,6 +1757,7 @@ type OrbitParams = {
     target?: vec3;
     dampingFactor?: number;
 };
+/** @group Cameras & Controls */
 declare class OrbitControls implements CameraControls {
     private readonly camera_;
     private readonly orbitVelocity_;
@@ -1875,5 +1983,12 @@ declare const Image: z.ZodObject<{
 }>;
 type Image = z.infer<typeof Image>;
 
-export { AxesLayer, Color, Idetik, ImageLayer, ImageRenderable, LabelColorMap, LabelImageRenderable, LabelLayer, Layer, Image as OmeZarrImage, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, Points, ProjectedLine, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
-export type { ChannelProps, ColorLike, LayerState, MemoryStats, Overlay, SliceCoordinates };
+/**
+ * Parsed OME-Zarr (OME-NGFF 0.4) image metadata.
+ *
+ * @group Data Loading
+ */
+type OmeZarrImage = Image;
+
+export { AxesLayer, Color, Idetik, ImageLayer, ImageRenderable, LabelColorMap, LabelImageRenderable, LabelLayer, Layer, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, Points, ProjectedLine, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
+export type { ChannelProps, ColorLike, LayerState, MemoryStats, OmeZarrImage, Overlay, SliceCoordinates };