@aics/vole-core 3.15.7 → 4.0.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/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/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.0.0",
   "description": "volume renderer for 3d, 4d, or 5d imaging data with OME-Zarr support",
   "main": "es/index.js",
   "type": "module",