@fideus-labs/fidnii 0.2.0 → 0.4.0

package/src/ResolutionSelector.ts

@@ -93,51 +93,67 @@ export function selectResolution(
 }
 
 /**
- * Get the chunk shape for a volume.
+ * Get the chunk shape for a volume as [z, y, x].
+ *
+ * Looks up `"z"`, `"y"`, `"x"` dimensions by name. If `"z"` is absent
+ * (e.g., 2D images with `dims=["y", "x"]` or `["y", "x", "c"]`),
+ * the z chunk size defaults to 1. Non-spatial dimensions like `"c"` and
+ * `"t"` are ignored.
  *
  * @param ngffImage - The NgffImage to get chunk shape from
  * @returns Chunk shape as [z, y, x]
+ * @throws If neither `"y"` nor `"x"` can be found in dims
  */
 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]
+  if (yIdx === -1 || xIdx === -1) {
+    throw new Error(
+      `Cannot determine chunk shape: dims=[${dims.join(",")}] ` +
+        `is missing required "y" and/or "x" axes`,
+    )
   }
 
-  return [chunks[zIdx], chunks[yIdx], chunks[xIdx]]
+  const zIdx = dims.indexOf("z")
+  const cz = zIdx !== -1 ? chunks[zIdx] : 1
+
+  return [cz, chunks[yIdx], chunks[xIdx]]
 }
 
 /**
- * Get the shape of a volume as [z, y, x].
+ * Get the spatial shape of a volume as [z, y, x].
+ *
+ * Looks up `"z"`, `"y"`, `"x"` dimensions by name. If `"z"` is absent
+ * (e.g., 2D images with `dims=["y", "x"]` or `["y", "x", "c"]`),
+ * the z size defaults to 1. Non-spatial dimensions like `"c"` and
+ * `"t"` are ignored.
  *
  * @param ngffImage - The NgffImage
  * @returns Shape as [z, y, x]
+ * @throws If neither `"y"` nor `"x"` can be found in dims
  */
 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]
+  if (yIdx === -1 || xIdx === -1) {
+    throw new Error(
+      `Cannot determine volume shape: dims=[${dims.join(",")}] ` +
+        `is missing required "y" and/or "x" axes`,
+    )
   }
 
