@aics/vole-core 3.15.3 → 3.15.5

package/es/Line3d.js

@@ -1,8 +1,8 @@
 import { Group, Vector3 } from "three";
-import { LineMaterial } from "three/addons/lines/LineMaterial";
-import { MESH_LAYER, OVERLAY_LAYER } from "./ThreeJsPanel";
-import { LineSegments2 } from "three/addons/lines/LineSegments2";
-import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry";
+import { LineMaterial } from "three/addons/lines/LineMaterial.js";
+import { MESH_LAYER, OVERLAY_LAYER } from "./ThreeJsPanel.js";
+import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 const DEFAULT_VERTEX_BUFFER_SIZE = 1020;
 
 /**

package/es/ThreeJsPanel.js

@@ -48,6 +48,7 @@ export class ThreeJsPanel {
     this.timestepIndicatorElement = document.createElement("div");
     this.showTimestepIndicator = false;
     this.animateFuncs = [];
+    this.postAnimateFuncs = [];
 
     // are we in a constant render loop or not?
     this.inRenderLoop = false;
@@ -572,6 +573,11 @@ export class ThreeJsPanel {
       this.renderer.render(this.axisHelperScene, this.axisCamera);
       this.renderer.autoClear = true;
     }
+    for (let i = 0; i < this.postAnimateFuncs.length; i++) {
+      if (this.postAnimateFuncs[i]) {
+        this.postAnimateFuncs[i](this.renderer, this.camera, this.meshRenderTarget.depthTexture);
+      }
+    }
     if (this.dataurlcallback) {
       this.dataurlcallback(this.canvas.toDataURL());
       this.dataurlcallback = undefined;
@@ -594,6 +600,7 @@ export class ThreeJsPanel {
     const delta = this.timer.lastFrameMs / 1000.0;
     this.controls.update(delta);
     this.render();
+    this.onRenderCallback?.();
   }
   startRenderLoop() {
     this.inRenderLoop = true;
@@ -610,6 +617,9 @@ export class ThreeJsPanel {
     }
     this.timer.end();
   }
+  setOnRenderCallback(callback) {
+    this.onRenderCallback = callback ?? undefined;
+  }
   removeControlHandlers() {
     if (this.controlStartHandler) {
       this.controls.removeEventListener("start", this.controlStartHandler);

package/es/View3d.js

@@ -1,4 +1,4 @@
-import { AmbientLight, Vector3, Object3D, SpotLight, DirectionalLight, Euler, Scene, Color } from "three";
+import { AmbientLight, Vector3, Object3D, SpotLight, DirectionalLight, Euler, Scene, Color, Matrix4 } from "three";
 import { Pane } from "tweakpane";
 import { MESH_LAYER, ThreeJsPanel } from "./ThreeJsPanel.js";
 import lightSettings from "./constants/lights.js";
@@ -107,6 +107,18 @@ export class View3d {
     this.redraw();
   }
 
+  /**
+   * Returns the view projection matrix, which transforms from world coordinates
+   * to clip space coordinates.
+   *
+   * 3D coordinates within the camera's view frustum will be transformed to a
+   * [-1, 1] range in the X and Y axes, and a [0, 1] range in the Z axis.
+   */
+  getViewProjectionMatrix() {
+    const camera = this.canvas3d.camera;
+    return new Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+  }
+
   /**
    * Force a redraw.
    * @param synchronous If true, the redraw will be done synchronously. If false (default), the
@@ -120,10 +132,18 @@ export class View3d {
       this.canvas3d.redraw();
     }
   }
+
+  /**
+   * Sets a listener that will be called after the 3D canvas renders.
+   */
+  setOnRenderCallback(callback) {
+    this.canvas3d.setOnRenderCallback(callback);
+  }
   unsetImage() {
     if (this.image) {
       this.canvas3d.removeControlHandlers();
       this.canvas3d.animateFuncs = [];
+      this.canvas3d.postAnimateFuncs = [];
       this.scene.remove(this.image.sceneRoot);
     }
     return this.image;
@@ -325,7 +345,11 @@ export class View3d {
     this.canvas3d.setControlHandlers(this.onStartControls.bind(this), this.onChangeControls.bind(this), this.onEndControls.bind(this));
     this.canvas3d.animateFuncs.push(this.preRender.bind(this));
     this.canvas3d.animateFuncs.push(img.onAnimate.bind(img));
-    this.canvas3d.animateFuncs.push(img.fillPickBuffer.bind(img));
+    // NOTE: `fillPickBuffer` MUST run after render occurs. This is because the
+    // pick buffer needs to access the `meshRenderTarget`'s depth texture, but
+    // during a resize, the texture is disposed of and not recreated until the
+    // next render.
+    this.canvas3d.postAnimateFuncs.push(img.fillPickBuffer.bind(img));
     this.updatePerspectiveScaleBar(img.volume);
     this.updateTimestepIndicator(img.volume);
 

package/es/Volume.js

@@ -14,13 +14,30 @@ export default class Volume {
    * 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 maximum of the measurements of 3 axes in physical units.
+   *
+   * Equivalent to `Math.max(physicalSize.x, physicalSize.y, physicalSize.z)`.
+   */
 
-  /** The physical size of a voxel in the original level 0 volume */
+  /**
+   * The size of a voxel in the original level 0 volume in real-world (physical)
+   * units (e.g. μm).
+   */
 
-  /** The physical dims of the whole volume (not accounting for subregion) */
+  /**
+   * The dimensions of the whole volume (not accounting for subregion) in
+   * real-world (physical) units. Equivalent to `imageInfo.originalSize *
+   * physicalPixelSize`.
+   */
 
-  /** Normalized physical size of the whole volume (not accounting for subregion) */
+  /**
+   * Physical size of the whole volume (not accounting for subregion) normalized
+   * along the largest axis, so that all dimensions are `<= 1`.
+   *
+   * Example: If the physical size is `[100, 50, 25]` μm, then the
+   * normPhysicalSize will be `[1, 0.5, 0.25]`.
+   */
 
   constructor(imageInfo = defaultImageInfo(), loadSpec = new LoadSpec(), loader) {
     this.loaded = false;

package/es/types/Line3d.d.ts

@@ -1,5 +1,5 @@
 import { Color, Euler, Group, Vector3 } from "three";
-import { IDrawableObject } from "./types";
+import { IDrawableObject } from "./types.js";
 /**
  * Simple wrapper for a 3D line segments object, with controls for vertex data,
  * color, width, and segments visible.

package/es/types/ThreeJsPanel.d.ts

@@ -13,13 +13,15 @@ export type CameraState = {
     /** The scale value for the orthographic camera controls; undefined for perspective cameras. */
     orthoScale?: number;
 };
+type AnimateFunction = (renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | null) => void;
 export declare class ThreeJsPanel {
     containerdiv: HTMLDivElement;
     private canvas;
     scene: Scene;
     private meshRenderTarget;
     private meshRenderToBuffer;
-    animateFuncs: ((renderer: WebGLRenderer, camera: PerspectiveCamera | OrthographicCamera, depthTexture?: DepthTexture | null) => void)[];
+    animateFuncs: AnimateFunction[];
+    postAnimateFuncs: AnimateFunction[];
     private inRenderLoop;
     private requestedRender;
     hasWebGL2: boolean;
@@ -54,6 +56,7 @@ export declare class ThreeJsPanel {
     private timestepIndicatorElement;
     showTimestepIndicator: boolean;
     private dataurlcallback?;
+    private onRenderCallback?;
     constructor(parentElement: HTMLElement | undefined, _useWebGL2: boolean);
     updateCameraFocus(fov: number, _focalDistance: number, _apertureSize: number): void;
     resetPerspectiveCamera(): void;
@@ -103,7 +106,9 @@ export declare class ThreeJsPanel {
     onAnimationLoop(): void;
     startRenderLoop(): void;
     stopRenderLoop(): void;
+    setOnRenderCallback(callback: (() => void) | null): void;
     removeControlHandlers(): void;
     setControlHandlers(onstart: EventListener<Event, "start", TrackballControls>, onchange: EventListener<Event, "change", TrackballControls>, onend: EventListener<Event, "end", TrackballControls>): void;
     hitTest(offsetX: number, offsetY: number, pickBuffer: WebGLRenderTarget | undefined): number;
 }
+export {};

package/es/types/View3d.d.ts

@@ -1,3 +1,4 @@
+import { Matrix4 } from "three";
 import { CameraState } from "./ThreeJsPanel.js";
 import VolumeDrawable from "./VolumeDrawable.js";
 import { Light } from "./Light.js";
@@ -53,6 +54,14 @@ export declare class View3d {
     getCanvasDOMElement(): HTMLCanvasElement;
     getCameraState(): CameraState;
     setCameraState(transform: Partial<CameraState>): void;
+    /**
+     * Returns the view projection matrix, which transforms from world coordinates
+     * to clip space coordinates.
+     *
+     * 3D coordinates within the camera's view frustum will be transformed to a
+     * [-1, 1] range in the X and Y axes, and a [0, 1] range in the Z axis.
+     */
+    getViewProjectionMatrix(): Matrix4;
     /**
      * Force a redraw.
      * @param synchronous If true, the redraw will be done synchronously. If false (default), the
@@ -60,6 +69,10 @@ export declare class View3d {
      * whenever possible for the best performance.
      */
     redraw(synchronous?: boolean): void;
+    /**
+     * Sets a listener that will be called after the 3D canvas renders.
+     */
+    setOnRenderCallback(callback: (() => void) | null): void;
     unsetImage(): VolumeDrawable | undefined;
     /**
      * Add a new volume image to the viewer.  (The viewer currently only supports a single image at a time - adding repeatedly, without removing in between, is a potential resource leak)

package/es/types/Volume.d.ts

@@ -30,13 +30,30 @@ export default class Volume {
     numChannels: number;
     channelNames: string[];
     channelColorsDefault: [number, number, number][];
-    /** The maximum of the measurements of 3 axes in physical units (pixels*physicalSize) */
+    /**
+     * The maximum of the measurements of 3 axes in physical units.
+     *
+     * Equivalent to `Math.max(physicalSize.x, physicalSize.y, physicalSize.z)`.
+     */
     physicalScale: number;
-    /** The physical size of a voxel in the original level 0 volume */
+    /**
+     * The size of a voxel in the original level 0 volume in real-world (physical)
+     * units (e.g. μm).
+     */
     physicalPixelSize: Vector3;
-    /** The physical dims of the whole volume (not accounting for subregion) */
+    /**
+     * The dimensions of the whole volume (not accounting for subregion) in
+     * real-world (physical) units. Equivalent to `imageInfo.originalSize *
+     * physicalPixelSize`.
+     */
     physicalSize: Vector3;
-    /** Normalized physical size of the whole volume (not accounting for subregion) */
+    /**
+     * Physical size of the whole volume (not accounting for subregion) normalized
+     * along the largest axis, so that all dimensions are `<= 1`.
+     *
+     * Example: If the physical size is `[100, 50, 25]` μm, then the
+     * normPhysicalSize will be `[1, 0.5, 0.25]`.
+     */
     normPhysicalSize: Vector3;
     normRegionSize: Vector3;
     normRegionOffset: Vector3;

package/es/types/loaders/zarr_utils/ChunkPrefetchIterator.d.ts

@@ -1,4 +1,4 @@
-import { PrefetchDirection, TCZYX } from "./types";
+import { PrefetchDirection, TCZYX } from "./types.js";
 type TZYX = [number, number, number, number];
 type PrefetchDirectionState = {
     direction: PrefetchDirection;

package/package.json

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