@aics/vole-core 3.12.4

package/es/Volume.js

@@ -0,0 +1,352 @@
+import { Vector3 } from "three";
+import Channel from "./Channel.js";
+import { getColorByChannelIndex } from "./constants/colors.js";
+import { LoadSpec } from "./loaders/IVolumeLoader.js";
+import { MAX_ATLAS_EDGE, pickLevelToLoadUnscaled } from "./loaders/VolumeLoaderUtils.js";
+import { CImageInfo, defaultImageInfo } from "./ImageInfo.js";
+/**
+ * A renderable multichannel volume image with 8-bits per channel intensity values.
+ * @class
+ * @param {ImageInfo} imageInfo
+ */
+export default class Volume {
+  /** `LoadSpec` representing the minimum data required to display what's in the viewer (subregion, channels, etc.).
+   * Used to intelligently issue load requests whenever required by a state change. Modify with `updateRequiredData`.
+   */
+
+  /** The maximum of the measurements of 3 axes in physical units (pixels*physicalSize) */
+
+  /** The physical size of a voxel in the original level 0 volume */
+
+  /** The physical dims of the whole volume (not accounting for subregion) */
+
+  /** Normalized physical size of the whole volume (not accounting for subregion) */
+
+  constructor(imageInfo = defaultImageInfo(), loadSpec = new LoadSpec(), loader) {
+    this.loaded = false;
+    this.imageInfo = new CImageInfo(imageInfo);
+    // TODO: use getter?
+    this.name = imageInfo.name;
+    this.loadSpec = {
+      // Fill in defaults for optional properties
+      multiscaleLevel: 0,
+      scaleLevelBias: 0,
+      maxAtlasEdge: MAX_ATLAS_EDGE,
+      channels: Array.from({
+        length: this.imageInfo.numChannels
+      }, (_val, idx) => idx),
+      ...loadSpec
+    };
+    this.loadSpecRequired = {
+      ...this.loadSpec,
+      channels: this.loadSpec.channels.slice(),
+      subregion: this.loadSpec.subregion.clone()
+    };
+    this.loader = loader;
+    // imageMetadata to be filled in by Volume Loaders
+    this.imageMetadata = {};
+    this.normRegionSize = new Vector3(1, 1, 1);
+    this.normRegionOffset = new Vector3(0, 0, 0);
+    this.physicalSize = new Vector3(1, 1, 1);
+    this.physicalScale = 1;
+    this.normPhysicalSize = new Vector3(1, 1, 1);
+    this.physicalPixelSize = this.imageInfo.physicalPixelSize;
+    this.tickMarkPhysicalLength = 1;
+    this.setVoxelSize(this.physicalPixelSize);
+    this.numChannels = this.imageInfo.numChannels;
+    this.channelNames = this.imageInfo.channelNames.slice();
+    this.channelColorsDefault = this.imageInfo.channelColors ? this.imageInfo.channelColors.slice() : this.channelNames.map((name, index) => getColorByChannelIndex(index));
+    // fill in gaps
+    if (this.channelColorsDefault.length < this.imageInfo.numChannels) {
+      for (let i = this.channelColorsDefault.length - 1; i < this.imageInfo.numChannels; ++i) {
+        this.channelColorsDefault[i] = getColorByChannelIndex(i);
+      }
+    }
+    this.channels = [];
+    for (let i = 0; i < this.imageInfo.numChannels; ++i) {
+      const channel = new Channel(this.channelNames[i]);
+      this.channels.push(channel);
+      // TODO pass in channel constructor...
+      channel.dims = this.imageInfo.subregionSize.toArray();
+    }
+    this.physicalUnitSymbol = this.imageInfo.spatialUnit;
+    this.volumeDataObservers = [];
+  }
+  setUnloaded() {
+    this.loaded = false;
+    this.channels.forEach(channel => {
+      channel.loaded = false;
+    });
+  }
+  isLoaded() {
+    return this.loaded;
+  }
+  updateDimensions() {
+    const {
+      volumeSize,
+      subregionSize,
+      subregionOffset
+    } = this.imageInfo;
+    this.setVoxelSize(this.physicalPixelSize);
+    this.normRegionSize = subregionSize.clone().divide(volumeSize);
+    this.normRegionOffset = subregionOffset.clone().divide(volumeSize);
+  }
+
+  /** Returns `true` iff differences between `loadSpec` and `loadSpecRequired` indicate new data *must* be loaded. */
+  mustLoadNewData() {
+    return this.loadSpec.useExplicitLevel !== this.loadSpecRequired.useExplicitLevel ||
+    // explicit vs automatic level changed
+    this.loadSpec.time !== this.loadSpecRequired.time ||
+    // time point changed
+    !this.loadSpec.subregion.containsBox(this.loadSpecRequired.subregion) ||
+    // new subregion not contained in old
+    this.loadSpecRequired.channels.some(channel => !this.loadSpec.channels.includes(channel)) // new channel(s)
+    ;
+  }
+
+  /**
+   * Returns `true` iff differences between `loadSpec` and `loadSpecRequired` indicate a new load *may* get a
+   * different scale level than is currently loaded.
+   *
+   * This checks for changes in properties that *can*, but do not *always*, change the scale level the loader picks.
+   * For example, a smaller `subregion` *may* mean a higher scale level will fit within memory constraints, or it may
+   * not. A higher `scaleLevelBias` *may* nudge the volume into a higher scale level, or we may already be at the max
+   * imposed by `multiscaleLevel`.
+   */
+  mayLoadNewScaleLevel() {
+    return !this.loadSpec.subregion.equals(this.loadSpecRequired.subregion) || this.loadSpecRequired.maxAtlasEdge !== this.loadSpec.maxAtlasEdge || this.loadSpecRequired.multiscaleLevel !== this.loadSpec.multiscaleLevel || this.loadSpecRequired.scaleLevelBias !== this.loadSpec.scaleLevelBias;
+  }
+
+  /** Call on any state update that may require new data to be loaded (subregion, enabled channels, time, etc.) */
+  async updateRequiredData(required, onChannelLoaded) {
+    this.loadSpecRequired = {
+      ...this.loadSpecRequired,
+      ...required
+    };
+    let shouldReload = this.mustLoadNewData();
+
+    // If we're not reloading due to required data changes, check if we should load a new scale level
+    if (!shouldReload && this.mayLoadNewScaleLevel()) {
+      // Loaders should cache loaded dimensions so that this call blocks no more than once per valid `LoadSpec`.
+      const dims = await this.loadScaleLevelDims();
+      if (dims) {
+        const dimsZYX = dims.map(({
+          shape
+        }) => [shape[2], shape[3], shape[4]]);
+        // Determine which scale level *would* be loaded, and see if it's different than what we have
+        const levelToLoad = pickLevelToLoadUnscaled(this.loadSpecRequired, dimsZYX);
+        shouldReload = this.imageInfo.multiscaleLevel !== levelToLoad;
+      }
+    }
+    if (shouldReload) {
+      this.loadNewData(onChannelLoaded);
+    }
+  }
+  async loadScaleLevelDims() {
+    try {
+      return await this.loader?.loadDims(this.loadSpecRequired);
+    } catch (e) {
+      this.volumeDataObservers.forEach(observer => observer.onVolumeLoadError(this, e));
+      return undefined;
+    }
+  }
+
+  /**
+   * Loads new data as specified in `this.loadSpecRequired`. Clones `loadSpecRequired` into `loadSpec` to indicate
+   * that the data that *must* be loaded is now the data that *has* been loaded.
+   */
+  async loadNewData(onChannelLoaded) {
+    this.setUnloaded();
+    this.loadSpec = {
+      ...this.loadSpecRequired,
+      subregion: this.loadSpecRequired.subregion.clone()
+    };
+    try {
+      await this.loader?.loadVolumeData(this, undefined, onChannelLoaded);
+    } catch (e) {
+      this.volumeDataObservers.forEach(observer => observer.onVolumeLoadError(this, e));
+      throw e;
+    }
+  }
+
+  // we calculate the physical size of the volume (voxels*pixel_size)
+  // and then normalize to the max physical dimension
+  // NOTE: This function MUST be called to set up some important dimensional info
+  setVoxelSize(size) {
+    // only set the data if it is > 0.  zero is not an allowed value.
+    size.x = size.x > 0 ? size.x : 1.0;
+    size.y = size.y > 0 ? size.y : 1.0;
+    size.z = size.z > 0 ? size.z : 1.0;
+    this.physicalPixelSize = size;
+    this.physicalSize = this.imageInfo.originalSize.clone().multiply(this.physicalPixelSize);
+    // Volume is scaled such that its largest physical dimension is 1 world unit - save that dimension for conversions
+    this.physicalScale = Math.max(this.physicalSize.x, this.physicalSize.y, this.physicalSize.z);
+    // Compute the volume's max extent - scaled to max dimension.
+    this.normPhysicalSize = this.physicalSize.clone().divideScalar(this.physicalScale);
+    // While we're here, pick a power of 10 that divides into our max dimension a reasonable number of times
+    // and save it to be the length of tick marks in 3d.
+    this.tickMarkPhysicalLength = 10 ** Math.floor(Math.log10(this.physicalScale / 2));
+  }
+  setUnitSymbol(symbol) {
+    this.physicalUnitSymbol = symbol;
+  }
+
+  /** Computes the center of the volume subset */
+  getContentCenter() {
+    // center point: (normRegionSize / 2 + normRegionOffset - 0.5) * normPhysicalSize;
+    return this.normRegionSize.clone().divideScalar(2).add(this.normRegionOffset).subScalar(0.5).multiply(this.normPhysicalSize);
+  }
+  cleanup() {
+    // no op
+  }
+  getChannel(channelIndex) {
+    return this.channels[channelIndex];
+  }
+  onChannelLoaded(batch) {
+    // check to see if all channels are now loaded, and fire an event(?)
+    if (this.loadSpec.channels.every(channelIndex => this.channels[channelIndex].loaded)) {
+      this.loaded = true;
+    }
+    batch.forEach(channelIndex => this.channelLoadCallback?.(this, channelIndex));
+    this.volumeDataObservers.forEach(observer => observer.onVolumeData(this, batch));
+  }
+
+  /**
+   * Assign volume data via a 2d array containing the z slices as tiles across it.  Assumes that the incoming data is consistent with the image's pre-existing imageInfo tile metadata.
+   * @param {number} channelIndex
+   * @param {Uint8Array} atlasdata
+   * @param {number} atlaswidth
+   * @param {number} atlasheight
+   */
+  setChannelDataFromAtlas(channelIndex, atlasdata, atlaswidth, atlasheight, range, dtype = "uint8") {
+    this.channels[channelIndex].setFromAtlas(atlasdata, atlaswidth, atlasheight, dtype, range[0], range[1], this.imageInfo.subregionSize);
+    this.onChannelLoaded([channelIndex]);
+  }
+
+  // ASSUMES that this.channelData.options is already set and incoming data is consistent with it
+  /**
+   * Assign volume data as a 3d array ordered x,y,z. The xy size must be equal to tilewidth*tileheight from the imageInfo used to construct this Volume.  Assumes that the incoming data is consistent with the image's pre-existing imageInfo tile metadata.
+   * @param {number} channelIndex
+   * @param {Uint8Array} volumeData
+   */
+  setChannelDataFromVolume(channelIndex, volumeData, range, dtype = "uint8") {
+    const {
+      subregionSize,
+      atlasTileDims
+    } = this.imageInfo;
+    this.channels[channelIndex].setFromVolumeData(volumeData, subregionSize.x, subregionSize.y, subregionSize.z, atlasTileDims.x * subregionSize.x, atlasTileDims.y * subregionSize.y, range[0], range[1], dtype);
+    this.onChannelLoaded([channelIndex]);
+  }
+
+  // TODO: decide if this should update imageInfo or not. For now, leave imageInfo alone as the "original" data
+  /**
+   * Add a new channel ready to receive data from one of the setChannelDataFrom* calls.
+   * Name and color will be defaulted if not provided. For now, leave imageInfo alone as the "original" data
+   * @param {string} name
+   * @param {Array.<number>} color [r,g,b]
+   */
+  appendEmptyChannel(name, color) {
+    const idx = this.imageInfo.numChannels;
+    const chname = name || "channel_" + idx;
+    const chcolor = color || getColorByChannelIndex(idx);
+    this.numChannels += 1;
+    this.channelNames.push(chname);
+    this.channelColorsDefault.push(chcolor);
+    this.channels.push(new Channel(chname));
+    for (let i = 0; i < this.volumeDataObservers.length; ++i) {
+      this.volumeDataObservers[i].onVolumeChannelAdded(this, idx);
+    }
+    return idx;
+  }
+
+  /**
+   * Get a value from the volume data
+   * @return {number} the intensity value from the given channel at the given xyz location
+   * @param {number} c The channel index
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   */
+  getIntensity(c, x, y, z) {
+    return this.channels[c].getIntensity(x, y, z);
+  }
+
+  /**
+   * Get the 256-bin histogram for the given channel
+   * @return {Histogram} the histogram
+   * @param {number} c The channel index
+   */
+  getHistogram(c) {
+    return this.channels[c].getHistogram();
+  }
+
+  /**
+   * Set the lut for the given channel
+   * @param {number} c The channel index
+   * @param {Array.<number>} lut The lut as a 256 element array
+   */
+  setLut(c, lut) {
+    this.channels[c].setLut(lut);
+  }
+
+  /**
+   * Set the color palette for the given channel
+   * @param {number} c The channel index
+   * @param {Array.<number>} palette The colors as a 256 element array * RGBA
+   */
+  setColorPalette(c, palette) {
+    this.channels[c].setColorPalette(palette);
+  }
+
+  /**
+   * Set the color palette alpha multiplier for the given channel.
+   * This will blend between the ordinary color lut and this colorPalette lut.
+   * @param {number} c The channel index
+   * @param {number} alpha The alpha value as a number from 0 to 1
+   */
+  setColorPaletteAlpha(c, alpha) {
+    this.channels[c].setColorPaletteAlpha(alpha);
+  }
+
+  /**
+   * Return the intrinsic rotation associated with this volume (radians)
+   * @return {Array.<number>} the xyz Euler angles (radians)
+   */
+  getRotation() {
+    // default axis order is XYZ
+    return this.imageInfo.transform.rotation.toArray();
+  }
+
+  /**
+   * Return the intrinsic translation (pivot center delta) associated with this volume, in normalized volume units
+   * @return {Array.<number>} the xyz translation in normalized volume units
+   */
+  getTranslation() {
+    return this.voxelsToWorldSpace(this.imageInfo.transform.translation.toArray());
+  }
+
+  /**
+   * Return a translation in normalized volume units, given a translation in image voxels
+   * @return {Array.<number>} the xyz translation in normalized volume units
+   */
+  voxelsToWorldSpace(xyz) {
+    // ASSUME: xyz is in original (level 0) image voxels, compatible with physicalPixelSize.
+    // account for pixel_size and normalized scaling in the threejs volume representation we're using
+    const m = 1.0 / Math.max(this.physicalSize.x, Math.max(this.physicalSize.y, this.physicalSize.z));
+    return new Vector3().fromArray(xyz).multiply(this.physicalPixelSize).multiplyScalar(m).toArray();
+  }
+  addVolumeDataObserver(o) {
+    this.volumeDataObservers.push(o);
+  }
+  removeVolumeDataObserver(o) {
+    if (o) {
+      const i = this.volumeDataObservers.indexOf(o);
+      if (i !== -1) {
+        this.volumeDataObservers.splice(i, 1);
+      }
+    }
+  }
+  removeAllVolumeDataObservers() {
+    this.volumeDataObservers = [];
+  }
+}

