@idetik/core 0.27.3 → 0.29.0

package/dist/index.d.ts

@@ -27,10 +27,13 @@ declare abstract class Texture extends Node {
     wrapT: TextureWrapMode;
     needsUpdate: boolean;
     readTexel?: (x: number, y: number, z: number) => Promise<number>;
+    protected data_: DataTextureTypedArray | null;
+    get data(): DataTextureTypedArray | null;
+    set data(data: DataTextureTypedArray);
+    releaseCpuData(): void;
     abstract get width(): number;
     abstract get height(): number;
-    abstract get data(): TexImageSource | ArrayBufferView | null;
-    abstract set data(data: DataTextureTypedArray);
+    get depth(): number;
     get type(): string;
 }
 
@@ -45,6 +48,7 @@ type ChunkViewState = {
 };
 type Chunk = {
     data?: ChunkData;
+    texture?: Texture;
     state: "unloaded" | "queued" | "loading" | "loaded";
     lod: number;
     shape: {
@@ -92,6 +96,7 @@ type SourceDimensionLod = {
     scale: number;
     translation: number;
 };
+/** @group Layer Configuration */
 type SliceCoordinates = {
     z?: number;
     c?: number[];
@@ -102,6 +107,7 @@ type ChunkSource = {
 };
 type ChunkLoader = {
     getSourceDimensionMap(): SourceDimensionMap;
+    getBytesPerElement(): number;
     loadChunkData(chunk: Chunk, signal: AbortSignal): Promise<void>;
 };
 
@@ -138,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 {
@@ -243,10 +253,15 @@ type QueueStats = {
     pending: number;
     running: number;
 };
-
 declare class ChunkManager {
     private readonly stores_;
     private readonly queue_;
+    private readonly uploadTexture_?;
+    private readonly disposeTexture_?;
+    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;
@@ -254,6 +269,10 @@ declare class ChunkManager {
     };
     addView(source: ChunkSource, policy: ImageSourcePolicy): ChunkStoreView;
     update(): void;
+    private enqueueWithinBudget;
+    private chunkBytes;
+    private uploadLoadedChunks;
+    private disposeChunkTexture;
 }
 
 declare class Box3 {
@@ -327,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;
@@ -367,6 +388,8 @@ declare abstract class RenderableObject extends Node {
     private programName_;
     private cullFaceMode_;
     setTexture(index: number, texture: Texture): void;
+    protected clearTextures(): void;
+    protected markStaleTexture(texture: Texture | undefined): void;
     popStaleTextures(): Texture[];
     get geometry(): Geometry;
     get wireframeGeometry(): WireframeGeometry;
@@ -437,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;
@@ -457,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_;
@@ -510,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;
@@ -517,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_;
@@ -576,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;
@@ -596,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_;
@@ -966,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>;
 }
 
@@ -1275,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 = {
@@ -1291,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;
@@ -1320,6 +1410,7 @@ declare class OmeZarrImageSource {
     static fromFileSystem(props: FileSystemOmeZarrImageSourceProps): Promise<OmeZarrImageSource>;
 }
 
+/** @group Layers */
 declare class AxesLayer extends Layer {
     readonly type = "AxesLayer";
     constructor(params: {
@@ -1329,6 +1420,7 @@ declare class AxesLayer extends Layer {
     update(): void;
 }
 
+/** @group Layer Configuration */
 type ChannelProps = {
     visible?: boolean;
     color?: ColorLike;
@@ -1349,6 +1441,7 @@ interface PointPickingResult {
     value: number;
 }
 
+/** @inline */
 type ImageLayerProps = LayerOptions & {
     source: ChunkSource;
     sliceCoords: SliceCoordinates;
@@ -1356,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_;
@@ -1412,6 +1519,7 @@ type VolumeLayerProps = {
     policy: ImageSourcePolicy;
     channelProps?: ChannelProps[];
 };
+/** @group Layers */
 declare class VolumeLayer extends Layer implements ChannelsEnabled {
     readonly type = "VolumeLayer";
     private readonly source_;
@@ -1455,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>;
@@ -1469,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_;
@@ -1519,6 +1629,7 @@ type UniformValues = {
     u_valueScale: number;
     u_zTexCoord: number;
 };
+/** @group Renderable Objects */
 declare class ImageRenderable extends RenderableObject {
     private channels_;
     zTexCoord: number;
@@ -1537,6 +1648,7 @@ type LabelImageRenderableProps = {
     outlineSelected?: boolean;
     selectedValue?: number | null;
 };
+/** @group Renderable Objects */
 declare class LabelImageRenderable extends RenderableObject {
     private outlineSelected_;
     private selectedValue_;
@@ -1564,6 +1676,7 @@ type PointProperties = {
     size: number;
     marker: Marker;
 };
+/** @group Renderable Objects */
 declare class Points extends RenderableObject {
     constructor(points: PointProperties[]);
     get type(): string;
@@ -1580,6 +1693,7 @@ type LineParameters = {
     color: ColorLike;
     width: number;
 };
+/** @group Renderable Objects */
 declare class ProjectedLine extends RenderableObject {
     private color_;
     private width_;
@@ -1595,17 +1709,19 @@ declare class ProjectedLine extends RenderableObject {
     };
 }
 
+/** @group Renderable Objects */
 declare class VolumeRenderable extends RenderableObject {
     voxelScale: vec3;
     private channels_;
-    private channelToTextureIndex_;
     private loadedChannels_;
+    private readonly channelToTextureIndex_;
     constructor();
     get type(): string;
     updateVolumeWithChunk(chunk: Chunk): void;
     private addChannelTexture;
     private updateChannelTexture;
     clearLoadedChannels(): void;
+    reset(): void;
     getUniforms(): Record<string, number[] | number>;
     /**
      * Get an available texture for a channel. If desiredChannelIndex is provided, it will try to return the texture for that channel index. If that texture is not available, or no desiredChannelIndex is passed, return the first available channel texture. This is used to determine which texture to use when updating channel properties, since channel properties can be updated even if the channel's texture hasn't been loaded yet. If no textures are available, it returns null, which signals that default contrast limits should be used when validating the channel properties.
@@ -1622,6 +1738,7 @@ type PerspectiveCameraOptions = {
     far?: number;
     position?: vec3;
 };
+/** @group Cameras & Controls */
 declare class PerspectiveCamera extends Camera {
     private fov_;
     private aspectRatio_;
@@ -1640,6 +1757,7 @@ type OrbitParams = {
     target?: vec3;
     dampingFactor?: number;
 };
+/** @group Cameras & Controls */
 declare class OrbitControls implements CameraControls {
     private readonly camera_;
     private readonly orbitVelocity_;
@@ -1865,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 };