@aics/vole-core 4.3.1 → 4.4.0

package/es/BaseDrawableMeshObject.js

@@ -0,0 +1,72 @@
+import { Group, Mesh, Vector3 } from "three";
+/**
+ * Abstract base class for drawable 3D mesh objects.
+ *
+ * Provides default implementations for some methods in the IDrawableObject
+ * interface, including handling for visibility, transformations, and cleanup.
+ *
+ * As a default, subclasses should call `this.addChildMesh(mesh)` to register
+ * any meshes that should be managed by the base class.
+ */
+export default class BaseDrawableMeshObject {
+  /**
+   * Pivot group that all child meshes are parented to. Transformations are
+   * applied to this group.
+   */
+
+  constructor() {
+    this.meshPivot = new Group();
+    this.scale = new Vector3(1, 1, 1);
+    this.flipAxes = new Vector3(1, 1, 1);
+  }
+  addChildMesh(mesh) {
+    this.meshPivot.add(mesh);
+  }
+  removeChildMesh(mesh) {
+    this.meshPivot.remove(mesh);
+  }
+  cleanup() {
+    this.meshPivot.traverse(obj => {
+      if (obj instanceof Mesh) {
+        obj.geometry.dispose();
+        obj.material.dispose();
+      }
+    });
+    this.meshPivot.clear();
+  }
+  doRender() {
+    // no op
+  }
+  setVisible(visible) {
+    this.meshPivot.visible = visible;
+  }
+  get3dObject() {
+    return this.meshPivot;
+  }
+  setTranslation(translation) {
+    this.meshPivot.position.copy(translation);
+  }
+  setScale(scale) {
+    this.scale.copy(scale);
+    this.meshPivot.scale.copy(scale).multiply(this.flipAxes);
+  }
+  setRotation(eulerXYZ) {
+    this.meshPivot.rotation.copy(eulerXYZ);
+  }
+  setFlipAxes(flipX, flipY, flipZ) {
+    this.flipAxes.set(flipX, flipY, flipZ);
+    this.meshPivot.scale.copy(this.scale).multiply(this.flipAxes);
+  }
+  setOrthoThickness(_thickness) {
+    // no op
+  }
+  setResolution(_x, _y) {
+    // no op
+  }
+  setAxisClip(_axis, _minval, _maxval, _isOrthoAxis) {
+    // no op
+  }
+  updateClipRegion(_xmin, _xmax, _ymin, _ymax, _zmin, _zmax) {
+    // no op
+  }
+}

package/es/Line3d.js

@@ -1,16 +1,17 @@
-import { Group, Vector3 } from "three";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { MESH_NO_PICK_OCCLUSION_LAYER, OVERLAY_LAYER } from "./ThreeJsPanel.js";
+import BaseDrawableMeshObject from "./BaseDrawableMeshObject.js";
 const DEFAULT_VERTEX_BUFFER_SIZE = 1020;
 
 /**
  * Simple wrapper for a 3D line segments object, with controls for vertex data,
  * color, width, and segments visible.
  */
