fl-web-component 2.1.1-beta.2 → 2.1.1-beta.21

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 = 10;
+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',
@@ -215,7 +221,11 @@ export default {
         isPaused: false,
       },
       isolateMode: false,
-      collisionObbDebugEnabled: isDebug,
+      sceneBoundingBoxDebugEnabled: false,
+      // collisionObbDebugEnabled: isDebug,
+      collisionObbDebugEnabled: false,
+      // occlusionBoundsDebugEnabled: isDebug,
+      occlusionBoundsDebugEnabled: false,
     };
   },
   watch: {
@@ -224,6 +234,13 @@ export default {
         this.detachTransformControls();
       }
     },
+    sceneBoundingBoxDebugEnabled(val) {
+      if (val) {
+        this.refreshSceneBoundingBoxHelper(true);
+      } else {
+        this.hideSceneBoundingBox();
+      }
+    },
   },
   beforeCreate() {
     this.spaceUp = true;
@@ -258,6 +275,7 @@ export default {
       'sceneBoundingBox',
       'sceneBoundingBoxHelper',
       'collisionObbDebugGroup',
+      'occlusionBoundsDebugGroup',
     ];
     arr.forEach(item => {
       this[item] = null;
@@ -279,6 +297,7 @@ export default {
       'isDragging',
       'boundingBoxVisible',
       'collisionObbDebugEnabled',
+      'occlusionBoundsDebugEnabled',
     ].forEach(item => {
       this[item] = false;
     });
@@ -360,11 +379,16 @@ export default {
           wheelTimeout: null,
         },
       },
+      cameraControlMoveObserver: {
+        enabled: false,
+        interval: 500,
+      },
       streamLoader: null,
       // isPerformingInitialCentering: false, // 标记是否正在执行初始居中
       isObserverEnabled: true, // 标记相机变更观察者是否启用
       sceneBoxes: new Map(),
       documentModelIds: new Map(),
+      documentSceneBoundsIds: new Map(),
       outlineInstanceProxyMap: new Map(),
       occlusionWorker: null,
       occlusionWorkerRequestMap: new Map(),
@@ -1204,6 +1228,28 @@ 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) {
@@ -1469,71 +1515,178 @@ export default {
     updateGlobalSceneBoundingBox() {
       const state = this.noObserver || {};
       const occScene = state.occlusionState && state.occlusionState._occScene;
+      const mergedBox = new this.THREE.Box3();
+      let hasValidBox = false;
+      const mergeBox = box => {
+        if (!box || !box.isBox3 || box.isEmpty()) return;
+        if (!hasValidBox) {
+          mergedBox.copy(box);
+          hasValidBox = true;
+          return;
+        }
+        mergedBox.union(box);
+      };
 
-      // 优先使用由 boxIndex 构建出的离屏全场景，作为整体居中与 home 的统一范围
+      // 离屏遮挡场景只包含参与遮挡的模型，需要继续合并场景范围索引中的二维图形范围。
       if (occScene && occScene.children && occScene.children.length > 0) {
         const occBox = new this.THREE.Box3().setFromObject(occScene);
-        if (!occBox.isEmpty()) {
-          this.sceneBoundingBox = occBox;
-          return this.sceneBoundingBox;
-        }
+        mergeBox(occBox);
       }
 
-      // 离屏场景尚未完成时，回退到 boxIndex 联合包围盒，确保每次 add boxIndex 都能更新全场景范围
-      if (this._boxIndex && this._boxIndex.size > 0) {
-        let minX = Infinity,
-          minY = Infinity,
-          minZ = Infinity;
-        let maxX = -Infinity,
-          maxY = -Infinity,
-          maxZ = -Infinity;
-        this._boxIndex.forEach(box => {
-          if (!box || !box.isBox3 || box.isEmpty()) return;
-          const mn = box.min;
-          const mx = box.max;
-          if (mn.x < minX) minX = mn.x;
-          if (mn.y < minY) minY = mn.y;
-          if (mn.z < minZ) minZ = mn.z;
-          if (mx.x > maxX) maxX = mx.x;
-          if (mx.y > maxY) maxY = mx.y;
-          if (mx.z > maxZ) maxZ = mx.z;
+      // sceneBoundsIndex 包含二维和三维图形，是全场景 dolly 距离的主要范围来源。
+      if (this._sceneBoundsIndex && this._sceneBoundsIndex.size > 0) {
+        this._sceneBoundsIndex.forEach(box => {
+          mergeBox(box);
         });
-        if (
-          Number.isFinite(minX) &&
-          Number.isFinite(minY) &&
-          Number.isFinite(minZ) &&
-          Number.isFinite(maxX) &&
-          Number.isFinite(maxY) &&
-          Number.isFinite(maxZ)
-        ) {
-          this.sceneBoundingBox = new this.THREE.Box3(
-            new this.THREE.Vector3(minX, minY, minZ),
-            new this.THREE.Vector3(maxX, maxY, maxZ)
-          );
-          return this.sceneBoundingBox;
-        }
       }
 
       const boxes = Array.from((state.sceneBoxes && state.sceneBoxes.values()) || []);
       if (boxes.length > 0) {
-        const firstBox = boxes[0].clone();
-        for (let i = 1; i < boxes.length; i++) {
-          firstBox.union(boxes[i]);
+        for (let i = 0; i < boxes.length; i++) {
+          mergeBox(boxes[i]);
         }
-        this.sceneBoundingBox = firstBox;
+      }
+
+      if (hasValidBox) {
+        this.sceneBoundingBox = mergedBox;
+        this.refreshSceneBoundingBoxHelper(this.sceneBoundingBoxDebugEnabled);
         return this.sceneBoundingBox;
       }
 
       this.sceneBoundingBox = new this.THREE.Box3();
+      this.refreshSceneBoundingBoxHelper(this.sceneBoundingBoxDebugEnabled);
       return this.sceneBoundingBox;
     },
+    upsertIndexedBox(indexMap, modelId, box) {
+      if (!indexMap || !modelId || !box || !box.isBox3) return null;
+      const key = String(modelId);
+      const existingBox = indexMap.get(key);
+      if (!existingBox) {
+        indexMap.set(key, box);
+        return box;
+      }
+      existingBox.union(box);
+      return existingBox;
+    },
+    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 =
+        !!targetUserData.occlusionEnabled && !!sourceUserData.occlusionEnabled;
+      targetUserData.occlusionProxyBoxes = targetProxyBoxes.concat(sourceProxyBoxes);
+
+      const targetObbs = Array.isArray(targetUserData.collisionObbs)
+        ? targetUserData.collisionObbs
+        : [];
+      const sourceObbs = Array.isArray(sourceUserData.collisionObbs)
+        ? sourceUserData.collisionObbs
+        : [];
+      if (sourceObbs.length > 0) {
+        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);
+      const existingBox = this._boxIndex.get(key);
+      if (!existingBox) {
+        this._boxIndex.set(key, box);
+        return;
+      }
+      this.mergeModelBoxUserData(existingBox, box);
+      existingBox.union(box);
+    },
     setBoxIndex(boxJson, documentId, isAdd = true) {
       if (!this._boxIndex) this._boxIndex = new Map();
+      if (!this._sceneBoundsIndex) this._sceneBoundsIndex = new Map();
       if (!documentId) {
         this._boxIndex.clear();
+        this._sceneBoundsIndex.clear();
         if (this.noObserver && this.noObserver.documentModelIds) {
           this.noObserver.documentModelIds.clear();
         }
+        if (this.noObserver && this.noObserver.documentSceneBoundsIds) {
+          this.noObserver.documentSceneBoundsIds.clear();
+        }
         this.hasExecutedCentering = false;
         this.buildOctreeFromBoxIndex();
         return;
@@ -1542,32 +1695,50 @@ export default {
       if (isAdd && boxJson) {
         const arr = boxJson ? boxJson : [];
         const modelIds = new Set();
+        const sceneBoundIds = new Set();
         const validGeomTypes = new Set(Object.values(GEOM_TYPES));
         for (let i = 0; i < arr.length; i++) {
           const it = arr[i];
-          if (!validGeomTypes.has(it.geomType)) {
+          const tempGeomType = it.geomType || it.geom_type;
+          if (!validGeomTypes.has(tempGeomType)) {
             continue;
           }
-          if (it.obb.length == 0) {
+          const minSource = it.min;
+          const maxSource = it.max;
+          const hasValidMinMax =
+            minSource &&
+            maxSource &&
+            minSource.length >= 3 &&
+            maxSource.length >= 3 &&
+            Number.isFinite(minSource[0]) &&
+            Number.isFinite(minSource[1]) &&
+            Number.isFinite(minSource[2]) &&
+            Number.isFinite(maxSource[0]) &&
+            Number.isFinite(maxSource[1]) &&
+            Number.isFinite(maxSource[2]);
+          if (!hasValidMinMax) {
             continue;
           }
+          const obbData = it.obb || [];
+          const modelId = String(it.id);
 
           // 使用新的 min/max 数据结构
-          const min = new this.THREE.Vector3(it.min[0], it.min[1], it.min[2]);
-          const max = new this.THREE.Vector3(it.max[0], it.max[1], it.max[2]);
+          const min = new this.THREE.Vector3(minSource[0], minSource[1], minSource[2]);
+          const max = new this.THREE.Vector3(maxSource[0], maxSource[1], maxSource[2]);
 
           const sourceBox = new this.THREE.Box3(min.clone(), max.clone());
           // 八叉树仍使用 AABB 粗筛，最终碰撞使用 sourceBox 派生的 OBB 精筛
           const boxThree = sourceBox.clone();
 
+          const tempMeshMatrix = it.meshMatrix || it.mesh_matrix;
           const hasMatrix = Array.isArray(it.matrix) && it.matrix.length >= 16;
-          const hasMeshMatrix = Array.isArray(it.meshMatrix) && it.meshMatrix.length >= 16;
+          const hasMeshMatrix = Array.isArray(tempMeshMatrix) && tempMeshMatrix.length >= 16;
           let localMatrix = null;
           let collisionMatrix = null;
           if (hasMatrix || hasMeshMatrix) {
             localMatrix = new this.THREE.Matrix4();
             if (hasMeshMatrix) {
-              localMatrix.fromArray(it.meshMatrix);
+              localMatrix.fromArray(tempMeshMatrix);
             } else {
               localMatrix.identity();
             }
@@ -1588,25 +1759,32 @@ export default {
             boxThree.applyMatrix4(collisionMatrix);
           }
 
+          this.upsertIndexedBox(this._sceneBoundsIndex, modelId, boxThree.clone());
+          sceneBoundIds.add(modelId);
+
+          // 没有 OBB 数据的二维图形只参与全场景范围，不纳入碰撞和遮挡索引。
+          if (obbData.length === 0) {
+            continue;
+          }
+
           const userData = {
             flag: it.flag || 1, // 默认为 1
-            geomType: it.geomType,
-            obbData: it.obb, // 存储原始 OBB 数据
+            geomType: tempGeomType,
+            obbData, // 存储原始 OBB 数据
             transparent: it.transp > 0,
             sourceVisible: it.visible === false ? false : true,
             visible: it.visible === false ? false : true, // 默认显示
             occlusionEnabled:
-              it.geomType === GEOM_TYPES.geom_3d || it.geomType === GEOM_TYPES.geom_3d_obj,
+              tempGeomType === GEOM_TYPES.geom_3d || tempGeomType === GEOM_TYPES.geom_3d_obj,
           };
           if (it.flag === 1) {
             userData.indices = it.indices;
             userData.matrix = localMatrix ? localMatrix.toArray() : it.matrix;
-            userData.meshMatrix = it.meshMatrix;
+            userData.meshMatrix = tempMeshMatrix;
             // userData.matrix = new this.THREE.Matrix4().identity();
           }
           // 如果是 flag=3，解析并存储中心点、半轴长、旋转矩阵
-          else if (it.flag === 3 && it.obb && it.obb.length === 15) {
-            const obbData = it.obb;
+          else if (it.flag === 3 && obbData.length === 15) {
             const center = new this.THREE.Vector3(obbData[0], obbData[1], obbData[2]);
             const halfSize = new this.THREE.Vector3(obbData[3], obbData[4], obbData[5]);
             const rotation = new this.THREE.Matrix3().fromArray(obbData.slice(6, 15));
@@ -1629,27 +1807,26 @@ 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)
-          else if (it.flag === 2 && it.obb && it.obb.length > 0) {
+          else if (it.flag === 2 && obbData.length > 0) {
             const subBoxes = [];
             const collisionObbs = [];
-            for (let k = 0; k < it.obb.length; k += 6) {
-              if (k + 5 < it.obb.length) {
-                const min = new this.THREE.Vector3(it.obb[k], it.obb[k + 1], it.obb[k + 2]);
-                const max = new this.THREE.Vector3(it.obb[k + 3], it.obb[k + 4], it.obb[k + 5]);
+            for (let k = 0; k < obbData.length; k += 6) {
+              if (k + 5 < obbData.length) {
+                const min = new this.THREE.Vector3(obbData[k], obbData[k + 1], obbData[k + 2]);
+                const max = new this.THREE.Vector3(obbData[k + 3], obbData[k + 4], obbData[k + 5]);
                 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);
               }
             }
@@ -1660,20 +1837,17 @@ 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];
           }
 
           boxThree.userData = userData;
 
-          const modelId = String(it.id);
-          this._boxIndex.set(modelId, boxThree);
+          this.upsertModelBox(modelId, boxThree);
           modelIds.add(modelId);
         }
         this.noObserver.documentModelIds.set(documentId, modelIds);
+        this.noObserver.documentSceneBoundsIds.set(documentId, sceneBoundIds);
       } else {
         const modelIds = this.noObserver.documentModelIds.get(documentId);
         if (modelIds) {
@@ -1687,14 +1861,38 @@ export default {
             this.hasExecutedCentering = false;
           }
         }
+        const sceneBoundIds =
+          this.noObserver.documentSceneBoundsIds &&
+          this.noObserver.documentSceneBoundsIds.get(documentId);
+        if (sceneBoundIds) {
+          sceneBoundIds.forEach(id => {
+            this._sceneBoundsIndex.delete(id);
+          });
+          this.noObserver.documentSceneBoundsIds.delete(documentId);
+        }
       }
       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 (
@@ -1703,7 +1901,9 @@ export default {
         this.sceneBoundingBox.isEmpty()
       )
         return;
-      if (!this._boxIndex || this._boxIndex.size === 0) return;
+      const hasBoxIndex = this._boxIndex && this._boxIndex.size > 0;
+      const hasSceneBoundsIndex = this._sceneBoundsIndex && this._sceneBoundsIndex.size > 0;
+      if (!hasBoxIndex && !hasSceneBoundsIndex) return;
 
       this.smartModelCenter(this.sceneBoundingBox, 0);
     },
@@ -1805,6 +2005,53 @@ export default {
       }
       node.items.push({ id, box });
     },
+    _buildCollisionOctreeFromEntries(entries) {
+      if (!Array.isArray(entries) || entries.length === 0) {
+        return null;
+      }
+
+      let minX = Infinity;
+      let minY = Infinity;
+      let minZ = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      let maxZ = -Infinity;
+
+      entries.forEach(item => {
+        const box = item && item.box;
+        if (!box || !box.isBox3) return;
+        const mn = box.min;
+        const mx = box.max;
+        if (mn.x < minX) minX = mn.x;
+        if (mn.y < minY) minY = mn.y;
+        if (mn.z < minZ) minZ = mn.z;
+        if (mx.x > maxX) maxX = mx.x;
+        if (mx.y > maxY) maxY = mx.y;
+        if (mx.z > maxZ) maxZ = mx.z;
+      });
+
+      if (minX === Infinity) {
+        return null;
+      }
+
+      const rootBox = new this.THREE.Box3(
+        new this.THREE.Vector3(minX, minY, minZ),
+        new this.THREE.Vector3(maxX, maxY, maxZ)
+      );
+      const root = {
+        box: rootBox,
+        items: [],
+        children: null,
+        depth: 0,
+      };
+
+      entries.forEach(item => {
+        if (!item || !item.box) return;
+        this._octreeInsert(root, String(item.id), item.box);
+      });
+
+      return root;
+    },
     _isCollisionBoxAvailable(box) {
       if (!box || !box.isBox3 || box.isEmpty()) return false;
       if (box.userData && box.userData.visible === false) return false;
@@ -1935,7 +2182,8 @@ export default {
     _buildCollisionPairMap() {
       const pairMap = new Map();
       const collisionPairs = this.getOctreeCollisionPairs();
-      const pairs = collisionPairs && Array.isArray(collisionPairs.pairs) ? collisionPairs.pairs : [];
+      const pairs =
+        collisionPairs && Array.isArray(collisionPairs.pairs) ? collisionPairs.pairs : [];
       for (let i = 0; i < pairs.length; i++) {
         const pair = pairs[i];
         if (!pair) continue;
@@ -1956,20 +2204,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++) {
@@ -1995,6 +2238,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();
@@ -2064,16 +2466,15 @@ 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;
           }
         }
       }
       return false;
     },
-    _queryOctreeByBox(box) {
+    _queryOctreeByBoxWithRoot(root, box) {
       const results = [];
-      const root = this._octree;
       if (!root || !this._isCollisionBoxAvailable(box)) return results;
 
       const stack = [root];
@@ -2099,25 +2500,88 @@ export default {
 
       return results;
     },
-    getOctreeCollisionPairs() {
+    _queryOctreeByBox(box) {
+      return this._queryOctreeByBoxWithRoot(this._octree, box);
+    },
+    getOctreeCollisionPairs(options = {}) {
       const pairs = [];
       if (!this._boxIndex || this._boxIndex.size === 0) return { pairs };
 
-      if (!this._octree) {
-        this.buildOctreeFromBoxIndex();
+      const normalizeIds = value =>
+        Array.isArray(value)
+          ? Array.from(
+              new Set(
+                value
+                  .map(item => (item === null || item === undefined ? '' : String(item)))
+                  .filter(item => item !== '')
+              )
+            )
+          : [];
+
+      const getEntriesByIds = ids => {
+        const entries = [];
+        const idSet = new Set(ids);
+        this._boxIndex.forEach((box, id) => {
+          const key = String(id);
+          if (idSet.has(key)) {
+            entries.push({
+              id: key,
+              box,
+            });
+          }
+        });
+        return entries;
+      };
+
+      const sourceIds = normalizeIds(options.sourceIds);
+      const targetIds = normalizeIds(options.targetIds);
+      const includeIds = Array.isArray(options.includeIds) ? normalizeIds(options.includeIds) : [];
+
+      let root = this._octree;
+      let sourceEntries = [];
+      let dedupePairKeySet = null;
+
+      if (sourceIds.length > 0 && targetIds.length > 0) {
+        const targetEntries = getEntriesByIds(targetIds);
+        sourceEntries = getEntriesByIds(sourceIds);
+        if (sourceEntries.length === 0 || targetEntries.length === 0) return { pairs };
+        root = this._buildCollisionOctreeFromEntries(targetEntries);
+        if (!root) return { pairs };
+        dedupePairKeySet = new Set();
+      } else if (includeIds.length > 0) {
+        sourceEntries = getEntriesByIds(includeIds);
+        if (sourceEntries.length === 0) return { pairs };
+        root = this._buildCollisionOctreeFromEntries(sourceEntries);
+        if (!root) return { pairs };
+      } else {
+        if (!this._octree) {
+          this.buildOctreeFromBoxIndex();
+        }
+        if (!this._octree) return { pairs };
+        this._boxIndex.forEach((box, id) => {
+          sourceEntries.push({
+            id: String(id),
+            box,
+          });
+        });
       }
-      if (!this._octree) return { pairs };
 
-      this._boxIndex.forEach((boxA, idA) => {
+      sourceEntries.forEach(({ id: idA, box: boxA }) => {
         if (!this._isCollisionBoxAvailable(boxA)) return;
 
-        const hits = this._queryOctreeByBox(boxA);
+        const hits = this._queryOctreeByBoxWithRoot(root, boxA);
         for (let i = 0; i < hits.length; i++) {
           const item = hits[i];
           if (!item || String(item.id) === String(idA)) continue;
           const boxB = item.box;
           if (!this._isCollisionBoxMatched(boxA, boxB)) continue;
 
+          if (dedupePairKeySet) {
+            const pairKey = `${String(idA)}__${String(item.id)}`;
+            if (dedupePairKeySet.has(pairKey)) continue;
+            dedupePairKeySet.add(pairKey);
+          }
+
           pairs.push({
             idA: this._formatCollisionPairId(idA),
             idB: this._formatCollisionPairId(item.id),
@@ -2571,7 +3035,8 @@ export default {
     /**
      * 执行视椎体裁切，清理视椎体外的InstancedMesh实例
      */
-    async performFrustumCulling() {
+    async performFrustumCulling(options = {}) {
+      const skipUnload = !!(options && options.skipUnload);
       const modelState = this.noObserver
         ? this.noObserver.modelStateManager
         : this.modelStateManager;
@@ -2613,7 +3078,7 @@ 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) => {
@@ -2624,7 +3089,7 @@ export default {
               visibleIdSet.add(this.formatModelId(modelId));
               return;
             }
-            candidates.push({ modelId, box });
+            this.appendOcclusionCandidates(candidates, modelId, box, globalFrustum);
           }
         });
       }
@@ -2740,6 +3205,7 @@ export default {
             const tBuild0 = performance.now();
 
             const flag1Items = [];
+            const flag2Items = [];
             const flag3Items = [];
 
             let globalIdx = 1;
@@ -2753,6 +3219,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 });
               }
@@ -2769,7 +3237,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;
@@ -2799,19 +3268,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);
@@ -3254,12 +3730,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;
@@ -3268,37 +3744,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))
@@ -3306,16 +3788,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;
               }
             }
@@ -3329,20 +3814,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 (!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)) {
@@ -3351,10 +3840,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))
@@ -3362,18 +3859,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 (!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 });
         }
       });
@@ -3491,9 +3983,15 @@ export default {
      * @param {Object} config - 配置项
      * @param {Object} config.modelApi - 模型API接口
      * @param {string} [config.projectId] - 项目ID
+     * @param {Object} [config.cameraControlMoveObserver] - 普通视角运动中触发加载的配置
+     * @param {boolean} [config.cameraControlMoveObserver.enabled=false] - 是否开启普通视角运动中加载
+     * @param {number} [config.cameraControlMoveObserver.interval=500] - 触发间隔，单位毫秒
+     * @param {boolean} [config.enableCameraControlMoveObserver=false] - 是否开启普通视角运动中加载
+     * @param {number} [config.cameraControlMoveInterval=500] - 触发间隔，单位毫秒
      */
     init(config = {}) {
       console.log('init');
+      this.setCameraControlMoveObserverConfig(config);
       this.initStreamLoader(config.modelApi, config);
     },
 
@@ -3920,6 +4418,124 @@ export default {
       this.noObserver.isObserverEnabled = enabled;
     },
 
+    setCameraControlMoveObserverConfig(config = {}) {
+      if (!this.noObserver) return;
+      const nestedConfig = config.cameraControlMoveObserver || {};
+      const enabled =
+        typeof nestedConfig.enabled === 'boolean'
+          ? nestedConfig.enabled
+          : typeof config.enableCameraControlMoveObserver === 'boolean'
+          ? config.enableCameraControlMoveObserver
+          : false;
+      const rawInterval =
+        nestedConfig.interval !== undefined
+          ? nestedConfig.interval
+          : config.cameraControlMoveInterval;
+      const interval = Number(rawInterval);
+      const safeInterval = Number.isFinite(interval) && interval > 0 ? interval : 500;
+
+      this.noObserver.cameraControlMoveObserver = {
+        enabled,
+        interval: safeInterval,
+      };
+      this.resetCameraControlMoveSnapshot(false);
+    },
+
+    isCameraControlMoveObserverEnabled() {
+      const config = this.noObserver && this.noObserver.cameraControlMoveObserver;
+      return !!(config && config.enabled);
+    },
+
+    getCameraControlTarget(target) {
+      if (!target || !this.cameraControls) return false;
+      if (typeof this.cameraControls.getTarget === 'function') {
+        this.cameraControls.getTarget(target);
+        return true;
+      }
+      if (this.cameraControls._target) {
+        target.copy(this.cameraControls._target);
+        return true;
+      }
+      return false;
+    },
+
+    resetCameraControlMoveSnapshot(syncCurrent = false) {
+      if (!this.noObserver) return;
+      if (!this.noObserver._cameraControlMoveState) {
+        this.noObserver._cameraControlMoveState = {
+          position: new this.THREE.Vector3(),
+          quaternion: new this.THREE.Quaternion(),
+          target: new this.THREE.Vector3(),
+          currentTarget: new this.THREE.Vector3(),
+          initialized: false,
+          hasTarget: false,
+        };
+      }
+      const state = this.noObserver._cameraControlMoveState;
+      if (!syncCurrent || !this.camera) {
+        state.initialized = false;
+        state.hasTarget = false;
+        return;
+      }
+
+      this.camera.updateMatrixWorld(true);
+      state.position.copy(this.camera.position);
+      state.quaternion.copy(this.camera.quaternion);
+      state.hasTarget = this.getCameraControlTarget(state.target);
+      state.initialized = true;
+    },
+
+    observeCameraControlMove() {
+      if (
+        !this.noObserver ||
+        !this.noObserver.isObserverEnabled ||
+        !this.isCameraControlMoveObserverEnabled() ||
+        !this.camera ||
+        !this.cameraControls ||
+        typeof this._cameraChangeObserver !== 'function'
+      ) {
+        return;
+      }
+
+      const loadingState = this.noObserver.batchLoadingState || {};
+      const interactionState = loadingState.interactionState || {};
+      const wheelActive = !!interactionState.wheelTimeout;
+      const controlActive = !!this.noObserver.isControlActive;
+      if ((!controlActive && !wheelActive) || this.firstPerSign) {
+        this.resetCameraControlMoveSnapshot(false);
+        return;
+      }
+
+      if (!this.noObserver._cameraControlMoveState) {
+        this.resetCameraControlMoveSnapshot(true);
+        return;
+      }
+
+      const state = this.noObserver._cameraControlMoveState;
+      if (!state.initialized) {
+        this.resetCameraControlMoveSnapshot(true);
+        return;
+      }
+
+      this.camera.updateMatrixWorld(true);
+      const hasTarget = this.getCameraControlTarget(state.currentTarget);
+      const positionMoved = state.position.distanceToSquared(this.camera.position) > 1e-8;
+      const quaternionMoved = 1 - Math.abs(state.quaternion.dot(this.camera.quaternion)) > 1e-10;
+      const targetMoved =
+        hasTarget !== state.hasTarget ||
+        (hasTarget && state.target.distanceToSquared(state.currentTarget) > 1e-8);
+
+      if (!positionMoved && !quaternionMoved && !targetMoved) return;
+
+      state.position.copy(this.camera.position);
+      state.quaternion.copy(this.camera.quaternion);
+      state.hasTarget = hasTarget;
+      if (hasTarget) {
+        state.target.copy(state.currentTarget);
+      }
+      this._cameraChangeObserver('controlMove');
+    },
+
     /**
      * 初始化相机变更观察者 (CameraChangeObserver)
      * 统一监听：用户交互(Wheel/Control)、程序化动画、API调用
@@ -3954,7 +4570,9 @@ export default {
           // 执行视锥体裁剪
           // 第一视角不裁切
           if (this.modelStateManager.frustumCheckEnabled) {
-            await this.performFrustumCulling();
+            await this.performFrustumCulling({
+              skipUnload: source === 'controlMove',
+            });
           }
 
           // 执行流式加载请求
@@ -3966,11 +4584,19 @@ export default {
           }
         },
         source => {
-          // 漫游模式下，或者第一人称移动时，使用节流策略（每300ms触发一次）
+          // 漫游、第一人称移动、普通视角拖拽/缩放中，使用节流策略避免持续运动被防抖吞掉。
           // 避免在持续运动中因防抖重置定时器而无法触发
           if (source === 'roam' || source === 'firstPersonMove') {
             return { type: 'throttle', limit: 1000 };
           }
+          if (source === 'controlMove') {
+            const config = this.noObserver && this.noObserver.cameraControlMoveObserver;
+            const interval =
+              config && Number.isFinite(config.interval) && config.interval > 0
+                ? config.interval
+                : 500;
+            return { type: 'throttle', limit: interval };
+          }
           return 300; // 默认防抖 300ms
         }
       );
@@ -3984,8 +4610,20 @@ export default {
       this._wheelHandler = res => {
         this.$emit('wheelStart', res);
 
-        // 统一交互开始处理
-        this.beginInteraction('wheel');
+        const cameraControlMoveEnabled = this.isCameraControlMoveObserverEnabled();
+        const loadingState = this.noObserver
+          ? this.noObserver.batchLoadingState
+          : this.batchLoadingState;
+        const wheelAlreadyActive =
+          loadingState &&
+          loadingState.interactionState &&
+          loadingState.interactionState.wheelTimeout;
+        if (cameraControlMoveEnabled && !wheelAlreadyActive) {
+          this.resetCameraControlMoveSnapshot(true);
+        } else if (!cameraControlMoveEnabled) {
+          // 未开启普通视角运动加载时，保持原有交互中断流程。
+          this.beginInteraction('wheel');
+        }
 
         // 设置滚轮交互的结束检测
         this.scheduleWheelInteractionEnd(res, 100);
@@ -4027,9 +4665,12 @@ export default {
       // 4. 监听器 - Controls (用户拖拽/操作)
       this._onControlStart = res => {
         this.noObserver.isControlActive = true;
-
-        // 统一交互开始处理（相机）
-        this.beginInteraction('this.camera');
+        if (this.isCameraControlMoveObserverEnabled()) {
+          this.resetCameraControlMoveSnapshot(true);
+        } else {
+          // 未开启普通视角运动加载时，保持原有交互中断流程。
+          this.beginInteraction('this.camera');
+        }
         this.$emit('controlStart', res);
 
         // 记录鼠标按下时的位置
@@ -4046,8 +4687,10 @@ export default {
 
         this.$emit('controlEnd', res);
 
-        // 统一交互结束处理（相机）
-        this.endInteraction('this.camera', res, { immediateResume: false });
+        if (!this.isCameraControlMoveObserverEnabled()) {
+          // 未开启普通视角运动加载时，保持原有交互中断流程。
+          this.endInteraction('this.camera', res, { immediateResume: false });
+        }
 
         // 记录鼠标抬起时的位置并计算是否发生了拖拽
         const event = res.originalEvent || window.event;
@@ -4076,6 +4719,9 @@ export default {
           // 触发观察者
           this._cameraChangeObserver('control');
         }
+        if (this.isCameraControlMoveObserverEnabled()) {
+          this.resetCameraControlMoveSnapshot(false);
+        }
       };
 
       this.cameraControls.addEventListener('controlstart', this._onControlStart);
@@ -4136,12 +4782,37 @@ export default {
     },
     // 动态设置视角滚轮的距离
     setCameraConfig() {
+      if (
+        !this.sceneBoundingBox ||
+        !this.sceneBoundingBox.isBox3 ||
+        this.sceneBoundingBox.isEmpty()
+      ) {
+        return;
+      }
       // let box3 = new this.THREE.Box3().setFromObject(this.sceneBoundingBox);
       let size = new this.THREE.Vector3();
       this.sceneBoundingBox.getSize(size);
       const maxBorder = Math.max(size.x, size.y, size.z);
+      if (isDebug) {
+        const center = this.sceneBoundingBox.getCenter(new this.THREE.Vector3());
+        console.log('sceneBoundingBox 调试信息', {
+          size: {
+            x: size.x,
+            y: size.y,
+            z: size.z,
+          },
+          center: {
+            x: center.x,
+            y: center.y,
+            z: center.z,
+          },
+          maxBorder,
+        });
+        this.refreshSceneBoundingBoxHelper(this.sceneBoundingBoxDebugEnabled);
+      }
       // this.cameraControls.this.camera.far = maxBorder * 10; // 设置相机的远裁剪面
       this.cameraControls.minDistance = maxBorder * 0.2; // 动态设置视角滚轮的距离
+      // this.cameraControls.minDistance = 1000; // 动态设置视角滚轮的距离
       this.camera.updateProjectionMatrix();
     },
     // 获取mesh的中心点
@@ -4469,8 +5140,19 @@ export default {
         if (this.threeMeasure) {
           this.threeMeasure.updateParams(width, height);
         }
+        this.updateMeshLineResolution(width, height);
       }
     },
+    updateMeshLineResolution(width, height) {
+      if (!this.modelGroup || !width || !height) return;
+      this.modelGroup.traverse(child => {
+        const material = child && child.material;
+        if (material && material.type === 'MeshLineMaterial' && material.resolution) {
+          material.resolution.set(width, height);
+          material.needsUpdate = true;
+        }
+      });
+    },
     setModelCenter(target, options = {}) {
       // return
       let box3;
@@ -4644,7 +5326,9 @@ export default {
                 children.instanceMatrix.needsUpdate = true;
               });
               this.refreshCollisionObbDebug();
-              this.notifyCameraChange(); // 触发场景更新
+              this.refreshOcclusionBoundsDebug();
+              // 调用此方法后 模型隐藏后再执行显示操作后无法正常显示，故在此先注释
+              // this.notifyCameraChange(); // 触发场景更新
               break;
             }
             case 'opacity':
@@ -4749,6 +5433,7 @@ export default {
         this.buildOctreeFromBoxIndex();
       }
       this.refreshCollisionObbDebug();
+      this.refreshOcclusionBoundsDebug();
     },
     showOutlinePass(instanceId) {
       let targetObj = this.getObjectByName(instanceId);
@@ -4896,6 +5581,7 @@ export default {
                   children.instanceMatrix.needsUpdate = true;
                 });
                 this.refreshCollisionObbDebug();
+                this.refreshOcclusionBoundsDebug();
                 break;
               }
               case 'opacity':
@@ -5317,6 +6003,7 @@ export default {
       }
       this.clearBypassCullingModelIds();
       this.hideCollisionObbDebug();
+      this.hideOcclusionBoundsDebug();
 
       if (this.scene) {
         this.removeTraverse();
@@ -5582,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';
@@ -6545,6 +7233,7 @@ export default {
           });
         }
         this.cameraControls.enabled && this.cameraControls.update(this.timeStamp);
+        this.observeCameraControlMove();
         // 计算相机近裁面到包围盒当前面的距离
         this.cameraTrack();
         this.firstPerspective();
@@ -6692,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))
@@ -6755,6 +7445,13 @@ export default {
       const loadingState = this.noObserver
         ? this.noObserver.batchLoadingState
         : this.batchLoadingState;
+      const rect = this.renderer
+        ? this.renderer.domElement.getBoundingClientRect()
+        : { width: window.innerWidth, height: window.innerHeight };
+      options.meshLineResolution = {
+        width: rect.width || window.innerWidth || 1,
+        height: rect.height || window.innerHeight || 1,
+      };
       // 如果已经在加载中，先停止之前的加载
       if (loadingState.isLoading) {
         this.stopBatchLoading('restart');
@@ -7318,8 +8015,15 @@ export default {
 
       loadingState.interactionState.wheelTimeout = setTimeout(() => {
         this.$emit('wheelEnd', event);
-        this.endInteraction('wheel', event, { immediateResume: false });
         loadingState.interactionState.wheelTimeout = null;
+        if (this.isCameraControlMoveObserverEnabled()) {
+          this.resetCameraControlMoveSnapshot(false);
+          if (typeof this._cameraChangeObserver === 'function') {
+            this._cameraChangeObserver('wheel');
+          }
+        } else {
+          this.endInteraction('wheel', event, { immediateResume: false });
+        }
       }, delay);
     },
 
@@ -7347,9 +8051,87 @@ export default {
     /**
      * 隐藏场景包围盒
      */
+    refreshSceneBoundingBoxHelper(forceVisible = this.boundingBoxVisible) {
+      if (this.sceneBoundingBoxHelper && this.scene) {
+        this.scene.remove(this.sceneBoundingBoxHelper);
+        this.sceneBoundingBoxHelper.geometry && this.sceneBoundingBoxHelper.geometry.dispose();
+        if (Array.isArray(this.sceneBoundingBoxHelper.material)) {
+          this.sceneBoundingBoxHelper.material.forEach(material => {
+            material && material.dispose && material.dispose();
+          });
+        } else if (
+          this.sceneBoundingBoxHelper.material &&
+          this.sceneBoundingBoxHelper.material.dispose
+        ) {
+          this.sceneBoundingBoxHelper.material.dispose();
+        }
+        this.sceneBoundingBoxHelper = null;
+      }
+
+      if (
+        !forceVisible ||
+        !this.scene ||
+        !this.sceneBoundingBox ||
+        !this.sceneBoundingBox.isBox3 ||
+        this.sceneBoundingBox.isEmpty()
+      ) {
+        this.boundingBoxVisible = false;
+        return false;
+      }
+
+      const helper = new this.THREE.Box3Helper(this.sceneBoundingBox, 0x00ff88);
+      helper.name = 'sceneBoundingBoxHelper';
+      helper.renderOrder = 999;
+      if (helper.material) {
+        helper.material.depthTest = false;
+        helper.material.transparent = true;
+        helper.material.opacity = 0.9;
+      }
+      this.scene.add(helper);
+      this.sceneBoundingBoxHelper = helper;
+      this.boundingBoxVisible = true;
+      return true;
+    },
+
+    showSceneBoundingBox() {
+      this.sceneBoundingBoxDebugEnabled = true;
+      const shown = this.refreshSceneBoundingBoxHelper(true);
+      if (!shown) {
+        console.warn('sceneBoundingBox 无有效范围，无法绘制调试线框');
+        return;
+      }
+
+      const size = this.sceneBoundingBox.getSize(new this.THREE.Vector3());
+      const center = this.sceneBoundingBox.getCenter(new this.THREE.Vector3());
+      console.log('sceneBoundingBox 线框已绘制', {
+        size: {
+          x: size.x,
+          y: size.y,
+          z: size.z,
+        },
+        center: {
+          x: center.x,
+          y: center.y,
+          z: center.z,
+        },
+      });
+    },
+
     hideSceneBoundingBox() {
+      this.sceneBoundingBoxDebugEnabled = false;
       if (this.sceneBoundingBoxHelper && this.scene) {
         this.scene.remove(this.sceneBoundingBoxHelper);
+        this.sceneBoundingBoxHelper.geometry && this.sceneBoundingBoxHelper.geometry.dispose();
+        if (Array.isArray(this.sceneBoundingBoxHelper.material)) {
+          this.sceneBoundingBoxHelper.material.forEach(material => {
+            material && material.dispose && material.dispose();
+          });
+        } else if (
+          this.sceneBoundingBoxHelper.material &&
+          this.sceneBoundingBoxHelper.material.dispose
+        ) {
+          this.sceneBoundingBoxHelper.material.dispose();
+        }
         this.sceneBoundingBoxHelper = null;
         this.boundingBoxVisible = false;
         console.log('场景包围盒已隐藏');
@@ -7360,7 +8142,7 @@ export default {
      * 切换场景包围盒显示状态
      */
     toggleSceneBoundingBox() {
-      if (this.boundingBoxVisible) {
+      if (this.sceneBoundingBoxDebugEnabled) {
         this.hideSceneBoundingBox();
       } else {
         this.showSceneBoundingBox();