@fideus-labs/fidnii 0.1.0

package/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026-present Fideus Labs LLC <info@fideus.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @fideus-labs/fidnii
+
+Render OME-Zarr images in NiiVue with progressive multi-resolution loading.
+
+## Features
+
+- **Progressive loading** - Quick preview from lowest resolution, then target
+  resolution
+- **Automatic resolution selection** - Picks optimal resolution based on pixel
+  budget
+- **Clip planes** - Up to 6 arbitrary clip planes for cropping/visualization
+- **Dynamic buffer sizing** - Matches fetched data exactly (no upsampling)
+- **Chunk caching** - LRU decoded-chunk cache avoids redundant decompression
+- **Request coalescing** - Efficient chunk fetching
+- **Event system** - Browser-native EventTarget API for loading states
+
+## Installation
+
+```bash
+npm install @fideus-labs/fidnii @fideus-labs/ngff-zarr @niivue/niivue
+```
+
+## Quick Start
+
+```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"));
+nv.setSliceType(nv.sliceTypeRender);
+
+const multiscales = await fromNgffZarr("/path/to/data.ome.zarr");
+
+// Image is automatically added to NiiVue and loads progressively
+await OMEZarrNVImage.create({ multiscales, niivue: nv });
+```
+
+## Options
+
+| Option                | Type          | Default      | Description                                     |
+| --------------------- | ------------- | ------------ | ----------------------------------------------- |
+| `multiscales`         | `Multiscales` | required     | OME-Zarr multiscales data from `fromNgffZarr()` |
+| `niivue`              | `Niivue`      | required     | NiiVue instance                                 |
+| `maxPixels`           | `number`      | `50_000_000` | Maximum pixels to load (controls resolution)    |
+| `autoLoad`            | `boolean`     | `true`       | Auto-add to NiiVue and start loading            |
+| `clipPlaneDebounceMs` | `number`      | `300`        | Debounce delay for clip plane updates           |
+| `maxCacheEntries`     | `number`      | `200`        | Max decoded-chunk cache entries (0 to disable)  |
+| `cache`               | `ChunkCache`  | —            | Pre-built cache (overrides `maxCacheEntries`)   |
+
+## Events
+
+Listen to loading events using the browser-native EventTarget API:
+
+```typescript
+const image = await OMEZarrNVImage.create({ multiscales, niivue: nv });
+
+image.addEventListener("loadingStart", (e) => {
+  console.log(`Loading level ${e.detail.levelIndex}...`);
+});
+
+image.addEventListener("populateComplete", (e) => {
+  console.log(`Loaded level ${e.detail.currentLevel}`);
+});
+```
+
+### Available Events
+
+| Event              | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| `loadingStart`     | Fired when loading starts for a resolution level    |
+| `loadingComplete`  | Fired when loading completes for a resolution level |
+| `resolutionChange` | Fired when resolution level changes                 |
+| `populateComplete` | Fired when all loading is done                      |
+| `clipPlanesChange` | Fired when clip planes are updated (after debounce) |
+
+## Advanced Usage
+
+For manual control over when loading starts, use `autoLoad: false`:
+
+```typescript
+const image = await OMEZarrNVImage.create({
+  multiscales,
+  niivue: nv,
+  autoLoad: false,
+});
+
+// Set up event listeners before loading starts
+image.addEventListener("populateComplete", () => {
+  console.log("Loading complete!");
+});
+
+// Manually add to NiiVue and start loading
+nv.addVolume(image);
+await image.populateVolume();
+```
+
+## Clip Planes
+
+Clip planes define visible regions of the volume. Up to 6 clip planes can be
+active.
+
+```typescript
+import { createAxisAlignedClipPlane } from "@fideus-labs/fidnii";
+
+const image = await OMEZarrNVImage.create({ multiscales, niivue: nv });
+
+// Wait for initial load
+image.addEventListener("populateComplete", () => {
+  const bounds = image.getVolumeBounds();
+
+  // Clip at X = midpoint, keeping +X side visible
+  const midX = (bounds.min[0] + bounds.max[0]) / 2;
+  const clipPlane = createAxisAlignedClipPlane("x", midX, "positive", bounds);
+
+  image.setClipPlanes([clipPlane]);
+}, { once: true });
+```
+
+## Chunk Caching
+
+Fidnii ships with an LRU decoded-chunk cache that avoids redundant
+decompression when the same Zarr chunk is read more than once. This happens
+frequently with overlapping clip-plane selections, repeated `populateVolume`
+calls, and progressive loading where 2D slabs and 3D volumes share chunks.
+
+Caching is **enabled by default** with a 200-entry limit. No extra code is
+needed:
+
+```typescript
+// Default: 200-entry LRU cache created automatically
+const image = await OMEZarrNVImage.create({ multiscales, niivue: nv });
+```
+
+### Custom cache size
+
+```typescript
+const image = await OMEZarrNVImage.create({
+  multiscales,
+  niivue: nv,
+  maxCacheEntries: 500,
+});
+```
+
+### Disabling caching
+
+```typescript
+const image = await OMEZarrNVImage.create({
+  multiscales,
+  niivue: nv,
+  maxCacheEntries: 0,
+});
+```
+
+### Bring-your-own cache
+
+Any object that satisfies the `ChunkCache` interface (`get` / `set` with
+`string` keys and `ArrayBuffer` values) can be passed directly:
+
+```typescript
+import type { ChunkCache } from "@fideus-labs/fidnii";
+
+const myCache: ChunkCache = {
+  get(key: string) { /* ... */ },
+  set(key: string, value: ArrayBuffer) { /* ... */ },
+};
+
+const image = await OMEZarrNVImage.create({
+  multiscales,
+  niivue: nv,
+  cache: myCache,
+});
+```
+
+When `cache` is provided it takes precedence over `maxCacheEntries`.
+
+## License
+
+MIT

