@inweb/viewer-three 27.2.2 → 27.3.0

package/src/Viewer/loaders/DynamicGltfLoader/DynamicGltfLoader.js

@@ -23,6 +23,10 @@ import {
   NormalBlending,
   BufferAttribute,
   LineBasicMaterial,
+  DataTexture,
+  RGBAFormat,
+  FloatType,
+  NearestFilter,
 } from "three";
 import { GL_CONSTANTS } from "./GltfStructure.js";
 import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
@@ -61,10 +65,6 @@ export class DynamicGltfLoader {
 
     this.memoryLimit = this.getAvailableMemory();
     this.optimizationMemoryMultiplier = 5;
-    /**
-     * Real memory ~1.7x raw geometry (Three.js objects, Map/Set, buffers overhead). Used for limit
-     * checks and display.
-     */
     this.memoryEstimationFactor = 1.7;
     this.loadedGeometrySize = 0;
     this.geometryCache = new Map();
@@ -110,6 +110,12 @@ export class DynamicGltfLoader {
     this.objectTransforms = new Map(); // originalObject -> Matrix4
     this.transformedGeometries = new Map(); // mergedObject.uuid -> original position data
 
+    // TODO: Remove when highlight is implemented via shader.
+    // Sync transforms to original (hidden) objects so GeometryHighlighter
+    // wireframes follow the exploded positions.
+    this.syncTransformsToOriginalObjects = true;
+    this._originalObjectMatrices = new Map(); // object -> original matrix (for restore)
+
     this.activeChunkLoads = 0;
     this.chunkQueue = [];
 
@@ -126,6 +132,123 @@ export class DynamicGltfLoader {
     this.mergedGeometryVisibility = new Map(); // mergedObject -> visibility array
 
     this._webglInfoCache = null;
+
+    // Transform texture support
+    this.transformTextureSize = 1024;
+    this.transformTexture = this.createDummyTexture();
+    this.transformData = null;
+    this.identityTransformData = null;
+    this.visibilityMaterials = new Set(); // Keep track of materials to update uniforms
+  }
+
+  // layout (1 matrix = 4 pixels)
+  //      RGBA RGBA RGBA RGBA (=> column1, column2, column3, column4)
+  //  with  8x8  pixel texture max   16 matrices * 4 pixels =  (8 * 8)
+  //       16x16 pixel texture max   64 matrices * 4 pixels = (16 * 16)
+  //       32x32 pixel texture max  256 matrices * 4 pixels = (32 * 32)
+  //       64x64 pixel texture max 1024 matrices * 4 pixels = (64 * 64)
+
+  createDummyTexture() {
+    // Create 1x1 dummy texture with identity matrix to prevent shader crash/black screen
+    const data = new Float32Array(16); // 4x4 matrix
+    const identity = new Matrix4();
+    identity.toArray(data);
+
+    // Correct dummy size: 4x1 to hold at least one matrix
+    const dummyData = new Float32Array(16);
+    identity.toArray(dummyData);
+    const dummyTexture = new DataTexture(dummyData, 4, 1, RGBAFormat, FloatType);
+
+    dummyTexture.minFilter = NearestFilter;
+    dummyTexture.magFilter = NearestFilter;
+    dummyTexture.needsUpdate = true;
+    return dummyTexture;
+  }
+
+  initTransformTexture() {
+    if (this.transformTexture) {
+      this.transformTexture.dispose();
+    }
+
+    // Logic from BatchedMesh.js _initMatricesTexture
+    // layout (1 matrix = 4 pixels)
+    // RGBA RGBA RGBA RGBA (=> column1, column2, column3, column4)
+    const maxInstanceCount = this.maxObjectId + 1;
+    let size = Math.sqrt(maxInstanceCount * 4); // 4 pixels needed for 1 matrix
+    size = Math.ceil(size / 4) * 4;
+    size = Math.max(size, 4);
+
+    this.transformTextureSize = size;
+    const arraySize = size * size * 4; // 4 floats per RGBA pixel
+    this.transformData = new Float32Array(arraySize);
+
+    // Create and cache identity matrices for fast reset
+    this.identityTransformData = new Float32Array(arraySize);
+    for (let i = 0; i <= this.maxObjectId; i++) {
+      const base = i * 16;
+      if (base + 15 < arraySize) {
+        this.identityTransformData[base + 0] = 1; // m00
+        this.identityTransformData[base + 5] = 1; // m11
+        this.identityTransformData[base + 10] = 1; // m22
+        this.identityTransformData[base + 15] = 1; // m33
+      }
+    }
+
+    // Initialize with identity matrices
+    this._resetTransformData(false);
+
+    this.transformTexture = new DataTexture(this.transformData, size, size, RGBAFormat, FloatType);
+
+    this.transformTexture.needsUpdate = true;
+    this.transformTexture.generateMipmaps = false;
+
+    console.log(`Initialized transform texture: ${size}x${size} for ${maxInstanceCount} objects`);
+
+    this.updateMaterialUniforms();
+
+    // Force all visibility materials to update
+    this.visibilityMaterials.forEach((material) => {
+      material.needsUpdate = true;
+    });
+  }
+
+  // Fast reset to Identity matrices without creating Matrix4 objects
+  _resetTransformData(updateTexture = true) {
+    if (!this.transformData || !this.identityTransformData) return;
+
+    // Fast copy from cached identity array
+    this.transformData.set(this.identityTransformData);
+
+    if (updateTexture) {
+      this.updateTransformTexture();
+    }
+  }
+
+  updateMaterialUniforms() {
+    // Only update if the texture actually changed
+    // In three.js, setting `.value = this.transformTexture` triggers uniformity checks
+    // We can avoid looping over all materials if the texture reference hasn't changed
+    if (
+      this._lastTransformTexture === this.transformTexture &&
+      this._lastTransformTextureSize === this.transformTextureSize
+    ) {
+      return;
+    }
+
+    this._lastTransformTexture = this.transformTexture;
+    this._lastTransformTextureSize = this.transformTextureSize;
+
+    this.visibilityMaterials.forEach((material) => {
+      if (material.userData && material.userData.visibilityUniforms) {
+        material.userData.visibilityUniforms.transformTexture.value = this.transformTexture;
+        material.userData.visibilityUniforms.transformTextureSize.value = this.transformTextureSize;
+      }
+    });
+  }
+
+  updateTransformTexture() {
+    if (!this.transformTexture) return;
+    this.transformTexture.needsUpdate = true;
   }
 
   setVisibleEdges(visible) {
@@ -1169,42 +1292,100 @@ export class DynamicGltfLoader {
   }
 
   createVisibilityMaterial(material) {
+    this.visibilityMaterials.add(material);
+
+    const uniforms = {
+      transformTexture: { value: this.transformTexture },
+      transformTextureSize: { value: this.transformTextureSize },
+    };
+    material.userData.visibilityUniforms = uniforms;
+
     material.onBeforeCompile = (shader) => {
+      shader.uniforms.transformTexture = uniforms.transformTexture;
+      shader.uniforms.transformTextureSize = uniforms.transformTextureSize;
+
+      // 1. Common Definitions
       shader.vertexShader = shader.vertexShader.replace(
         "#include <common>",
         `
         #include <common>
+        
         attribute float visibility;
+        attribute float objectId;
         varying float vVisibility;
+        uniform highp sampler2D transformTexture;
+        uniform float transformTextureSize;
+
+        mat4 getTransformMatrix(float instanceId) {
+            int size = int(transformTextureSize);
+            int index = int(instanceId) * 4;
+            
+            int x0 = index % size;
+            int y0 = index / size;
+            
+            vec4 row0 = texelFetch(transformTexture, ivec2(x0, y0), 0);
+            vec4 row1 = texelFetch(transformTexture, ivec2(x0 + 1, y0), 0);
+            vec4 row2 = texelFetch(transformTexture, ivec2(x0 + 2, y0), 0);
+            vec4 row3 = texelFetch(transformTexture, ivec2(x0 + 3, y0), 0);
+            
+            return mat4(row0, row1, row2, row3);
+        }
         `
       );
 
-      shader.fragmentShader = shader.fragmentShader.replace(
-        "#include <common>",
+      // 2. Inject matrix retrieval at start of main()
+      shader.vertexShader = shader.vertexShader.replace(
+        "void main() {",
         `
-        #include <common>
-        varying float vVisibility;
+        void main() {
+            mat4 batchingMatrix = getTransformMatrix(objectId);
+            vVisibility = visibility;
         `
       );
 
+      // 3. Transform Normal
+      if (shader.vertexShader.includes("#include <beginnormal_vertex>")) {
+        shader.vertexShader = shader.vertexShader.replace(
+          "#include <beginnormal_vertex>",
+          `
+            vec3 objectNormal = vec3( normal );
+            mat3 bm = mat3( batchingMatrix );
+            objectNormal = bm * objectNormal;
+            `
+        );
+      }
+
+      // 4. Transform Position
       shader.vertexShader = shader.vertexShader.replace(
-        "void main() {",
+        "#include <begin_vertex>",
         `
-        void main() {
-          vVisibility = visibility;
+        vec3 transformed = vec3( position );
+        transformed = ( batchingMatrix * vec4( transformed, 1.0 ) ).xyz;
         `
       );
 
-      shader.fragmentShader = shader.fragmentShader.replace(
-        "void main() {",
+      // 5. Fragment Shader
+      shader.fragmentShader = shader.fragmentShader
+        .replace(
+          "#include <common>",
+          `
+        #include <common>
+        varying float vVisibility;
         `
+        )
+        .replace(
+          "void main() {",
+          `
         void main() {
           if (vVisibility < 0.5) discard;
         `
-      );
+        );
+
+      //console.log("!vertex", shader.vertexShader);
     };
-    material.needsUpdate = true;
 
+    // Ensure the material recompiles to pick up changes
+    material.needsUpdate = true;
     return material;
   }
 
@@ -1320,6 +1501,7 @@ export class DynamicGltfLoader {
 
     this.objectTransforms.clear();
     this.transformedGeometries.clear();
+    this._originalObjectMatrices.clear();
 
     this.totalLoadedObjects = 0;
     this.currentMemoryUsage = 0;
@@ -1332,6 +1514,8 @@ export class DynamicGltfLoader {
     this.objectIdToIndex.clear();
     this.maxObjectId = 0;
     this.objectVisibility = new Float32Array();
+    this.meshToNodeMap = null;
+    this.visibilityMaterials.clear();
   }
 
   setStructureTransform(structureId, matrix) {
@@ -1466,6 +1650,10 @@ export class DynamicGltfLoader {
 
     this.originalObjects.clear();
     this.originalObjectsToSelection.clear();
+    // Clear previous optimization data
+    this.objectIdToIndex.clear();
+    this.maxObjectId = 0;
+
     const structureGroups = new Map();
 
     this.dispatchEvent("optimizationprogress", {
@@ -1474,6 +1662,8 @@ export class DynamicGltfLoader {
       message: "Collecting scene objects...",
     });
 
+    let totalObjectsToMerge = 0;
+
     this.scene.traverse((object) => {
       if (object.userData.structureId) {
         const structureId = object.userData.structureId;
@@ -1493,19 +1683,41 @@ export class DynamicGltfLoader {
         }
 
         const group = structureGroups.get(structureId);
+        let added = false;
 
         if (object instanceof Mesh) {
           this.addToMaterialGroup(object, group.mapMeshes, group.meshes);
+          added = true;
         } else if (object instanceof LineSegments) {
           this.addToMaterialGroup(object, group.mapLineSegments, group.lineSegments);
+          added = true;
         } else if (object instanceof Line) {
           this.addToMaterialGroup(object, group.mapLines, group.lines);
+          added = true;
         } else if (object instanceof Points) {
           this.addToMaterialGroup(object, group.mapPoints, group.points);
+          added = true;
+        }
+
+        if (added) {
+          totalObjectsToMerge++;
         }
       }
     });
 
+    // Initialize transform texture and visibility arrays BEFORE merging
+    // This ensures that as we create merged objects, the texture is large enough
+    // and populated with identity matrices, so objects don't disappear (scale 0).
+    if (totalObjectsToMerge > 0) {
+      console.log(`Pre-allocating transform texture for ${totalObjectsToMerge} objects`);
+      this.maxObjectId = totalObjectsToMerge;
+      this.initTransformTexture();
+      this.initializeObjectVisibility();
+
+      // Reset counter so IDs are assigned from 0 during merge
+      this.maxObjectId = 0;
+    }
+
     let processedGroups = 0;
     const totalGroups = structureGroups.size;
 
@@ -1563,7 +1775,7 @@ export class DynamicGltfLoader {
       }
     });
 
-    this.initializeObjectVisibility();
+    // Texture and visibility initialized at start of optimization
 
     console.log(`Optimization complete. Total objects: ${this.maxObjectId}`);
 
@@ -1658,6 +1870,7 @@ export class DynamicGltfLoader {
           const visibilityMaterial = this.createVisibilityMaterial(group.material);
 
           const mergedMesh = new Mesh(mergedGeometry, visibilityMaterial);
+          mergedMesh.frustumCulled = false; // Disable culling because vertex shader moves objects
           mergedMesh.userData.isOptimized = true;
           rootGroup.add(mergedMesh);
 
@@ -1804,6 +2017,7 @@ export class DynamicGltfLoader {
       const visibilityMaterial = this.createVisibilityMaterial(group.material);
 
       const mergedLine = new LineSegments(geometry, visibilityMaterial);
+      mergedLine.frustumCulled = false;
       mergedLine.userData.isEdge = isEdge;
       mergedLine.userData.isOptimized = true;
 
@@ -1915,6 +2129,7 @@ export class DynamicGltfLoader {
           const visibilityMaterial = this.createVisibilityMaterial(group.material);
 
           const mergedLine = new LineSegments(mergedGeometry, visibilityMaterial);
+          mergedLine.frustumCulled = false;
           mergedLine.userData.isEdge = isEdge;
           mergedLine.userData.isOptimized = true;
 
@@ -2001,7 +2216,33 @@ export class DynamicGltfLoader {
 
         if (geometries.length > 0) {
           const mergedGeometry = mergeGeometries(geometries, false);
-          const mergedPoints = new Points(mergedGeometry, group.material);
+
+          // Add objectId attribute
+          const totalVertices = mergedGeometry.attributes.position.count;
+          const objectIds = new Float32Array(totalVertices);
+          let vertexOffset = 0;
+
+          group.objects.forEach((points) => {
+            const handle = points.userData.handle;
+            if (!this.objectIdToIndex.has(handle)) {
+              this.objectIdToIndex.set(handle, this.maxObjectId++);
+            }
+            const objectId = this.objectIdToIndex.get(handle);
+            const count = points.geometry.attributes.position.count;
+            for (let i = 0; i < count; i++) {
+              objectIds[vertexOffset++] = objectId;
+            }
+          });
+          mergedGeometry.setAttribute("objectId", new BufferAttribute(objectIds, 1));
+
+          // Add visibility attribute
+          const visibilityArray = new Float32Array(totalVertices);
+          visibilityArray.fill(1.0);
+          mergedGeometry.setAttribute("visibility", new BufferAttribute(visibilityArray, 1));
+
+          const visibilityMaterial = this.createVisibilityMaterial(group.material);
+          const mergedPoints = new Points(mergedGeometry, visibilityMaterial);
+          mergedPoints.frustumCulled = false;
           mergedPoints.userData.isOptimized = true;
 
           if (this.useVAO) {
@@ -2085,15 +2326,41 @@ export class DynamicGltfLoader {
       });
 
       const finalGeometry = mergeGeometries(geometriesWithIndex, false);
+
+      // Add objectId attribute
+      const totalVertices = finalGeometry.attributes.position.count;
+      const objectIds = new Float32Array(totalVertices);
+      let vertexOffset = 0;
+
+      lineSegmentsArray.forEach((segment) => {
+        const handle = segment.userData.handle;
+        if (!this.objectIdToIndex.has(handle)) {
+          this.objectIdToIndex.set(handle, this.maxObjectId++);
+        }
+        const objectId = this.objectIdToIndex.get(handle);
+        const count = segment.geometry.attributes.position.count;
+        for (let i = 0; i < count; i++) {
+          objectIds[vertexOffset++] = objectId;
+        }
+      });
+      finalGeometry.setAttribute("objectId", new BufferAttribute(objectIds, 1));
+
+      // Add visibility attribute
+      const visibilityArray = new Float32Array(totalVertices);
+      visibilityArray.fill(1.0);
+      finalGeometry.setAttribute("visibility", new BufferAttribute(visibilityArray, 1));
+
       const material = new LineBasicMaterial({
         vertexColors: true,
       });
+      const visibilityMaterial = this.createVisibilityMaterial(material);
 
       if (this.useVAO) {
         this.createVAO(finalGeometry);
       }
 
-      const mergedLine = new LineSegments(finalGeometry, material);
+      const mergedLine = new LineSegments(finalGeometry, visibilityMaterial);
+      mergedLine.frustumCulled = false;
       mergedLine.userData.structureId = structureId;
       mergedLine.userData.isOptimized = true;
       rootGroup.add(mergedLine);
@@ -2238,223 +2505,269 @@ export class DynamicGltfLoader {
       return;
     }
 
-    // Store transform map directly
-    this.objectTransforms = new Map(objectTransformMap);
-
-    // Apply transforms to all merged meshes
-    for (const mesh of this.mergedMesh) {
-      this._applyTransformToMergedObject(mesh);
-    }
-    for (const line of this.mergedLines) {
-      this._applyTransformToMergedObject(line);
-    }
-    for (const lineSegment of this.mergedLineSegments) {
-      this._applyTransformToMergedObject(lineSegment);
-    }
-    for (const point of this.mergedPoints) {
-      this._applyTransformToMergedObject(point);
-    }
-  }
-
-  createExplodeTransforms(objects = null, explodeCenter = null, explodeFactor = 1.5) {
-    const transformMap = new Map();
-
-    if (!explodeCenter) {
-      explodeCenter = new Vector3();
-      const extent = this.getTotalGeometryExtent();
-      if (!extent.isEmpty()) {
-        extent.getCenter(explodeCenter);
-      }
+    if (!this.transformData) {
+      console.warn("Transform texture not initialized");
+      return;
     }
 
-    const objectsArray = objects
-      ? Array.isArray(objects)
-        ? objects
-        : Array.from(objects)
-      : Array.from(this.originalObjects);
+    // Store transform map directly
+    this.objectTransforms = objectTransformMap;
 
-    for (const obj of objectsArray) {
-      if (!obj.geometry || !obj.geometry.attributes.position) continue;
+    // Reset to identity first to ensure clean state
+    this._resetTransformData(false);
 
-      const boundingBox = new Box3().setFromBufferAttribute(obj.geometry.attributes.position);
+    // Cache references for tight loop
+    const transformData = this.transformData;
+    const objectIdToIndex = this.objectIdToIndex;
 
-      if (obj.matrixWorld) {
-        boundingBox.applyMatrix4(obj.matrixWorld);
-      }
+    // Fast track map iteration using an array of values if we can
+    // While .entries() is fast, sometimes direct properties check is faster
+    let textureNeedsUpdate = false;
 
-      if (boundingBox.isEmpty()) continue;
+    // Process matrices directly into texture array
+    if (objectTransformMap instanceof Map) {
+      // Modern V8 engines optimize for...of on Maps better than Array.from or destructuring iterators
+      for (const [object, matrix] of objectTransformMap.entries()) {
+        const userData = object.userData;
+        if (!userData) continue;
 
-      const objectCenter = new Vector3();
-      boundingBox.getCenter(objectCenter);
+        const handle = userData.handle;
+        if (handle === undefined) continue;
 
-      const direction = objectCenter.clone().sub(explodeCenter);
-      const distance = direction.length();
+        const objectId = objectIdToIndex.get(handle);
+        if (objectId !== undefined) {
+          // TypedArray.set is highly optimized in modern JS engines
+          transformData.set(matrix.elements, objectId * 16);
+          textureNeedsUpdate = true;
+        }
+      }
+    } else {
+      // Fallback for arrays of [object, matrix] pairs
+      const len = objectTransformMap.length;
+      for (let i = 0; i < len; i++) {
+        const pair = objectTransformMap[i];
+        const userData = pair[0].userData;
+        if (!userData) continue;
 
-      if (distance > 0) {
-        direction.normalize();
-        const offset = direction.multiplyScalar(distance * (explodeFactor - 1.0));
+        const handle = userData.handle;
+        if (handle === undefined) continue;
 
-        const matrix = new Matrix4().makeTranslation(offset.x, offset.y, offset.z);
-        transformMap.set(obj, matrix);
+        const objectId = objectIdToIndex.get(handle);
+        if (objectId !== undefined) {
+          transformData.set(pair[1].elements, objectId * 16);
+          textureNeedsUpdate = true;
+        }
       }
     }
 
-    return transformMap;
-  }
-
-  clearTransforms() {
-    this.objectTransforms.clear();
-
-    for (const mesh of this.mergedMesh) {
-      this._restoreOriginalGeometry(mesh);
-    }
-    for (const line of this.mergedLines) {
-      this._restoreOriginalGeometry(line);
-    }
-    for (const lineSegment of this.mergedLineSegments) {
-      this._restoreOriginalGeometry(lineSegment);
-    }
-    for (const point of this.mergedPoints) {
-      this._restoreOriginalGeometry(point);
+    if (textureNeedsUpdate) {
+      this.updateTransformTexture();
+      if (
+        this._lastTransformTexture !== this.transformTexture ||
+        this._lastTransformTextureSize !== this.transformTextureSize
+      ) {
+        this.updateMaterialUniforms();
+      }
     }
-  }
 
-  clearHandleTransforms() {
-    this.clearTransforms();
+    // TODO: Remove this block when highlight is implemented via shader.
+    // Sync transforms to original (hidden) objects so that
+    // GeometryHighlighter wireframes follow exploded positions.
+    if (this.syncTransformsToOriginalObjects) {
+      this._syncOriginalObjectTransforms(objectTransformMap);
+    }
   }
 
-  _applyTransformToMergedObject(mergedObject) {
-    const objectData = this.mergedObjectMap.get(mergedObject.uuid);
-    if (!objectData || !objectData.objectMapping) return;
-
-    const geometry = mergedObject.geometry;
-    if (!geometry || !geometry.attributes.position) return;
-
-    const positionAttr = geometry.attributes.position;
-    const positions = positionAttr.array;
-
-    if (!this.transformedGeometries.has(mergedObject.uuid)) {
-      this.transformedGeometries.set(mergedObject.uuid, new Float32Array(positions));
+  // TODO: Remove when highlight is implemented via shader.
+  _syncOriginalObjectTransforms(objectTransformMap) {
+    // First, restore any previously transformed objects back to their saved position
+    for (const [obj, savedPos] of this._originalObjectMatrices) {
+      obj.position.copy(savedPos);
+      if (obj.userData.highlight) {
+        obj.userData.highlight.position.copy(savedPos);
+      }
     }
+    this._originalObjectMatrices.clear();
 
-    const originalPositions = this.transformedGeometries.get(mergedObject.uuid);
-    const tempVector = new Vector3();
+    // The transform matrix is in the structure root's local space.
+    // Original objects may be nested inside groups with their own transforms,
+    // so we must convert the offset from structure-root-local → parent-local space.
+    const _offset = new Vector3();
+    const _parentInverse = new Matrix4();
 
-    for (const [originalMesh, mappingData] of objectData.objectMapping) {
-      const transform = this.objectTransforms.get(originalMesh);
+    if (objectTransformMap instanceof Map) {
+      for (const [object, matrix] of objectTransformMap.entries()) {
+        if (!object.userData?.handle) continue;
 
-      if (!transform) {
-        const startIdx = mappingData.startVertexIndex * 3;
-        const endIdx = (mappingData.startVertexIndex + mappingData.vertexCount) * 3;
-        for (let i = startIdx; i < endIdx; i++) {
-          positions[i] = originalPositions[i];
+        // Save original position before modifying
+        if (!this._originalObjectMatrices.has(object)) {
+          this._originalObjectMatrices.set(object, object.position.clone());
         }
-        continue;
-      }
 
-      const startVertex = mappingData.startVertexIndex;
-      const vertexCount = mappingData.vertexCount;
+        // Extract translation from the transform matrix (structure-root-local space)
+        _offset.setFromMatrixPosition(matrix);
 
-      for (let i = 0; i < vertexCount; i++) {
-        const idx = (startVertex + i) * 3;
+        // Convert offset from structure-root-local to world space,
+        // then from world space to parent-local space.
+        // The structure root's matrixWorld converts local→world.
+        // The parent's inverse matrixWorld converts world→parent-local.
+        // But we only need to transform a direction/offset (not a point),
+        // so we transform two points and subtract.
+        if (object.userData.structureId) {
+          const rootGroup = this.structureRoots.get(object.userData.structureId);
+          if (rootGroup && object.parent && object.parent !== rootGroup) {
+            // Transform offset: structureRoot-local → world → parent-local
+            // For a vector (not point): apply rotation/scale only
+            const origin = new Vector3(0, 0, 0);
+            origin.applyMatrix4(rootGroup.matrixWorld);
+            _offset.applyMatrix4(rootGroup.matrixWorld);
+            _offset.sub(origin);
 
-        tempVector.set(originalPositions[idx], originalPositions[idx + 1], originalPositions[idx + 2]);
+            const parentOrigin = new Vector3(0, 0, 0);
+            _parentInverse.copy(object.parent.matrixWorld).invert();
+            parentOrigin.applyMatrix4(_parentInverse);
+            _offset.applyMatrix4(_parentInverse);
+            _offset.sub(parentOrigin);
+          }
+        }
 
-        tempVector.applyMatrix4(transform);
+        object.position.add(_offset);
 
-        positions[idx] = tempVector.x;
-        positions[idx + 1] = tempVector.y;
-        positions[idx + 2] = tempVector.z;
+        // Also update highlight wireframe if it exists right now
+        if (object.userData.highlight) {
+          object.userData.highlight.position.copy(object.position);
+        }
       }
     }
+  }
 
-    if (geometry.attributes.normal) {
-      this._updateNormalsForTransform(geometry, objectData, originalPositions);
-    }
+  createExplodeTransforms(objects = null, explodeCenter = null, explodeFactor = 1.5) {
+    const transformMap = new Map();
 
-    positionAttr.needsUpdate = true;
-    geometry.computeBoundingSphere();
-    geometry.computeBoundingBox();
-  }
+    if (!explodeCenter) {
+      explodeCenter = new Vector3();
+      const extent = this.getTotalGeometryExtent();
+      if (!extent.isEmpty()) {
+        extent.getCenter(explodeCenter);
+      }
+    }
 
-  _updateNormalsForTransform(geometry, objectData, originalPositions) {
-    const normalAttr = geometry.attributes.normal;
-    if (!normalAttr) return;
+    const objectsArray = objects
+      ? Array.isArray(objects)
+        ? objects
+        : Array.from(objects)
+      : Array.from(this.originalObjects);
 
-    const normals = normalAttr.array;
-    const tempVector = new Vector3();
-    const normalMatrix = new Matrix4();
+    // Cache inverse matrices for structures
+    const structureInverseMatrices = new Map();
 
-    // Store original normals if not already stored
-    const normalsKey = `${geometry.uuid}_normals`;
-    if (!this.transformedGeometries.has(normalsKey)) {
-      this.transformedGeometries.set(normalsKey, new Float32Array(normals));
+    // Map mesh -> node to access cached geometryExtents
+    if (!this.meshToNodeMap) {
+      this.meshToNodeMap = new Map();
+      for (const node of this.nodes.values()) {
+        if (node.object) {
+          this.meshToNodeMap.set(node.object, node);
+        }
+      }
     }
 
-    const originalNormals = this.transformedGeometries.get(normalsKey);
+    for (const obj of objectsArray) {
+      if (!obj.geometry || !obj.geometry.attributes.position) continue;
 
-    for (const [originalMesh, mappingData] of objectData.objectMapping) {
-      // Direct lookup by object reference - NO HANDLE LOOKUP!
-      const transform = this.objectTransforms.get(originalMesh);
+      // OPTIMIZATION: Use cached node extent if available
+      if (!obj.userData.explodeVector) {
+        let center = null;
 
-      if (!transform) {
-        // Restore original normals
-        const startIdx = mappingData.startVertexIndex * 3;
-        const endIdx = (mappingData.startVertexIndex + mappingData.vertexCount) * 3;
-        for (let i = startIdx; i < endIdx; i++) {
-          normals[i] = originalNormals[i];
+        // 1. Try to get extent from node (fastest, pre-calculated)
+        const node = this.meshToNodeMap.get(obj);
+        if (node && node.geometryExtents) {
+          const box = node.geometryExtents.clone();
+          box.applyMatrix4(obj.matrixWorld);
+          center = new Vector3();
+          box.getCenter(center);
         }
-        continue;
-      }
 
-      // Create normal matrix (inverse transpose of transform)
-      normalMatrix.copy(transform).invert().transpose();
+        // 2. Fallback to geometry bounding box
+        if (!center) {
+          if (!obj.geometry.boundingBox) obj.geometry.computeBoundingBox();
+          const box = obj.geometry.boundingBox.clone();
+          box.applyMatrix4(obj.matrixWorld);
+          center = new Vector3();
+          box.getCenter(center);
+        }
 
-      const startVertex = mappingData.startVertexIndex;
-      const vertexCount = mappingData.vertexCount;
+        // Calculate vector from explode center to object center
+        const explodeVector = center.sub(explodeCenter);
 
-      for (let i = 0; i < vertexCount; i++) {
-        const idx = (startVertex + i) * 3;
+        // Cache it
+        obj.userData.explodeVector = explodeVector;
+      }
+      const explodeVector = obj.userData.explodeVector;
+      const distance = explodeVector.length();
 
-        // Get original normal
-        tempVector.set(originalNormals[idx], originalNormals[idx + 1], originalNormals[idx + 2]);
+      if (distance > 0) {
+        // Calculate offset in World Space
+        const offset = explodeVector.clone().multiplyScalar(explodeFactor - 1.0);
+
+        // Convert offset from World Space to Local Space of the merged mesh
+        const localOffset = offset.clone();
+
+        if (obj.userData.structureId) {
+          const structureId = obj.userData.structureId;
+          let inverseMatrix = structureInverseMatrices.get(structureId);
+
+          if (!inverseMatrix) {
+            const rootGroup = this.structureRoots.get(structureId);
+            if (rootGroup) {
+              // Reuse cached inverse matrix if possible
+              if (!rootGroup.userData.inverseWorldMatrix) {
+                // rootGroup.updateMatrixWorld(true); // Trust current state
+                rootGroup.userData.inverseWorldMatrix = new Matrix4().copy(rootGroup.matrixWorld).invert();
+              }
+              inverseMatrix = rootGroup.userData.inverseWorldMatrix;
+              structureInverseMatrices.set(structureId, inverseMatrix);
+            }
+          }
 
-        // Apply normal transformation
-        tempVector.applyMatrix4(normalMatrix).normalize();
+          if (inverseMatrix) {
+            const zero = new Vector3(0, 0, 0).applyMatrix4(inverseMatrix);
+            const vec = offset.clone().applyMatrix4(inverseMatrix).sub(zero);
+            localOffset.copy(vec);
+          }
+        }
 
-        // Write back transformed normal
-        normals[idx] = tempVector.x;
-        normals[idx + 1] = tempVector.y;
-        normals[idx + 2] = tempVector.z;
+        let matrix = obj.userData.explodeMatrix;
+        if (!matrix) {
+          matrix = new Matrix4();
+          obj.userData.explodeMatrix = matrix;
+        }
+        matrix.makeTranslation(localOffset.x, localOffset.y, localOffset.z);
+        transformMap.set(obj, matrix);
       }
     }
 
-    normalAttr.needsUpdate = true;
+    return transformMap;
   }
 
-  _restoreOriginalGeometry(mergedObject) {
-    const geometry = mergedObject.geometry;
-    if (!geometry || !geometry.attributes.position) return;
-
-    // Restore original positions
-    const originalPositions = this.transformedGeometries.get(mergedObject.uuid);
-    if (originalPositions) {
-      const positions = geometry.attributes.position.array;
-      positions.set(originalPositions);
-      geometry.attributes.position.needsUpdate = true;
-    }
+  clearTransforms() {
+    this.objectTransforms.clear();
+    this._resetTransformData(true);
 
-    // Restore original normals
-    const normalsKey = `${geometry.uuid}_normals`;
-    const originalNormals = this.transformedGeometries.get(normalsKey);
-    if (originalNormals && geometry.attributes.normal) {
-      const normals = geometry.attributes.normal.array;
-      normals.set(originalNormals);
-      geometry.attributes.normal.needsUpdate = true;
+    // TODO: Remove when highlight is implemented via shader.
+    // Restore original object positions
+    if (this.syncTransformsToOriginalObjects) {
+      for (const [obj, savedPos] of this._originalObjectMatrices) {
+        obj.position.copy(savedPos);
+        if (obj.userData.highlight) {
+          obj.userData.highlight.position.copy(savedPos);
+        }
+      }
+      this._originalObjectMatrices.clear();
     }
+  }
 
-    geometry.computeBoundingSphere();
-    geometry.computeBoundingBox();
+  clearHandleTransforms() {
+    this.clearTransforms();
   }
 
   syncHiddenObjects() {