@aics/vole-core 3.15.7 → 4.1.0

package/es/Histogram.js

@@ -1,3 +1,4 @@
+import { isFloatTypeArray } from "./types.js";
 const NBINS = 256;
 /**
  * Builds a histogram with 256 bins from a data array. Assume data is 8 bit single channel grayscale.
@@ -59,20 +60,38 @@ export default class Histogram {
       }
     }
   }
-
-  // return the bin index of the given data value
-  static findBin(dataValue, dataMin, binSize, numBins) {
-    let binIndex = Math.floor((dataValue - dataMin) / binSize);
-    // for values that lie exactly on last bin we need to subtract one
-    if (binIndex === numBins) {
-      binIndex--;
+  static findBin(dataValue, dataMin, binSize, castToInt) {
+    const binIndex = (dataValue - dataMin) / binSize;
+    if (!castToInt) {
+      return binIndex;
     }
-    return binIndex;
+    return Math.max(Math.min(Math.floor(binIndex), NBINS - 1), 0);
   }
 
-  // return the bin index of the given data value
+  /**
+   * Returns the integer bin index for the given value. If a value is outside
+   * the histogram range, it will be clamped to the nearest bin.
+   */
   findBinOfValue(value) {
-    return Histogram.findBin(value, this.min, this.binSize, NBINS);
+    return Histogram.findBin(value, this.min, this.binSize, true);
+  }
+
+  /**
+   * Returns a fractional bin index for the given value. If a value is not a bin
+   * boundary, returns an interpolated index. Note that this can return a value
+   * outside the range of valid bins.
+   */
+  findFractionalBinOfValue(value) {
+    return Histogram.findBin(value, this.min, this.binSize, false);
+  }
+
+  /**
+   * Returns an absolute data value from a given (integer or fractional) bin index.
+   * Note that, if the bin index is outside of the bin range, the returned value
+   * will also be outside the value range.
+   */
+  getValueFromBinIndex(binIndex) {
+    return this.min + binIndex * this.binSize;
   }
 
   /**
@@ -234,10 +253,34 @@ export default class Histogram {
       }
     }
     const bins = new Uint32Array(numBins).fill(0);
-    const binSize = (max - min) / numBins === 0 ? 1 : (max - min) / numBins;
+
+    // Bins should have equal widths and span the data min to the data max. The
+    // handling of the max value is slightly different between integers and
+    // floats; in the float case, the last bin should have `max` as its
+    // inclusive upper bound, while in the integer case, the last bin should
+    // have an exclusive upper bound of `max + 1`.
+    //
+    // For example, let's say we have a data range of `[min=0, max=3]` and 4
+    // bins.
+    //
+    // If this is integer data, we want each bin to have ranges [0, 1), [1, 2),
+    // [2, 3), [3, 4), and a bin size of 1.
+    //
+    // |----|----|----|----|
+    // 0    1    2    3    4 <- exclusive
+    //
+    // For continuous (float) data, our bins should have ranges [0, 0.75),
+    // [0.75, 1.5), [1.5, 2.25), [2.25, 3] and a bin size of 0.75.
+    //
+    // |----|----|----|----|
+    // 0  0.75  1.5  2.25  3 <- inclusive
+    //
+
+    const binMax = isFloatTypeArray(arr) ? max : max + 1;
+    const binSize = binMax <= min ? 1 : (binMax - min) / numBins;
     for (let i = 0; i < arr.length; i++) {
       const item = arr[i];
-      const binIndex = Histogram.findBin(item, min, binSize, numBins);
+      const binIndex = Histogram.findBin(item, min, binSize, true);
       bins[binIndex]++;
     }
     return {

package/es/VolumeMaker.js

@@ -1,3 +1,5 @@
+import { ARRAY_CONSTRUCTORS } from "./types.js";
+
 /**
  * Basic utility functions to create sample volume data
  * @class
@@ -9,9 +11,11 @@ export default class VolumeMaker {
    * @param {number} vy
    * @param {number} vz
    * @param {function} sdFunc A function f(x,y,z) that returns a distance. f < 0 will be the interior of the volume, and f>=0 will be outside.
+   * @param {NumberType} dtype The data type for the output array
    */
