Merge branch 'main' into feature/rename-package

Author: ShrimpCryptid

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,39 @@
-**Pull request recommendations:**
+# Problem
 
-- [ ] Name your pull request _your-development-type/short-description_. Ex: _feature/read-tiff-files_
-- [ ] Link to any relevant issue in the PR description. Ex: _Resolves [gh-##], adds tiff file format support_
-- [ ] Provide description and context of changes.
-- [ ] Provide relevant tests for your feature or bug fix.
-- [ ] Provide or update documentation for any feature added by your pull request.
+What is the problem this work solves, including
+[Link to story or ticket](https://my-tracking-system.url/ticket-number)
+
+# Solution
+
+What I/we did to solve this problem
+
+with @pairperson1
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- Bug fix (non-breaking change which fixes an issue)
+- New feature (non-breaking change which adds functionality)
+- Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- This change requires a documentation update
+- This change requires updated or new tests
+
+## Steps to Verify:
+
+1. A setup step / beginning state
+1. What to do next
+1. Any other instructions
+1. Expected behavior
+1. Suggestions for testing
+
+## Screenshots (optional):
+
+Show-n-tell images/animations here
+
+## Keyfiles (delete if not relevant):
+
+1. main file/entry point
+2. other important file
 
 Thanks for contributing!

.github/workflows/ci.yml

@@ -3,7 +3,7 @@
 
 name: Node.js CI
 env:
-  NODE_VERSION: "18"
+  NODE_VERSION: "20"
 
 on: [push]
 

.github/workflows/nightly.yml

@@ -1,7 +1,7 @@
 name: github pages
 
 env:
-  NODE_VERSION: "18"
+  NODE_VERSION: "20"
 
 on:
   schedule:
@@ -19,7 +19,7 @@ jobs:
 
       - name: Cache dependencies
 
-        uses: actions/cache@v1
+        uses: actions/cache@v4
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

.github/workflows/publish.yml

@@ -3,7 +3,7 @@
 
 name: NPM Package
 env:
-  NODE_VERSION: "18"
+  NODE_VERSION: "20"
 on:
   push:
     # Sequence of patterns matched against refs/tags

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@aics/vole-core",
-  "version": "3.12.0",
+  "version": "3.12.3",
   "description": "volume renderer for 3d, 4d, or 5d imaging data with OME-Zarr support",
   "main": "es/index.js",
   "type": "module",
@@ -36,7 +36,7 @@
     "@babel/runtime": "^7.25.6",
     "geotiff": "^2.0.5",
     "serialize-error": "^11.0.3",
-    "three": "^0.162.0",
+    "three": "^0.171.0",
     "throttled-queue": "^2.1.4",
     "tweakpane": "^3.1.9",
     "zarrita": "^0.3.2"

package.json

@@ -96,7 +96,6 @@ export default class Atlas2DSlice implements VolumeRenderImpl {
   public updateVolumeDimensions(): void {
     const volumeScale = this.volume.normPhysicalSize.clone().multiply(this.settings.scale);
     const regionScale = volumeScale.clone().multiply(this.volume.normRegionSize);
-    console.log(regionScale);
     const volumeOffset = this.volume.getContentCenter().clone().multiply(this.settings.scale);
     this.geometryMesh.position.copy(volumeOffset);
     // set scale

src/Atlas2DSlice.ts

@@ -17,10 +17,15 @@ type HistogramData = {
 export default class Histogram {
   // no more than 2^32 pixels of any one intensity in the data!?!?!
   private bins: Uint32Array;
+  /** Min value in the original raw data. */
   private min: number;
+  /** Max value in the original raw data. */
   private max: number;
+  /** Size of each histogram bin in the scale of the original data. */
   private binSize: number;
+  /** Index of the first bin (other than 0) with at least 1 value. */
   private dataMinBin: number;
+  /** Index of the last bin (other than 0) with at least 1 value. */
   private dataMaxBin: number;
   private pixelCount: number;
   public maxBin: number;
@@ -41,14 +46,15 @@ export default class Histogram {
     this.max = hinfo.max;
     this.binSize = hinfo.binSize;
 
-    // track the first and last nonzero bins with at least 1 sample
-    for (let i = 1; i < this.bins.length; i++) {
+    // TODO: These should always return 0 and NBINS - 1, respectively. Test if these
+    // can be removed.
+    for (let i = 0; i < this.bins.length; i++) {
       if (this.bins[i] > 0) {
         this.dataMinBin = i;
         break;
       }
     }
-    for (let i = this.bins.length - 1; i >= 1; i--) {
+    for (let i = this.bins.length - 1; i >= 0; i--) {
       if (this.bins[i] > 0) {
         this.dataMaxBin = i;
         break;
@@ -83,27 +89,36 @@ export default class Histogram {
     return Histogram.findBin(value, this.min, this.binSize, NBINS);
   }
 
+  /**
+   * Return the min data value
+   * @return {number}
+   */
   getDataMin(): number {
     return this.min;
   }
 
+  /**
+   * Return the max data value
+   * @return {number}
+   */
   getDataMax(): number {
     return this.max;
   }
 
   /**
-   * Return the min data value
+   * Returns the first bin index with at least 1 value, other than the 0th bin.
    * @return {number}
    */
   getMin(): number {
     return this.dataMinBin;
   }
 
   /**
-   * Return the max data value
+   * Returns the last bin index with at least 1 value, other than the 0th bin.
    * @return {number}
    */
   getMax(): number {
+    // Note that this will always return `NBINS - 1`.
     return this.dataMaxBin;
   }
 

src/Histogram.ts

@@ -5,6 +5,7 @@ import {
   BufferAttribute,
   BufferGeometry,
   Color,
+  DataTexture,
   DepthTexture,
   Group,
   LineBasicMaterial,
@@ -16,10 +17,10 @@ import {
   PerspectiveCamera,
   ShaderMaterial,
   ShapeGeometry,
+  Texture,
   Vector2,
   Vector3,
   WebGLRenderer,
-  WebGLRenderTarget,
 } from "three";
 
 import FusedChannelData from "./FusedChannelData.js";
@@ -37,17 +38,6 @@ import { VolumeRenderSettings, SettingsFlags } from "./VolumeRenderSettings.js";
 
 const BOUNDING_BOX_DEFAULT_COLOR = new Color(0xffff00);
 
-function createEmptyDepthTexture(renderer: WebGLRenderer): DepthTexture {
-  const depthTexture = new DepthTexture(2, 2);
-  const target = new WebGLRenderTarget(2, 2);
-  target.depthTexture = depthTexture;
-  renderer.setRenderTarget(target);
-  // Don't clear color, do clear depth, don't clear stencil
-  renderer.clear(false, true, false);
-  renderer.setRenderTarget(null);
-  return depthTexture;
-}
-
 export default class RayMarchedAtlasVolume implements VolumeRenderImpl {
   private settings: VolumeRenderSettings;
   public volume: Volume;
@@ -59,7 +49,7 @@ export default class RayMarchedAtlasVolume implements VolumeRenderImpl {
   private geometryTransformNode: Group;
   private uniforms: ReturnType<typeof rayMarchingShaderUniforms>;
   private channelData!: FusedChannelData;
-  private emptyDepthTex?: DepthTexture;
+  private emptyPositionTex: DataTexture;
 
   /**
    * Creates a new RayMarchedAtlasVolume.
@@ -89,6 +79,8 @@ export default class RayMarchedAtlasVolume implements VolumeRenderImpl {
 
     this.geometryTransformNode.add(this.boxHelper, this.tickMarksMesh, this.geometryMesh);
 
+    this.emptyPositionTex = new DataTexture(new Uint8Array(Array(16).fill(0)), 2, 2);
+
     this.settings = settings;
     this.updateSettings(settings, SettingsFlags.ALL);
     // TODO this is doing *more* redundant work! Fix?
@@ -325,17 +317,15 @@ export default class RayMarchedAtlasVolume implements VolumeRenderImpl {
   public doRender(
     renderer: WebGLRenderer,
     camera: PerspectiveCamera | OrthographicCamera,
-    depthTexture?: DepthTexture
+    depthTexture?: DepthTexture | Texture
   ): void {
     if (!this.geometryMesh.visible) {
       return;
     }
 
-    if (!this.emptyDepthTex) {
-      this.emptyDepthTex = createEmptyDepthTexture(renderer);
-    }
-
-    this.setUniform("textureDepth", depthTexture ?? this.emptyDepthTex);
+    const depthTex = depthTexture ?? this.emptyPositionTex;
+    this.setUniform("textureDepth", depthTex);
+    this.setUniform("usingPositionTexture", (depthTex as DepthTexture).isDepthTexture ? 0 : 1);
     this.setUniform("CLIP_NEAR", camera.near);
     this.setUniform("CLIP_FAR", camera.far);
 

src/RayMarchedAtlasVolume.ts

@@ -226,6 +226,7 @@ export class View3d {
     if (this.image) {
       this.removeVolume(this.image.volume);
     }
+    this.image = undefined;
   }
 
   /**

src/View3d.ts

@@ -8,6 +8,7 @@ import {
   OrthographicCamera,
   PerspectiveCamera,
   WebGLRenderer,
+  Texture,
 } from "three";
 import { Pane } from "tweakpane";
 
@@ -117,22 +118,23 @@ export default class VolumeDrawable {
   }
 
   /**
-   * Updates whether a channel's data must be loaded for rendering, based on if its volume or isosurface is enabled.
+   * Updates whether a channel's data must be loaded for rendering,
+   * based on if its volume or isosurface is enabled, or whether it is needed for masking.
    * Calls `Volume.updateRequiredData` to update the list of required channels if necessary.
    */
   private updateChannelDataRequired(channelIndex: number): void {
     const { enabled, isosurfaceEnabled } = this.channelOptions[channelIndex];
-    const channelIsRequired = enabled || isosurfaceEnabled;
+    const channelIsRequired = enabled || isosurfaceEnabled || channelIndex === this.settings.maskChannelIndex;
     const requiredChannels = this.volume.loadSpecRequired.channels;
 
     if (requiredChannels.includes(channelIndex)) {
       if (!channelIsRequired) {
-        // This channel is currently marked required, but both its volume and isosurface are off. Remove it!
+        // This channel is currently marked required, but both its volume and isosurface are off, and it's not a mask. Remove it!
         this.volume.updateRequiredData({ channels: requiredChannels.filter((i) => i !== channelIndex) });
       }
     } else {
       if (channelIsRequired) {
-        // This channel is not marked required, but either its volume or isosurface is on. Add it!
+        // This channel is not marked required, but either its volume or isosurface is on, or it is a mask. Add it!
         this.volume.updateRequiredData({ channels: [...requiredChannels, channelIndex] });
       }
     }
@@ -386,7 +388,7 @@ export default class VolumeDrawable {
   onAnimate(
     renderer: WebGLRenderer,
     camera: PerspectiveCamera | OrthographicCamera,
-    depthTexture?: DepthTexture
+    depthTexture?: DepthTexture | Texture
   ): void {
     // TODO: this is inefficient, as this work is duplicated by threejs.
     // we need camera matrix up to date before giving the 3d objects a chance to use it.
@@ -596,6 +598,7 @@ export default class VolumeDrawable {
       return;
     }
     this.settings.maskChannelIndex = channelIndex;
+    this.updateChannelDataRequired(channelIndex);
     this.volumeRendering.updateSettings(this.settings, SettingsFlags.MASK_DATA);
   }
 

src/VolumeDrawable.ts

@@ -1,4 +1,4 @@
-import { DepthTexture, Object3D, OrthographicCamera, PerspectiveCamera, WebGLRenderer } from "three";
+import { DepthTexture, Object3D, OrthographicCamera, PerspectiveCamera, Texture, WebGLRenderer } from "three";
 
 import { SettingsFlags, VolumeRenderSettings } from "./VolumeRenderSettings.js";
 import type { FuseChannel } from "./types.js";
@@ -19,7 +19,7 @@ export interface VolumeRenderImpl {
   doRender: (
     renderer: WebGLRenderer,
     camera: PerspectiveCamera | OrthographicCamera,
-    depthTexture?: DepthTexture
+    depthTexture?: DepthTexture | Texture
   ) => void;
   updateVolumeDimensions: () => void;
   cleanup: () => void;