@fideus-labs/fidnii 0.1.0 → 0.2.0

package/src/ClipPlanes.ts

@@ -1,19 +1,20 @@
 // SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
 // SPDX-License-Identifier: MIT
 
-import type { Multiscales, NgffImage } from "@fideus-labs/ngff-zarr";
+import type { Multiscales, NgffImage } from "@fideus-labs/ngff-zarr"
+
+import { getChunkShape, getVolumeShape } from "./ResolutionSelector.js"
 import type {
   ChunkAlignedRegion,
   ClipPlane,
   ClipPlanes,
   PixelRegion,
   VolumeBounds,
-} from "./types.js";
-import { pixelToWorld, worldToPixel } from "./utils/coordinates.js";
-import { getChunkShape, getVolumeShape } from "./ResolutionSelector.js";
+} from "./types.js"
+import { pixelToWorld, worldToPixel } from "./utils/coordinates.js"
 
 /** Maximum number of clip planes supported by NiiVue */
-export const MAX_CLIP_PLANES = 6;
+export const MAX_CLIP_PLANES = 6
 
 /**
  * Normalize a 3D vector to unit length.
@@ -25,11 +26,11 @@ export const MAX_CLIP_PLANES = 6;
 export function normalizeVector(
   v: [number, number, number],
 ): [number, number, number] {
-  const length = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+  const length = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2])
   if (length === 0) {
-    throw new Error("Cannot normalize zero-length vector");
+    throw new Error("Cannot normalize zero-length vector")
   }
-  return [v[0] / length, v[1] / length, v[2] / length];
+  return [v[0] / length, v[1] / length, v[2] / length]
 }
 
 /**
@@ -47,7 +48,7 @@ export function createClipPlane(
   return {
     point: [...point],
     normal: normalizeVector(normal),
-  };
+  }
 }
 
 /**
@@ -57,7 +58,7 @@ export function createClipPlane(
  * @returns Empty ClipPlanes array
  */
 export function createDefaultClipPlanes(_multiscales: Multiscales): ClipPlanes {
-  return [];
+  return []
 }
 
 /**
@@ -70,14 +71,14 @@ export function getVolumeBoundsFromMultiscales(
   multiscales: Multiscales,
 ): VolumeBounds {
   // Use highest resolution for most accurate bounds
-  const image = multiscales.images[0];
-  const shape = getVolumeShape(image);
+  const image = multiscales.images[0]
+  const shape = getVolumeShape(image)
 
-  const minPixel: [number, number, number] = [0, 0, 0];
-  const maxPixel: [number, number, number] = [shape[0], shape[1], shape[2]];
+  const minPixel: [number, number, number] = [0, 0, 0]
+  const maxPixel: [number, number, number] = [shape[0], shape[1], shape[2]]
 
-  const minWorld = pixelToWorld(minPixel, image);
-  const maxWorld = pixelToWorld(maxPixel, image);
+  const minWorld = pixelToWorld(minPixel, image)
+  const maxWorld = pixelToWorld(maxPixel, image)
 
   return {
     min: [
@@ -90,7 +91,7 @@ export function getVolumeBoundsFromMultiscales(
       Math.max(minWorld[1], maxWorld[1]),
       Math.max(minWorld[2], maxWorld[2]),
     ],
-  };
+  }
 }
 
 /**
@@ -103,22 +104,23 @@ export function getVolumeBoundsFromMultiscales(
  * @param normal - Unit normal vector [x, y, z]
  * @returns Object with azimuth and elevation in degrees
  */
