fl-web-component 2.1.1-beta.10 → 2.1.1-beta.11

package/packages/components/com-graphics/index.vue

@@ -165,9 +165,15 @@ import { onContextHandle } from './component/context';
 
 const isDebug = process.env.NODE_ENV !== 'production' || process.env.VUE_APP_IS_WATCH === true;
 // const isDebug = false;
-const COLLISION_PENETRATION_EPSILON = 1;
+const COLLISION_CONTACT_EPSILON = 1;
 const COLLISION_OBB_AXIS_EPSILON = 1e-8;
 const COLLISION_DEBUG_GROUP_NAME = '__collision_obb_debug_group__';
+const OCCLUSION_DEBUG_GROUP_NAME = '__occlusion_bounds_debug_group__';
+const OCCLUSION_DEBUG_FLAG_COLORS = {
+  1: 0xffc107,
+  2: 0x409eff,
+  3: 0xff4dff,
+};
 
 export default {
   name: 'FlModel',
@@ -198,8 +204,8 @@ export default {
       occlusionState: {
         // enabled: false,
         enabled: true,
-        // previewEnabled: false,
-        previewEnabled: isDebug,
+        previewEnabled: false,
+        // previewEnabled: isDebug,
         bufferWidth: 1700,
         sampleStride: 1,
         minSampleCount: 5,
@@ -218,6 +224,8 @@ export default {
       sceneBoundingBoxDebugEnabled: false,
       // collisionObbDebugEnabled: isDebug,
       collisionObbDebugEnabled: false,
+      // occlusionBoundsDebugEnabled: isDebug,
+      occlusionBoundsDebugEnabled: false,
     };
   },
   watch: {
@@ -267,6 +275,7 @@ export default {
       'sceneBoundingBox',
       'sceneBoundingBoxHelper',
       'collisionObbDebugGroup',
+      'occlusionBoundsDebugGroup',
     ];
     arr.forEach(item => {
       this[item] = null;
@@ -288,6 +297,7 @@ export default {
       'isDragging',
       'boundingBoxVisible',
       'collisionObbDebugEnabled',
+      'occlusionBoundsDebugEnabled',
     ].forEach(item => {
       this[item] = false;
     });
@@ -1218,6 +1228,26 @@ export default {
       if (instancedMesh && instancedMesh.userData) return instancedMesh.userData.copyMatrix || null;
       return null;
     },
+    setInstanceCullingVisible(instancedMesh, instanceId, visible) {
+      const instanceState = this.getInstanceState(instancedMesh, instanceId);
+      if (!instanceState || typeof instanceState.instanceIndex !== 'number') return;
+
+      const copyMatrix =
+        instanceState.copyMatrix || this.getInstanceCopyMatrix(instancedMesh, instanceId);
+      if (!copyMatrix) return;
+
+      const shouldShow =
+        visible && instanceState.visible !== false && this.isSourceVisible(instanceId, instancedMesh);
+      const matrix = new this.THREE.Matrix4().copy(copyMatrix);
+      if (!shouldShow) {
+        matrix.makeTranslation(9999999, 9999999, 9999999);
+        this.removeOutlineObject(instancedMesh, instanceState.instanceIndex);
+      }
+
+      instancedMesh.setMatrixAt(instanceState.instanceIndex, matrix);
+      instancedMesh.instanceMatrix.needsUpdate = true;
+      instanceState.cullingVisible = !!visible;
+    },
     isSourceHiddenInstance(instancedMesh, instanceId) {
       const instanceState = this.getInstanceState(instancedMesh, instanceId);
       if (instanceState && instanceState.sourceVisible !== undefined) {
@@ -1536,21 +1566,37 @@ export default {
       existingBox.union(box);
       return existingBox;
     },
-    mergeModelBoxUserData(targetBox, sourceUserData) {
-      if (!targetBox || !sourceUserData) return;
+    createOcclusionProxyBox(box) {
+      if (!box || !box.isBox3) return null;
+      const proxyBox = box.clone();
+      proxyBox.userData = { ...(box.userData || {}) };
+      delete proxyBox.userData.occlusionProxyBoxes;
+      return proxyBox;
+    },
+    mergeModelBoxUserData(targetBox, sourceBox) {
+      if (!targetBox || !sourceBox || !sourceBox.userData) return;
+      const sourceUserData = sourceBox.userData;
       if (!targetBox.userData) {
         targetBox.userData = sourceUserData;
         return;
       }
 
       const targetUserData = targetBox.userData;
+      const targetProxyBoxes = Array.isArray(targetUserData.occlusionProxyBoxes)
+        ? targetUserData.occlusionProxyBoxes
+        : [this.createOcclusionProxyBox(targetBox)].filter(Boolean);
+      const sourceProxyBoxes = Array.isArray(sourceUserData.occlusionProxyBoxes)
+        ? sourceUserData.occlusionProxyBoxes
+        : [this.createOcclusionProxyBox(sourceBox)].filter(Boolean);
       targetUserData.visible = targetUserData.visible !== false || sourceUserData.visible !== false;
       targetUserData.sourceVisible =
         targetUserData.sourceVisible !== false || sourceUserData.sourceVisible !== false;
       targetUserData.transparent = !!targetUserData.transparent && !!sourceUserData.transparent;
       targetUserData.mergedBoxCount = (targetUserData.mergedBoxCount || 1) + 1;
-      // 同一模型包含多个图元时，单个图元的遮挡代理不再可靠，改由视锥体合并盒兜底加载。
-      targetUserData.occlusionEnabled = false;
+      // 多图元模型分别参与遮挡测试，任一图元可见时都会保留整个模型。
+      targetUserData.occlusionEnabled =
+        !!targetUserData.occlusionEnabled && !!sourceUserData.occlusionEnabled;
+      targetUserData.occlusionProxyBoxes = targetProxyBoxes.concat(sourceProxyBoxes);
 
       const targetObbs = Array.isArray(targetUserData.collisionObbs)
         ? targetUserData.collisionObbs
@@ -1562,6 +1608,60 @@ export default {
         targetUserData.collisionObbs = targetObbs.concat(sourceObbs);
       }
     },
+    _createCollisionObb(center, halfSize, rotation, matrix) {
+      const worldCenter = center.clone();
+      const worldHalfSize = halfSize.clone();
+      const worldRotation = new this.THREE.Matrix3();
+
+      if (!matrix) {
+        return new OBB(worldCenter, worldHalfSize, rotation.clone());
+      }
+
+      worldCenter.applyMatrix4(matrix);
+
+      const localAxes = [
+        new this.THREE.Vector3(),
+        new this.THREE.Vector3(),
+        new this.THREE.Vector3(),
+      ];
+      rotation.extractBasis(localAxes[0], localAxes[1], localAxes[2]);
+
+      const linearMatrix = new this.THREE.Matrix3().setFromMatrix4(matrix);
+      const worldAxes = localAxes.map(axis => axis.clone().applyMatrix3(linearMatrix));
+      const halfSizes = [halfSize.x, halfSize.y, halfSize.z];
+
+      for (let i = 0; i < 3; i++) {
+        const axisLength = worldAxes[i].length();
+        if (axisLength <= COLLISION_OBB_AXIS_EPSILON) {
+          worldAxes[i].copy(localAxes[i]);
+          continue;
+        }
+
+        worldAxes[i].multiplyScalar(1 / axisLength);
+        halfSizes[i] *= axisLength;
+      }
+
+      worldHalfSize.set(halfSizes[0], halfSizes[1], halfSizes[2]);
+      worldRotation.set(
+        worldAxes[0].x,
+        worldAxes[1].x,
+        worldAxes[2].x,
+        worldAxes[0].y,
+        worldAxes[1].y,
+        worldAxes[2].y,
+        worldAxes[0].z,
+        worldAxes[1].z,
+        worldAxes[2].z
+      );
+
+      return new OBB(worldCenter, worldHalfSize, worldRotation);
+    },
+    _createCollisionObbFromBox(box, matrix) {
+      const center = box.getCenter(new this.THREE.Vector3());
+      const halfSize = box.getSize(new this.THREE.Vector3()).multiplyScalar(0.5);
+      const rotation = new this.THREE.Matrix3().identity();
+      return this._createCollisionObb(center, halfSize, rotation, matrix);
+    },
     upsertModelBox(modelId, box) {
       if (!this._boxIndex || !modelId || !box || !box.isBox3) return;
       const key = String(modelId);
@@ -1570,8 +1670,8 @@ export default {
         this._boxIndex.set(key, box);
         return;
       }
+      this.mergeModelBoxUserData(existingBox, box);
       existingBox.union(box);
-      this.mergeModelBoxUserData(existingBox, box.userData);
     },
     setBoxIndex(boxJson, documentId, isAdd = true) {
       if (!this._boxIndex) this._boxIndex = new Map();
@@ -1703,10 +1803,12 @@ export default {
               halfSize: halfSize,
             };
 
-            const collisionObb = new OBB(center.clone(), halfSize.clone(), rotation.clone());
-            if (collisionMatrix) {
-              collisionObb.applyMatrix4(collisionMatrix);
-            }
+            const collisionObb = this._createCollisionObb(
+              center,
+              halfSize,
+              rotation,
+              collisionMatrix
+            );
             userData.collisionObbs = [collisionObb];
           }
           // 如果是 flag=2，解析并存储多个子包围盒 (min, max)
@@ -1720,10 +1822,7 @@ export default {
                 subBoxes.push({ min, max });
 
                 const subBox = new this.THREE.Box3(min.clone(), max.clone());
-                const collisionObb = new OBB().fromBox3(subBox);
-                if (collisionMatrix) {
-                  collisionObb.applyMatrix4(collisionMatrix);
-                }
+                const collisionObb = this._createCollisionObbFromBox(subBox, collisionMatrix);
                 collisionObbs.push(collisionObb);
               }
             }
@@ -1734,10 +1833,7 @@ export default {
           }
 
           if (!userData.collisionObbs || userData.collisionObbs.length === 0) {
-            const collisionObb = new OBB().fromBox3(sourceBox);
-            if (collisionMatrix) {
-              collisionObb.applyMatrix4(collisionMatrix);
-            }
+            const collisionObb = this._createCollisionObbFromBox(sourceBox, collisionMatrix);
             userData.collisionObbs = [collisionObb];
           }
 
@@ -1773,11 +1869,26 @@ export default {
       }
       this.buildOctreeFromBoxIndex();
       this.refreshCollisionObbDebug();
+      this.refreshOcclusionBoundsDebug();
       console.log('time end', Date.now());
     },
     shouldApplyOcclusionByBox(box) {
       return !!(box && box.userData && box.userData.occlusionEnabled);
     },
+    appendOcclusionCandidates(candidates, modelId, box, frustum) {
+      if (!box) return;
+      const userData = box.userData || {};
+      const proxyBoxes = Array.isArray(userData.occlusionProxyBoxes)
+        ? userData.occlusionProxyBoxes
+        : [box];
+
+      for (let i = 0; i < proxyBoxes.length; i++) {
+        const proxyBox = proxyBoxes[i];
+        if (!proxyBox || (proxyBox.userData && proxyBox.userData.visible === false)) continue;
+        if (frustum && !frustum.intersectsBox(proxyBox)) continue;
+        candidates.push({ modelId, box: proxyBox });
+      }
+    },
     tryInitialCenterAfterBoundsReady() {
       if (this.hasExecutedCentering || this.userInteracting) return;
       if (
@@ -2089,20 +2200,15 @@ export default {
 
       this._clearCollisionObbDebugGroup(false);
       const pairMap = this._buildCollisionPairMap();
-      if (pairMap.size === 0) return;
+      if (!this._boxIndex || this._boxIndex.size === 0) return;
 
-      pairMap.forEach((relatedIds, modelId) => {
-        const box =
-          this._boxIndex && this._boxIndex.has(String(modelId))
-            ? this._boxIndex.get(String(modelId))
-            : this._boxIndex && this._boxIndex.has(modelId)
-            ? this._boxIndex.get(modelId)
-            : null;
+      this._boxIndex.forEach((box, modelId) => {
         if (!this._isCollisionBoxAvailable(box)) return;
 
         const obbs = this._getCollisionObbs(box);
         if (!obbs.length) return;
 
+        const relatedIds = pairMap.get(String(modelId));
         const isColliding = relatedIds && relatedIds.size > 0;
         const color = isColliding ? 0xff3b30 : 0x36cfc9;
         for (let i = 0; i < obbs.length; i++) {
@@ -2128,6 +2234,165 @@ export default {
         this.hideCollisionObbDebug();
       }
     },
+    _getOcclusionDebugGroup() {
+      if (!this.scene) return null;
+      if (this.occlusionBoundsDebugGroup && this.occlusionBoundsDebugGroup.parent === this.scene) {
+        return this.occlusionBoundsDebugGroup;
+      }
+
+      const group = new this.THREE.Group();
+      group.name = OCCLUSION_DEBUG_GROUP_NAME;
+      group.userData.transformControlHelper = true;
+      group.userData.occlusionBoundsDebugHelper = true;
+      this.scene.add(group);
+      this.occlusionBoundsDebugGroup = group;
+      return group;
+    },
+    _createOcclusionFlag1LineSegments(box, color) {
+      const userData = box && box.userData ? box.userData : {};
+      const vertices = userData.obbData;
+      if (!vertices || vertices.length < 9) return null;
+
+      const sourceGeometry = new this.THREE.BufferGeometry();
+      sourceGeometry.setAttribute(
+        'position',
+        new this.THREE.BufferAttribute(new Float32Array(vertices), 3)
+      );
+
+      const indices = userData.indices;
+      if (indices && indices.length >= 3) {
+        if (indices.isBufferAttribute) {
+          sourceGeometry.setIndex(indices);
+        } else if (ArrayBuffer.isView(indices)) {
+          sourceGeometry.setIndex(new this.THREE.BufferAttribute(indices, 1));
+        } else {
+          sourceGeometry.setIndex(indices);
+        }
+      }
+
+      let wireframeGeometry = null;
+      try {
+        // flag=1 对应真实遮挡网格，必须按顶点和三角形索引绘制，不能退化成 AABB/OBB。
+        wireframeGeometry = new this.THREE.WireframeGeometry(sourceGeometry);
+      } catch (error) {
+        console.warn('flag=1 遮挡调试线框生成失败', error);
+      }
+      sourceGeometry.dispose();
+      if (!wireframeGeometry || wireframeGeometry.getAttribute('position').count === 0) {
+        if (wireframeGeometry) wireframeGeometry.dispose();
+        return null;
+      }
+
+      const material = new this.THREE.LineBasicMaterial({
+        color,
+        transparent: true,
+        opacity: 0.95,
+        depthTest: false,
+        depthWrite: false,
+        toneMapped: false,
+      });
+      const lineSegments = new this.THREE.LineSegments(wireframeGeometry, material);
+      const transformMatrix = new this.THREE.Matrix4();
+      const matrixArr = userData.matrix;
+      if (matrixArr && matrixArr.length >= 16) {
+        transformMatrix.fromArray(matrixArr);
+      }
+      if (this.bizToThreeMatrix) {
+        transformMatrix.premultiply(this.bizToThreeMatrix);
+      }
+      lineSegments.matrixAutoUpdate = false;
+      lineSegments.matrix.copy(transformMatrix);
+      lineSegments.matrixWorldNeedsUpdate = true;
+      lineSegments.renderOrder = 998;
+      lineSegments.userData.transformControlHelper = true;
+      lineSegments.userData.occlusionBoundsDebugHelper = true;
+      lineSegments.userData.occlusionFlag = 1;
+      return lineSegments;
+    },
+    _createOcclusionBoxLineSegments(obb, color, flag) {
+      const lineSegments = this._createCollisionObbLineSegments(obb, color);
+      if (!lineSegments) return null;
+
+      lineSegments.renderOrder = 998;
+      lineSegments.userData.collisionObbDebugHelper = false;
+      lineSegments.userData.occlusionBoundsDebugHelper = true;
+      lineSegments.userData.occlusionFlag = flag;
+      return lineSegments;
+    },
+    _clearOcclusionBoundsDebugGroup(removeGroup = false) {
+      const group = this.occlusionBoundsDebugGroup;
+      if (!group) return;
+
+      while (group.children.length > 0) {
+        const child = group.children[group.children.length - 1];
+        group.remove(child);
+        if (child.geometry) child.geometry.dispose();
+        if (Array.isArray(child.material)) {
+          child.material.forEach(material => material && material.dispose());
+        } else if (child.material) {
+          child.material.dispose();
+        }
+      }
+
+      if (removeGroup && this.scene && group.parent === this.scene) {
+        this.scene.remove(group);
+        this.occlusionBoundsDebugGroup = null;
+      } else if (!this.scene) {
+        this.occlusionBoundsDebugGroup = null;
+      }
+    },
+    hideOcclusionBoundsDebug() {
+      this._clearOcclusionBoundsDebugGroup();
+      this.occlusionBoundsDebugEnabled = false;
+    },
+    refreshOcclusionBoundsDebug() {
+      if (!this.occlusionBoundsDebugEnabled) return;
+      const group = this._getOcclusionDebugGroup();
+      if (!group) return;
+
+      this._clearOcclusionBoundsDebugGroup(false);
+      if (!this._boxIndex || this._boxIndex.size === 0) return;
+
+      this._boxIndex.forEach((box, modelId) => {
+        if (!this._isCollisionBoxAvailable(box) || !this.shouldApplyOcclusionByBox(box)) return;
+
+        const userData = box.userData || {};
+        const flag = Number(userData.flag) || 1;
+        const color = OCCLUSION_DEBUG_FLAG_COLORS[flag];
+        if (!color) return;
+
+        if (flag === 1) {
+          const lineSegments = this._createOcclusionFlag1LineSegments(box, color);
+          if (!lineSegments) return;
+          lineSegments.name = `${OCCLUSION_DEBUG_GROUP_NAME}:${modelId}:flag-1`;
+          lineSegments.userData.modelId = modelId;
+          group.add(lineSegments);
+          return;
+        }
+
+        const obbs = this._getCollisionObbs(box);
+        for (let i = 0; i < obbs.length; i++) {
+          const lineSegments = this._createOcclusionBoxLineSegments(obbs[i], color, flag);
+          if (!lineSegments) continue;
+          lineSegments.name = `${OCCLUSION_DEBUG_GROUP_NAME}:${modelId}:flag-${flag}:${i}`;
+          lineSegments.userData.modelId = modelId;
+          group.add(lineSegments);
+        }
+      });
+    },
+    showOcclusionBoundsDebug() {
+      this.occlusionBoundsDebugEnabled = true;
+      this.refreshOcclusionBoundsDebug();
+    },
+    toggleOcclusionBoundsDebug(forceVisible) {
+      const nextVisible =
+        typeof forceVisible === 'boolean' ? forceVisible : !this.occlusionBoundsDebugEnabled;
+      if (nextVisible) {
+        this.showOcclusionBoundsDebug();
+      } else {
+        this.hideOcclusionBoundsDebug();
+      }
+    },
     _getObbAxisInfo(obb) {
       const xAxis = new this.THREE.Vector3();
       const yAxis = new this.THREE.Vector3();
@@ -2197,7 +2462,7 @@ export default {
       const obbsB = this._getCollisionObbs(boxB);
       for (let i = 0; i < obbsA.length; i++) {
         for (let j = 0; j < obbsB.length; j++) {
-          if (this._getObbMinPenetration(obbsA[i], obbsB[j]) > COLLISION_PENETRATION_EPSILON) {
+          if (this._getObbMinPenetration(obbsA[i], obbsB[j]) >= COLLISION_CONTACT_EPSILON) {
             return true;
           }
         }
@@ -2809,7 +3074,12 @@ export default {
             visibleIdSet.add(this.formatModelId(hits[i].modelId));
             continue;
           }
-          candidates.push(hits[i]);
+          this.appendOcclusionCandidates(
+            candidates,
+            hits[i].modelId,
+            hits[i].box,
+            globalFrustum
+          );
         }
       } else if (this._boxIndex && this._boxIndex.size > 0) {
         this._boxIndex.forEach((box, modelId) => {
@@ -2820,7 +3090,7 @@ export default {
               visibleIdSet.add(this.formatModelId(modelId));
               return;
             }
-            candidates.push({ modelId, box });
+            this.appendOcclusionCandidates(candidates, modelId, box, globalFrustum);
           }
         });
       }
@@ -2936,6 +3206,7 @@ export default {
             const tBuild0 = performance.now();
 
             const flag1Items = [];
+            const flag2Items = [];
             const flag3Items = [];
 
             let globalIdx = 1;
@@ -2949,6 +3220,8 @@ export default {
               const flag = (c.box.userData && c.box.userData.flag) || 1;
               if (flag === 3 && c.box.userData && c.box.userData.obb) {
                 flag3Items.push({ c, idx });
+              } else if (flag === 2) {
+                flag2Items.push({ c, idx });
               } else if (flag === 1) {
                 flag1Items.push({ c, idx });
               }
@@ -2965,7 +3238,8 @@ export default {
             const _tempMatA = occObjs._tempMatA || (occObjs._tempMatA = new this.THREE.Matrix4());
 
             let boxes = occObjs.boxes;
-            const boxCount = flag3Items.length;
+            const boxItems = flag3Items.concat(flag2Items);
+            const boxCount = boxItems.length;
             if (boxCount > 0) {
               const needCapacity = boxCount;
               const capacity = boxes && typeof boxes.capacity === 'number' ? boxes.capacity : 0;
@@ -2995,19 +3269,26 @@ export default {
               }
               boxes.mesh.count = boxCount;
               for (let i = 0; i < boxCount; i++) {
-                const item = flag3Items[i];
-                const { matrix, halfSize } = item.c.box.userData.obb;
+                const item = boxItems[i];
                 const idx = item.idx;
                 const r = (idx & 255) / 255;
                 const g = ((idx >> 8) & 255) / 255;
                 const b = ((idx >> 16) & 255) / 255;
                 _tempColor.setRGB(r, g, b);
 
-                _tempScale.copy(halfSize).multiplyScalar(2);
-                _tempMatrix.copy(matrix);
-                _tempMatrix.scale(_tempScale);
-                if (typeof this.bizToThreeMatrix !== 'undefined' && this.bizToThreeMatrix) {
-                  _tempMatrix.premultiply(this.bizToThreeMatrix);
+                const obb = item.c.box.userData && item.c.box.userData.obb;
+                if (obb) {
+                  _tempScale.copy(obb.halfSize).multiplyScalar(2);
+                  _tempMatrix.copy(obb.matrix);
+                  _tempMatrix.scale(_tempScale);
+                  if (typeof this.bizToThreeMatrix !== 'undefined' && this.bizToThreeMatrix) {
+                    _tempMatrix.premultiply(this.bizToThreeMatrix);
+                  }
+                } else {
+                  item.c.box.getSize(_tempScale);
+                  item.c.box.getCenter(_tempVec3);
+                  _tempMatrix.makeTranslation(_tempVec3.x, _tempVec3.y, _tempVec3.z);
+                  _tempMatrix.scale(_tempScale);
                 }
 
                 boxes.mesh.setMatrixAt(i, _tempMatrix);
@@ -3450,12 +3731,12 @@ export default {
           this.renderer.toneMapping = prevToneMapping;
         } catch (e) {
           for (let i = 0; i < candidates.length; i++) {
-            visibleIdSet.add(candidates[i].modelId);
+            visibleIdSet.add(this.formatModelId(candidates[i].modelId));
           }
         }
       } else {
         for (let i = 0; i < candidates.length; i++) {
-          visibleIdSet.add(candidates[i].modelId);
+          visibleIdSet.add(this.formatModelId(candidates[i].modelId));
         }
       }
       visibleIds.length = 0;
@@ -3464,37 +3745,43 @@ export default {
       const parentsToCheck = new Set();
       this.scene.traverse(child => {
         if (!child.isInstancedMesh) return;
-        // 如果复用数量等于大于2个，则跳过裁剪和剔除处理（始终保留）
-        if (child.count >= 2) {
-          let instancesMap =
-            child && child.userData && child.userData.instancesMap instanceof Map
-              ? child.userData.instancesMap
-              : child.parent &&
-                child.parent.userData &&
-                child.parent.userData.instancesMap instanceof Map
-              ? child.parent.userData.instancesMap
-              : null;
+        const instancesMap =
+          child && child.userData && child.userData.instancesMap instanceof Map
+            ? child.userData.instancesMap
+            : child.parent &&
+              child.parent.userData &&
+              child.parent.userData.instancesMap instanceof Map
+            ? child.parent.userData.instancesMap
+            : null;
 
+        // 多实例复用同一个 InstancedMesh 时，仅在全部实例都不可见时整体卸载。
+        if (child.count >= 2) {
           if (instancesMap) {
             let allInactive = true;
             const modelIds = Array.from(instancesMap.keys());
+            let unloadModelId = null;
 
             // 第一遍遍历：检查是否有任何一个实例处于活跃状态（在视锥体内且可见）
             for (const modelId of modelIds) {
               // 检查已取消勾选模型进行卸载
-              const documentId = modelId.split(':')[1];
-              if (!this.noObserver.documentModelIds.get(documentId)) {
-                toUnload.push({ modelId, child });
-                return;
+              const documentId = String(modelId).split(':')[1];
+              if (documentId && !this.noObserver.documentModelIds.get(documentId)) {
+                if (!skipUnload) this.setInstanceCullingVisible(child, modelId, false);
+                unloadModelId = modelId;
+                continue;
               }
 
-              if (bypassList && bypassList.size > 0 && bypassList.has(modelId)) return;
+              const formattedModelId = this.formatModelId(modelId);
+              if (
+                bypassList &&
+                bypassList.size > 0 &&
+                (bypassList.has(modelId) || bypassList.has(formattedModelId))
+              ) {
+                if (!skipUnload) this.setInstanceCullingVisible(child, modelId, true);
+                allInactive = false;
+                continue;
+              }
 
-              const instanceInfo = instancesMap.get(modelId);
-              const instanceIndex =
-                instanceInfo && typeof instanceInfo.instanceIndex === 'number'
-                  ? instanceInfo.instanceIndex
-                  : null;
               const box =
                 this._boxIndex && this._boxIndex.has(String(modelId))
                   ? this._boxIndex.get(String(modelId))
@@ -3502,16 +3789,19 @@ export default {
                   ? this._boxIndex.get(modelId)
                   : null;
               if (!this.shouldApplyOcclusionByBox(box)) {
+                if (!skipUnload) this.setInstanceCullingVisible(child, modelId, true);
                 allInactive = false;
+                toLoadSet.delete(formattedModelId);
                 continue;
               }
 
-              const inFrustum = this.isModelInFrustum(child, instanceIndex, globalFrustum);
-              const modelInVisible = toLoadSet.has(modelId);
-              // console.log('modelId', modelId, 'inFrustum', inFrustum, 'modelInVisible', modelInVisible)
+              const modelInVisible = visibleIdSet.has(formattedModelId);
+              toLoadSet.delete(formattedModelId);
 
-              // 只要有一个实例在视锥体内且在可见列表中，就不整体卸载
-              if (inFrustum || modelInVisible) {
+              // 可见集合已经聚合了同一模型的全部图元，任一图元可见时都保留该模型实例。
+              const isActive = modelInVisible;
+              if (!skipUnload) this.setInstanceCullingVisible(child, modelId, isActive);
+              if (isActive) {
                 allInactive = false;
               }
             }
@@ -3525,20 +3815,24 @@ export default {
                   ? this._boxIndex.get(modelId)
                   : null;
               if (!this.shouldApplyOcclusionByBox(box)) {
-                if (toLoadSet.has(modelId)) {
-                  toLoadSet.delete(modelId);
-                }
+                toLoadSet.delete(this.formatModelId(modelId));
                 continue;
               }
               // 无论是否卸载，只要模型已在场景中，就从待加载集合中移除
-              if (toLoadSet.has(modelId)) {
-                toLoadSet.delete(modelId);
-              }
+              toLoadSet.delete(this.formatModelId(modelId));
 
-              // 仅当所有实例都不活跃时，才执行卸载
-              if (!skipUnload && !this.firstPerSign && !this.roaming && allInactive) {
-                toUnload.push({ modelId, child });
-              }
+              if (!unloadModelId) unloadModelId = modelId;
+            }
+
+            // 仅当所有实例都不活跃时，才整体卸载一次，避免重复释放同一网格。
+            if (
+              !skipUnload &&
+              !this.firstPerSign &&
+              !this.roaming &&
+              allInactive &&
+              unloadModelId !== null
+            ) {
+              toUnload.push({ modelId: unloadModelId, child });
             }
           }
           // if (toLoadSet.has(modelId)) {
@@ -3547,10 +3841,18 @@ export default {
           return;
         }
         const modelId =
-          child.parent && child.parent.userData && child.parent.userData.instanceId
+          instancesMap && instancesMap.size > 0
+            ? instancesMap.keys().next().value
+            : child.parent && child.parent.userData && child.parent.userData.instanceId
             ? child.parent.userData.instanceId
             : child.uuid;
-        if (bypassList && bypassList.size > 0 && bypassList.has(modelId)) return;
+        const formattedModelId = this.formatModelId(modelId);
+        if (
+          bypassList &&
+          bypassList.size > 0 &&
+          (bypassList.has(modelId) || bypassList.has(formattedModelId))
+        )
+          return;
         const box =
           this._boxIndex && this._boxIndex.has(String(modelId))
             ? this._boxIndex.get(String(modelId))
@@ -3558,18 +3860,13 @@ export default {
             ? this._boxIndex.get(modelId)
             : null;
         if (!this.shouldApplyOcclusionByBox(box)) {
-          if (toLoadSet.has(modelId)) {
-            toLoadSet.delete(modelId);
-          }
+          toLoadSet.delete(formattedModelId);
           return;
         }
 
-        const inFrustum = this.isModelInFrustum(child, null, globalFrustum);
-        let modelInVisible = toLoadSet.has(modelId);
-        if (modelInVisible) {
-          toLoadSet.delete(modelId);
-        }
-        if (!skipUnload && !this.firstPerSign && !this.roaming && (!inFrustum || !modelInVisible)) {
+        const modelInVisible = visibleIdSet.has(formattedModelId);
+        toLoadSet.delete(formattedModelId);
+        if (!skipUnload && !this.firstPerSign && !this.roaming && !modelInVisible) {
           toUnload.push({ modelId, child });
         }
       });
@@ -5030,6 +5327,7 @@ export default {
                 children.instanceMatrix.needsUpdate = true;
               });
               this.refreshCollisionObbDebug();
+              this.refreshOcclusionBoundsDebug();
               this.notifyCameraChange(); // 触发场景更新
               break;
             }
@@ -5135,6 +5433,7 @@ export default {
         this.buildOctreeFromBoxIndex();
       }
       this.refreshCollisionObbDebug();
+      this.refreshOcclusionBoundsDebug();
     },
     showOutlinePass(instanceId) {
       let targetObj = this.getObjectByName(instanceId);
@@ -5282,6 +5581,7 @@ export default {
                   children.instanceMatrix.needsUpdate = true;
                 });
                 this.refreshCollisionObbDebug();
+                this.refreshOcclusionBoundsDebug();
                 break;
               }
               case 'opacity':
@@ -5703,6 +6003,7 @@ export default {
       }
       this.clearBypassCullingModelIds();
       this.hideCollisionObbDebug();
+      this.hideOcclusionBoundsDebug();
 
       if (this.scene) {
         this.removeTraverse();
@@ -5968,6 +6269,7 @@ export default {
       if (nodeType === 'custom-root') return true;
       if (userData.transformControlHelper === true) return true;
       if (userData.collisionObbDebugHelper === true) return true;
+      if (userData.occlusionBoundsDebugHelper === true) return true;
       if (object.isCamera || object.isLight) return true;
       if (typeof object.type === 'string' && /Helper$/i.test(object.type)) return true;
       return object.type === 'CSS2DObject' || object.type === 'TransformControlsRoot';
@@ -7079,6 +7381,7 @@ export default {
         object.userData.instancesMap instanceof Map &&
         object.userData.instancesMap.get(instanceId);
       if (instanceInfo && instanceInfo.visible === false) return false;
+      if (instanceInfo && instanceInfo.cullingVisible === false) return false;
 
       const box =
         this._boxIndex && this._boxIndex.has(String(instanceId))