@fideus-labs/fidnii 0.1.0

package/src/types.ts

@@ -0,0 +1,429 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+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;
+
+// Re-export SLICE_TYPE for convenience
+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 const NiftiDataType = {
+  UINT8: 2,
+  INT16: 4,
+  INT32: 8,
+  FLOAT32: 16,
+  FLOAT64: 64,
+  INT8: 256,
+  UINT16: 512,
+  UINT32: 768,
+} as const;
+
+export type NiftiDataTypeCode =
+  (typeof NiftiDataType)[keyof typeof NiftiDataType];
+
+/**
+ * Map zarr dtype to typed array constructor.
+ */
+export function getTypedArrayConstructor(
+  dtype: ZarrDtype,
+): TypedArrayConstructor {
+  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: ZarrDtype): number {
+  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: ZarrDtype): NiftiDataTypeCode {
+  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: string): ZarrDtype {
+  // 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}`);
+  }
+}

package/src/utils/affine.ts

@@ -0,0 +1,218 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+import { mat4 } from "gl-matrix";
+import type { NgffImage } from "@fideus-labs/ngff-zarr";
+
+/**
+ * Create a 4x4 affine transformation matrix from OME-Zarr scale and translation.
+ *
+ * The affine matrix transforms from pixel indices to world coordinates.
+ * NIfTI uses a column-major 4x4 matrix stored as a flat array of 16 elements.
+ *
+ * For OME-Zarr, the transformation is:
+ *   world = scale * pixel + translation
+ *
+ * The matrix form is:
+ *   | sx  0   0  tx |
+ *   | 0   sy  0  ty |
+ *   | 0   0   sz tz |
+ *   | 0   0   0  1  |
+ *
+ * @param scale - Scale factors { x, y, z }
+ * @param translation - Translation offsets { x, y, z }
+ * @returns 4x4 affine matrix as a flat Float32Array (column-major)
+ */
+export function createAffineFromOMEZarr(
+  scale: Record<string, number>,
+  translation: Record<string, number>,
+): mat4 {
+  const affine = mat4.create();
+
+  // NIfTI expects the matrix in a specific orientation
+  // The affine maps from (i, j, k) voxel indices to (x, y, z) world coordinates
+  // For OME-Zarr with [z, y, x] ordering, we need to handle the axis mapping
+
+  // Extract scale and translation for each axis
+  const sx = scale.x ?? scale.X ?? 1;
+  const sy = scale.y ?? scale.Y ?? 1;
+  const sz = scale.z ?? scale.Z ?? 1;
+
+  const tx = translation.x ?? translation.X ?? 0;
+  const ty = translation.y ?? translation.Y ?? 0;
+  const tz = translation.z ?? translation.Z ?? 0;
+
+  // Build affine matrix
+  // NIfTI convention: first index (i) -> x, second (j) -> y, third (k) -> z
+  // OME-Zarr stores data as [z, y, x], so we need to account for this
+
+  // Column 0: x direction (from third array index in [z,y,x])
+  affine[0] = sx;
+  affine[1] = 0;
+  affine[2] = 0;
+  affine[3] = 0;
+
+  // Column 1: y direction (from second array index in [z,y,x])
+  affine[4] = 0;
+  affine[5] = sy;
+  affine[6] = 0;
+  affine[7] = 0;
+
+  // Column 2: z direction (from first array index in [z,y,x])
+  affine[8] = 0;
+  affine[9] = 0;
+  affine[10] = sz;
+  affine[11] = 0;
+
+  // Column 3: translation
+  affine[12] = tx;
+  affine[13] = ty;
+  affine[14] = tz;
+  affine[15] = 1;
+
+  return affine;
+}
+
+/**
+ * Create an affine matrix from an NgffImage.
+ *
+ * @param ngffImage - The NgffImage containing scale and translation
+ * @returns 4x4 affine matrix
+ */
+export function createAffineFromNgffImage(ngffImage: NgffImage): mat4 {
+  return createAffineFromOMEZarr(ngffImage.scale, ngffImage.translation);
+}
+
+/**
+ * Convert an affine matrix to a flat array for NIfTI header.
+ * NIfTI uses srow_x, srow_y, srow_z which are the first 3 rows of the affine.
+ *
+ * @param affine - The 4x4 affine matrix
+ * @returns Object with srow_x, srow_y, srow_z arrays
+ */
+export function affineToNiftiSrows(affine: mat4): {
+  srow_x: [number, number, number, number];
+  srow_y: [number, number, number, number];
+  srow_z: [number, number, number, number];
+} {
+  // gl-matrix uses column-major order
+  // Row 0 (srow_x): elements 0, 4, 8, 12
+  // Row 1 (srow_y): elements 1, 5, 9, 13
+  // Row 2 (srow_z): elements 2, 6, 10, 14
+  return {
+    srow_x: [affine[0], affine[4], affine[8], affine[12]],
+    srow_y: [affine[1], affine[5], affine[9], affine[13]],
+    srow_z: [affine[2], affine[6], affine[10], affine[14]],
+  };
+}
+
+/**
+ * Get pixel dimensions (voxel sizes) from an affine matrix.
+ *
+ * @param affine - The 4x4 affine matrix
+ * @returns Pixel dimensions [x, y, z]
+ */
+export function getPixelDimensions(affine: mat4): [number, number, number] {
+  // The pixel dimensions are the lengths of the column vectors
+  const dx = Math.sqrt(affine[0] ** 2 + affine[1] ** 2 + affine[2] ** 2);
+  const dy = Math.sqrt(affine[4] ** 2 + affine[5] ** 2 + affine[6] ** 2);
+  const dz = Math.sqrt(affine[8] ** 2 + affine[9] ** 2 + affine[10] ** 2);
+
+  return [dx, dy, dz];
+}
+
+/**
+ * Update affine matrix for a cropped/subsampled region.
+ *
+ * When we load a subregion or at a different resolution, we need to update
+ * the affine to reflect the new origin and voxel sizes.
+ *
+ * @param originalAffine - Original affine matrix
+ * @param regionStart - Start pixel indices [z, y, x] of the region
+ * @param scaleFactor - Scale factor applied (> 1 means downsampled)
+ * @returns Updated affine matrix
+ */
+export function updateAffineForRegion(
+  originalAffine: mat4,
+  regionStart: [number, number, number],
+  scaleFactor: [number, number, number],
+): mat4 {
+  const result = mat4.clone(originalAffine);
+
+  // Scale the voxel dimensions
+  // Column 0 (x direction)
+  result[0] *= scaleFactor[2]; // x scale factor
+  result[1] *= scaleFactor[2];
+  result[2] *= scaleFactor[2];
+
+  // Column 1 (y direction)
+  result[4] *= scaleFactor[1]; // y scale factor
+  result[5] *= scaleFactor[1];
+  result[6] *= scaleFactor[1];
+
+  // Column 2 (z direction)
+  result[8] *= scaleFactor[0]; // z scale factor
+  result[9] *= scaleFactor[0];
+  result[10] *= scaleFactor[0];
+
+  // Update translation for region offset
+  // New origin = original_origin + regionStart * original_voxel_size
+  const originalPixelDims = getPixelDimensions(originalAffine);
+
+  result[12] += regionStart[2] * originalPixelDims[0]; // x offset
+  result[13] += regionStart[1] * originalPixelDims[1]; // y offset
+  result[14] += regionStart[0] * originalPixelDims[2]; // z offset
+
+  return result;
+}
+
+/**
+ * Calculate the world-space bounding box from an affine and dimensions.
+ *
+ * @param affine - The 4x4 affine matrix
+ * @param dimensions - Volume dimensions [z, y, x]
+ * @returns Bounding box { min: [x,y,z], max: [x,y,z] }
+ */
+export function calculateWorldBounds(
+  affine: mat4,
+  dimensions: [number, number, number],
+): { min: [number, number, number]; max: [number, number, number] } {
+  // Calculate all 8 corners of the volume in world space
+  const [dimZ, dimY, dimX] = dimensions;
+  const corners = [
+    [0, 0, 0],
+    [dimX, 0, 0],
+    [0, dimY, 0],
+    [0, 0, dimZ],
+    [dimX, dimY, 0],
+    [dimX, 0, dimZ],
+    [0, dimY, dimZ],
+    [dimX, dimY, dimZ],
+  ];
+
+  let minX = Infinity,
+    minY = Infinity,
+    minZ = Infinity;
+  let maxX = -Infinity,
+    maxY = -Infinity,
+    maxZ = -Infinity;
+
+  for (const [i, j, k] of corners) {
+    // Apply affine: world = affine * [i, j, k, 1]^T
+    const wx = affine[0] * i + affine[4] * j + affine[8] * k + affine[12];
+    const wy = affine[1] * i + affine[5] * j + affine[9] * k + affine[13];
+    const wz = affine[2] * i + affine[6] * j + affine[10] * k + affine[14];
+
+    minX = Math.min(minX, wx);
+    minY = Math.min(minY, wy);
+    minZ = Math.min(minZ, wz);
+    maxX = Math.max(maxX, wx);
+    maxY = Math.max(maxY, wy);
+    maxZ = Math.max(maxZ, wz);
+  }
+
+  return {
+    min: [minX, minY, minZ],
+    max: [maxX, maxY, maxZ],
+  };
+}