@fideus-labs/fidnii 0.1.0

package/dist/events.d.ts

@@ -0,0 +1,122 @@
+import type { SLICE_TYPE } from "@niivue/niivue";
+import type { ClipPlanes } from "./types.js";
+/**
+ * Identifies what triggered a volume population.
+ * Extensible for future triggers (pan, zoom, etc.)
+ */
+export type PopulateTrigger = "initial" | "clipPlanesChanged" | "sliceChanged" | "viewportChanged";
+/**
+ * Type-safe event map for OMEZarrNVImage events.
+ * Maps event names to their detail types.
+ *
+ * Uses the browser-native EventTarget API pattern, following the same
+ * conventions as NiiVue's event system (see niivue/niivue#1530).
+ *
+ * @example
+ * ```typescript
+ * // Type-safe event listening
+ * image.addEventListener('resolutionChange', (event) => {
+ *   console.log('Resolution changed:', event.detail.currentLevel);
+ * });
+ *
+ * // One-time listener
+ * image.addEventListener('loadingComplete', (event) => {
+ *   console.log('Loaded level:', event.detail.levelIndex);
+ * }, { once: true });
+ *
+ * // Using AbortController to remove multiple listeners
+ * const controller = new AbortController();
+ * image.addEventListener('loadingStart', handler1, { signal: controller.signal });
+ * image.addEventListener('loadingComplete', handler2, { signal: controller.signal });
+ * controller.abort(); // removes both listeners
+ * ```
+ */
+export interface OMEZarrNVImageEventMap {
+    /** Fired when loading starts for a resolution level */
+    loadingStart: {
+        levelIndex: number;
+        trigger: PopulateTrigger;
+    };
+    /** Fired when loading completes for a resolution level */
+    loadingComplete: {
+        levelIndex: number;
+        trigger: PopulateTrigger;
+    };
+    /**
+     * Fired when resolution level changes.
+     * This happens during progressive loading or when clip planes
+     * cause a resolution change.
+     */
+    resolutionChange: {
+        currentLevel: number;
+        targetLevel: number;
+        previousLevel: number;
+        trigger: PopulateTrigger;
+    };
+    /**
+     * Fired when clip planes are updated (after debounce).
+     * This is emitted after the debounce delay, not on every slider movement.
+     */
+    clipPlanesChange: {
+        clipPlanes: ClipPlanes;
+    };
+    /**
+     * Fired when populateVolume() completes and no more requests are queued.
+     * This is the final event after all loading is done.
+     */
+    populateComplete: {
+        currentLevel: number;
+        targetLevel: number;
+        trigger: PopulateTrigger;
+    };
+    /**
+     * Fired when a queued load request is replaced by a newer one.
+     * This only fires when a pending request is overwritten, not when
+     * the first request is queued.
+     */
+    loadingSkipped: {
+        reason: "queued-replaced";
+        trigger: PopulateTrigger;
+    };
+    /**
+     * Fired when a slab (2D slice buffer) finishes loading.
+     * This event is specific to slab-based loading for 2D slice views.
+     */
+    slabLoadingComplete: {
+        sliceType: SLICE_TYPE;
+        levelIndex: number;
+        slabStart: number;
+        slabEnd: number;
+        trigger: PopulateTrigger;
+    };
+    /**
+     * Fired when a slab starts loading.
+     */
+    slabLoadingStart: {
+        sliceType: SLICE_TYPE;
+        levelIndex: number;
+        trigger: PopulateTrigger;
+    };
+}
+/**
+ * Type-safe event class for OMEZarrNVImage events.
+ * Extends CustomEvent with typed detail property.
+ */
+export declare class OMEZarrNVImageEvent<K extends keyof OMEZarrNVImageEventMap> extends CustomEvent<OMEZarrNVImageEventMap[K]> {
+    constructor(type: K, detail: OMEZarrNVImageEventMap[K]);
+}
+/**
+ * Type-safe event listener for OMEZarrNVImage events.
+ * Listeners can be synchronous or asynchronous.
+ */
+export type OMEZarrNVImageEventListener<K extends keyof OMEZarrNVImageEventMap> = (event: OMEZarrNVImageEvent<K>) => void | Promise<void>;
+/**
+ * Options for addEventListener/removeEventListener.
+ * Supports all standard EventTarget options including:
+ * - capture: boolean - Use capture phase
+ * - once: boolean - Remove listener after first invocation
+ * - passive: boolean - Listener will never call preventDefault()
+ * - signal: AbortSignal - Remove listener when signal is aborted
+ */
+export type OMEZarrNVImageEventListenerOptions = boolean | AddEventListenerOptions;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,mBAAmB,GACnB,cAAc,GACd,iBAAiB,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,sBAAsB;IACrC,uDAAuD;IACvD,YAAY,EAAE;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;IAEF,0DAA0D;IAC1D,eAAe,EAAE;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;IAEF;;;;OAIG;IACH,gBAAgB,EAAE;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;IAEF;;;OAGG;IACH,gBAAgB,EAAE;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC;IAE7C;;;OAGG;IACH,gBAAgB,EAAE;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;IAEF;;;;OAIG;IACH,cAAc,EAAE;QACd,MAAM,EAAE,iBAAiB,CAAC;QAC1B,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;IAEF;;;OAGG;IACH,mBAAmB,EAAE;QACnB,SAAS,EAAE,UAAU,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;IAEF;;OAEG;IACH,gBAAgB,EAAE;QAChB,SAAS,EAAE,UAAU,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,eAAe,CAAC;KAC1B,CAAC;CACH;AAED;;;GAGG;AACH,qBAAa,mBAAmB,CAC9B,CAAC,SAAS,MAAM,sBAAsB,CACtC,SAAQ,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;gBAClC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAGvD;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,CACrC,CAAC,SAAS,MAAM,sBAAsB,IACpC,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,MAAM,kCAAkC,GAC1C,OAAO,GACP,uBAAuB,CAAC"}

