@fideus-labs/fidnii 0.1.0

package/src/RegionCoalescer.ts

@@ -0,0 +1,217 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+import * as zarr from "zarrita";
+import type { NgffImage } from "@fideus-labs/ngff-zarr";
+import { zarrGet } from "@fideus-labs/ngff-zarr/browser";
+import type {
+  ChunkCache,
+  PixelRegion,
+  RegionFetchResult,
+  TypedArray,
+} from "./types.js";
+
+/**
+ * Represents a pending request that may have multiple consumers waiting for the result.
+ */
+interface PendingRequest {
+  /** The promise that resolves when the request completes */
+  promise: Promise<RegionFetchResult>;
+  /** Function to resolve the promise with the result */
+  resolve: (data: RegionFetchResult) => void;
+  /** Function to reject the promise with an error */
+  reject: (error: Error) => void;
+  /** Set of requester IDs waiting for this result */
+  requesters: Set<string>;
+}
+
+/**
+ * RegionCoalescer handles fetching sub-regions from OME-Zarr images with:
+ *
+ * 1. Request deduplication - Multiple async triggers (zoom, crop changes, etc.)
+ *    requesting the same region receive the same promise
+ * 2. Parallel fetching - Uses fizarrita's worker-pool-accelerated zarrGet
+ *    for concurrent, worker-offloaded chunk fetches
+ * 3. Requester tracking - Tracks who is waiting for each request
+ * 4. Chunk caching - Optional decoded-chunk cache to avoid redundant
+ *    decompression on repeated or overlapping reads
+ *
+ * This design supports future scenarios where multiple UI events may trigger
+ * overlapping region requests simultaneously.
+ */
+export class RegionCoalescer {
+  private readonly pending: Map<string, PendingRequest> = new Map();
+
+  /** Optional decoded-chunk cache forwarded to fizarrita's getWorker. */
+  private readonly _cache: ChunkCache | undefined;
+
+  /**
+   * @param cache - Optional decoded-chunk cache. When provided, `zarrGet`
+   *   caches decoded chunks to avoid redundant decompression on repeated
+   *   or overlapping reads.
+   */
+  constructor(cache?: ChunkCache) {
+    this._cache = cache;
+  }
+
+  /**
+   * Generate a unique key for a request based on image path, level index, and region.
+   */
+  private makeKey(
+    imagePath: string,
+    levelIndex: number,
+    region: PixelRegion,
+  ): string {
+    const start = region.start.join(",");
+    const end = region.end.join(",");
+    return `${imagePath}:${levelIndex}:${start}:${end}`;
+  }
+
+  /**
+   * Request a region, coalescing with any in-flight request for the same data.
+   *
+   * @param ngffImage - The NgffImage to fetch from
+   * @param levelIndex - The resolution level index
+   * @param region - The pixel region to fetch
+   * @param requesterId - ID of the requester (e.g., 'zoom', 'crop-change', 'progressive-load')
+   * @returns The fetched region data
+   */
+  async fetchRegion(
+    ngffImage: NgffImage,
+    levelIndex: number,
+    region: PixelRegion,
+    requesterId: string = "default",
+  ): Promise<RegionFetchResult> {
+    const key = this.makeKey(ngffImage.data.path, levelIndex, region);
+
+    // Check if there's already a pending request for this data
+    const existing = this.pending.get(key);
+    if (existing) {
+      // Add this requester to the waiters and return the existing promise
+      existing.requesters.add(requesterId);
+      return existing.promise;
+    }
+
+    // Create a new pending request
+    let resolvePromise!: (data: RegionFetchResult) => void;
+    let rejectPromise!: (error: Error) => void;
+
+    const promise = new Promise<RegionFetchResult>((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+
+    const pendingRequest: PendingRequest = {
+      promise,
+      resolve: resolvePromise,
+      reject: rejectPromise,
+      requesters: new Set([requesterId]),
+    };
+
+    this.pending.set(key, pendingRequest);
+
+    // Fetch using fizarrita's worker-accelerated zarrGet
+    try {
+      const selection = [
+        zarr.slice(region.start[0], region.end[0]),
+        zarr.slice(region.start[1], region.end[1]),
+        zarr.slice(region.start[2], region.end[2]),
+      ];
+      // Pass the chunk cache to fizarrita's getWorker via zarrGet.
+      // The `cache` option is available in @fideus-labs/fizarrita >=1.2.0.
+      const zarrOpts = this._cache
+        ? { cache: this._cache } as Record<string, unknown>
+        : undefined;
+      const result = await zarrGet(ngffImage.data, selection, zarrOpts);
+
+      const fetchResult: RegionFetchResult = {
+        data: result.data as TypedArray,
+        shape: result.shape,
+        stride: result.stride,
+      };
+
+      pendingRequest.resolve(fetchResult);
+      return fetchResult;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      pendingRequest.reject(err);
+      throw err;
+    } finally {
+      this.pending.delete(key);
+    }
+  }
+
+  /**
+   * Fetch multiple regions in parallel, with deduplication.
+   * Useful for fetching multiple chunks for a single view update.
+   *
+   * @param ngffImage - The NgffImage to fetch from
+   * @param levelIndex - The resolution level index
+   * @param regions - Array of pixel regions to fetch
+   * @param requesterId - ID of the requester
+   * @returns Array of fetched region data
+   */
+  async fetchRegions(
+    ngffImage: NgffImage,
+    levelIndex: number,
+    regions: PixelRegion[],
+    requesterId: string = "default",
+  ): Promise<RegionFetchResult[]> {
+    return Promise.all(
+      regions.map((region) =>
+        this.fetchRegion(ngffImage, levelIndex, region, requesterId)
+      ),
+    );
+  }
+
+  /**
+   * Check if there's a pending request for the given parameters.
+   */
+  hasPending(
+    ngffImage: NgffImage,
+    levelIndex: number,
+    region: PixelRegion,
+  ): boolean {
+    const key = this.makeKey(ngffImage.data.path, levelIndex, region);
+    return this.pending.has(key);
+  }
+
+  /**
+   * Get the set of requesters waiting for a pending request.
+   * Returns undefined if no pending request exists.
+   */
+  getPendingRequesters(
+    ngffImage: NgffImage,
+    levelIndex: number,
+    region: PixelRegion,
+  ): Set<string> | undefined {
+    const key = this.makeKey(ngffImage.data.path, levelIndex, region);
+    return this.pending.get(key)?.requesters;
+  }
+
+  /**
+   * Wait for all pending fetches to complete.
+   */
+  async onIdle(): Promise<void> {
+    // Wait for all in-flight requests to settle
+    const promises = Array.from(this.pending.values()).map((p) =>
+      p.promise.catch(() => {})
+    );
+    await Promise.all(promises);
+  }
+
+  /**
+   * Get the number of pending requests (unique region requests).
+   */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  /**
+   * Clear all pending requests.
+   * Note: Does not resolve or reject pending promises.
+   */
+  clear(): void {
+    this.pending.clear();
+  }
+}

package/src/ResolutionSelector.ts

@@ -0,0 +1,325 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+import type { Multiscales, NgffImage } from "@fideus-labs/ngff-zarr";
+import type {
+  ClipPlanes,
+  PixelRegion,
+  ResolutionSelection,
+  VolumeBounds,
+} from "./types.js";
+import { clipPlanesToPixelRegion } from "./ClipPlanes.js";
+
+/**
+ * Orthogonal axis index in [z, y, x] order.
+ * 0 = Z (axial view), 1 = Y (coronal view), 2 = X (sagittal view)
+ */
+export type OrthogonalAxis = 0 | 1 | 2;
+
+/**
+ * Select the appropriate resolution level based on pixel budget and clip planes.
+ *
+ * The selection process:
+ * 1. Starts from the highest resolution (level 0)
+ * 2. Finds the highest resolution that fits within maxPixels
+ * 3. Considers the clipped region size, not full volume
+ *
+ * @param multiscales - The OME-Zarr multiscales data
+ * @param maxPixels - Maximum number of pixels to use
+ * @param clipPlanes - Current clip planes in world space
+ * @param volumeBounds - Full volume bounds in world space
+ * @param viewportBounds - Optional viewport bounds (for viewport-aware mode)
+ * @returns The selected resolution level and buffer dimensions
+ */
+export function selectResolution(
+  multiscales: Multiscales,
+  maxPixels: number,
+  clipPlanes: ClipPlanes,
+  volumeBounds: VolumeBounds,
+  viewportBounds?: VolumeBounds,
+): ResolutionSelection {
+  const images = multiscales.images;
+
+  // Try each resolution from highest to lowest
+  for (let i = 0; i < images.length; i++) {
+    const image = images[i];
+    const region = clipPlanesToPixelRegion(
+      clipPlanes,
+      volumeBounds,
+      image,
+      viewportBounds,
+    );
+    const alignedRegion = alignRegionToChunks(region, image);
+
+    const dimensions: [number, number, number] = [
+      alignedRegion.end[0] - alignedRegion.start[0],
+      alignedRegion.end[1] - alignedRegion.start[1],
+      alignedRegion.end[2] - alignedRegion.start[2],
+    ];
+
+    const pixelCount = dimensions[0] * dimensions[1] * dimensions[2];
+
+    if (pixelCount <= maxPixels) {
+      return {
+        levelIndex: i,
+        dimensions,
+        pixelCount,
+      };
+    }
+  }
+
+  // Fall back to lowest resolution
+  const lowestImage = images[images.length - 1];
+  const region = clipPlanesToPixelRegion(
+    clipPlanes,
+    volumeBounds,
+    lowestImage,
+    viewportBounds,
+  );
+  const alignedRegion = alignRegionToChunks(region, lowestImage);
+
+  const dimensions: [number, number, number] = [
+    alignedRegion.end[0] - alignedRegion.start[0],
+    alignedRegion.end[1] - alignedRegion.start[1],
+    alignedRegion.end[2] - alignedRegion.start[2],
+  ];
+
+  return {
+    levelIndex: images.length - 1,
+    dimensions,
+    pixelCount: dimensions[0] * dimensions[1] * dimensions[2],
+  };
+}
+
+/**
+ * Get the chunk shape for a volume.
+ *
+ * @param ngffImage - The NgffImage to get chunk shape from
+ * @returns Chunk shape as [z, y, x]
+ */
+export function getChunkShape(ngffImage: NgffImage): [number, number, number] {
+  const chunks = ngffImage.data.chunks;
+  const dims = ngffImage.dims;
+
+  // Find z, y, x indices in dims
+  const zIdx = dims.indexOf("z");
+  const yIdx = dims.indexOf("y");
+  const xIdx = dims.indexOf("x");
+
+  if (zIdx === -1 || yIdx === -1 || xIdx === -1) {
+    // Fallback: assume last 3 dimensions are z, y, x
+    const n = chunks.length;
+    return [chunks[n - 3] || 1, chunks[n - 2] || 1, chunks[n - 1] || 1];
+  }
+
+  return [chunks[zIdx], chunks[yIdx], chunks[xIdx]];
+}
+
+/**
+ * Get the shape of a volume as [z, y, x].
+ *
+ * @param ngffImage - The NgffImage
+ * @returns Shape as [z, y, x]
+ */
+export function getVolumeShape(ngffImage: NgffImage): [number, number, number] {
+  const shape = ngffImage.data.shape;
+  const dims = ngffImage.dims;
+
+  // Find z, y, x indices in dims
+  const zIdx = dims.indexOf("z");
+  const yIdx = dims.indexOf("y");
+  const xIdx = dims.indexOf("x");
+
+  if (zIdx === -1 || yIdx === -1 || xIdx === -1) {
+    // Fallback: assume last 3 dimensions are z, y, x
+    const n = shape.length;
+    return [shape[n - 3] || 1, shape[n - 2] || 1, shape[n - 1] || 1];
+  }
+
+  return [shape[zIdx], shape[yIdx], shape[xIdx]];
+}
+
+/**
+ * Align a pixel region to chunk boundaries.
+ * Expands the region to include complete chunks.
+ *
+ * @param region - The pixel region to align
+ * @param ngffImage - The NgffImage (for chunk shape)
+ * @returns Aligned region
+ */
+export function alignRegionToChunks(
+  region: PixelRegion,
+  ngffImage: NgffImage,
+): PixelRegion {
+  const chunkShape = getChunkShape(ngffImage);
+  const volumeShape = getVolumeShape(ngffImage);
+
+  // Align start down to chunk boundary
+  const alignedStart: [number, number, number] = [
+    Math.floor(region.start[0] / chunkShape[0]) * chunkShape[0],
+    Math.floor(region.start[1] / chunkShape[1]) * chunkShape[1],
+    Math.floor(region.start[2] / chunkShape[2]) * chunkShape[2],
+  ];
+
+  // Align end up to chunk boundary (but don't exceed volume size)
+  const alignedEnd: [number, number, number] = [
+    Math.min(
+      Math.ceil(region.end[0] / chunkShape[0]) * chunkShape[0],
+      volumeShape[0],
+    ),
+    Math.min(
+      Math.ceil(region.end[1] / chunkShape[1]) * chunkShape[1],
+      volumeShape[1],
+    ),
+    Math.min(
+      Math.ceil(region.end[2] / chunkShape[2]) * chunkShape[2],
+      volumeShape[2],
+    ),
+  ];
+
+  return {
+    start: alignedStart,
+    end: alignedEnd,
+  };
+}
+
+/**
+ * Calculate the middle resolution level index.
+ *
+ * @param multiscales - The OME-Zarr multiscales data
+ * @returns Middle resolution level index
+ */
+export function getMiddleResolutionIndex(multiscales: Multiscales): number {
+  return Math.floor(multiscales.images.length / 2);
+}
+
+/**
+ * Calculate upsample factor from one resolution level to another.
+ *
+ * @param multiscales - The OME-Zarr multiscales data
+ * @param fromLevel - Source resolution level
+ * @param toLevel - Target resolution level (should be higher resolution, i.e., lower index)
+ * @returns Upsample factor for each dimension [z, y, x]
+ */
+export function calculateUpsampleFactor(
+  multiscales: Multiscales,
+  fromLevel: number,
+  toLevel: number,
+): [number, number, number] {
+  const fromImage = multiscales.images[fromLevel];
+  const toImage = multiscales.images[toLevel];
+
+  const fromShape = getVolumeShape(fromImage);
+  const toShape = getVolumeShape(toImage);
+
+  return [
+    toShape[0] / fromShape[0],
+    toShape[1] / fromShape[1],
+    toShape[2] / fromShape[2],
+  ];
+}
+
+/**
+ * Get dimensions for the full volume at a given resolution level.
+ */
+export function getFullVolumeDimensions(
+  multiscales: Multiscales,
+  levelIndex: number,
+): [number, number, number] {
+  return getVolumeShape(multiscales.images[levelIndex]);
+}
+
+/**
+ * Select the appropriate resolution level for a 2D slice view.
+ *
+ * Unlike `selectResolution` which counts all 3D pixels (z*y*x), this function
+ * counts only the 2D in-plane pixels (e.g., x*y for axial), ignoring the
+ * orthogonal axis. This allows much higher resolution for 2D slice views.
+ *
+ * The slab dimensions returned include one chunk of thickness in the
+ * orthogonal direction (needed for zarr fetching efficiency). The pixel
+ * budget accounts for the full 3D slab volume (in-plane area multiplied
+ * by the chunk thickness along the orthogonal axis).
+ *
+ * @param multiscales - The OME-Zarr multiscales data
+ * @param maxPixels - Maximum number of voxels for the slab (in-plane area × chunk depth)
+ * @param clipPlanes - Current clip planes in world space
+ * @param volumeBounds - Full volume bounds in world space
+ * @param orthogonalAxis - The axis perpendicular to the slice plane (0=Z, 1=Y, 2=X)
+ * @param viewportBounds - Optional viewport bounds (for viewport-aware mode)
+ * @returns The selected resolution level and slab dimensions
+ */
+export function select2DResolution(
+  multiscales: Multiscales,
+  maxPixels: number,
+  clipPlanes: ClipPlanes,
+  volumeBounds: VolumeBounds,
+  orthogonalAxis: OrthogonalAxis,
+  viewportBounds?: VolumeBounds,
+): ResolutionSelection {
+  const images = multiscales.images;
+
+  // Try each resolution from highest to lowest
+  for (let i = 0; i < images.length; i++) {
+    const image = images[i];
+    const region = clipPlanesToPixelRegion(
+      clipPlanes,
+      volumeBounds,
+      image,
+      viewportBounds,
+    );
+    const alignedRegion = alignRegionToChunks(region, image);
+
+    const dimensions: [number, number, number] = [
+      alignedRegion.end[0] - alignedRegion.start[0],
+      alignedRegion.end[1] - alignedRegion.start[1],
+      alignedRegion.end[2] - alignedRegion.start[2],
+    ];
+
+    // Count the full slab volume: in-plane area × chunk depth along the
+    // orthogonal axis. The slab is always one chunk thick, so we use the
+    // chunk shape rather than the full volume extent in that axis.
+    const chunkShape = getChunkShape(image);
+    const slabDepth = chunkShape[orthogonalAxis];
+    const inPlaneAxes = ([0, 1, 2] as const).filter((a) =>
+      a !== orthogonalAxis
+    );
+    const slabVoxelCount = dimensions[inPlaneAxes[0]] *
+      dimensions[inPlaneAxes[1]] * slabDepth;
+
+    if (slabVoxelCount <= maxPixels) {
+      return {
+        levelIndex: i,
+        dimensions,
+        pixelCount: slabVoxelCount,
+      };
+    }
+  }
+
+  // Fall back to lowest resolution
+  const lowestImage = images[images.length - 1];
+  const region = clipPlanesToPixelRegion(
+    clipPlanes,
+    volumeBounds,
+    lowestImage,
+    viewportBounds,
+  );
+  const alignedRegion = alignRegionToChunks(region, lowestImage);
+
+  const dimensions: [number, number, number] = [
+    alignedRegion.end[0] - alignedRegion.start[0],
+    alignedRegion.end[1] - alignedRegion.start[1],
+    alignedRegion.end[2] - alignedRegion.start[2],
+  ];
+
+  const chunkShape = getChunkShape(lowestImage);
+  const slabDepth = chunkShape[orthogonalAxis];
+  const inPlaneAxes = ([0, 1, 2] as const).filter((a) => a !== orthogonalAxis);
+
+  return {
+    levelIndex: images.length - 1,
+    dimensions,
+    pixelCount: dimensions[inPlaneAxes[0]] * dimensions[inPlaneAxes[1]] *
+      slabDepth,
+  };
+}