-  static createVolume(vx, vy, vz, sdFunc) {
-    const data = new Uint8Array(vx * vy * vz).fill(0);
+  static createVolume(vx, vy, vz, sdFunc, dtype = "uint8") {
+    const ctor = ARRAY_CONSTRUCTORS[dtype];
+    const data = new ctor(vx * vy * vz).fill(0);
     const cx = vx / 2;
     const cy = vy / 2;
     const cz = vz / 2;
@@ -40,11 +44,12 @@ export default class VolumeMaker {
    * @param {number} vy
    * @param {number} vz
    * @param {number} radius
+   * @param {NumberType} dtype The data type for the output array
    */
-  static createSphere(vx, vy, vz, radius) {
+  static createSphere(vx, vy, vz, radius, dtype = "uint8") {
     return VolumeMaker.createVolume(vx, vy, vz, (px, py, pz) => {
       return Math.sqrt(px * px + py * py + pz * pz) - radius;
-    });
+    }, dtype);
   }
 
   /**
@@ -54,8 +59,9 @@ export default class VolumeMaker {
    * @param {number} vz
    * @param {number} hx width of cap (?)
    * @param {number} hy depth of cap (?)
+   * @param {NumberType} dtype The data type for the output array
    */
-  static createCylinder(vx, vy, vz, hx, hy) {
+  static createCylinder(vx, vy, vz, hx, hy, dtype = "uint8") {
     let dx, dy, mdx, mdy;
     return VolumeMaker.createVolume(vx, vy, vz, (px, py, pz) => {
       dx = Math.abs(Math.sqrt(px * px + pz * pz)) - hx;
@@ -63,7 +69,7 @@ export default class VolumeMaker {
       mdx = Math.max(dx, 0.0);
       mdy = Math.max(dy, 0.0);
       return Math.min(Math.max(dx, dy), 0.0) + Math.sqrt(mdx * mdx + mdy * mdy);
-    });
+    }, dtype);
   }
 
   /**
@@ -73,14 +79,15 @@ export default class VolumeMaker {
    * @param {number} vz
    * @param {number} tx inner radius
    * @param {number} ty outer radius
+   * @param {NumberType} dtype The data type for the output array
    */
-  static createTorus(vx, vy, vz, tx, ty) {
+  static createTorus(vx, vy, vz, tx, ty, dtype = "uint8") {
     let qx, qy;
     return VolumeMaker.createVolume(vx, vy, vz, (px, py, pz) => {
       qx = Math.sqrt(px * px + pz * pz) - tx;
       qy = py;
       return Math.sqrt(qx * qx + qy * qy) - ty;
-    });
+    }, dtype);
   }
 
   /**
@@ -90,12 +97,30 @@ export default class VolumeMaker {
    * @param {number} vz
    * @param {number} cx base radius
    * @param {number} cy height
+   * @param {NumberType} dtype The data type for the output array
    */
-  static createCone(vx, vy, vz, cx, cy) {
+  static createCone(vx, vy, vz, cx, cy, dtype = "uint8") {
     let q;
     return VolumeMaker.createVolume(vx, vy, vz, (px, py, pz) => {
       q = Math.sqrt(px * px + py * py);
       return cx * q + cy * pz;
-    });
+    }, dtype);
+  }
+
+  // take a list of TypedArrays and concatenate them into a single TypedArray of the same Type:
+  static concatenateArrays(arrays, dtype) {
+    if (arrays.length === 0) {
+      throw new Error("Cannot concatenate empty array list");
+    }
+    const totalLength = arrays.reduce((acc, arr) => acc + arr.length, 0);
+
+    // Create a new array of the same type as the input arrays
+    const result = new ARRAY_CONSTRUCTORS[dtype](totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+      result.set(arr, offset);
+      offset += arr.length;
+    }
+    return result;
   }
 }

package/es/loaders/RawArrayLoader.js