package/es/VolumeCache.js

@@ -0,0 +1,161 @@
+/** Default: 250MB. Should be large enough to be useful but safe for most any computer that can run the app */
+const CACHE_MAX_SIZE_DEFAULT = 250_000_000;
+export default class VolumeCache {
+  // Ends of a linked list of entries, to track LRU and evict efficiently
+
+  // TODO implement some way to manage used vs unused (prefetched) entries so
+  // that prefetched entries which are never used don't get highest priority!
+
+  constructor(maxSize = CACHE_MAX_SIZE_DEFAULT) {
+    this.entries = new Map();
+    this.maxSize = maxSize;
+    this.currentSize = 0;
+    this.first = null;
+    this.last = null;
+  }
+
+  // Hide these behind getters so they're definitely never set from the outside
+  /** The size of all data arrays currently stored in this cache, in bytes. */
+  get size() {
+    return this.currentSize;
+  }
+
+  /** The number of entries currently stored in this cache. */
+  get numberOfEntries() {
+    return this.entries.size;
+  }
+
+  /**
+   * Removes an entry from a store but NOT the LRU list.
+   * Only call from a method with the word "evict" in it!
+   */
+  removeEntryFromStore(entry) {
+    this.entries.delete(entry.key);
+    this.currentSize -= entry.data.byteLength;
+  }
+
+  /**
+   * Removes an entry from the LRU list but NOT its store.
+   * Entry must be replaced in list or removed from store, or it will never be evicted!
+   */
+  removeEntryFromList(entry) {
+    const {
+      prev,
+      next
+    } = entry;
+    if (prev) {
+      prev.next = next;
+    } else {
+      this.first = next;
+    }
+    if (next) {
+      next.prev = prev;
+    } else {
+      this.last = prev;
+    }
+  }
+
+  /** Adds an entry which is *not currently in the list* to the front of the list. */
+  addEntryAsFirst(entry) {
+    if (this.first) {
+      this.first.prev = entry;
+    } else {
+      this.last = entry;
+    }
+    entry.next = this.first;
+    entry.prev = null;
+    this.first = entry;
+  }
+
+  /** Moves an entry which is *currently in the list* to the front of the list. */
+  moveEntryToFirst(entry) {
+    if (entry === this.first) return;
+    this.removeEntryFromList(entry);
+    this.addEntryAsFirst(entry);
+  }
+
+  /** Evicts the least recently used entry from the cache. */
+  evictLast() {
+    if (!this.last) {
+      console.error("VolumeCache: attempt to evict last entry from cache when no last entry is set");
+      return;
+    }
+    this.removeEntryFromStore(this.last);
+    if (this.last.prev) {
+      this.last.prev.next = null;
+    }
+    this.last = this.last.prev;
+  }
+
+  /** Evicts a specific entry from the cache. */
+  evict(entry) {
+    this.removeEntryFromStore(entry);
+    this.removeEntryFromList(entry);
+  }
+
+  /**
+   * Adds a new entry to the cache.
+   * @returns {boolean} a boolean indicating whether the insertion succeeded.
+   */
+  insert(key, data) {
+    if (data.byteLength > this.maxSize) {
+      console.error("VolumeCache: attempt to insert a single entry larger than the cache");
+      return false;
+    }
+
+    // Check if entry is already in cache
+    // This will move the entry to the front of the LRU list, if present
+    const getResult = this.getEntry(key);
+    if (getResult !== undefined) {
+      getResult.data = data;
+      return true;
+    }
+
+    // Add new entry to cache
+    const newEntry = {
+      data,
+      prev: null,
+      next: null,
+      key
+    };
+    this.addEntryAsFirst(newEntry);
+    this.entries.set(key, newEntry);
+    this.currentSize += data.byteLength;
+
+    // Evict until size is within limit
+    while (this.currentSize > this.maxSize) {
+      this.evictLast();
+    }
+    return true;
+  }
+
+  /** Internal implementation of `get`. Returns all entry metadata, not just the raw data. */
+  getEntry(key) {
+    const result = this.entries.get(key);
+    if (result) {
+      this.moveEntryToFirst(result);
+    }
+    return result;
+  }
+
+  /** Attempts to get a single entry from the cache. */
+  get(key) {
+    return this.getEntry(key)?.data;
+  }
+
+  /** Clears all cache entries whose keys begin with the specified prefix. */
+  clearWithPrefix(prefix) {
+    for (const [key, entry] of this.entries.entries()) {
+      if (key.startsWith(prefix)) {
+        this.evict(entry);
+      }
+    }
+  }
+
+  /** Clears all data from the cache. */
+  clear() {
+    while (this.last) {
+      this.evictLast();
+    }
+  }
+}

package/es/VolumeDims.js

@@ -0,0 +1,16 @@
+import { Vector3 } from "three";
+export function defaultVolumeDims() {
+  return {
+    shape: [0, 0, 0, 0, 0],
+    spacing: [1, 1, 1, 1, 1],
+    spaceUnit: "μm",
+    timeUnit: "s",
+    dataType: "uint8"
+  };
+}
+export function volumeSize(volumeDims) {
+  return new Vector3(volumeDims.shape[4], volumeDims.shape[3], volumeDims.shape[2]);
+}
+export function physicalPixelSize(volumeDims) {
+  return new Vector3(volumeDims.spacing[4], volumeDims.spacing[3], volumeDims.spacing[2]);
+}