zincjs 3.0.1 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zincjs",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "ZincJS (Web-based-Zinc-Visualisation)",
   "type": "module",
   "main": "build/zinc.js",

package/src/primitives/lod.js

@@ -1,5 +1,11 @@
 import * as THREE from 'three/webgpu';
-import { keepIndexType, toBufferGeometry, updateMorphColorAttribute } from '../utilities';
+import {
+  keepIndexType,
+  extractVertices,
+  getTubeLinesGeometry,
+  toBufferGeometry,
+  updateMorphColorAttribute,
+} from '../utilities';
 import { LineSegments } from '../three/line/LineSegments';
 
 /**
@@ -28,6 +34,9 @@ const LOD = function (parent) {
   this._parent = parent;
   //Levels loaded after dispose are discarded
   this._disposed = false;
+  this._dirty = true;
+  this._bandMin = 0;
+  this._bandMax = -1;
 
   /*
    * Add a level of LOD at the specified distance
@@ -224,7 +233,7 @@ const LOD = function (parent) {
       const options = {
         localTimeEnabled: this._parent.timeEnabled,
         localMorphColour: this._parent.morphColour,
-        isLines: this._parent.isLines,
+        isLines: this._parent.isLines || this._parent.isTubeLines,
       };
       const geometry = toBufferGeometry(geometryIn, options);
       let mesh = undefined;
@@ -232,6 +241,15 @@ const LOD = function (parent) {
         mesh = new THREE.Mesh(geometry, material);
       } else if (this._parent.isLines) {
         mesh = new LineSegments(geometry, material);
+      } else if (this._parent.isTubeLines) {
+        const { radius, radialSegments, smooth } = this._parent.getGeometryConfig();
+        const tubeGeometry = getTubeLinesGeometry(
+          extractVertices(geometry),
+          radius,
+          radialSegments,
+          smooth,
+        );
+        mesh = new THREE.Mesh(tubeGeometry, material);
       }
       mesh.userData = this._parent;
       mesh.renderOrder = this._renderOrder;
@@ -348,50 +366,35 @@ const LOD = function (parent) {
   /* Update layers based on the */
   this.update = (camera, center) => {
     const levels = this.levels;
-    if (levels.length > 1) {
-      const distance = camera.cameraObject.position.distanceTo(center);
-      let visibleIndex = -1;
-      let optimalIndex = -1;
-      let i, l;
-      //Found a visible index that is within range of the LOD
-      for (i = 0, l = levels.length; i < l; i++) {
-        if (distance >= levels[i].distance) {
-          //Check if a level is loading
-          if (levels[i].morph) {
-            if (visibleIndex > -1 && levels[visibleIndex].morph) {
-              levels[visibleIndex].morph.visible = false;
-            }
-            visibleIndex = i;
-            levels[i].morph.visible = true;
-            optimalIndex = -1;
-          } else {
-            optimalIndex = i;
-          }
-        } else {
-          break;
-        }
-      }
-      if (optimalIndex > -1) {
-        this.loadLevel(optimalIndex);
-      }
-      for (; i < l; i++) {
-        if (levels[i].morph) {
-          //Set visibility of other morph to false
-          //and set the closest lod to true if
-          //none is found
-          if (visibleIndex > -1) {
-            levels[i].morph.visible = false;
-          } else {
-            levels[i].morph.visible = true;
-            visibleIndex = i;
-          }
-        }
-      }
-      if (this._currentLevel != visibleIndex) {
-        this._currentLevel = visibleIndex;
-        this.checkTransparentMesh();
-        this._parent?.requestRender?.();
-      }
+    const l = levels.length;
+    if (l < 2) return;
+    const distance = camera.cameraObject.position.distanceTo(center);
+
+    // Still in the same band and nothing new has loaded
+    if (!this._dirty && distance >= this._bandMin && distance < this._bandMax) return;
+    this._dirty = false;
+
+    // Furthest level whose threshold has been passed (levels are sorted by distance)
+    let target = -1;
+    while (target + 1 < l && distance >= levels[target + 1].distance) target++;
+    this._bandMin = target >= 0 ? levels[target].distance : -Infinity;
+    this._bandMax = target + 1 < l ? levels[target + 1].distance : Infinity;
+
+    if (target > -1 && !levels[target].morph) this.loadLevel(target);
+
+    // Show the nearest loaded level at or below target, else the nearest loaded one above
+    let visible = -1;
+    for (let i = target; i >= 0 && visible < 0; i--) if (levels[i].morph) visible = i;
+    for (let i = target + 1; i < l && visible < 0; i++) if (levels[i].morph) visible = i;
+
+    for (let i = 0; i < l; i++) {
+      if (levels[i].morph) levels[i].morph.visible = i === visible;
+    }
+
+    if (this._currentLevel !== visible) {
+      this._currentLevel = visible;
+      this.checkTransparentMesh();
+      this._parent?.requestRender?.();
     }
   };
 

package/src/primitives/marker.js

@@ -52,6 +52,9 @@ const Marker = function (zincObject) {
   let initialise = () => {
     sprite = new THREE.Sprite(spriteMaterial);
     sprite.center.set(0.5, 0);
+    //Culling sphere ignores sizeAttenuation: false, it may cull sprite
+    //and label independently
+    sprite.frustumCulled = false;
     this.morph.add(sprite);
     this.morph.position.set(0, 0, 0);
     this.morph.renderOrder = 10000;
@@ -133,6 +136,7 @@ const Marker = function (zincObject) {
     }
     userSprite = new THREE.Sprite(userMaterial);
     userSprite.center.set(0.5, 0);
+    userSprite.frustumCulled = false;
     userSprite.scale.set(size[0], size[1], size[2]);
     userSprite.userData = this;
     this.setUserSprite();
@@ -201,6 +205,7 @@ const Marker = function (zincObject) {
     if (!label && numberIn) {
       label = createNewSpriteText(numberIn, 0.012, 'black', 'Asap', 120, 700);
       label.renderOrder = 10001;
+      label.frustumCulled = false;
       this.morph.add(label);
     }
     number = numberIn;

package/src/primitives/markerCluster.js

@@ -74,6 +74,9 @@ const MarkerCluster = function (sceneIn) {
     const sprite = new THREE.Sprite(spriteMaterial);
     sprite.clusterIndex = index;
     sprite.center.set(0.5, 0);
+    //Culling sphere ignores sizeAttenuation: false, it may cull sprite
+    //and label independently
+    sprite.frustumCulled = false;
     sprite.position.set(0, 0, 0);
     sprite.renderOrder = 10000;
     sprite.scale.set(size[0], size[1], size[2]);
@@ -102,6 +105,7 @@ const MarkerCluster = function (sceneIn) {
       }
       sprite.label = createNewSpriteText(number, 0.012, 'black', 'Asap', 120, 700);
       sprite.label.renderOrder = 10001;
+      sprite.label.frustumCulled = false;
       sprite.number = number;
       sprite.group.add(sprite.label);
     }
@@ -177,6 +181,7 @@ const MarkerCluster = function (sceneIn) {
       const current = Date.now();
       if (current - start > 500) {
         let clusters = [];
+        //Make a shallow copy of the markers array
         getCluster({ ...this.markers }, clusters);
         drawClusters(clusters);
         scene?.invalidate?.();

package/src/primitives/textureSlides.js

@@ -336,6 +336,20 @@ const TextureSlides = function (textureIn) {
     return this.cachedBoundingBox;
   };
 
+  /**
+   * Get the normalised coordinates of a point in world coordinates.
+   * The returned values can be used as the value of {@link SLIDE_SETTINGS}.
+   * Values within [0, 1] are inside the texture box.
+   *
+   * @param {Array} position - World coordinates [x, y, z].
+   * @return {Array} - Normalised coordinates [x, y, z].
+   */
+  this.getPositionInBox = (position) => {
+    const matrix = updateWorldMatrixFromAncestors(this.morph).clone().invert();
+    const vector = new THREE.Vector3(...position).applyMatrix4(matrix);
+    return vector.toArray();
+  };
+
   this.applyTransformation = (rotation, position, scale) => {
     this.requestRender();
     const matrix = new THREE.Matrix4();

package/src/primitives/tubeLines.js

@@ -1,5 +1,5 @@
 import * as THREE from 'three/webgpu';
-import { mergeGeometries } from '../utilities';
+import { extractVertices, getTubeLinesGeometry } from '../utilities';
 import { ZincObject } from './zincObject';
 
 /**
@@ -31,13 +31,27 @@ const TubeLines = function () {
   this.createLineSegment = (geometryIn, materialIn, options) => {
     if (geometryIn && materialIn) {
       dataIn = { geometryIn, materialIn, options };
-      const geometry = getTubeLinesGeometry(extractVertices(geometryIn));
+      const { radius, radialSegments, smooth } = geometryConfig;
+      const geometry = getTubeLinesGeometry(
+        extractVertices(geometryIn),
+        radius,
+        radialSegments,
+        smooth,
+      );
       const material = new THREE.MeshStandardMaterial({ color: materialIn.color });
       const mesh = new THREE.Mesh(geometry, material);
       this.setMesh(mesh, options.localTimeEnabled, options.localMorphColour);
     }
   };
 
+  /**
+   * Return the settings used for creating the tube line.
+   *
+   */
+  this.getGeometryConfig = () => {
+    return geometryConfig;
+  };
+
   /**
    * Set the width for the lines.
    *
@@ -90,50 +104,13 @@ const TubeLines = function () {
       mesh.geometry.dispose();
 
       geometryConfig = Object.assign(geometryConfig, { radius, radialSegments });
-      mesh.geometry = getTubeLinesGeometry(extractVertices(geometryIn));
-    }
-  };
-
-  /**
-   * Read the position attribute of a BufferGeometry into an array of
-   * THREE.Vector3, since TubeGeometry/CatmullRomCurve3/LineCurve3 need
-   * actual Vector3 instances to work with, not a flat typed array.
-   *
-   * @param {THREE.BufferGeometry} geometry
-   * @returns {Array}
-   */
-  const extractVertices = (geometry) => {
-    const position = geometry.getAttribute('position');
-    const vertices = [];
-    for (let i = 0; i < position.count; i++) {
-      vertices.push(new THREE.Vector3().fromBufferAttribute(position, i));
-    }
-    return vertices;
-  };
-
-  /**
-   * Get merged geometry from list of geometry vertices
-   *
-   * @param {Array} vertices - An array of THREE.Vector3 vertices.
-   * @returns {Object}
-   */
-  const getTubeLinesGeometry = (vertices) => {
-    const { radius, radialSegments, smooth } = geometryConfig;
-    let finalGeometry;
-    if (smooth) {
-      const curve = new THREE.CatmullRomCurve3(vertices);
-      finalGeometry = new THREE.TubeGeometry(curve, vertices.length, radius, radialSegments, false);
-    } else {
-      const geometries = [];
-      for (let i = 0; i + 1 < vertices.length; i = i + 2) {
-        const curve = new THREE.LineCurve3(vertices[i], vertices[i + 1]);
-        const tubeGeometry = new THREE.TubeGeometry(curve, 1, radius, radialSegments, false);
-        geometries.push(tubeGeometry);
-      }
-      finalGeometry = mergeGeometries(geometries, true);
-      geometries.forEach((g) => g.dispose());
+      mesh.geometry = getTubeLinesGeometry(
+        extractVertices(geometryIn),
+        radius,
+        radialSegments,
+        geometryConfig.smooth,
+      );
     }
-    return finalGeometry;
   };
 };
 

package/src/renderer.js

@@ -38,7 +38,6 @@ const Renderer = function (containerIn) {
   let contextLostCallbackFunctions_id = 0;
   let contextRestoredCallbackFunctions = {};
   let contextRestoredCallbackFunctions_id = 0;
-  let animated_id = undefined;
   let cameraOrtho = undefined,
     sceneOrtho = undefined,
     logoSprite = undefined;
@@ -179,6 +178,8 @@ const Renderer = function (containerIn) {
       }
       renderer = new THREE.WebGPURenderer(parameters);
       await renderer.init();
+      //animate() may have been called before the renderer was ready
+      if (isRendering) renderer.setAnimationLoop(this.render);
       //GPU glyph animation requires the WebGPU backend, the WebGL fallback
       //cannot index storage buffers freely.
       setGlyphComputeSupported(renderer.backend?.isWebGPUBackend === true);
@@ -378,22 +379,13 @@ const Renderer = function (containerIn) {
     currentScene.updateDirectionalLight();
   };
 
-  let runAnimation = () => {
-    if (isRendering) {
-      animated_id = requestAnimationFrame(runAnimation);
-      this.render();
-    } else {
-      cancelAnimationFrame(animated_id);
-      animated_id = undefined;
-    }
-  };
-
   /**
    * Stop the animation and renderer to get into the render loop.
    */
   this.stopAnimate = () => {
     if (isRendering) {
       isRendering = false;
+      renderer?.setAnimationLoop(null);
     }
   };
 
@@ -405,7 +397,10 @@ const Renderer = function (containerIn) {
       clock.reset();
       isRendering = true;
       needsRender = true;
-      runAnimation();
+      //WebGPURenderer always runs its own requestAnimationFrame loop which
+      //updates the node frame and the per frame info, render from that loop
+      //instead of running a second one.
+      renderer?.setAnimationLoop(this.render);
     }
   };
 
@@ -646,7 +641,16 @@ const Renderer = function (containerIn) {
     }
     clock.update();
     const delta = clock.getDelta();
-    let changed = currentScene.renderGeometries(playRate, delta, this.playAnimation);
+    //Objects are only updated on every frame when render on demand is off
+    //or the renderer itself has requested a frame, e.g. on resize
+    const forceUpdate = !renderOnDemand || needsRender;
+    let changed = currentScene.renderGeometries(
+      playRate,
+      delta,
+      this.playAnimation,
+      undefined,
+      forceUpdate,
+    );
     if (additionalActiveScenes.length > 0) {
       //Additional scenes are displayed with the current scene's camera
       sharedCamera.controls = currentScene.getZincCameraControls();
@@ -654,7 +658,9 @@ const Renderer = function (containerIn) {
     }
     for (let i = 0; i < additionalActiveScenes.length; i++) {
       const sceneItem = additionalActiveScenes[i];
-      if (sceneItem.renderGeometries(playRate, delta, this.playAnimation, sharedCamera))
+      if (
+        sceneItem.renderGeometries(playRate, delta, this.playAnimation, sharedCamera, forceUpdate)
+      )
         changed = true;
     }
     for (let key in preRenderCallbackFunctions) {
@@ -756,7 +762,6 @@ const Renderer = function (containerIn) {
    * Dispose all memory allocated, this will effetively destroy all scenes.
    */
   this.dispose = () => {
-    if (isRendering) cancelAnimationFrame(animated_id);
     for (const key in sceneMap) {
       if (sceneMap.hasOwnProperty(key)) {
         sceneMap[key].clearAll();

package/src/scene.js

@@ -624,11 +624,25 @@ const Scene = function (containerIn, rendererIn) {
    * Update geometries and glyphsets based on the calculated time.
    * @private
    */
-  this.renderGeometries = (playRate, delta, playAnimation, sharedCamera) => {
+  this.renderGeometries = (playRate, delta, playAnimation, sharedCamera, forceUpdate) => {
     //Anything requested since the last frame
     let changed = needsRender;
     needsRender = false;
     cameraUpdated = false;
+    //These are plain properties, check if they have changed before
+    //the objects are updated so markers are toggled on this frame
+    if (
+      lastDisplayState.displayMarkers !== this.displayMarkers ||
+      lastDisplayState.displayMinimap !== this.displayMinimap ||
+      lastDisplayState.displayMiniAxes !== this.displayMiniAxes ||
+      lastDisplayState.playAnimation !== playAnimation
+    ) {
+      lastDisplayState.displayMarkers = this.displayMarkers;
+      lastDisplayState.displayMinimap = this.displayMinimap;
+      lastDisplayState.displayMiniAxes = this.displayMiniAxes;
+      lastDisplayState.playAnimation = playAnimation;
+      changed = true;
+    }
     //Additional active scenes are displayed with the current scene's camera
     const cameraControls = sharedCamera ? sharedCamera.controls : zincCameraControls;
     //Reused on every frame to avoid allocations
@@ -680,25 +694,30 @@ const Scene = function (containerIn, rendererIn) {
             zincCameraControls.calculateHeightPerPixelAtZeroDepth(getDrawingHeight());
           }
         }
-        rootRegion.renderGeometries(playRate, delta, playAnimation, cameraControls, options, true);
+        //Walking every object is costly for large scenes, only do it when
+        //something may have changed, LOD and markers depend on the camera
+        if (
+          forceUpdate ||
+          changed ||
+          options.ndcToBeUpdated ||
+          playAnimation ||
+          //Clusters are recalculated during the walk
+          (markerCluster.isEnabled() && markerCluster.markerUpdateRequired)
+        ) {
+          rootRegion.renderGeometries(
+            playRate,
+            delta,
+            playAnimation,
+            cameraControls,
+            options,
+            true,
+          );
+        }
       } else if (!sharedCamera && zincCameraControls.update(0)) {
         changed = true;
         cameraUpdated = true;
       }
     }
-    //These are plain properties, check if they have changed
-    if (
-      lastDisplayState.displayMarkers !== this.displayMarkers ||
-      lastDisplayState.displayMinimap !== this.displayMinimap ||
-      lastDisplayState.displayMiniAxes !== this.displayMiniAxes ||
-      lastDisplayState.playAnimation !== playAnimation
-    ) {
-      lastDisplayState.displayMarkers = this.displayMarkers;
-      lastDisplayState.displayMinimap = this.displayMinimap;
-      lastDisplayState.displayMiniAxes = this.displayMiniAxes;
-      lastDisplayState.playAnimation = playAnimation;
-      changed = true;
-    }
     //The flag is only cleared when the minimap is drawn
     if (this.minimapScissor.updateRequired && (this.displayMinimap || this.displayMiniAxes)) {
       changed = true;

package/src/utilities.js

@@ -31,6 +31,23 @@ function createNewURL(target, reference) {
   }
 }
 
+/**
+ * Read the position attribute of a BufferGeometry into an array of
+ * THREE.Vector3, since TubeGeometry/CatmullRomCurve3/LineCurve3 need
+ * actual Vector3 instances to work with, not a flat typed array.
+ *
+ * @param {THREE.BufferGeometry} geometry
+ * @returns {Array}
+ */
+const extractVertices = (geometry) => {
+  const position = geometry.getAttribute('position');
+  const vertices = [];
+  for (let i = 0; i < position.count; i++) {
+    vertices.push(new THREE.Vector3().fromBufferAttribute(position, i));
+  }
+  return vertices;
+};
+
 /*
  * Compute the world matrix of an object from its ancestors and return it.
  * three.js only recomputes world matrices flagged by matrixWorldNeedsUpdate,
@@ -85,6 +102,30 @@ function getBoundingBox(mesh, cachedBox, b1, v1, v2) {
   cachedBox.applyMatrix4(updateWorldMatrixFromAncestors(mesh));
 }
 
+/**
+ * Create tube line geometry based on lines geometry, radius, segments and smooth.
+ *
+ * @param {Array} vertices - An array of THREE.Vector3 vertices.
+ * @returns {Object}
+ */
+function getTubeLinesGeometry(vertices, radius, radialSegments, smooth) {
+  let finalGeometry;
+  if (smooth) {
+    const curve = new THREE.CatmullRomCurve3(vertices);
+    finalGeometry = new THREE.TubeGeometry(curve, vertices.length, radius, radialSegments, false);
+  } else {
+    const geometries = [];
+    for (let i = 0; i + 1 < vertices.length; i = i + 2) {
+      const curve = new THREE.LineCurve3(vertices[i], vertices[i + 1]);
+      const tubeGeometry = new THREE.TubeGeometry(curve, 1, radius, radialSegments, false);
+      geometries.push(tubeGeometry);
+    }
+    finalGeometry = mergeGeometries(geometries, true);
+    geometries.forEach((g) => g.dispose());
+  }
+  return finalGeometry;
+}
+
 //Convenient function
 function loadExternalFile(url, data, callback, errorCallback) {
   // Set up an asynchronous request
@@ -908,8 +949,10 @@ export {
   createBufferGeometry,
   createNewSpriteText,
   createNewURL,
+  extractVertices,
   getBoundingBox,
   getCircularTexture,
+  getTubeLinesGeometry,
   keepIndexType,
   updateWorldMatrixFromAncestors,
   useStandardIndexType,