-export default class Line3d {
+export default class Line3d extends BaseDrawableMeshObject {
   constructor() {
+    super();
     this.bufferSize = DEFAULT_VERTEX_BUFFER_SIZE;
     const geometry = new LineSegmentsGeometry();
     geometry.setPositions(new Float32Array(this.bufferSize));
@@ -27,55 +28,10 @@ export default class Line3d {
     // artifacts can occur where contours are drawn around lines. This layer
     // (MESH_NO_PICK_OCCLUSION_LAYER) does not occlude/interact with the pick
     // buffer but still writes depth information for the volume.
+    this.meshPivot.layers.set(MESH_NO_PICK_OCCLUSION_LAYER);
     this.lineMesh.layers.set(MESH_NO_PICK_OCCLUSION_LAYER);
     this.lineMesh.frustumCulled = false;
-    this.meshPivot = new Group();
-    this.meshPivot.add(this.lineMesh);
-    this.meshPivot.layers.set(MESH_NO_PICK_OCCLUSION_LAYER);
-    this.scale = new Vector3(1, 1, 1);
-    this.flipAxes = new Vector3(1, 1, 1);
-  }
-
-  // IDrawableObject interface methods
-
-  cleanup() {
-    this.lineMesh.geometry.dispose();
-    this.lineMesh.material.dispose();
-  }
-  setVisible(visible) {
-    this.lineMesh.visible = visible;
-  }
-  doRender() {
-    // no op
-  }
-  get3dObject() {
-    return this.meshPivot;
-  }
-  setTranslation(translation) {
-    this.meshPivot.position.copy(translation);
-  }
-  setScale(scale) {
-    this.scale.copy(scale);
-    this.meshPivot.scale.copy(scale).multiply(this.flipAxes);
-  }
-  setRotation(eulerXYZ) {
-    this.meshPivot.rotation.copy(eulerXYZ);
-  }
-  setFlipAxes(flipX, flipY, flipZ) {
-    this.flipAxes.set(flipX, flipY, flipZ);
-    this.meshPivot.scale.copy(this.scale).multiply(this.flipAxes);
-  }
-  setOrthoThickness(_thickness) {
-    // no op
-  }
-  setResolution(_x, _y) {
-    // no op
-  }
-  setAxisClip(_axis, _minval, _maxval, _isOrthoAxis) {
-    // no op
-  }
-  updateClipRegion(_xmin, _xmax, _ymin, _ymax, _zmin, _zmax) {
-    // no op
+    this.addChildMesh(this.lineMesh);
   }
 
   // Line-specific functions

package/es/VectorArrows3d.js

@@ -0,0 +1,325 @@
+import { InstancedMesh, CylinderGeometry, ConeGeometry, Object3D, Vector3, MeshBasicMaterial, Color, DynamicDrawUsage, Matrix4 } from "three";
+import BaseDrawableMeshObject from "./BaseDrawableMeshObject";
+import { MESH_NO_PICK_OCCLUSION_LAYER } from "./ThreeJsPanel";
+
+// Unscaled arrowhead dimensions.
+const SHAFT_BASE_RADIUS = 0.5;
+const HEAD_BASE_RADIUS = 1.5;
+const HEAD_BASE_HEIGHT = 4;
+
+/** Default arrow shaft thickness, in world units. */
+const DEFAULT_DIAMETER = 0.002;
+const DEFAULT_INSTANCE_COUNT = 256;
+
+/**
+ * A drawable vector arrow field, which uses instanced meshes for performance.
+ */
+export default class VectorArrows3d extends BaseDrawableMeshObject {
+  /**
+   * Scale of this object in world coordinates, when unscaled. Used to
+   * compensate for parent transforms in order to keep arrow meshes from being
+   * distorted.
+   */
+
+  // Temporary calculation objects. Optimization taken from three.js examples.
+
+  constructor() {
+    super();
+    this.worldScale = new Vector3(1, 1, 1);
+    this.meshPivot.layers.set(MESH_NO_PICK_OCCLUSION_LAYER);
+    this.maxInstanceCount = DEFAULT_INSTANCE_COUNT;
+    const {
+      headMesh: headMesh,
+      shaftMesh: shaftMesh
+    } = this.initInstancedMeshes(DEFAULT_INSTANCE_COUNT);
+    this.headInstancedMesh = headMesh;
+    this.shaftInstancedMesh = shaftMesh;
+    this.headInstancedMesh.count = 0;
+    this.shaftInstancedMesh.count = 0;
+    this.positions = null;
+    this.deltas = null;
+    this.colors = null;
+    this.diameter = new Float32Array([DEFAULT_DIAMETER]);
+    this.tempDst = new Vector3();
+    this.tempScale = new Vector3();
+    this.tempMatrix = new Object3D();
+    this.onParentTransformUpdated();
+  }
+
+  /**
+   * Returns (unscaled) buffer geometry for the head and shaft parts of the
+   * arrow.
+   * @returns
+   * - `head`: BufferGeometry for the arrowhead, a cone pointing along the +Z
+   *   axis, with the pivot at the tip of the cone. Height and radius are based
+   *   on constant values (`HEAD_BASE_HEIGHT` and `HEAD_BASE_RADIUS`).
+   * - `shaft`: BufferGeometry for the cylindrical arrow shaft. The cylinder
+   *   points along the +Z axis, with the pivot at the base of the cylinder.
+   *   Height is 1 and diameter is 1.
+   *
+   * ```txt
+   *  ^ +Z axis ^
+   *  _____      x
+   * |     |    / \
+   * |     |   /   \
+   *  --x--   /-----\
+   *
+   *   x = pivot (0,0,0)
+   * ```
+   */
+  static generateGeometry() {
+    // TODO: Currently the shape of the arrow head is fixed. Allow configuring
+    // this in the future?
+    const cylinderGeometry = new CylinderGeometry(SHAFT_BASE_RADIUS, SHAFT_BASE_RADIUS, 2 * SHAFT_BASE_RADIUS,
+    // height
+    8,
+    // radial segments
+    1,
+    // height segments
+    false // capped ends
+    );
+    const coneRadius = HEAD_BASE_RADIUS;
+    const coneHeight = HEAD_BASE_HEIGHT;
+    const coneGeometry = new ConeGeometry(coneRadius, coneHeight, 12);
+
+    // Rotate both to point along +Z axis
+    const rotateToPositiveZ = new Matrix4().makeRotationX(Math.PI / 2);
+    // Change cone pivot to be at the tip.
+    const coneTranslation = new Matrix4().makeTranslation(0, 0, -coneHeight / 2);
+    coneGeometry.applyMatrix4(coneTranslation.multiply(rotateToPositiveZ));
+    // Change cylinder pivot to be at the base.
+    const cylinderTranslation = new Matrix4().makeTranslation(0, 0, 0.5);
+    cylinderGeometry.applyMatrix4(cylinderTranslation.multiply(rotateToPositiveZ));
+    return {
+      head: coneGeometry,
+      shaft: cylinderGeometry
+    };
+  }
+
+  /**
+   * Create new instanced meshes with the specified instance count, and adds
+   * them to the mesh pivot and internal meshes array for future cleanup.
+   *
+   * If calling outside of the constructor, be sure to call `cleanup()` first.
+   */
+  initInstancedMeshes(instanceCount) {
+    this.cleanup();
+    this.meshPivot.clear();
+    const basicMaterial = new MeshBasicMaterial({
+      color: "#fff"
+    });
+    const {
+      head: headGeometry,
+      shaft: shaftGeometry
+    } = VectorArrows3d.generateGeometry();
+    const headMesh = new InstancedMesh(headGeometry, basicMaterial, instanceCount);
+    const shaftMesh = new InstancedMesh(shaftGeometry, basicMaterial, instanceCount);
+    headMesh.layers.set(MESH_NO_PICK_OCCLUSION_LAYER);
+    shaftMesh.layers.set(MESH_NO_PICK_OCCLUSION_LAYER);
+    headMesh.frustumCulled = false;
+    shaftMesh.frustumCulled = false;
+    headMesh.instanceMatrix.setUsage(DynamicDrawUsage);
+    shaftMesh.instanceMatrix.setUsage(DynamicDrawUsage);
+    this.addChildMesh(headMesh);
+    this.addChildMesh(shaftMesh);
+    return {
+      headMesh,
+      shaftMesh
+    };
+  }
+  increaseInstanceCountMax(instanceCount) {
+    // Max instance count is set when instanced meshes are created. If we need
+    // to increase the max, we need to recreate the instanced meshes.
+    let newInstanceCount = this.maxInstanceCount;
+    while (newInstanceCount < instanceCount) {
+      newInstanceCount *= 2;
+    }
+    // Delete existing meshes
+    this.cleanup();
+    const {
+      headMesh,
+      shaftMesh
+    } = this.initInstancedMeshes(newInstanceCount);
+    this.headInstancedMesh = headMesh;
+    this.shaftInstancedMesh = shaftMesh;
+    this.maxInstanceCount = newInstanceCount;
+  }
+  setScale(scale) {
+    if (scale !== this.scale) {
+      this.onParentTransformUpdated();
+      this.scale.copy(scale);
+      if (this.positions && this.deltas) {
+        // Update arrows
+        this.setArrowData(this.positions, this.deltas);
+      }
+    }
+  }
+
+  /**
+   * Called when scaling of parent transforms has been updated or whenever
+   * vector data is updated.
+   */
+  onParentTransformUpdated() {
+    // Measure world scale by temporarily resetting mesh pivot scale
+    this.meshPivot.scale.set(1, 1, 1);
+    let newWorldScale = new Vector3();
+    newWorldScale = this.meshPivot.getWorldScale(newWorldScale);
+
+    // Scale is inverted on mesh pivot to cancel out parent transforms (though
+    // translation and rotation are still affected by any parent transforms).
+    // This allows arrows meshes to be scaled 1:1 with world space, regardless
+    // of parent transforms, and prevents distortion or skewing of the mesh.
+    // Parent scaling is  applied to arrow positions and deltas (see
+    // `updateAllArrowTransforms`), rather than the meshes themselves.
+    const invertScale = new Vector3(1, 1, 1).divide(newWorldScale);
+    this.meshPivot.scale.copy(invertScale);
+    if (!newWorldScale.equals(this.worldScale)) {
+      this.worldScale.copy(newWorldScale);
+      if (this.positions && this.deltas) {
+        this.setArrowData(this.positions, this.deltas);
+      }
+    }
+  }
+  updateSingleArrowTransform(index, src, delta, diameter) {
+    // Update the arrow shaft
+    const headHeight = HEAD_BASE_HEIGHT * diameter;
+    const length = delta.length();
+    const shaftHeight = Math.max(length - headHeight, 0);
+    if (shaftHeight < 1e-6) {
+      // If the shaft height is too small, scale to 0.
+      this.tempScale.set(0, 0, 0);
+    } else {
+      this.tempScale.set(diameter, diameter, shaftHeight);
+    }
+    this.tempMatrix.scale.copy(this.tempScale);
+    this.tempMatrix.position.copy(src);
+    this.tempDst.copy(src).add(delta);
+    this.tempMatrix.lookAt(this.tempDst);
+    this.tempMatrix.updateMatrix();
+    this.shaftInstancedMesh.setMatrixAt(index, this.tempMatrix.matrix);
+    if (length < headHeight) {
+      // If head is longer than the total length, shrink the head to match
+      // length. TODO: Is it okay to do this automatically?
+      const newDiameter = length / HEAD_BASE_HEIGHT;
+      this.tempScale.set(newDiameter, newDiameter, newDiameter);
+    } else {
+      this.tempScale.set(diameter, diameter, diameter);
+    }
+    this.tempMatrix.scale.copy(this.tempScale);
+    this.tempMatrix.position.copy(this.tempDst);
+    this.tempDst.add(delta);
+    this.tempMatrix.lookAt(this.tempDst);
+    this.tempMatrix.updateMatrix();
+    this.headInstancedMesh.setMatrixAt(index, this.tempMatrix.matrix);
+  }
+  updateAllArrowTransforms() {
+    if (!this.positions || !this.deltas) {
+      return;
+    }
+    const count = this.positions.length / 3;
+    const combinedScale = new Vector3().copy(this.scale).multiply(this.flipAxes).multiply(this.worldScale);
+    const tempSrc = new Vector3();
+    const tempDelta = new Vector3();
+    let tempDiameter;
+    for (let i = 0; i < count; i++) {
+      // Points and deltas scaled to volume space.
+      tempSrc.fromArray(this.positions, i * 3).multiply(combinedScale);
+      tempDelta.fromArray(this.deltas, i * 3).multiply(combinedScale);
+      tempDiameter = this.diameter[i % this.diameter.length] ?? DEFAULT_DIAMETER;
+      this.updateSingleArrowTransform(i, tempSrc, tempDelta, tempDiameter);
+    }
+    this.headInstancedMesh.instanceMatrix.needsUpdate = true;
+    this.shaftInstancedMesh.instanceMatrix.needsUpdate = true;
+  }
+  applyColors() {
+    if (!this.colors) {
+      return;
+    }
+    const colorCount = Math.round(this.colors.length / 3);
+    const color = new Color();
+    for (let i = 0; i < this.headInstancedMesh.count; i++) {
+      // Wrap colors if there are fewer colors than arrows
+      const colorIndex = i % colorCount;
+      color.fromArray(this.colors, colorIndex * 3);
+      this.headInstancedMesh.setColorAt(i, color);
+      this.shaftInstancedMesh.setColorAt(i, color);
+    }
+    if (this.headInstancedMesh.instanceColor) {
+      this.headInstancedMesh.instanceColor.needsUpdate = true;
+    }
+    if (this.shaftInstancedMesh.instanceColor) {
+      this.shaftInstancedMesh.instanceColor.needsUpdate = true;
+    }
+  }
+
+  /**
+   * Sets the colors for the arrows as either a single Color or an array of RGB values.
+   * If there are more arrows than colors, colors will be repeated in order.
+   * @param colors Color object or numeric array of RGB values in the [0, 1] range.
+   * @throws {Error} If colors array length is not a multiple of 3.
+   */
+  setColors(colors) {
+    if (colors instanceof Color) {
+      this.colors = new Float32Array(3);
+      colors.toArray(this.colors);
+    } else {
+      if (colors.length % 3 !== 0) {
+        throw new Error("VectorArrows.setColors: colors array length must be a multiple of 3.");
+      }
+      this.colors = new Float32Array(colors);
+    }
+    this.applyColors();
+  }
+
+  /**
+   * Sets all arrows to a uniform diameter (default is `0.002`). To set
+   * per-arrow diameter, pass an array of values into `setArrowData` instead.
+   * @param diameter Diameter value to set for all arrows.
+   */
+  setDiameter(diameter) {
+    this.diameter = new Float32Array([diameter]);
+    this.updateAllArrowTransforms();
+  }
+
+  /**
+   * Sets the per-arrow data. The number of rendered arrows is equal to
+   * `positions.length / 3`.
+   * @param positions Float32Array, where every three values is the XYZ position
+   * of the base of an arrow.
+   * @param deltas Float32Array, where every three values is the XYZ delta
+   * vector for each arrow.
+   * @param diameters Optional Float32Array of diameter thickness values for
+   * each arrow's shaft. If provided, overrides a single diameter value set by
+   * `setDiameter`. If fewer diameter values are provided than arrows, the
+   * values will be repeated in order.
+   * @throws {Error} If positions and deltas arrays have different lengths or if
+   * their length is not a multiple of 3.
+   */
+  setArrowData(positions, deltas, diameters) {
+    if (positions.length !== deltas.length) {
+      throw new Error("VectorArrows.setArrowData: positions and deltas arrays must have the same length");
+    }
+    if (positions.length % 3 !== 0) {
+      throw new Error("VectorArrows.setArrowData: positions and deltas arrays length must be a multiple of 3");
+    }
+    this.positions = positions;
+    this.deltas = deltas;
+    if (diameters) {
+      this.diameter = diameters;
+    }
+
+    // Update instance count, add more instances as needed.
+    const count = positions.length / 3;
+    const didInstanceCountIncrease = this.headInstancedMesh.count < count;
+    if (this.maxInstanceCount < count) {
+      this.increaseInstanceCountMax(count);
+    }
+    this.headInstancedMesh.count = count;
+    this.shaftInstancedMesh.count = count;
+    this.updateAllArrowTransforms();
+    if (didInstanceCountIncrease) {
+      // Apply colors to new arrows as needed
+      this.applyColors();
+    }
+  }
+}

package/es/View3d.js

@@ -852,29 +852,54 @@ export class View3d {
    * be in the normalized coordinate space of the Volume, where the origin
    * (0,0,0) is at the center of the Volume and the extent is from -0.5 to 0.5
    * in each axis.
+   * @deprecated Will be removed in the next major release. Use `addDrawableObject` instead.
    */
   addLineObject(line) {
-    if (this.image) {
-      this.image.addLineObject(line);
-      this.redraw();
-    }
+    return this.addDrawableObject(line);
   }
 
-  /** Returns whether a Line3d object exists as a child of the volume. */
+  /**
+   * Returns whether a Line3d object exists as a child of the volume.
+   * @deprecated Will be removed in the next major release. Use `hasDrawableObject` instead.
+   */
   hasLineObject(line) {
-    if (this.image) {
-      return this.image.hasLineObject(line);
-    }
-    return false;
+    return this.hasDrawableObject(line);
   }
 
   /**
    * Removes a Line3d object from the Volume, if it exists. Note that the
    * object's resources are not freed automatically (e.g. via `line.cleanup()`).
+   * @deprecated Will be removed in the next major release. Use `removeDrawableObject` instead.
    */
   removeLineObject(line) {
+    return this.removeDrawableObject(line);
+  }
+
+  /**
+   * Adds a drawable object as a child of the Volume, if it does not already
+   * exist. Objects will be in the normalized coordinate space of the Volume,
+   * where the origin (0,0,0) is at the center of the Volume and the extent is
+   * from -0.5 to 0.5 in each axis.
+   */
+  addDrawableObject(object) {
+    if (this.image) {
+      this.image.addDrawableObject(object);
+      this.redraw();
+    }
+  }
+
+  /** Returns whether a drawable object exists as a child of the volume. */
+  hasDrawableObject(object) {
+    return this.image ? this.image.hasDrawableObject(object) : false;
+  }
+
+  /**
+   * Removes a drawable object from the Volume, if it exists. Note that the
+   * object's resources are not freed automatically (e.g. via `object.cleanup()`).
+   */
+  removeDrawableObject(object) {
     if (this.image) {
-      this.image.removeLineObject(line);
+      this.image.removeDrawableObject(object);
       this.redraw();
     }
   }

package/es/VolumeDrawable.js

@@ -240,6 +240,8 @@ export default class VolumeDrawable {
     const scale = normPhysicalSize.clone().multiply(normRegionSize).multiply(this.settings.scale);
     this.childObjectsGroup.scale.copy(scale);
     this.childObjectsGroup.position.copy(this.volume.getContentCenter().multiply(this.settings.scale));
+    this.childObjects.forEach(obj => obj.onParentTransformUpdated?.());
+
     // TODO only `RayMarchedAtlasVolume` handles scale properly. Get the others on board too!
     this.volumeRendering.updateVolumeDimensions();
     this.volumeRendering.updateSettings(this.settings, SettingsFlags.TRANSFORM);
@@ -773,33 +775,31 @@ export default class VolumeDrawable {
   }
 
   /**
-   * Adds a Line3d object as a child of the Volume, if it does not already
-   * exist. Line objects will be in the normalized coordinate space of the
-   * Volume, where the origin (0,0,0) is at the center of the Volume and the
-   * extent is from -0.5 to 0.5 in each axis.
+   * Adds a drawable object as a child of the Volume, if it does not already
+   * exist. Objects will be in the normalized coordinate space of the Volume,
+   * where the origin (0,0,0) is at the center of the Volume and the extent is
+   * from -0.5 to 0.5 in each axis.
    */
-  addLineObject(line) {
-    if (!this.childObjects.has(line)) {
-      this.childObjects.add(line);
-      this.childObjectsGroup.add(line.get3dObject());
-      line.setResolution(this.settings.resolution.x, this.settings.resolution.y);
-      line.setFlipAxes(this.settings.flipAxes.x, this.settings.flipAxes.y, this.settings.flipAxes.z);
+  addDrawableObject(object) {
+    if (!this.childObjects.has(object)) {
+      this.childObjectsGroup.add(object.get3dObject());
+      this.childObjects.add(object);
+      this.updateScale();
     }
   }
 
-  /** Returns whether a line object exists as a child of the volume. */
-  hasLineObject(line) {
-    return this.childObjects.has(line);
+  /** Returns whether a drawable object exists as a child of the volume. */
+  hasDrawableObject(object) {
+    return this.childObjects.has(object);
   }
 
-  /**
-   * Removes a Line3d object from the Volume, if it exists. Note that the
-   * object's resources are not freed automatically (e.g. via `line.cleanup()`).
+  /** Removes a drawable object from the Volume, if it exists. Note that the
+   * object's resources are not freed automatically (e.g. via `object.cleanup()`).
    */
-  removeLineObject(line) {
-    if (this.childObjects.has(line)) {
-      this.childObjects.delete(line);
-      this.childObjectsGroup.remove(line.get3dObject());
+  removeDrawableObject(object) {
+    if (this.childObjects.has(object)) {
+      this.childObjects.delete(object);
+      this.childObjectsGroup.remove(object.get3dObject());
     }
   }
   setupGui(pane) {

package/es/index.js

@@ -19,4 +19,5 @@ import VolumeLoaderContext from "./workers/VolumeLoaderContext.js";
 import { VolumeLoadError, VolumeLoadErrorType } from "./loaders/VolumeLoadError.js";
 import { Light, AREA_LIGHT, SKY_LIGHT } from "./Light.js";
 import Line3d from "./Line3d.js";
-export { Histogram, Lut, Line3d, remapControlPoints, View3d, Volume, VolumeDrawable, LoadSpec, VolumeMaker, VolumeCache, RequestQueue, SubscribableRequestQueue, PrefetchDirection, OMEZarrLoader, JsonImageInfoLoader, RawArrayLoader, TiffLoader, VolumeLoaderContext, VolumeLoadError, VolumeLoadErrorType, VolumeFileFormat, createVolumeLoader, Channel, Light, ViewportCorner, AREA_LIGHT, RENDERMODE_PATHTRACE, RENDERMODE_RAYMARCH, SKY_LIGHT };
+import VectorArrows3d from "./VectorArrows3d.js";
+export { Histogram, Lut, Line3d, VectorArrows3d, remapControlPoints, View3d, Volume, VolumeDrawable, LoadSpec, VolumeMaker, VolumeCache, RequestQueue, SubscribableRequestQueue, PrefetchDirection, OMEZarrLoader, JsonImageInfoLoader, RawArrayLoader, TiffLoader, VolumeLoaderContext, VolumeLoadError, VolumeLoadErrorType, VolumeFileFormat, createVolumeLoader, Channel, Light, ViewportCorner, AREA_LIGHT, RENDERMODE_PATHTRACE, RENDERMODE_RAYMARCH, SKY_LIGHT };

package/es/loaders/zarr_utils/utils.js

@@ -78,6 +78,7 @@ export function remapAxesToTCZYX(axes) {
 export function orderByDimension(valsTCZYX, orderTCZYX) {
   const specLen = getDimensionCount(orderTCZYX);
   const result = Array(specLen);
+  let curIdx = 0;
   orderTCZYX.forEach((val, idx) => {
     if (val >= 0) {
       if (val >= specLen) {
@@ -85,7 +86,7 @@ export function orderByDimension(valsTCZYX, orderTCZYX) {
           type: VolumeLoadErrorType.INVALID_METADATA
         });
       }
-      result[val] = valsTCZYX[idx];
+      result[curIdx++] = valsTCZYX[idx];
     }
   });
   return result;

package/es/types/BaseDrawableMeshObject.d.ts

@@ -0,0 +1,35 @@
+import { Euler, Group, Mesh, Vector3 } from "three";
+import { IDrawableObject } from "./types";
+/**
+ * Abstract base class for drawable 3D mesh objects.
+ *
+ * Provides default implementations for some methods in the IDrawableObject
+ * interface, including handling for visibility, transformations, and cleanup.
+ *
+ * As a default, subclasses should call `this.addChildMesh(mesh)` to register
+ * any meshes that should be managed by the base class.
+ */
+export default abstract class BaseDrawableMeshObject implements IDrawableObject {
+    /**
+     * Pivot group that all child meshes are parented to. Transformations are
+     * applied to this group.
+     */
+    protected readonly meshPivot: Group;
+    protected scale: Vector3;
+    protected flipAxes: Vector3;
+    constructor();
+    protected addChildMesh(mesh: Mesh): void;
+    protected removeChildMesh(mesh: Mesh): void;
+    cleanup(): void;
+    doRender(): void;
+    setVisible(visible: boolean): void;
+    get3dObject(): Group;
+    setTranslation(translation: Vector3): void;
+    setScale(scale: Vector3): void;
+    setRotation(eulerXYZ: Euler): void;
+    setFlipAxes(flipX: number, flipY: number, flipZ: number): void;
+    setOrthoThickness(_thickness: number): void;
+    setResolution(_x: number, _y: number): void;
+    setAxisClip(_axis: "x" | "y" | "z", _minval: number, _maxval: number, _isOrthoAxis: boolean): void;
+    updateClipRegion(_xmin: number, _xmax: number, _ymin: number, _ymax: number, _zmin: number, _zmax: number): void;
+}

package/es/types/Line3d.d.ts

@@ -1,28 +1,14 @@
-import { Color, Euler, Group, Vector3 } from "three";
+import { Color } from "three";
 import { IDrawableObject } from "./types.js";
+import BaseDrawableMeshObject from "./BaseDrawableMeshObject.js";
 /**
  * Simple wrapper for a 3D line segments object, with controls for vertex data,
  * color, width, and segments visible.
  */
-export default class Line3d implements IDrawableObject {
-    private meshPivot;
-    private scale;
-    private flipAxes;
+export default class Line3d extends BaseDrawableMeshObject implements IDrawableObject {
     private lineMesh;
     private bufferSize;
     constructor();
-    cleanup(): void;
-    setVisible(visible: boolean): void;
-    doRender(): void;
-    get3dObject(): Group;
-    setTranslation(translation: Vector3): void;
-    setScale(scale: Vector3): void;
-    setRotation(eulerXYZ: Euler): void;
-    setFlipAxes(flipX: number, flipY: number, flipZ: number): void;
-    setOrthoThickness(_thickness: number): void;
-    setResolution(_x: number, _y: number): void;
-    setAxisClip(_axis: "x" | "y" | "z", _minval: number, _maxval: number, _isOrthoAxis: boolean): void;
-    updateClipRegion(_xmin: number, _xmax: number, _ymin: number, _ymax: number, _zmin: number, _zmax: number): void;
     /**
      * Sets the color of the line material.
      * @param color Base line color.

package/es/types/VectorArrows3d.d.ts

@@ -0,0 +1,92 @@
+import { Vector3, Color } from "three";
+import { IDrawableObject } from "./types";
+import BaseDrawableMeshObject from "./BaseDrawableMeshObject";
+/**
+ * A drawable vector arrow field, which uses instanced meshes for performance.
+ */
+export default class VectorArrows3d extends BaseDrawableMeshObject implements IDrawableObject {
+    /**
+     * Scale of this object in world coordinates, when unscaled. Used to
+     * compensate for parent transforms in order to keep arrow meshes from being
+     * distorted.
+     */
+    protected worldScale: Vector3;
+    private headInstancedMesh;
+    private shaftInstancedMesh;
+    private maxInstanceCount;
+    private positions;
+    private deltas;
+    private colors;
+    private diameter;
+    private tempDst;
+    private tempScale;
+    private tempMatrix;
+    constructor();
+    /**
+     * Returns (unscaled) buffer geometry for the head and shaft parts of the
+     * arrow.
+     * @returns
+     * - `head`: BufferGeometry for the arrowhead, a cone pointing along the +Z
+     *   axis, with the pivot at the tip of the cone. Height and radius are based
+     *   on constant values (`HEAD_BASE_HEIGHT` and `HEAD_BASE_RADIUS`).
+     * - `shaft`: BufferGeometry for the cylindrical arrow shaft. The cylinder
+     *   points along the +Z axis, with the pivot at the base of the cylinder.
+     *   Height is 1 and diameter is 1.
+     *
+     * ```txt
+     *  ^ +Z axis ^
+     *  _____      x
+     * |     |    / \
+     * |     |   /   \
+     *  --x--   /-----\
+     *
+     *   x = pivot (0,0,0)
+     * ```
+     */
+    private static generateGeometry;
+    /**
+     * Create new instanced meshes with the specified instance count, and adds
+     * them to the mesh pivot and internal meshes array for future cleanup.
+     *
+     * If calling outside of the constructor, be sure to call `cleanup()` first.
+     */
+    private initInstancedMeshes;
+    private increaseInstanceCountMax;
+    setScale(scale: Vector3): void;
+    /**
+     * Called when scaling of parent transforms has been updated or whenever
+     * vector data is updated.
+     */
+    onParentTransformUpdated(): void;
+    private updateSingleArrowTransform;
+    private updateAllArrowTransforms;
+    private applyColors;
+    /**
+     * Sets the colors for the arrows as either a single Color or an array of RGB values.
+     * If there are more arrows than colors, colors will be repeated in order.
+     * @param colors Color object or numeric array of RGB values in the [0, 1] range.
+     * @throws {Error} If colors array length is not a multiple of 3.
+     */
+    setColors(colors: Float32Array | Color): void;
+    /**
+     * Sets all arrows to a uniform diameter (default is `0.002`). To set
+     * per-arrow diameter, pass an array of values into `setArrowData` instead.
+     * @param diameter Diameter value to set for all arrows.
+     */
+    setDiameter(diameter: number): void;
+    /**
+     * Sets the per-arrow data. The number of rendered arrows is equal to
+     * `positions.length / 3`.
+     * @param positions Float32Array, where every three values is the XYZ position
+     * of the base of an arrow.
+     * @param deltas Float32Array, where every three values is the XYZ delta
+     * vector for each arrow.
+     * @param diameters Optional Float32Array of diameter thickness values for
+     * each arrow's shaft. If provided, overrides a single diameter value set by
+     * `setDiameter`. If fewer diameter values are provided than arrows, the
+     * values will be repeated in order.
+     * @throws {Error} If positions and deltas arrays have different lengths or if
+     * their length is not a multiple of 3.
+     */
+    setArrowData(positions: Float32Array, deltas: Float32Array, diameters?: Float32Array): void;
+}

package/es/types/View3d.d.ts

@@ -3,7 +3,7 @@ import { CameraState } from "./ThreeJsPanel.js";
 import VolumeDrawable from "./VolumeDrawable.js";
 import { Light } from "./Light.js";
 import Volume from "./Volume.js";
-import { type ColorizeFeature, type VolumeChannelDisplayOptions, type VolumeDisplayOptions, ViewportCorner, RenderMode } from "./types.js";
+import { type ColorizeFeature, type VolumeChannelDisplayOptions, type VolumeDisplayOptions, ViewportCorner, RenderMode, IDrawableObject } from "./types.js";
 import { PerChannelCallback } from "./loaders/IVolumeLoader.js";
 import Line3d from "./Line3d.js";
 export declare const RENDERMODE_RAYMARCH = RenderMode.RAYMARCH;
@@ -389,15 +389,34 @@ export declare class View3d {
      * be in the normalized coordinate space of the Volume, where the origin
      * (0,0,0) is at the center of the Volume and the extent is from -0.5 to 0.5
      * in each axis.
+     * @deprecated Will be removed in the next major release. Use `addDrawableObject` instead.
      */
     addLineObject(line: Line3d): void;
-    /** Returns whether a Line3d object exists as a child of the volume. */
+    /**
+     * Returns whether a Line3d object exists as a child of the volume.
+     * @deprecated Will be removed in the next major release. Use `hasDrawableObject` instead.
+     */
     hasLineObject(line: Line3d): boolean;
     /**
      * Removes a Line3d object from the Volume, if it exists. Note that the
      * object's resources are not freed automatically (e.g. via `line.cleanup()`).
+     * @deprecated Will be removed in the next major release. Use `removeDrawableObject` instead.
      */
     removeLineObject(line: Line3d): void;
+    /**
+     * Adds a drawable object as a child of the Volume, if it does not already
+     * exist. Objects will be in the normalized coordinate space of the Volume,
+     * where the origin (0,0,0) is at the center of the Volume and the extent is
+     * from -0.5 to 0.5 in each axis.
+     */
+    addDrawableObject(object: IDrawableObject): void;
+    /** Returns whether a drawable object exists as a child of the volume. */
+    hasDrawableObject(object: IDrawableObject): boolean;
+    /**
+     * Removes a drawable object from the Volume, if it exists. Note that the
+     * object's resources are not freed automatically (e.g. via `object.cleanup()`).
+     */
+    removeDrawableObject(object: IDrawableObject): void;
     /**
      * @description Enable or disable picking on a volume.  If enabled, the channelIndex is used to determine which channel to pick.
      * @param volume the image to enable picking on

package/es/types/VolumeDrawable.d.ts

@@ -1,12 +1,11 @@
 import { Vector3, Object3D, Euler, DepthTexture, OrthographicCamera, PerspectiveCamera, WebGLRenderer, WebGLRenderTarget, Texture } from "three";
 import { Pane } from "tweakpane";
 import Volume from "./Volume.js";
-import type { VolumeDisplayOptions, VolumeChannelDisplayOptions, ColorizeFeature } from "./types.js";
+import type { VolumeDisplayOptions, VolumeChannelDisplayOptions, ColorizeFeature, IDrawableObject } from "./types.js";
 import { RenderMode } from "./types.js";
 import { Light } from "./Light.js";
 import Channel from "./Channel.js";
 import { Axis } from "./VolumeRenderSettings.js";
-import Line3d from "./Line3d.js";
 type ColorArray = [number, number, number];
 type ColorObject = {
     r: number;
@@ -120,19 +119,18 @@ export default class VolumeDrawable {
     setRotation(eulerXYZ: Euler): void;
     setScale(xyz: Vector3): void;
     /**
-     * Adds a Line3d object as a child of the Volume, if it does not already
-     * exist. Line objects will be in the normalized coordinate space of the
-     * Volume, where the origin (0,0,0) is at the center of the Volume and the
-     * extent is from -0.5 to 0.5 in each axis.
+     * Adds a drawable object as a child of the Volume, if it does not already
+     * exist. Objects will be in the normalized coordinate space of the Volume,
+     * where the origin (0,0,0) is at the center of the Volume and the extent is
+     * from -0.5 to 0.5 in each axis.
      */
-    addLineObject(line: Line3d): void;
-    /** Returns whether a line object exists as a child of the volume. */
-    hasLineObject(line: Line3d): boolean;
-    /**
-     * Removes a Line3d object from the Volume, if it exists. Note that the
-     * object's resources are not freed automatically (e.g. via `line.cleanup()`).
+    addDrawableObject(object: IDrawableObject): void;
+    /** Returns whether a drawable object exists as a child of the volume. */
+    hasDrawableObject(object: IDrawableObject): boolean;
+    /** Removes a drawable object from the Volume, if it exists. Note that the
+     * object's resources are not freed automatically (e.g. via `object.cleanup()`).
      */
-    removeLineObject(line: Line3d): void;
+    removeDrawableObject(object: IDrawableObject): void;
     setupGui(pane: Pane): void;
     setZSlice(slice: number): boolean;
     get showBoundingBox(): boolean;

package/es/types/index.d.ts

@@ -20,10 +20,11 @@ import { VolumeLoadError, VolumeLoadErrorType } from "./loaders/VolumeLoadError.
 import { type CameraState } from "./ThreeJsPanel.js";
 import { Light, AREA_LIGHT, SKY_LIGHT } from "./Light.js";
 import Line3d from "./Line3d.js";
+import VectorArrows3d from "./VectorArrows3d.js";
 export type { ImageInfo } from "./ImageInfo.js";
 export type { ControlPoint } from "./Lut.js";
 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, type NumberType, };
+export { Histogram, Lut, Line3d, VectorArrows3d, 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/types.d.ts

@@ -80,6 +80,10 @@ export interface IDrawableObject {
     get3dObject(): Group;
     setTranslation(translation: Vector3): void;
     setScale(scale: Vector3): void;
+    /**
+     * Optional. Should be called when parent transforms are updated.
+     */
+    onParentTransformUpdated?(): void;
     setRotation(eulerXYZ: Euler): void;
     setFlipAxes(flipX: number, flipY: number, flipZ: number): void;
     setOrthoThickness(thickness: number): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aics/vole-core",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "volume renderer for 3d, 4d, or 5d imaging data with OME-Zarr support",
   "main": "es/index.js",
   "type": "module",
@@ -17,6 +17,7 @@
     "build": "npm run transpileES && npm run build-types",
     "build-types": "tsc -p tsconfig.types.json",
     "build-demo": "vite build public/ --config vite.config.ts --outDir ./demo",
+    "checks": "npm run lint & npm run typeCheck & npx vitest run",
     "clean": "rimraf es/",
     "format": "prettier --write src/**/*.ts",
     "gh-build": "vite build public/ --config vite.config.ts --outDir ./vole-core",