@@ -1,6 +1,7 @@
 import { Box3, Vector3 } from "three";
 import { ThreadableVolumeLoader } from "./IVolumeLoader.js";
 import { computePackedAtlasDims } from "./VolumeLoaderUtils.js";
+import { ARRAY_CONSTRUCTORS } from "../types.js";
 import { getDataRange } from "../utils/num_utils.js";
 
 // this is the form in which a 4D numpy array arrives as converted
@@ -9,7 +10,25 @@ import { getDataRange } from "../utils/num_utils.js";
 
 // minimal metadata for visualization
 
-const convertImageInfo = json => {
+function getBytesPerPixel(dtype) {
+  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}`);
+  }
+}
+const convertImageInfo = (json, dtype) => {
   const atlasTileDims = computePackedAtlasDims(json.sizeZ, json.sizeX, json.sizeY);
   return {
     name: json.name,
@@ -27,7 +46,7 @@ const convertImageInfo = json => {
       spacing: [1, 1, json.physicalPixelSize[2], json.physicalPixelSize[1], json.physicalPixelSize[0]],
       spaceUnit: json.spatialUnit || "μm",
       timeUnit: "s",
-      dataType: "uint8"
+      dataType: dtype
     }],
     transform: {
       translation: [0, 0, 0],
@@ -53,14 +72,14 @@ class RawArrayLoader extends ThreadableVolumeLoader {
       shape: [1, jsonInfo.sizeC, jsonInfo.sizeZ, jsonInfo.sizeY, jsonInfo.sizeX],
       spacing: [1, 1, jsonInfo.physicalPixelSize[2], jsonInfo.physicalPixelSize[1], jsonInfo.physicalPixelSize[0]],
       spaceUnit: jsonInfo.spatialUnit || "μm",
-      dataType: "uint8",
+      dataType: this.data.dtype,
       timeUnit: "s" // time unit not specified
     };
     return [d];
   }
   async createImageInfo(loadSpec) {
     return {
-      imageInfo: convertImageInfo(this.jsonInfo),
+      imageInfo: convertImageInfo(this.jsonInfo, this.data.dtype),
       loadSpec
     };
   }
@@ -77,11 +96,12 @@ class RawArrayLoader extends ThreadableVolumeLoader {
       if (requestedChannels && requestedChannels.length > 0 && !requestedChannels.includes(chindex)) {
         continue;
       }
-      const volSizeBytes = this.data.shape[3] * this.data.shape[2] * this.data.shape[1]; // x*y*z pixels * 1 byte/pixel
-      const channelData = new Uint8Array(this.data.buffer.buffer, chindex * volSizeBytes, volSizeBytes);
+      // x*y*z pixels
+      const volSizePixels = this.data.shape[3] * this.data.shape[2] * this.data.shape[1];
+      const ctor = ARRAY_CONSTRUCTORS[this.data.dtype];
+      const channelData = new ctor(this.data.buffer.buffer, chindex * volSizePixels * getBytesPerPixel(this.data.dtype), volSizePixels);
       const range = getDataRange(channelData);
-      // all data coming from this loader is natively 8-bit
-      onData([chindex], ["uint8"], [channelData], [range]);
+      onData([chindex], [this.data.dtype], [channelData], [range]);
     }
     return Promise.resolve();
   }

package/es/types/Histogram.d.ts

@@ -1,4 +1,4 @@
-import type { TypedArray, NumberType } from "./types.js";
+import { type TypedArray, type NumberType } from "./types.js";
 /**
  * Builds a histogram with 256 bins from a data array. Assume data is 8 bit single channel grayscale.
  * @class
@@ -19,8 +19,24 @@ export default class Histogram {
     private pixelCount;
     maxBin: number;
     constructor(data: TypedArray<NumberType>);
-    static findBin(dataValue: number, dataMin: number, binSize: number, numBins: number): number;
+    private static findBin;
+    /**
+     * Returns the integer bin index for the given value. If a value is outside
+     * the histogram range, it will be clamped to the nearest bin.
+     */
     findBinOfValue(value: number): number;
+    /**
+     * Returns a fractional bin index for the given value. If a value is not a bin
+     * boundary, returns an interpolated index. Note that this can return a value
+     * outside the range of valid bins.
+     */
+    findFractionalBinOfValue(value: number): number;
+    /**
+     * Returns an absolute data value from a given (integer or fractional) bin index.
+     * Note that, if the bin index is outside of the bin range, the returned value
+     * will also be outside the value range.
+     */
+    getValueFromBinIndex(binIndex: number): number;
     /**
      * Return the min data value
      * @return {number}

package/es/types/VolumeMaker.d.ts

@@ -1,3 +1,4 @@
+import { type NumberType, type TypedArray } from "./types.js";
 /**
  * Basic utility functions to create sample volume data
  * @class
@@ -9,16 +10,18 @@ export default class VolumeMaker {
      * @param {number} vy
      * @param {number} vz
      * @param {function} sdFunc A function f(x,y,z) that returns a distance. f < 0 will be the interior of the volume, and f>=0 will be outside.
+     * @param {NumberType} dtype The data type for the output array
      */
-    static createVolume(vx: number, vy: number, vz: number, sdFunc: (px: number, py: number, pz: number) => number): Uint8Array;
+    static createVolume(vx: number, vy: number, vz: number, sdFunc: (px: number, py: number, pz: number) => number, dtype?: NumberType): TypedArray<NumberType>;
     /**
      * Create a volume filled with a sphere in the center
      * @param {number} vx
      * @param {number} vy
      * @param {number} vz
      * @param {number} radius
+     * @param {NumberType} dtype The data type for the output array
      */
-    static createSphere(vx: number, vy: number, vz: number, radius: number): Uint8Array;
+    static createSphere(vx: number, vy: number, vz: number, radius: number, dtype?: NumberType): TypedArray<NumberType>;
     /**
      * Create a volume with a cylinder centered inside.
      * @param {number} vx
@@ -26,8 +29,9 @@ export default class VolumeMaker {
      * @param {number} vz
      * @param {number} hx width of cap (?)
      * @param {number} hy depth of cap (?)
+     * @param {NumberType} dtype The data type for the output array
      */
-    static createCylinder(vx: number, vy: number, vz: number, hx: number, hy: number): Uint8Array;
+    static createCylinder(vx: number, vy: number, vz: number, hx: number, hy: number, dtype?: NumberType): TypedArray<NumberType>;
     /**
      * Create a volume with a torus centered inside
      * @param {number} vx
@@ -35,8 +39,9 @@ export default class VolumeMaker {
      * @param {number} vz
      * @param {number} tx inner radius
      * @param {number} ty outer radius
+     * @param {NumberType} dtype The data type for the output array
      */
-    static createTorus(vx: number, vy: number, vz: number, tx: number, ty: number): Uint8Array;
+    static createTorus(vx: number, vy: number, vz: number, tx: number, ty: number, dtype?: NumberType): TypedArray<NumberType>;
     /**
      * Create a volume with a cone centered inside.  cx, cy must be a 2d normalized pair...?
      * @param {number} vx
@@ -44,6 +49,8 @@ export default class VolumeMaker {
      * @param {number} vz
      * @param {number} cx base radius
      * @param {number} cy height
+     * @param {NumberType} dtype The data type for the output array
      */
-    static createCone(vx: number, vy: number, vz: number, cx: number, cy: number): Uint8Array;
+    static createCone(vx: number, vy: number, vz: number, cx: number, cy: number, dtype?: NumberType): TypedArray<NumberType>;
+    static concatenateArrays(arrays: TypedArray<NumberType>[], dtype: NumberType): TypedArray<NumberType>;
 }

package/es/types/index.d.ts

@@ -8,7 +8,7 @@ import RequestQueue from "./utils/RequestQueue.js";
 import SubscribableRequestQueue from "./utils/SubscribableRequestQueue.js";
 import Histogram from "./Histogram.js";
 import { Lut, remapControlPoints } from "./Lut.js";
-import { type ColorizeFeature, ViewportCorner } from "./types.js";
+import { type ColorizeFeature, type NumberType, ViewportCorner } from "./types.js";
 import { VolumeFileFormat, createVolumeLoader, PrefetchDirection } from "./loaders/index.js";
 import { LoadSpec } from "./loaders/IVolumeLoader.js";
 import { OMEZarrLoader } from "./loaders/OmeZarrLoader.js";
@@ -26,4 +26,4 @@ export type { CreateLoaderOptions } from "./loaders/index.js";
 export type { IVolumeLoader, PerChannelCallback, ThreadableVolumeLoader } from "./loaders/IVolumeLoader.js";
 export type { ZarrLoaderFetchOptions } from "./loaders/OmeZarrLoader.js";
 export type { WorkerLoader } from "./workers/VolumeLoaderContext.js";
-export { Histogram, Lut, Line3d, remapControlPoints, View3d, Volume, VolumeDrawable, LoadSpec, VolumeMaker, VolumeCache, RequestQueue, SubscribableRequestQueue, PrefetchDirection, OMEZarrLoader, JsonImageInfoLoader, RawArrayLoader, type RawArrayData, type RawArrayInfo, type RawArrayLoaderOptions, TiffLoader, VolumeLoaderContext, VolumeLoadError, VolumeLoadErrorType, VolumeFileFormat, createVolumeLoader, Channel, Light, ViewportCorner, AREA_LIGHT, RENDERMODE_PATHTRACE, RENDERMODE_RAYMARCH, SKY_LIGHT, type CameraState, type ColorizeFeature, };
+export { Histogram, Lut, Line3d, remapControlPoints, View3d, Volume, VolumeDrawable, LoadSpec, VolumeMaker, VolumeCache, RequestQueue, SubscribableRequestQueue, PrefetchDirection, OMEZarrLoader, JsonImageInfoLoader, RawArrayLoader, type RawArrayData, type RawArrayInfo, type RawArrayLoaderOptions, TiffLoader, VolumeLoaderContext, VolumeLoadError, VolumeLoadErrorType, VolumeFileFormat, createVolumeLoader, Channel, Light, ViewportCorner, AREA_LIGHT, RENDERMODE_PATHTRACE, RENDERMODE_RAYMARCH, SKY_LIGHT, type CameraState, type ColorizeFeature, type NumberType, };

package/es/types/loaders/RawArrayLoader.d.ts

@@ -1,9 +1,9 @@
 import { ThreadableVolumeLoader, type LoadSpec, type RawChannelDataCallback, type LoadedVolumeInfo } from "./IVolumeLoader.js";
 import type { ImageInfo } from "../ImageInfo.js";
 import type { VolumeDims } from "../VolumeDims.js";
-import { Uint8 } from "../types.js";
+import { NumberType } from "../types.js";
 export type RawArrayData = {
-    dtype: Uint8;
+    dtype: NumberType;
     shape: [number, number, number, number];
     buffer: DataView;
 };

package/es/types/types.d.ts

@@ -27,6 +27,7 @@ export declare const ARRAY_CONSTRUCTORS: {
     float32: Float32ArrayConstructor;
     float64: Float64ArrayConstructor;
 };
+export declare function isFloatTypeArray(array: TypedArray<NumberType>): array is Float32Array | Float64Array;
 export interface ColorizeFeature {
     idsToFeatureValue: DataTexture;
     featureValueToColor: DataTexture;

package/es/types.js

@@ -13,6 +13,9 @@ export const ARRAY_CONSTRUCTORS = {
   float32: Float32Array,
   float64: Float64Array
 };
+export function isFloatTypeArray(array) {
+  return array instanceof Float32Array || array instanceof Float64Array;
+}
 /** If `FuseChannel.rgbColor` is this value, it is disabled from fusion. */
 export const FUSE_DISABLED_RGB_COLOR = 0;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aics/vole-core",
-  "version": "3.15.7",
+  "version": "4.1.0",
   "description": "volume renderer for 3d, 4d, or 5d imaging data with OME-Zarr support",
   "main": "es/index.js",
   "type": "module",