package/dist/BufferManager.d.ts

@@ -0,0 +1,86 @@
+import type { TypedArray, ZarrDtype } from "./types.js";
+/**
+ * Manages a dynamically-sized pixel buffer for volume data.
+ *
+ * The buffer is resized to match the fetched data dimensions exactly.
+ * Memory is reused when possible to avoid unnecessary allocations.
+ *
+ * Memory reuse strategy:
+ * - Reuse buffer if newSize <= currentCapacity
+ * - Reallocate if newSize > currentCapacity OR newSize < 25% of currentCapacity
+ */
+export declare class BufferManager {
+    private buffer;
+    private currentDimensions;
+    private readonly maxPixels;
+    private readonly TypedArrayCtor;
+    private readonly bytesPerPixel;
+    private readonly dtype;
+    /**
+     * Create a new BufferManager.
+     *
+     * @param maxPixels - Maximum number of pixels allowed (budget)
+     * @param dtype - Data type for the buffer
+     */
+    constructor(maxPixels: number, dtype: ZarrDtype);
+    /**
+     * Resize the buffer to fit the given dimensions.
+     *
+     * Reuses existing buffer if large enough, otherwise allocates new buffer.
+     * Will also reallocate if the buffer is significantly oversized (< 25% utilization).
+     *
+     * If dimensions exceed maxPixels, a warning is logged but the buffer is still
+     * allocated. This handles the case where even the lowest resolution exceeds the
+     * pixel budget - we still want to load something rather than failing.
+     *
+     * @param dimensions - New dimensions [z, y, x]
+     * @returns TypedArray view over the (possibly new) buffer
+     */
+    resize(dimensions: [number, number, number]): TypedArray;
+    /**
+     * Get the underlying ArrayBuffer.
+     */
+    getBuffer(): ArrayBuffer;
+    /**
+     * Get a typed array view over the current buffer region.
+     *
+     * The view is sized to match currentDimensions, not the full buffer capacity.
+     */
+    getTypedArray(): TypedArray;
+    /**
+     * Get the current buffer dimensions [z, y, x].
+     */
+    getDimensions(): [number, number, number];
+    /**
+     * Get the total number of pixels in the current buffer region.
+     */
+    getPixelCount(): number;
+    /**
+     * Get the buffer capacity in pixels.
+     */
+    getCapacity(): number;
+    /**
+     * Get the bytes per pixel.
+     */
+    getBytesPerPixel(): number;
+    /**
+     * Get the data type.
+     */
+    getDtype(): ZarrDtype;
+    /**
+     * Get the maximum pixels budget.
+     */
+    getMaxPixels(): number;
+    /**
+     * Clear the current buffer region to zeros.
+     */
+    clear(): void;
+    /**
+     * Check if the buffer can accommodate the given dimensions without reallocation.
+     *
+     * @param dimensions - Dimensions to check [z, y, x]
+     * @returns True if current buffer can fit the dimensions
+     */
+    canAccommodate(dimensions: [number, number, number]): boolean;
+}
+//# sourceMappingURL=BufferManager.d.ts.map