-export function normalToAzimuthElevation(
-  normal: [number, number, number],
-): { azimuth: number; elevation: number } {
-  const [x, y, z] = normal;
+export function normalToAzimuthElevation(normal: [number, number, number]): {
+  azimuth: number
+  elevation: number
+} {
+  const [x, y, z] = normal
 
   // Elevation: angle from XY plane (arcsin of z component)
   // Clamp to [-1, 1] to handle floating point errors
-  const elevation = Math.asin(Math.max(-1, Math.min(1, z))) * (180 / Math.PI);
+  const elevation = Math.asin(Math.max(-1, Math.min(1, z))) * (180 / Math.PI)
 
   // Azimuth: angle in XY plane from +Y axis
   // atan2(x, y) gives angle from +Y, which matches NiiVue's azimuth=0 = posterior (+Y)
-  let azimuth = Math.atan2(x, y) * (180 / Math.PI);
+  let azimuth = Math.atan2(x, y) * (180 / Math.PI)
   // Normalize to [0, 360)
-  azimuth = ((azimuth % 360) + 360) % 360;
+  azimuth = ((azimuth % 360) + 360) % 360
 
-  return { azimuth, elevation };
+  return { azimuth, elevation }
 }
 
 /**
@@ -132,15 +134,15 @@ export function azimuthElevationToNormal(
   azimuth: number,
   elevation: number,
 ): [number, number, number] {
-  const azRad = (azimuth * Math.PI) / 180;
-  const elRad = (elevation * Math.PI) / 180;
+  const azRad = (azimuth * Math.PI) / 180
+  const elRad = (elevation * Math.PI) / 180
 
-  const cosEl = Math.cos(elRad);
-  const x = cosEl * Math.sin(azRad);
-  const y = cosEl * Math.cos(azRad);
-  const z = Math.sin(elRad);
+  const cosEl = Math.cos(elRad)
+  const x = cosEl * Math.sin(azRad)
+  const y = cosEl * Math.cos(azRad)
+  const z = Math.sin(elRad)
 
-  return [x, y, z];
+  return [x, y, z]
 }
 
 /**
@@ -159,41 +161,43 @@ export function calculateNiivueDepth(
   plane: ClipPlane,
   volumeBounds: VolumeBounds,
 ): number {
-  const { min, max } = volumeBounds;
+  const { min, max } = volumeBounds
 
   // Volume center
   const center: [number, number, number] = [
     (min[0] + max[0]) / 2,
     (min[1] + max[1]) / 2,
     (min[2] + max[2]) / 2,
-  ];
+  ]
 
   // Volume extent
   const extent: [number, number, number] = [
     max[0] - min[0],
     max[1] - min[1],
     max[2] - min[2],
-  ];
+  ]
 
   // Signed distance from center to plane along normal
-  const { point, normal } = plane;
-  const signedDistance = normal[0] * (point[0] - center[0]) +
+  const { point, normal } = plane
+  const signedDistance =
+    normal[0] * (point[0] - center[0]) +
     normal[1] * (point[1] - center[1]) +
-    normal[2] * (point[2] - center[2]);
+    normal[2] * (point[2] - center[2])
 
   // Full extent along normal direction (using absolute value of each component)
   // This is the "width" of the bounding box when projected onto the normal direction
-  const extentAlongNormal = Math.abs(normal[0]) * extent[0] +
+  const extentAlongNormal =
+    Math.abs(normal[0]) * extent[0] +
     Math.abs(normal[1]) * extent[1] +
-    Math.abs(normal[2]) * extent[2];
+    Math.abs(normal[2]) * extent[2]
 
   // Avoid division by zero
   if (extentAlongNormal === 0) {
-    return 0;
+    return 0
   }
 
   // Normalize to NiiVue's coordinate system where volume spans -0.5 to 0.5 from center
-  return signedDistance / extentAlongNormal;
+  return signedDistance / extentAlongNormal
 }
 
 /**
@@ -221,7 +225,7 @@ export function clipPlaneToNiivue(
   plane: ClipPlane,
   volumeBounds: VolumeBounds,
 ): [number, number, number] {
-  const depth = calculateNiivueDepth(plane, volumeBounds);
+  const depth = calculateNiivueDepth(plane, volumeBounds)
 
   // Negate the normal for azimuth/elevation calculation.
   // After NiiVue adds 180° to azimuth, the shader will see our original normal.
@@ -229,14 +233,14 @@ export function clipPlaneToNiivue(
     -plane.normal[0],
     -plane.normal[1],
     -plane.normal[2],
-  ];
-  const { azimuth, elevation } = normalToAzimuthElevation(negatedNormal);
+  ]
+  const { azimuth, elevation } = normalToAzimuthElevation(negatedNormal)
 
   // Also negate the depth to be consistent with the flipped normal.
   // The plane equation dot(n, p-center) + d = 0 changes sign when n is negated.
-  const negatedDepth = -depth;
+  const negatedDepth = -depth
 
-  return [negatedDepth, azimuth, elevation];
+  return [negatedDepth, azimuth, elevation]
 }
 
 /**
@@ -250,7 +254,7 @@ export function clipPlanesToNiivue(
   clipPlanes: ClipPlanes,
   volumeBounds: VolumeBounds,
 ): number[][] {
-  return clipPlanes.map((plane) => clipPlaneToNiivue(plane, volumeBounds));
+  return clipPlanes.map((plane) => clipPlaneToNiivue(plane, volumeBounds))
 }
 
 /**
@@ -267,12 +271,12 @@ export function pointToPlaneDistance(
   testPoint: [number, number, number],
   plane: ClipPlane,
 ): number {
-  const { point, normal } = plane;
+  const { point, normal } = plane
   return (
     normal[0] * (testPoint[0] - point[0]) +
     normal[1] * (testPoint[1] - point[1]) +
     normal[2] * (testPoint[2] - point[2])
-  );
+  )
 }
 
 /**
@@ -288,10 +292,10 @@ export function isInsideClipPlanes(
 ): boolean {
   for (const plane of clipPlanes) {
     if (pointToPlaneDistance(worldCoord, plane) < 0) {
-      return false;
+      return false
     }
   }
-  return true;
+  return true
 }
 
 /**
@@ -315,58 +319,62 @@ export function clipPlanesToBoundingBox(
     return {
       min: [...volumeBounds.min],
       max: [...volumeBounds.max],
-    };
+    }
   }
 
   // Start with full volume bounds
-  let minX = volumeBounds.min[0];
-  let maxX = volumeBounds.max[0];
-  let minY = volumeBounds.min[1];
-  let maxY = volumeBounds.max[1];
-  let minZ = volumeBounds.min[2];
-  let maxZ = volumeBounds.max[2];
+  let minX = volumeBounds.min[0]
+  let maxX = volumeBounds.max[0]
+  let minY = volumeBounds.min[1]
+  let maxY = volumeBounds.max[1]
+  let minZ = volumeBounds.min[2]
+  let maxZ = volumeBounds.max[2]
 
   // For each clip plane, constrain the bounding box
   // This is an approximation: we check the 8 corners and constrain based on
   // which corners are clipped. For axis-aligned planes, this is exact.
   // For oblique planes, it's a conservative approximation.
   for (const plane of clipPlanes) {
-    const { point, normal } = plane;
+    const { point, normal } = plane
 
     // For axis-aligned normals, we can compute exact bounds
-    const absNx = Math.abs(normal[0]);
-    const absNy = Math.abs(normal[1]);
-    const absNz = Math.abs(normal[2]);
+    const absNx = Math.abs(normal[0])
+    const absNy = Math.abs(normal[1])
+    const absNz = Math.abs(normal[2])
 
     // Check if plane is approximately axis-aligned
-    const tolerance = 0.001;
+    const tolerance = 0.001
 
     if (absNx > 1 - tolerance && absNy < tolerance && absNz < tolerance) {
       // X-aligned plane
       if (normal[0] > 0) {
         // Normal points +X, clips -X side
-        minX = Math.max(minX, point[0]);
+        minX = Math.max(minX, point[0])
       } else {
         // Normal points -X, clips +X side
-        maxX = Math.min(maxX, point[0]);
+        maxX = Math.min(maxX, point[0])
       }
     } else if (
-      absNy > 1 - tolerance && absNx < tolerance && absNz < tolerance
+      absNy > 1 - tolerance &&
+      absNx < tolerance &&
+      absNz < tolerance
     ) {
       // Y-aligned plane
       if (normal[1] > 0) {
-        minY = Math.max(minY, point[1]);
+        minY = Math.max(minY, point[1])
       } else {
-        maxY = Math.min(maxY, point[1]);
+        maxY = Math.min(maxY, point[1])
       }
     } else if (
-      absNz > 1 - tolerance && absNx < tolerance && absNy < tolerance
+      absNz > 1 - tolerance &&
+      absNx < tolerance &&
+      absNy < tolerance
     ) {
       // Z-aligned plane
       if (normal[2] > 0) {
-        minZ = Math.max(minZ, point[2]);
+        minZ = Math.max(minZ, point[2])
       } else {
-        maxZ = Math.min(maxZ, point[2]);
+        maxZ = Math.min(maxZ, point[2])
       }
     } else {
       // Oblique plane - use conservative approximation
@@ -377,38 +385,30 @@ export function clipPlanesToBoundingBox(
       // Project the plane point onto each axis and use as potential bound
       // Only constrain if the plane actually intersects that face
       if (normal[0] > tolerance) {
-        minX = Math.max(minX, Math.min(point[0], maxX));
+        minX = Math.max(minX, Math.min(point[0], maxX))
       } else if (normal[0] < -tolerance) {
-        maxX = Math.min(maxX, Math.max(point[0], minX));
+        maxX = Math.min(maxX, Math.max(point[0], minX))
       }
 
       if (normal[1] > tolerance) {
-        minY = Math.max(minY, Math.min(point[1], maxY));
+        minY = Math.max(minY, Math.min(point[1], maxY))
       } else if (normal[1] < -tolerance) {
-        maxY = Math.min(maxY, Math.max(point[1], minY));
+        maxY = Math.min(maxY, Math.max(point[1], minY))
       }
 
       if (normal[2] > tolerance) {
-        minZ = Math.max(minZ, Math.min(point[2], maxZ));
+        minZ = Math.max(minZ, Math.min(point[2], maxZ))
       } else if (normal[2] < -tolerance) {
-        maxZ = Math.min(maxZ, Math.max(point[2], minZ));
+        maxZ = Math.min(maxZ, Math.max(point[2], minZ))
       }
     }
   }
 
   // Ensure valid bounds (min <= max)
   return {
-    min: [
-      Math.min(minX, maxX),
-      Math.min(minY, maxY),
-      Math.min(minZ, maxZ),
-    ],
-    max: [
-      Math.max(minX, maxX),
-      Math.max(minY, maxY),
-      Math.max(minZ, maxZ),
-    ],
-  };
+    min: [Math.min(minX, maxX), Math.min(minY, maxY), Math.min(minZ, maxZ)],
+    max: [Math.max(minX, maxX), Math.max(minY, maxY), Math.max(minZ, maxZ)],
+  }
 }
 
 /**
@@ -431,7 +431,7 @@ export function clipPlanesToPixelRegion(
   ngffImage: NgffImage,
   viewportBounds?: VolumeBounds,
 ): PixelRegion {
-  let bounds = clipPlanesToBoundingBox(clipPlanes, volumeBounds);
+  let bounds = clipPlanesToBoundingBox(clipPlanes, volumeBounds)
 
   // If viewport bounds are provided, intersect with them
   if (viewportBounds) {
@@ -446,46 +446,46 @@ export function clipPlanesToPixelRegion(
         Math.min(bounds.max[1], viewportBounds.max[1]),
         Math.min(bounds.max[2], viewportBounds.max[2]),
       ],
-    };
+    }
     // Ensure valid bounds
     for (let i = 0; i < 3; i++) {
       if (bounds.min[i] > bounds.max[i]) {
-        bounds.min[i] = bounds.max[i] = (bounds.min[i] + bounds.max[i]) * 0.5;
+        bounds.min[i] = bounds.max[i] = (bounds.min[i] + bounds.max[i]) * 0.5
       }
     }
   }
 
-  const shape = getVolumeShape(ngffImage);
+  const shape = getVolumeShape(ngffImage)
 
   // Convert world corners to pixel coordinates
   const minWorld: [number, number, number] = [
     bounds.min[0],
     bounds.min[1],
     bounds.min[2],
-  ];
+  ]
   const maxWorld: [number, number, number] = [
     bounds.max[0],
     bounds.max[1],
     bounds.max[2],
-  ];
+  ]
 
-  const minPixel = worldToPixel(minWorld, ngffImage);
-  const maxPixel = worldToPixel(maxWorld, ngffImage);
+  const minPixel = worldToPixel(minWorld, ngffImage)
+  const maxPixel = worldToPixel(maxWorld, ngffImage)
 
   // Ensure proper ordering and clamp to valid range
   const start: [number, number, number] = [
     Math.max(0, Math.floor(Math.min(minPixel[0], maxPixel[0]))),
     Math.max(0, Math.floor(Math.min(minPixel[1], maxPixel[1]))),
     Math.max(0, Math.floor(Math.min(minPixel[2], maxPixel[2]))),
-  ];
+  ]
 
   const end: [number, number, number] = [
     Math.min(shape[0], Math.ceil(Math.max(minPixel[0], maxPixel[0]))),
     Math.min(shape[1], Math.ceil(Math.max(minPixel[1], maxPixel[1]))),
     Math.min(shape[2], Math.ceil(Math.max(minPixel[2], maxPixel[2]))),
-  ];
+  ]
 
-  return { start, end };
+  return { start, end }
 }
 
 /**
@@ -502,15 +502,15 @@ export function alignToChunks(
   region: PixelRegion,
   ngffImage: NgffImage,
 ): ChunkAlignedRegion {
-  const chunkShape = getChunkShape(ngffImage);
-  const volumeShape = getVolumeShape(ngffImage);
+  const chunkShape = getChunkShape(ngffImage)
+  const volumeShape = getVolumeShape(ngffImage)
 
   // Align start down to chunk boundary
   const chunkAlignedStart: [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 chunkAlignedEnd: [number, number, number] = [
@@ -526,15 +526,16 @@ export function alignToChunks(
       Math.ceil(region.end[2] / chunkShape[2]) * chunkShape[2],
       volumeShape[2],
     ),
-  ];
+  ]
 
   // Check if alignment changed the region
-  const needsClipping = chunkAlignedStart[0] !== region.start[0] ||
+  const needsClipping =
+    chunkAlignedStart[0] !== region.start[0] ||
     chunkAlignedStart[1] !== region.start[1] ||
     chunkAlignedStart[2] !== region.start[2] ||
     chunkAlignedEnd[0] !== region.end[0] ||
     chunkAlignedEnd[1] !== region.end[1] ||
-    chunkAlignedEnd[2] !== region.end[2];
+    chunkAlignedEnd[2] !== region.end[2]
 
   return {
     start: region.start,
@@ -542,7 +543,7 @@ export function alignToChunks(
     chunkAlignedStart,
     chunkAlignedEnd,
     needsClipping,
-  };
+  }
 }
 
 /**
@@ -564,35 +565,35 @@ export function createAxisAlignedClipPlane(
   direction: "positive" | "negative",
   volumeBounds: VolumeBounds,
 ): ClipPlane {
-  const { min, max } = volumeBounds;
+  const { min, max } = volumeBounds
   const center: [number, number, number] = [
     (min[0] + max[0]) / 2,
     (min[1] + max[1]) / 2,
     (min[2] + max[2]) / 2,
-  ];
+  ]
 
-  let point: [number, number, number];
-  let normal: [number, number, number];
+  let point: [number, number, number]
+  let normal: [number, number, number]
 
   // Normal points toward the visible region
-  const sign = direction === "positive" ? 1 : -1;
+  const sign = direction === "positive" ? 1 : -1
 
   switch (axis) {
     case "x":
-      point = [position, center[1], center[2]];
-      normal = [sign, 0, 0];
-      break;
+      point = [position, center[1], center[2]]
+      normal = [sign, 0, 0]
+      break
     case "y":
-      point = [center[0], position, center[2]];
-      normal = [0, sign, 0];
-      break;
+      point = [center[0], position, center[2]]
+      normal = [0, sign, 0]
+      break
     case "z":
-      point = [center[0], center[1], position];
-      normal = [0, 0, sign];
-      break;
+      point = [center[0], center[1], position]
+      normal = [0, 0, sign]
+      break
   }
 
-  return { point, normal };
+  return { point, normal }
 }
 
 /**
@@ -605,36 +606,36 @@ export function validateClipPlanes(clipPlanes: ClipPlanes): void {
   if (clipPlanes.length > MAX_CLIP_PLANES) {
     throw new Error(
       `Too many clip planes: ${clipPlanes.length} exceeds maximum of ${MAX_CLIP_PLANES}`,
-    );
+    )
   }
 
   for (let i = 0; i < clipPlanes.length; i++) {
-    const plane = clipPlanes[i];
+    const plane = clipPlanes[i]
 
     // Check point is valid
     if (
       !Array.isArray(plane.point) ||
       plane.point.length !== 3 ||
-      plane.point.some((v) => typeof v !== "number" || !isFinite(v))
+      plane.point.some((v) => typeof v !== "number" || !Number.isFinite(v))
     ) {
-      throw new Error(`Invalid point in clip plane ${i}`);
+      throw new Error(`Invalid point in clip plane ${i}`)
     }
 
     // Check normal is valid
     if (
       !Array.isArray(plane.normal) ||
       plane.normal.length !== 3 ||
-      plane.normal.some((v) => typeof v !== "number" || !isFinite(v))
+      plane.normal.some((v) => typeof v !== "number" || !Number.isFinite(v))
     ) {
-      throw new Error(`Invalid normal in clip plane ${i}`);
+      throw new Error(`Invalid normal in clip plane ${i}`)
     }
 
     // Check normal is not zero
     const length = Math.sqrt(
       plane.normal[0] ** 2 + plane.normal[1] ** 2 + plane.normal[2] ** 2,
-    );
+    )
     if (length < 0.0001) {
-      throw new Error(`Zero-length normal in clip plane ${i}`);
+      throw new Error(`Zero-length normal in clip plane ${i}`)
     }
   }
 }