-  return [shape[zIdx], shape[yIdx], shape[xIdx]]
+  const zIdx = dims.indexOf("z")
+  const sz = zIdx !== -1 ? shape[zIdx] : 1
+
+  return [sz, shape[yIdx], shape[xIdx]]
 }
 
 /**

package/src/fromTiff.ts

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+/**
+ * Load TIFF files (OME-TIFF, pyramidal, plain) and produce a
+ * {@link Multiscales} object ready for {@link OMEZarrNVImage.create}.
+ *
+ * Uses {@link https://github.com/fideus-labs/fiff | @fideus-labs/fiff}
+ * to present TIFFs as zarrita-compatible stores, then delegates to
+ * {@link fromNgffZarr} for OME-Zarr metadata parsing.
+ */
+
+import type { TiffStoreOptions } from "@fideus-labs/fiff"
+import { TiffStore } from "@fideus-labs/fiff"
+import type { Multiscales } from "@fideus-labs/ngff-zarr"
+import type { FromNgffZarrOptions } from "@fideus-labs/ngff-zarr/browser"
+import { fromNgffZarr } from "@fideus-labs/ngff-zarr/browser"
+import type { Readable } from "zarrita"
+
+/** Options for {@link fromTiff}. */
+export interface FromTiffOptions {
+  /** Options forwarded to {@link TiffStore} (e.g. IFD offsets, HTTP headers). */
+  tiff?: TiffStoreOptions
+  /** Options forwarded to {@link fromNgffZarr} (e.g. validate, cache). */
+  ngffZarr?: Omit<FromNgffZarrOptions, "version">
+}
+
+/**
+ * Load a TIFF file and return a {@link Multiscales} object ready for
+ * {@link OMEZarrNVImage.create}.
+ *
+ * Supports OME-TIFF, pyramidal TIFF (SubIFDs / legacy / COG), and
+ * plain single-image TIFFs. Both local (Blob/ArrayBuffer) and
+ * remote (URL with HTTP range requests) sources are supported.
+ *
+ * @param source - A URL string, Blob/File, ArrayBuffer, or
+ *   pre-built {@link TiffStore}.
+ * @param options - Optional {@link FromTiffOptions}.
+ * @returns A {@link Multiscales} object for use with
+ *   {@link OMEZarrNVImage.create}.
+ * @throws If the source cannot be opened as a TIFF or if the
+ *   synthesized OME-Zarr metadata is invalid.
+ *
+ * @example
+ * ```typescript
+ * // From a remote URL
+ * const ms = await fromTiff("https://example.com/image.ome.tif")
+ * const image = await OMEZarrNVImage.create({
+ *   multiscales: ms,
+ *   niivue: nv,
+ * })
+ *
+ * // From a File input
+ * const file = inputElement.files[0]
+ * const ms = await fromTiff(file)
+ * ```
+ */
+export async function fromTiff(
+  source: string | Blob | ArrayBuffer | TiffStore,
+  options: FromTiffOptions = {},
+): Promise<Multiscales> {
+  let store: TiffStore
+  if (source instanceof TiffStore) {
+    store = source
+  } else if (typeof source === "string") {
+    store = await TiffStore.fromUrl(source, options.tiff)
+  } else if (source instanceof Blob) {
+    store = await TiffStore.fromBlob(source, options.tiff)
+  } else if (source instanceof ArrayBuffer) {
+    store = await TiffStore.fromArrayBuffer(source, options.tiff)
+  } else {
+    throw new Error(
+      "[fidnii] fromTiff: source must be a URL string, Blob, " +
+        "ArrayBuffer, or TiffStore",
+    )
+  }
+
+  // TiffStore implements zarrita's Readable interface structurally
+  // (its get() method accepts string keys including the leading "/"
+  // that zarrita uses for AbsolutePath). Since fromNgffZarr (v0.10+)
+  // accepts zarr.Readable directly, we only need a type assertion.
+  //
+  // TiffStore always produces OME-Zarr v0.5 metadata.
+  return fromNgffZarr(store as unknown as Readable, {
+    version: "0.5",
+    ...options.ngffZarr,
+  })
+}

package/src/index.ts