package/dist/BufferManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BufferManager.d.ts","sourceRoot":"","sources":["../src/BufferManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAC;AAG/E;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAElC;;;;;OAKG;gBACS,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS;IAW/C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,UAAU;IA8BxD;;OAEG;IACH,SAAS,IAAI,WAAW;IAIxB;;;;OAIG;IACH,aAAa,IAAI,UAAU;IAO3B;;OAEG;IACH,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;IAIzC;;OAEG;IACH,aAAa,IAAI,MAAM;IAQvB;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,QAAQ,IAAI,SAAS;IAIrB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;;;;OAKG;IACH,cAAc,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;CAK9D"}

package/dist/BufferManager.js

@@ -0,0 +1,146 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+import { getBytesPerPixel, getTypedArrayConstructor } from "./types.js";
+/**
+ * Manages a dynamically-sized pixel buffer for volume data.
+ *
+ * The buffer is resized to match the fetched data dimensions exactly.
+ * Memory is reused when possible to avoid unnecessary allocations.
+ *
+ * Memory reuse strategy:
+ * - Reuse buffer if newSize <= currentCapacity
+ * - Reallocate if newSize > currentCapacity OR newSize < 25% of currentCapacity
+ */
+export class BufferManager {
+    buffer;
+    currentDimensions;
+    maxPixels;
+    TypedArrayCtor;
+    bytesPerPixel;
+    dtype;
+    /**
+     * Create a new BufferManager.
+     *
+     * @param maxPixels - Maximum number of pixels allowed (budget)
+     * @param dtype - Data type for the buffer
+     */
+    constructor(maxPixels, dtype) {
+        this.maxPixels = maxPixels;
+        this.dtype = dtype;
+        this.TypedArrayCtor = getTypedArrayConstructor(dtype);
+        this.bytesPerPixel = getBytesPerPixel(dtype);
+        // Initialize with empty buffer - will be allocated on first resize
+        this.currentDimensions = [0, 0, 0];
+        this.buffer = new ArrayBuffer(0);
+    }
+    /**
+     * Resize the buffer to fit the given dimensions.
+     *
+     * Reuses existing buffer if large enough, otherwise allocates new buffer.
+     * Will also reallocate if the buffer is significantly oversized (< 25% utilization).
+     *
+     * If dimensions exceed maxPixels, a warning is logged but the buffer is still
+     * allocated. This handles the case where even the lowest resolution exceeds the
+     * pixel budget - we still want to load something rather than failing.
+     *
+     * @param dimensions - New dimensions [z, y, x]
+     * @returns TypedArray view over the (possibly new) buffer
+     */
+    resize(dimensions) {
+        const requiredPixels = dimensions[0] * dimensions[1] * dimensions[2];
+        if (requiredPixels > this.maxPixels) {
+            console.warn(`[fidnii] BufferManager: Requested dimensions [${dimensions.join(", ")}] = ${requiredPixels} pixels exceeds maxPixels (${this.maxPixels}). ` +
+                `Proceeding anyway (likely at lowest resolution).`);
+        }
+        const currentCapacityPixels = this.buffer.byteLength / this.bytesPerPixel;
+        const utilizationRatio = currentCapacityPixels > 0
+            ? requiredPixels / currentCapacityPixels
+            : 0;
+        const needsReallocation = requiredPixels > currentCapacityPixels ||
+            utilizationRatio < 0.25;
+        if (needsReallocation) {
+            // Allocate new buffer
+            const newByteLength = requiredPixels * this.bytesPerPixel;
+            this.buffer = new ArrayBuffer(newByteLength);
+        }
+        this.currentDimensions = [...dimensions];
+        return this.getTypedArray();
+    }
+    /**
+     * Get the underlying ArrayBuffer.
+     */
+    getBuffer() {
+        return this.buffer;
+    }
+    /**
+     * Get a typed array view over the current buffer region.
+     *
+     * The view is sized to match currentDimensions, not the full buffer capacity.
+     */
+    getTypedArray() {
+        const pixelCount = this.currentDimensions[0] *
+            this.currentDimensions[1] *
+            this.currentDimensions[2];
+        return new this.TypedArrayCtor(this.buffer, 0, pixelCount);
+    }
+    /**
+     * Get the current buffer dimensions [z, y, x].
+     */
+    getDimensions() {
+        return [...this.currentDimensions];
+    }
+    /**
+     * Get the total number of pixels in the current buffer region.
+     */
+    getPixelCount() {
+        return (this.currentDimensions[0] *
+            this.currentDimensions[1] *
+            this.currentDimensions[2]);
+    }
+    /**
+     * Get the buffer capacity in pixels.
+     */
+    getCapacity() {
+        return this.buffer.byteLength / this.bytesPerPixel;
+    }
+    /**
+     * Get the bytes per pixel.
+     */
+    getBytesPerPixel() {
+        return this.bytesPerPixel;
+    }
+    /**
+     * Get the data type.
+     */
+    getDtype() {
+        return this.dtype;
+    }
+    /**
+     * Get the maximum pixels budget.
+     */
+    getMaxPixels() {
+        return this.maxPixels;
+    }
+    /**
+     * Clear the current buffer region to zeros.
+     */
+    clear() {
+        const pixelCount = this.getPixelCount();
+        if (pixelCount > 0) {
+            const view = new Uint8Array(this.buffer, 0, pixelCount * this.bytesPerPixel);
+            view.fill(0);
+        }
+    }
+    /**
+     * Check if the buffer can accommodate the given dimensions without reallocation.
+     *
+     * @param dimensions - Dimensions to check [z, y, x]
+     * @returns True if current buffer can fit the dimensions
+     */
+    canAccommodate(dimensions) {
+        const requiredPixels = dimensions[0] * dimensions[1] * dimensions[2];
+        const currentCapacityPixels = this.buffer.byteLength / this.bytesPerPixel;
+        return requiredPixels <= currentCapacityPixels;
+    }
+}
+//# sourceMappingURL=BufferManager.js.map