package/dist/events.js

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+/**
+ * Type-safe event class for OMEZarrNVImage events.
+ * Extends CustomEvent with typed detail property.
+ */
+export class OMEZarrNVImageEvent extends CustomEvent {
+    constructor(type, detail) {
+        super(type, { detail });
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,+BAA+B;AAkH/B;;;GAGG;AACH,MAAM,OAAO,mBAEX,SAAQ,WAAsC;IAC9C,YAAY,IAAO,EAAE,MAAiC;QACpD,KAAK,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fideus-labs/fidnii
+ *
+ * Render OME-Zarr images in NiiVue with progressive multi-resolution loading.
+ *
+ * @example
+ * ```typescript
+ * import { Niivue } from '@niivue/niivue';
+ * import { fromNgffZarr } from '@fideus-labs/ngff-zarr';
+ * import { OMEZarrNVImage } from '@fideus-labs/fidnii';
+ *
+ * const nv = new Niivue();
+ * await nv.attachToCanvas(document.getElementById('canvas'));
+ *
+ * const multiscales = await fromNgffZarr('/path/to/data.ome.zarr');
+ *
+ * // Image is automatically added to NiiVue and loads progressively
+ * const image = await OMEZarrNVImage.create({ multiscales, niivue: nv });
+ *
+ * // Listen for loading complete if needed
+ * image.addEventListener('populateComplete', () => console.log('Loaded!'));
+ *
+ * // For manual control, use autoLoad: false
+ * // const image = await OMEZarrNVImage.create({
+ * //   multiscales,
+ * //   niivue: nv,
+ * //   autoLoad: false,
+ * // });
+ * // nv.addVolume(image);
+ * // await image.populateVolume();
+ * ```
+ */
+export { OMEZarrNVImage } from "./OMEZarrNVImage.js";
+export type { AttachedNiivueState, ChunkAlignedRegion, ChunkCache, ClipPlane, ClipPlanes, OMEZarrNVImageOptions, PixelRegion, RegionFetchResult, ResolutionSelection, SlabBufferState, SlabSliceType, TypedArray, VolumeBounds, ZarrDtype, } from "./types.js";
+export { SLICE_TYPE } from "./types.js";
+export { alignToChunks, azimuthElevationToNormal, calculateNiivueDepth, clipPlanesToBoundingBox, clipPlanesToNiivue, clipPlanesToPixelRegion, clipPlaneToNiivue, createAxisAlignedClipPlane, createClipPlane, createDefaultClipPlanes, getVolumeBoundsFromMultiscales, isInsideClipPlanes, MAX_CLIP_PLANES, normalizeVector, normalToAzimuthElevation, pointToPlaneDistance, validateClipPlanes, } from "./ClipPlanes.js";
+export { alignRegionToChunks, calculateUpsampleFactor, getChunkShape, getFullVolumeDimensions, getMiddleResolutionIndex, getVolumeShape, select2DResolution, selectResolution, } from "./ResolutionSelector.js";
+export type { OrthogonalAxis } from "./ResolutionSelector.js";
+export { BufferManager } from "./BufferManager.js";
+export { RegionCoalescer } from "./RegionCoalescer.js";
+export { ceilPixelCoord, clampPixelCoord, floorPixelCoord, normalizedToWorld, pixelToWorld, pixelToWorldAffine, roundPixelCoord, worldToNormalized, worldToPixel, worldToPixelAffine, } from "./utils/coordinates.js";
+export { affineToNiftiSrows, calculateWorldBounds, createAffineFromNgffImage, createAffineFromOMEZarr, getPixelDimensions, updateAffineForRegion, } from "./utils/affine.js";
+export { getBytesPerPixel, getNiftiDataType, getTypedArrayConstructor, NiftiDataType, parseZarritaDtype, } from "./types.js";
+export { terminateWorkerPool } from "@fideus-labs/ngff-zarr/browser";
+export { boundsApproxEqual, computeViewportBounds2D, computeViewportBounds3D, intersectBounds, } from "./ViewportBounds.js";
+export { OMEZarrNVImageEvent } from "./events.js";
+export type { OMEZarrNVImageEventListener, OMEZarrNVImageEventListenerOptions, OMEZarrNVImageEventMap, PopulateTrigger, } from "./events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,EACf,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EACL,cAAc,EACd,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,2BAA2B,EAC3B,kCAAkC,EAClC,sBAAsB,EACtB,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+/**
+ * @fideus-labs/fidnii
+ *
+ * Render OME-Zarr images in NiiVue with progressive multi-resolution loading.
+ *
+ * @example
+ * ```typescript
+ * import { Niivue } from '@niivue/niivue';
+ * import { fromNgffZarr } from '@fideus-labs/ngff-zarr';
+ * import { OMEZarrNVImage } from '@fideus-labs/fidnii';
+ *
+ * const nv = new Niivue();
+ * await nv.attachToCanvas(document.getElementById('canvas'));
+ *
+ * const multiscales = await fromNgffZarr('/path/to/data.ome.zarr');
+ *
+ * // Image is automatically added to NiiVue and loads progressively
+ * const image = await OMEZarrNVImage.create({ multiscales, niivue: nv });
+ *
+ * // Listen for loading complete if needed
+ * image.addEventListener('populateComplete', () => console.log('Loaded!'));
+ *
+ * // For manual control, use autoLoad: false
+ * // const image = await OMEZarrNVImage.create({
+ * //   multiscales,
+ * //   niivue: nv,
+ * //   autoLoad: false,
+ * // });
+ * // nv.addVolume(image);
+ * // await image.populateVolume();
+ * ```
+ */
+// Main class
+export { OMEZarrNVImage } from "./OMEZarrNVImage.js";
+// Re-export SLICE_TYPE from types (which re-exports from niivue)
+export { SLICE_TYPE } from "./types.js";
+// Clip planes utilities
+export { alignToChunks, azimuthElevationToNormal, calculateNiivueDepth, clipPlanesToBoundingBox, clipPlanesToNiivue, clipPlanesToPixelRegion, clipPlaneToNiivue, createAxisAlignedClipPlane, createClipPlane, createDefaultClipPlanes, getVolumeBoundsFromMultiscales, isInsideClipPlanes, MAX_CLIP_PLANES, normalizeVector, normalToAzimuthElevation, pointToPlaneDistance, validateClipPlanes, } from "./ClipPlanes.js";
+// Resolution selector utilities
+export { alignRegionToChunks, calculateUpsampleFactor, getChunkShape, getFullVolumeDimensions, getMiddleResolutionIndex, getVolumeShape, select2DResolution, selectResolution, } from "./ResolutionSelector.js";
+// Buffer manager
+export { BufferManager } from "./BufferManager.js";
+// Region coalescer
+export { RegionCoalescer } from "./RegionCoalescer.js";
+// Coordinate utilities
+export { ceilPixelCoord, clampPixelCoord, floorPixelCoord, normalizedToWorld, pixelToWorld, pixelToWorldAffine, roundPixelCoord, worldToNormalized, worldToPixel, worldToPixelAffine, } from "./utils/coordinates.js";
+// Affine utilities
+export { affineToNiftiSrows, calculateWorldBounds, createAffineFromNgffImage, createAffineFromOMEZarr, getPixelDimensions, updateAffineForRegion, } from "./utils/affine.js";
+// Type utilities
+export { getBytesPerPixel, getNiftiDataType, getTypedArrayConstructor, NiftiDataType, parseZarritaDtype, } from "./types.js";
+// Worker pool lifecycle (re-exported from ngff-zarr)
+export { terminateWorkerPool } from "@fideus-labs/ngff-zarr/browser";
+// Viewport bounds utilities
+export { boundsApproxEqual, computeViewportBounds2D, computeViewportBounds3D, intersectBounds, } from "./ViewportBounds.js";
+// Event system (browser-native EventTarget API)
+export { OMEZarrNVImageEvent } from "./events.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,+BAA+B;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,aAAa;AACb,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAoBrD,iEAAiE;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,wBAAwB;AACxB,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,0BAA0B,EAC1B,eAAe,EACf,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,gCAAgC;AAChC,OAAO,EACL,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAIjC,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,mBAAmB;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,uBAAuB;AACvB,OAAO,EACL,cAAc,EACd,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAEhC,mBAAmB;AACnB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,iBAAiB;AACjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,qDAAqD;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,4BAA4B;AAC5B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,gDAAgD;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,273 @@
+import type { Multiscales } from "@fideus-labs/ngff-zarr";
+import type { Niivue, NVImage } from "@niivue/niivue";
+import { SLICE_TYPE } from "@niivue/niivue";
+import type { BufferManager } from "./BufferManager.js";
+import type { PopulateTrigger } from "./events.js";
+/**
+ * A single clip plane defined by a point and normal vector.
+ * The plane equation is: normal · (P - point) = 0
+ * Points on the positive side of the normal are kept (visible).
+ */
+export interface ClipPlane {
+    /** A point on the plane (center of volume projected to plane) [x, y, z] in world coordinates */
+    point: [number, number, number];
+    /** Unit normal vector pointing toward visible region [x, y, z] */
+    normal: [number, number, number];
+}
+/**
+ * Collection of clip planes that define the visible region.
+ * Each plane clips away the half-space on the negative side of its normal.
+ * Maximum 6 planes (NiiVue limit). Empty array = full volume visible.
+ */
+export type ClipPlanes = ClipPlane[];
+/**
+ * Volume bounds in world space.
+ */
+export interface VolumeBounds {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+/**
+ * A pixel region in array indices.
+ * Coordinates are in [z, y, x] order to match OME-Zarr conventions.
+ */
+export interface PixelRegion {
+    /** Start indices [z, y, x] (inclusive) */
+    start: [number, number, number];
+    /** End indices [z, y, x] (exclusive) */
+    end: [number, number, number];
+}
+/**
+ * A pixel region that has been aligned to chunk boundaries.
+ */
+export interface ChunkAlignedRegion extends PixelRegion {
+    /** Chunk-aligned start indices [z, y, x] */
+    chunkAlignedStart: [number, number, number];
+    /** Chunk-aligned end indices [z, y, x] */
+    chunkAlignedEnd: [number, number, number];
+    /** True if the original region didn't align with chunk boundaries */
+    needsClipping: boolean;
+}
+/**
+ * Result of selecting an appropriate resolution level.
+ */
+export interface ResolutionSelection {
+    /** Index into multiscales.images array */
+    levelIndex: number;
+    /** Dimensions of the buffer [z, y, x] */
+    dimensions: [number, number, number];
+    /** Total pixel count */
+    pixelCount: number;
+}
+/**
+ * Interface for a decoded-chunk cache, compatible with `Map`.
+ *
+ * Caches decoded chunks keyed by a string combining the store instance,
+ * array path, and chunk coordinates. This avoids redundant decompression
+ * when accessing overlapping selections or making repeated calls to the
+ * same data.
+ *
+ * Any object with `get(key)` and `set(key, value)` works — a plain `Map`
+ * is the simplest option. For bounded memory use an LRU cache such as
+ * `lru-cache`.
+ *
+ * @example
+ * ```ts
+ * // Use a plain Map (unbounded)
+ * const cache = new Map()
+ *
+ * // Use lru-cache (bounded)
+ * import { LRUCache } from 'lru-cache'
+ * const cache = new LRUCache({ max: 200 })
+ * ```
+ */
+export interface ChunkCache {
+    /** Look up a cached decoded chunk by key. */
+    get(key: string): unknown | undefined;
+    /** Store a decoded chunk under the given key. */
+    set(key: string, value: unknown): void;
+}
+/**
+ * Options for creating an OMEZarrNVImage.
+ */
+export interface OMEZarrNVImageOptions {
+    /** The OME-Zarr multiscales data */
+    multiscales: Multiscales;
+    /** Reference to the NiiVue instance for rendering updates */
+    niivue: Niivue;
+    /** Maximum number of pixels to use (default: 50,000,000) */
+    maxPixels?: number;
+    /** Debounce delay for clip plane data refetch in milliseconds (default: 300) */
+    clipPlaneDebounceMs?: number;
+    /**
+     * Automatically add to NiiVue and start progressive loading (default: true).
+     * Set to false to manually control when populateVolume() is called.
+     * Listen to 'populateComplete' event to know when loading finishes.
+     */
+    autoLoad?: boolean;
+    /**
+     * Maximum 3D render zoom level for scroll-wheel zoom (default: 10.0).
+     * NiiVue's built-in 3D zoom is hardcoded to [0.5, 2.0]. This option
+     * overrides the scroll-wheel zoom handler to allow zooming beyond that limit.
+     */
+    max3DZoom?: number;
+    /**
+     * Minimum 3D render zoom level for scroll-wheel zoom (default: 0.3).
+     * @see max3DZoom
+     */
+    min3DZoom?: number;
+    /**
+     * Enable viewport-aware resolution selection (default: true).
+     * When enabled, zoom/pan interactions constrain the fetch region to the
+     * visible viewport, allowing higher resolution within the same maxPixels budget.
+     */
+    viewportAware?: boolean;
+    /**
+     * Maximum number of decoded-chunk cache entries (default: 200).
+     *
+     * Fidnii creates an LRU cache that avoids redundant chunk decompression
+     * on repeated or overlapping reads (e.g. clip plane adjustments, viewport
+     * panning, progressive resolution loading).
+     *
+     * Set to `0` to disable caching entirely.
+     */
+    maxCacheEntries?: number;
+    /**
+     * Optional pre-built decoded-chunk cache. When provided, overrides the
+     * internal LRU cache created from `maxCacheEntries`.
+     *
+     * Any object with `get(key)` / `set(key, value)` works — a plain `Map`
+     * or any LRU cache implementing the same interface.
+     *
+     * @see {@link ChunkCache}
+     */
+    cache?: ChunkCache;
+}
+/**
+ * Result of fetching a region from the zarr store.
+ */
+export interface RegionFetchResult {
+    /** The pixel data as a typed array */
+    data: TypedArray;
+    /** Shape of the fetched data [z, y, x] */
+    shape: number[];
+    /** Stride of the fetched data */
+    stride: number[];
+}
+/**
+ * Supported zarr data types.
+ */
+export type ZarrDtype = "uint8" | "uint16" | "uint32" | "int8" | "int16" | "int32" | "float32" | "float64";
+/**
+ * Union of all typed array types we support.
+ */
+export type TypedArray = Uint8Array | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array;
+/**
+ * Typed arrays supported by NiiVue.
+ * NiiVue only supports a subset of typed arrays.
+ */
+export type NiiVueTypedArray = Uint8Array | Uint16Array | Int16Array | Float32Array | Float64Array;
+export { SLICE_TYPE };
+/**
+ * The 2D slice types that use slab-based loading.
+ * These are the Niivue slice types that show a single 2D plane.
+ */
+export type SlabSliceType = typeof SLICE_TYPE.AXIAL | typeof SLICE_TYPE.CORONAL | typeof SLICE_TYPE.SAGITTAL;
+/**
+ * State for a per-slice-type slab buffer.
+ *
+ * Each 2D slice view (axial, coronal, sagittal) gets its own NVImage buffer
+ * loaded with a slab (one chunk thick in the orthogonal direction) at the
+ * current slice position.
+ */
+export interface SlabBufferState {
+    /** The NVImage instance for this slab */
+    nvImage: NVImage;
+    /** Buffer manager for this slab's pixel data */
+    bufferManager: BufferManager;
+    /** Current resolution level index for this slab */
+    levelIndex: number;
+    /** Target resolution level index for this slab */
+    targetLevelIndex: number;
+    /** Start index of the currently loaded slab in the orthogonal axis (pixel coords at current level) */
+    slabStart: number;
+    /** End index of the currently loaded slab in the orthogonal axis (pixel coords at current level) */
+    slabEnd: number;
+    /** Whether this slab is currently loading */
+    isLoading: boolean;
+    /** Data type of the slab */
+    dtype: ZarrDtype;
+    /**
+     * The affine normalization scale applied to the slab NVImage header.
+     * NiiVue mm values = world * normalizationScale.
+     * This is 1/maxVoxelSize where maxVoxelSize = max(sx, sy, sz).
+     * Used to convert NiiVue 2D FOV coordinates back to physical world coords.
+     */
+    normalizationScale: number;
+    /**
+     * Pending reload request queued while this slab was loading.
+     * Latest-wins semantics: only the most recent request is kept.
+     * Auto-drained when the current load completes.
+     */
+    pendingReload: {
+        worldCoord: [number, number, number];
+        trigger: PopulateTrigger;
+    } | null;
+}
+/**
+ * State for a Niivue instance attached to an OMEZarrNVImage.
+ */
+export interface AttachedNiivueState {
+    /** The Niivue instance */
+    nv: Niivue;
+    /** The current slice type of this NV instance */
+    currentSliceType: SLICE_TYPE;
+    /** Previous onLocationChange callback (to chain) */
+    previousOnLocationChange?: (location: unknown) => void;
+    /** Previous onOptsChange callback (to chain) */
+    previousOnOptsChange?: (propertyName: string, newValue: unknown, oldValue: unknown) => void;
+    /** Previous onMouseUp callback (to chain, for viewport-aware mode) */
+    previousOnMouseUp?: (data: unknown) => void;
+    /** Previous onZoom3DChange callback (to chain, for viewport-aware mode) */
+    previousOnZoom3DChange?: (zoom: number) => void;
+    /** AbortController for viewport-aware event listeners (wheel, etc.) */
+    viewportAbortController?: AbortController;
+    /** AbortController for the 3D zoom override wheel listener */
+    zoomOverrideAbortController?: AbortController;
+}
+/**
+ * Typed array constructor types.
+ */
+export type TypedArrayConstructor = Uint8ArrayConstructor | Uint16ArrayConstructor | Uint32ArrayConstructor | Int8ArrayConstructor | Int16ArrayConstructor | Int32ArrayConstructor | Float32ArrayConstructor | Float64ArrayConstructor;
+/**
+ * NIfTI data type codes.
+ */
+export declare const NiftiDataType: {
+    readonly UINT8: 2;
+    readonly INT16: 4;
+    readonly INT32: 8;
+    readonly FLOAT32: 16;
+    readonly FLOAT64: 64;
+    readonly INT8: 256;
+    readonly UINT16: 512;
+    readonly UINT32: 768;
+};
+export type NiftiDataTypeCode = (typeof NiftiDataType)[keyof typeof NiftiDataType];
+/**
+ * Map zarr dtype to typed array constructor.
+ */
+export declare function getTypedArrayConstructor(dtype: ZarrDtype): TypedArrayConstructor;
+/**
+ * Get bytes per pixel for a dtype.
+ */
+export declare function getBytesPerPixel(dtype: ZarrDtype): number;
+/**
+ * Map zarr dtype to NIfTI data type code.
+ */
+export declare function getNiftiDataType(dtype: ZarrDtype): NiftiDataTypeCode;
+/**
+ * Parse a zarrita dtype string to our ZarrDtype.
+ * Handles formats like "|u1", "<u2", "<f4", etc.
+ */
+export declare function parseZarritaDtype(dtype: string): ZarrDtype;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+import { SLICE_TYPE } from "@niivue/niivue";
+// Re-export SLICE_TYPE for convenience
+export { SLICE_TYPE };
+/**
+ * NIfTI data type codes.
+ */
+export const NiftiDataType = {
+    UINT8: 2,
+    INT16: 4,
+    INT32: 8,
+    FLOAT32: 16,
+    FLOAT64: 64,
+    INT8: 256,
+    UINT16: 512,
+    UINT32: 768,
+};
+/**
+ * Map zarr dtype to typed array constructor.
+ */
+export function getTypedArrayConstructor(dtype) {
+    switch (dtype) {
+        case "uint8":
+            return Uint8Array;
+        case "uint16":
+            return Uint16Array;
+        case "uint32":
+            return Uint32Array;
+        case "int8":
+            return Int8Array;
+        case "int16":
+            return Int16Array;
+        case "int32":
+            return Int32Array;
+        case "float32":
+            return Float32Array;
+        case "float64":
+            return Float64Array;
+        default:
+            throw new Error(`Unsupported dtype: ${dtype}`);
+    }
+}
+/**
+ * Get bytes per pixel for a dtype.
+ */
+export function getBytesPerPixel(dtype) {
+    switch (dtype) {
+        case "uint8":
+        case "int8":
+            return 1;
+        case "uint16":
+        case "int16":
+            return 2;
+        case "uint32":
+        case "int32":
+        case "float32":
+            return 4;
+        case "float64":
+            return 8;
+        default:
+            throw new Error(`Unsupported dtype: ${dtype}`);
+    }
+}
+/**
+ * Map zarr dtype to NIfTI data type code.
+ */
+export function getNiftiDataType(dtype) {
+    switch (dtype) {
+        case "uint8":
+            return NiftiDataType.UINT8;
+        case "uint16":
+            return NiftiDataType.UINT16;
+        case "uint32":
+            return NiftiDataType.UINT32;
+        case "int8":
+            return NiftiDataType.INT8;
+        case "int16":
+            return NiftiDataType.INT16;
+        case "int32":
+            return NiftiDataType.INT32;
+        case "float32":
+            return NiftiDataType.FLOAT32;
+        case "float64":
+            return NiftiDataType.FLOAT64;
+        default:
+            throw new Error(`Unsupported dtype: ${dtype}`);
+    }
+}
+/**
+ * Parse a zarrita dtype string to our ZarrDtype.
+ * Handles formats like "|u1", "<u2", "<f4", etc.
+ */
+export function parseZarritaDtype(dtype) {
+    // Remove endianness prefix if present
+    const normalized = dtype.replace(/^[|<>]/, "");
+    switch (normalized) {
+        case "u1":
+        case "uint8":
+            return "uint8";
+        case "u2":
+        case "uint16":
+            return "uint16";
+        case "u4":
+        case "uint32":
+            return "uint32";
+        case "i1":
+        case "int8":
+            return "int8";
+        case "i2":
+        case "int16":
+            return "int16";
+        case "i4":
+        case "int32":
+            return "int32";
+        case "f4":
+        case "float32":
+            return "float32";
+        case "f8":
+        case "float64":
+            return "float64";
+        default:
+            throw new Error(`Unsupported zarrita dtype: ${dtype}`);
+    }
+}
+//# sourceMappingURL=types.js.map