@@ -34,10 +34,15 @@
  * ```
  */
 
+export type { TiffStoreOptions } from "@fideus-labs/fiff"
+export { TiffStore } from "@fideus-labs/fiff"
 // Re-export Methods enum so consumers can check isLabelImage or compare method values
 export { Methods } from "@fideus-labs/ngff-zarr"
 // Worker pool lifecycle (re-exported from ngff-zarr)
-export { terminateWorkerPool } from "@fideus-labs/ngff-zarr/browser"
+export {
+  terminateOmeroWorkerPool,
+  terminateWorkerPool,
+} from "@fideus-labs/ngff-zarr/browser"
 
 // Buffer manager
 export { BufferManager } from "./BufferManager.js"
@@ -69,10 +74,16 @@ export type {
 } from "./events.js"
 // Event system (browser-native EventTarget API)
 export { OMEZarrNVImageEvent } from "./events.js"
+export type { FromTiffOptions } from "./fromTiff.js"
+// TIFF support (via @fideus-labs/fiff)
+export { fromTiff } from "./fromTiff.js"
+// RGB normalization utilities
+export type { ChannelWindow } from "./normalize.js"
+export { computeChannelMinMax, normalizeToUint8 } from "./normalize.js"
 // Main class
 export { OMEZarrNVImage } from "./OMEZarrNVImage.js"
 // Region coalescer
-export { RegionCoalescer } from "./RegionCoalescer.js"
+export { buildSelection, RegionCoalescer } from "./RegionCoalescer.js"
 export type { OrthogonalAxis } from "./ResolutionSelector.js"
 // Resolution selector utilities
 export {
@@ -88,6 +99,7 @@ export {
 // Types
 export type {
   AttachedNiivueState,
+  ChannelInfo,
   ChunkAlignedRegion,
   ChunkCache,
   ClipPlane,
@@ -106,9 +118,13 @@ export type {
 // Type utilities
 export {
   getBytesPerPixel,
+  getChannelInfo,
   getNiftiDataType,
+  getRGBNiftiDataType,
   getTypedArrayConstructor,
+  isRGBImage,
   NiftiDataType,
+  needsRGBNormalization,
   parseZarritaDtype,
   SLICE_TYPE,
 } from "./types.js"

package/src/normalize.ts

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
+// SPDX-License-Identifier: MIT
+
+import type { TypedArray } from "./types.js"
+
+/**
+ * Per-channel display window for normalization.
+ * Maps source values in `[start, end]` to uint8 `[0, 255]`.
+ */
+export interface ChannelWindow {
+  /** Lower bound of the display window (maps to 0) */
+  start: number
+  /** Upper bound of the display window (maps to 255) */
+  end: number
+}
+
+/**
+ * Normalize interleaved multi-component data to uint8.
+ *
+ * Each channel is linearly mapped from its `[start, end]` window to
+ * `[0, 255]`, with clamping at both ends. Source data is expected to
+ * be interleaved: `[R0, G0, B0, R1, G1, B1, ...]`.
+ *
+ * @param source - Interleaved multi-component data in any typed array
+ * @param components - Number of components per voxel (3 for RGB, 4 for RGBA)
+ * @param channelWindows - Per-channel display windows; must have
+ *   `components` entries. If fewer are provided, remaining channels use
+ *   the last window.
+ * @returns A new `Uint8Array` with normalized uint8 values
+ *
+ * @example
+ * ```ts
+ * const src = new Uint16Array([0, 32768, 65535, 0, 0, 0])
+ * const windows = [
+ *   { start: 0, end: 65535 },
+ *   { start: 0, end: 65535 },
+ *   { start: 0, end: 65535 },
+ * ]
+ * const result = normalizeToUint8(src, 3, windows)
+ * // result ≈ Uint8Array [0, 128, 255, 0, 0, 0]
+ * ```
+ */
+export function normalizeToUint8(
+  source: TypedArray,
+  components: number,
+  channelWindows: ChannelWindow[],
+): Uint8Array {
+  const len = source.length
+  const output = new Uint8Array(len)
+  const numVoxels = len / components
+
+  // Pre-compute per-channel scale factors for performance
+  const scales = new Float64Array(components)
+  const offsets = new Float64Array(components)
+  for (let c = 0; c < components; c++) {
+    const win = channelWindows[Math.min(c, channelWindows.length - 1)]
+    const range = win.end - win.start
+    if (range > 0) {
+      scales[c] = 255 / range
+      offsets[c] = win.start
+    } else {
+      // Degenerate window: all values map to 0
+      scales[c] = 0
+      offsets[c] = 0
+    }
+  }
+
+  for (let v = 0; v < numVoxels; v++) {
+    const base = v * components
+    for (let c = 0; c < components; c++) {
+      const scaled = (source[base + c] - offsets[c]) * scales[c]
+      // Clamp to [0, 255] and round
+      output[base + c] =
+        scaled <= 0 ? 0 : scaled >= 255 ? 255 : (scaled + 0.5) | 0
+    }
+  }
+
+  return output
+}
+
+/**
+ * Compute per-channel min/max from interleaved multi-component data.
+ *
+ * Use this as a fallback when OMERO window metadata is not available.
+ * The result can be passed directly to {@link normalizeToUint8}.
+ *
+ * @param data - Interleaved multi-component data
+ * @param components - Number of components per voxel (3 for RGB, 4 for RGBA)
+ * @returns Per-channel windows with `start = min` and `end = max`
+ */
+export function computeChannelMinMax(
+  data: TypedArray,
+  components: number,
+): ChannelWindow[] {
+  const windows: ChannelWindow[] = Array.from({ length: components }, () => ({
+    start: Infinity,
+    end: -Infinity,
+  }))
+
+  const numVoxels = data.length / components
+  for (let v = 0; v < numVoxels; v++) {
+    const base = v * components
+    for (let c = 0; c < components; c++) {
+      const val = data[base + c]
+      if (val < windows[c].start) windows[c].start = val
+      if (val > windows[c].end) windows[c].end = val
+    }
+  }
+
+  // Handle empty data: set degenerate windows to [0, 0]
+  for (let c = 0; c < components; c++) {
+    if (windows[c].start === Infinity) {
+      windows[c].start = 0
+      windows[c].end = 0
+    }
+  }
+
+  return windows
+}

package/src/types.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) Fideus Labs LLC
 // SPDX-License-Identifier: MIT
 
-import type { Multiscales } from "@fideus-labs/ngff-zarr"
+import type { Multiscales, NgffImage } from "@fideus-labs/ngff-zarr"
 import type { Niivue, NVImage } from "@niivue/niivue"
 import { SLICE_TYPE } from "@niivue/niivue"
 
@@ -154,6 +154,17 @@ export interface OMEZarrNVImageOptions {
    * @see {@link ChunkCache}
    */
   cache?: ChunkCache
+  /**
+   * Flip the y-axis in the NIfTI affine for 2D images (default: true).
+   *
+   * 2D images (e.g., PNGs converted to OME-Zarr) store pixel data with
+   * y=0 at the top (increasing downward). NiiVue expects a negative
+   * y-scale in the affine to render these right-side up. Set to `false`
+   * if your 2D data already has bottom-to-top y ordering.
+   *
+   * This option has no effect on 3D volumes (images with a `"z"` axis).
+   */
+  flipY2D?: boolean
 }
 
 /**
@@ -307,14 +318,97 @@ export const NiftiDataType = {
   INT32: 8,
   FLOAT32: 16,
   FLOAT64: 64,
+  RGB24: 128,
   INT8: 256,
   UINT16: 512,
   UINT32: 768,
+  RGBA32: 2304,
 } as const
 
 export type NiftiDataTypeCode =
   (typeof NiftiDataType)[keyof typeof NiftiDataType]
 
+/**
+ * Information about a channel (component) dimension in the image.
+ */
+export interface ChannelInfo {
+  /** Index of the `"c"` dimension in `ngffImage.dims` */
+  channelAxis: number
+  /** Number of components (e.g. 3 for RGB, 4 for RGBA) */
+  components: number
+}
+
+/**
+ * Detect whether an NgffImage has a channel (`"c"`) dimension.
+ *
+ * @param ngffImage - The NgffImage to inspect
+ * @returns Channel information, or `null` if no `"c"` dimension exists
+ */
+export function getChannelInfo(ngffImage: NgffImage): ChannelInfo | null {
+  const channelAxis = ngffImage.dims.indexOf("c")
+  if (channelAxis === -1) return null
+  const components = ngffImage.data.shape[channelAxis]
+  return { channelAxis, components }
+}
+
+/**
+ * Check whether an NgffImage represents an RGB or RGBA image.
+ *
+ * An image is considered RGB/RGBA when it has a `"c"` dimension with
+ * 3 or 4 components. Any dtype is supported — non-uint8 data is
+ * normalized to uint8 at load time (see {@link needsRGBNormalization}).
+ *
+ * @param ngffImage - The NgffImage to inspect
+ * @returns `true` if the image is RGB (3 components) or RGBA (4 components)
+ */
+export function isRGBImage(ngffImage: NgffImage): boolean {
+  const info = getChannelInfo(ngffImage)
+  if (!info) return false
+  return info.components === 3 || info.components === 4
+}
+
+/**
+ * Check whether a multi-component RGB/RGBA image needs normalization
+ * to uint8 before NiiVue can render it.
+ *
+ * NiiVue only supports `DT_RGB24` (3×uint8) and `DT_RGBA32` (4×uint8)
+ * color rendering. Non-uint8 multi-component images must be normalized
+ * to uint8 using OMERO window metadata (or computed min/max).
+ *
+ * @param ngffImage - The NgffImage to inspect
+ * @param dtype - The parsed zarr dtype
+ * @returns `true` if the image is RGB/RGBA with a non-uint8 dtype
+ */
+export function needsRGBNormalization(
+  ngffImage: NgffImage,
+  dtype: ZarrDtype,
+): boolean {
+  return isRGBImage(ngffImage) && dtype !== "uint8"
+}
+
+/**
+ * Get the NIfTI data type code for a multi-component image.
+ *
+ * Returns `RGB24` for 3 components and `RGBA32` for 4 components,
+ * regardless of the source dtype. Non-uint8 data is normalized to
+ * uint8 at load time before being stored in the NVImage buffer.
+ *
+ * @param channelInfo - Channel information from `getChannelInfo()`
+ * @returns The NIfTI data type code (`RGB24` or `RGBA32`)
+ * @throws If the component count is not 3 or 4
+ */
+export function getRGBNiftiDataType(
+  channelInfo: ChannelInfo,
+): NiftiDataTypeCode {
+  if (channelInfo.components === 3) return NiftiDataType.RGB24
+  if (channelInfo.components === 4) return NiftiDataType.RGBA32
+  throw new Error(
+    `Unsupported multi-component image: ` +
+      `components=${channelInfo.components}. ` +
+      `Only 3 (RGB) or 4 (RGBA) components are supported.`,
+  )
+}
+
 /**
  * Map zarr dtype to typed array constructor.
  */

package/src/utils/coordinates.ts

@@ -135,23 +135,24 @@ export function normalizedToWorld(
   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")
 
-  let dimX: number, dimY: number, dimZ: number
-  if (zIdx === -1 || yIdx === -1 || xIdx === -1) {
-    const n = shape.length
-    dimZ = shape[n - 3] || 1
-    dimY = shape[n - 2] || 1
-    dimX = shape[n - 1] || 1
-  } else {
-    dimZ = shape[zIdx]
-    dimY = shape[yIdx]
-    dimX = shape[xIdx]
+  if (yIdx === -1 || xIdx === -1) {
+    const missingAxes = [xIdx === -1 ? "x" : null, yIdx === -1 ? "y" : null]
+      .filter((axis): axis is string => axis !== null)
+      .join(", ")
+    throw new Error(
+      `NgffImage is missing required spatial dimension(s): ${missingAxes}`,
+    )
   }
 
+  // Look up spatial dimensions by name; default z to 1 for 2D images
+  const zIdx = dims.indexOf("z")
+  const dimZ = zIdx !== -1 ? shape[zIdx] : 1
+  const dimY = shape[yIdx]
+  const dimX = shape[xIdx]
+
   // Convert normalized to pixel
   const pixelCoord: [number, number, number] = [
     normalizedCoord[2] * dimZ, // z
@@ -176,23 +177,24 @@ export function worldToNormalized(
   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")
 
-  let dimX: number, dimY: number, dimZ: number
-  if (zIdx === -1 || yIdx === -1 || xIdx === -1) {
-    const n = shape.length
-    dimZ = shape[n - 3] || 1
-    dimY = shape[n - 2] || 1
-    dimX = shape[n - 1] || 1
-  } else {
-    dimZ = shape[zIdx]
-    dimY = shape[yIdx]
-    dimX = shape[xIdx]
+  if (yIdx === -1 || xIdx === -1) {
+    const missingAxes = [xIdx === -1 ? "x" : null, yIdx === -1 ? "y" : null]
+      .filter((axis): axis is string => axis !== null)
+      .join(", ")
+    throw new Error(
+      `NgffImage is missing required spatial dimension(s): ${missingAxes}`,
+    )
   }
 
+  // Look up spatial dimensions by name; default z to 1 for 2D images
+  const zIdx = dims.indexOf("z")
+  const dimZ = zIdx !== -1 ? shape[zIdx] : 1
+  const dimY = shape[yIdx]
+  const dimX = shape[xIdx]
+
   // Convert world to pixel
   const pixelCoord = worldToPixel(worldCoord, ngffImage)