package/dist/BufferManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BufferManager.js","sourceRoot":"","sources":["../src/BufferManager.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,+BAA+B;AAG/B,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,CAAc;IACpB,iBAAiB,CAA2B;IACnC,SAAS,CAAS;IAClB,cAAc,CAAwB;IACtC,aAAa,CAAS;IACtB,KAAK,CAAY;IAElC;;;;;OAKG;IACH,YAAY,SAAiB,EAAE,KAAgB;QAC7C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,cAAc,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,CAAC,aAAa,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAE7C,mEAAmE;QACnE,IAAI,CAAC,iBAAiB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,UAAoC;QACzC,MAAM,cAAc,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAErE,IAAI,cAAc,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,OAAO,CAAC,IAAI,CACV,iDACE,UAAU,CAAC,IAAI,CAAC,IAAI,CACtB,OAAO,cAAc,8BAA8B,IAAI,CAAC,SAAS,KAAK;gBACpE,kDAAkD,CACrD,CAAC;QACJ,CAAC;QAED,MAAM,qBAAqB,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC;QAC1E,MAAM,gBAAgB,GAAG,qBAAqB,GAAG,CAAC;YAChD,CAAC,CAAC,cAAc,GAAG,qBAAqB;YACxC,CAAC,CAAC,CAAC,CAAC;QAEN,MAAM,iBAAiB,GAAG,cAAc,GAAG,qBAAqB;YAC9D,gBAAgB,GAAG,IAAI,CAAC;QAE1B,IAAI,iBAAiB,EAAE,CAAC;YACtB,sBAAsB;YACtB,MAAM,aAAa,GAAG,cAAc,GAAG,IAAI,CAAC,aAAa,CAAC;YAC1D,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC;QAC/C,CAAC;QAED,IAAI,CAAC,iBAAiB,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;YAC1C,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;QAC5B,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,CACL,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAC1B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACxC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,GAAG,IAAI,UAAU,CACzB,IAAI,CAAC,MAAM,EACX,CAAC,EACD,UAAU,GAAG,IAAI,CAAC,aAAa,CAChC,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,UAAoC;QACjD,MAAM,cAAc,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QACrE,MAAM,qBAAqB,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC;QAC1E,OAAO,cAAc,IAAI,qBAAqB,CAAC;IACjD,CAAC;CACF"}

