@aics/vole-core 3.15.3 → 3.15.4

package/es/ThreeJsPanel.js

@@ -594,6 +594,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 +611,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,6 +132,13 @@ 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();

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/ThreeJsPanel.d.ts

@@ -54,6 +54,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,6 +104,7 @@ 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;

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/package.json

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