package/dist/ClipPlanes.d.ts

@@ -0,0 +1,180 @@
+import type { Multiscales, NgffImage } from "@fideus-labs/ngff-zarr";
+import type { ChunkAlignedRegion, ClipPlane, ClipPlanes, PixelRegion, VolumeBounds } from "./types.js";
+/** Maximum number of clip planes supported by NiiVue */
+export declare const MAX_CLIP_PLANES = 6;
+/**
+ * Normalize a 3D vector to unit length.
+ *
+ * @param v - Vector to normalize [x, y, z]
+ * @returns Normalized vector [x, y, z]
+ * @throws Error if vector has zero length
+ */
+export declare function normalizeVector(v: [number, number, number]): [number, number, number];
+/**
+ * Create a clip plane from a point and normal vector.
+ * The normal is automatically normalized to unit length.
+ *
+ * @param point - A point on the plane [x, y, z] in world coordinates
+ * @param normal - Normal vector pointing toward visible region [x, y, z]
+ * @returns ClipPlane with normalized normal
+ */
+export declare function createClipPlane(point: [number, number, number], normal: [number, number, number]): ClipPlane;
+/**
+ * Create default clip planes (empty array = full volume visible).
+ *
+ * @param _multiscales - The OME-Zarr multiscales data (unused, kept for API consistency)
+ * @returns Empty ClipPlanes array
+ */
+export declare function createDefaultClipPlanes(_multiscales: Multiscales): ClipPlanes;
+/**
+ * Get volume bounds from multiscales metadata.
+ *
+ * @param multiscales - The OME-Zarr multiscales data
+ * @returns Volume bounds in world space
+ */
+export declare function getVolumeBoundsFromMultiscales(multiscales: Multiscales): VolumeBounds;
+/**
+ * Convert a normal vector to azimuth and elevation angles (for NiiVue).
+ *
+ * NiiVue convention:
+ * - Azimuth: 0 = posterior (+Y), 90 = right (+X), 180 = anterior (-Y), 270 = left (-X)
+ * - Elevation: 0 = horizontal, 90 = superior (+Z), -90 = inferior (-Z)
+ *
+ * @param normal - Unit normal vector [x, y, z]
+ * @returns Object with azimuth and elevation in degrees
+ */
+export declare function normalToAzimuthElevation(normal: [number, number, number]): {
+    azimuth: number;
+    elevation: number;
+};
+/**
+ * Convert azimuth and elevation angles to a unit normal vector.
+ *
+ * @param azimuth - Azimuth angle in degrees (0 = +Y, 90 = +X)
+ * @param elevation - Elevation angle in degrees (0 = horizontal, 90 = +Z)
+ * @returns Unit normal vector [x, y, z]
+ */
+export declare function azimuthElevationToNormal(azimuth: number, elevation: number): [number, number, number];
+/**
+ * Calculate the NiiVue depth parameter for a clip plane.
+ *
+ * NiiVue's clip plane depth is in normalized texture coordinates where
+ * the volume center is at 0.5. Depth represents the signed distance from
+ * the center (0) to the plane, where -0.5 is at min boundary and +0.5 is
+ * at max boundary. Values beyond [-0.5, 0.5] place the plane outside the volume.
+ *
+ * @param plane - The clip plane
+ * @param volumeBounds - Volume bounds in world space
+ * @returns Depth value for NiiVue (typically in range [-0.5, 0.5] for planes within volume)
+ */
+export declare function calculateNiivueDepth(plane: ClipPlane, volumeBounds: VolumeBounds): number;
+/**
+ * Convert a single clip plane to NiiVue format [depth, azimuth, elevation].
+ *
+ * NiiVue's shader convention:
+ * - The "back" side of the plane (sampleSide > 0) is VISIBLE
+ * - The "front" side of the plane (sampleSide < 0) is CLIPPED
+ * - sampleSide = dot(shaderNormal, p - 0.5) + depth
+ * - NiiVue internally adds 180° to azimuth, which flips the normal direction
+ *
+ * Our convention:
+ * - Normal points toward the VISIBLE region
+ *
+ * To reconcile these conventions:
+ * 1. We negate the normal before computing azimuth/elevation
+ * 2. After NiiVue's +180° flip, the shader sees our original normal direction
+ * 3. We also negate the depth to match the flipped normal
+ *
+ * @param plane - The clip plane
+ * @param volumeBounds - Volume bounds in world space
+ * @returns [depth, azimuth, elevation] for NiiVue
+ */
+export declare function clipPlaneToNiivue(plane: ClipPlane, volumeBounds: VolumeBounds): [number, number, number];
+/**
+ * Convert clip planes to NiiVue format.
+ *
+ * @param clipPlanes - Array of clip planes
+ * @param volumeBounds - Volume bounds in world space
+ * @returns Array of [depth, azimuth, elevation] for NiiVue
+ */
+export declare function clipPlanesToNiivue(clipPlanes: ClipPlanes, volumeBounds: VolumeBounds): number[][];
+/**
+ * Calculate the signed distance from a point to a plane.
+ *
+ * Positive = point is on the visible side (same side as normal)
+ * Negative = point is on the clipped side (opposite side from normal)
+ *
+ * @param testPoint - Point to test [x, y, z]
+ * @param plane - The clip plane
+ * @returns Signed distance
+ */
+export declare function pointToPlaneDistance(testPoint: [number, number, number], plane: ClipPlane): number;
+/**
+ * Check if a point is inside all clip planes (on the visible side).
+ *
+ * @param worldCoord - World coordinate [x, y, z]
+ * @param clipPlanes - Array of clip planes
+ * @returns True if the point is inside all clip planes (or if there are no planes)
+ */
+export declare function isInsideClipPlanes(worldCoord: [number, number, number], clipPlanes: ClipPlanes): boolean;
+/**
+ * Calculate the axis-aligned bounding box that contains the clipped region.
+ *
+ * For oblique clip planes, this finds the intersection of the clip planes
+ * with the volume bounds and returns the AABB of that intersection.
+ *
+ * This is used for data fetching (zarr is always axis-aligned).
+ *
+ * @param clipPlanes - Array of clip planes
+ * @param volumeBounds - Full volume bounds in world space
+ * @returns Bounding box of the clipped region
+ */
+export declare function clipPlanesToBoundingBox(clipPlanes: ClipPlanes, volumeBounds: VolumeBounds): VolumeBounds;
+/**
+ * Convert clip planes to a pixel region for a specific NgffImage.
+ *
+ * This calculates the axis-aligned bounding box of the clipped region
+ * and converts it to pixel coordinates. When viewportBounds is provided,
+ * the result is further constrained to only include the visible viewport
+ * area (for viewport-aware resolution selection).
+ *
+ * @param clipPlanes - Array of clip planes
+ * @param volumeBounds - Full volume bounds in world space
+ * @param ngffImage - The NgffImage to convert to
+ * @param viewportBounds - Optional viewport bounds to intersect with
+ * @returns Pixel region [z, y, x] start and end indices
+ */
+export declare function clipPlanesToPixelRegion(clipPlanes: ClipPlanes, volumeBounds: VolumeBounds, ngffImage: NgffImage, viewportBounds?: VolumeBounds): PixelRegion;
+/**
+ * Align a pixel region to chunk boundaries.
+ *
+ * This expands the region to include complete chunks, which is necessary
+ * for efficient zarr fetching.
+ *
+ * @param region - The pixel region to align
+ * @param ngffImage - The NgffImage (for chunk shape)
+ * @returns Chunk-aligned region with clipping information
+ */
+export declare function alignToChunks(region: PixelRegion, ngffImage: NgffImage): ChunkAlignedRegion;
+/**
+ * Create an axis-aligned clip plane at a specific position.
+ *
+ * The normal points toward the VISIBLE region (the region to keep).
+ * NiiVue's shader convention is that the "back" side of the plane (where
+ * dot(n, p-center) + depth > 0) is visible.
+ *
+ * @param axis - The axis ('x', 'y', or 'z')
+ * @param position - Position along the axis in world coordinates
+ * @param direction - Which side to keep visible ('positive' or 'negative')
+ * @param volumeBounds - Volume bounds for centering the point
+ * @returns ClipPlane with point at center of volume projected to the plane
+ */
+export declare function createAxisAlignedClipPlane(axis: "x" | "y" | "z", position: number, direction: "positive" | "negative", volumeBounds: VolumeBounds): ClipPlane;
+/**
+ * Validate clip planes array.
+ *
+ * @param clipPlanes - Array of clip planes to validate
+ * @throws Error if validation fails
+ */
+export declare function validateClipPlanes(clipPlanes: ClipPlanes): void;
+//# sourceMappingURL=ClipPlanes.d.ts.map

package/dist/ClipPlanes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClipPlanes.d.ts","sourceRoot":"","sources":["../src/ClipPlanes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EACV,kBAAkB,EAClB,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAIpB,wDAAwD;AACxD,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC1B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAM1B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC/B,SAAS,CAKX;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,WAAW,GAAG,UAAU,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,WAAW,GACvB,YAAY,CAuBd;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAC/B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAcxC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAU1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,YAAY,EAAE,YAAY,GACzB,MAAM,CAoCR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,YAAY,EAAE,YAAY,GACzB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAiB1B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,YAAY,GACzB,MAAM,EAAE,EAAE,CAEZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACnC,KAAK,EAAE,SAAS,GACf,MAAM,CAOR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACpC,UAAU,EAAE,UAAU,GACrB,OAAO,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,YAAY,GACzB,YAAY,CAoGd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,UAAU,EACtB,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,SAAS,EACpB,cAAc,CAAC,EAAE,YAAY,GAC5B,WAAW,CAwDb;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,SAAS,GACnB,kBAAkB,CA0CpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,UAAU,GAAG,UAAU,EAClC,YAAY,EAAE,YAAY,GACzB,SAAS,CA8BX;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAoC/D"}