@mapgis/webclient-cesium-plugin 17.8.0 → 17.10.9

package/{documention → documentation}/CollisionDetectionByRender.html

@@ -71,8 +71,6 @@
     
     </h2>
     
-        <div class="class-description"><p>CollisionDetectionByRender</p></div>
-    
 </header>  
 
 <article>
@@ -90,7 +88,7 @@
     
         
         <div class="tag-source">
-            engineExtensions/analysis/CollisionDetectionByRender.js, line 132
+            engineExtensions/analysis/CollisionDetectionByRender.js, line 4
         </div>
         
     </div>
@@ -100,6 +98,17 @@
 <dd>
     
     
+    <div class="description">
+        <p>基于深度渲染的碰撞检测工具。</p>
+<p><code>CollisionDetectionByRender</code> 会为相机、M3D 模型或 Entity 构建一个碰撞盒，
+通过俯视与正视两个深度视图判断目标位置是否与场景发生碰撞。该方案更适合室内、小范围、低速漫游场景；
+当物体单帧位移过大、目标区域不在当前视锥可见范围内，或碰撞对象形态过于尖锐时，检测结果可能出现误差。</p>
+<p>使用限制：
+高速运动物体容易出现穿隧问题，即单帧位移超过碰撞盒检测范围时可能跳过碰撞结果。
+场景相机不可见区域可能因 Cesium 视锥剔除而缺少深度信息，导致后退或遮挡区域检测失效。
+对锥形等尖锐物体，默认边框检测模式可能无法完整覆盖目标，可改用高精度模式提升识别率，但会增加性能开销。</p>
+    </div>
+    
 
     
     
@@ -118,6 +127,8 @@
 		<th>Type</th>
 		
 		
+		<th>Default</th>
+		
 		
 		<th class="last">Description</th>
 	</tr>
@@ -134,13 +145,17 @@
             <td class="type">
             
                 
-<span class="param-type">Viewer</span>
+<span class="param-type"><a href="Cesium.Viewer.html">Cesium.Viewer</a></span>
 
 
             
             </td>
             
             
+                <td class="default">
+                
+                </td>
+            
             
             <td class="description last">
                 
@@ -149,7 +164,7 @@
                         
                     
                 
-                <p>场景视图</p></td>
+                <p>场景视图对象。</p></td>
         </tr>
 	
 	
@@ -175,6 +190,10 @@
             </td>
             
             
+                <td class="default">
+                
+                </td>
+            
             
             <td class="description last">
                 
@@ -183,7 +202,7 @@
                         
                     
                 
-                <p>做碰撞检测的对象</p></td>
+                <p>需要参与碰撞检测的对象。</p></td>
         </tr>
 	
 	
@@ -203,6 +222,12 @@
             </td>
             
             
+                <td class="default">
+                
+                    {}
+                
+                </td>
+            
             
             <td class="description last">
                 
@@ -213,7 +238,7 @@
                         
                     
                 
-                <p>可选参数</p>
+                <p>碰撞检测初始化参数。</p>
                 
 
 <table class="params">
@@ -267,7 +292,7 @@
                         
                     
                 
-                <p>碰撞盒的长(单位米)</p></td>
+                <p>碰撞盒长度，单位为米。</p></td>
         </tr>
 	
 	
@@ -303,7 +328,7 @@
                         
                     
                 
-                <p>碰撞盒的宽(单位米)</p></td>
+                <p>碰撞盒宽度，单位为米。</p></td>
         </tr>
 	
 	
@@ -339,10 +364,7 @@
                         
                     
                 
-                <p>碰撞盒的高(单位米)
-<br/><br/>
-原点高度属性用于通知碰撞检测实例碰撞对象的坐标原点所在的高度，如单体模型的坐标原点有的在其底部，有的在其中间。<br/>
-默认值设为1.7是因为默认的碰撞对象是相机。</p></td>
+                <p>碰撞盒高度，单位为米。</p></td>
         </tr>
 	
 	
@@ -364,7 +386,7 @@
             
                 <td class="default">
                 
-                    (0,0,0)
+                    new Cesium.Cartesian3(0, 0, 0)
                 
                 </td>
             
@@ -378,7 +400,43 @@
                         
                     
                 
-                <p>碰撞盒的位置偏移(单位米)</p></td>
+                <p>碰撞盒相对碰撞对象原点的位置偏移，单位为米。</p></td>
+        </tr>
+	
+	
+	
+        <tr>
+            
+                <td class="name"><code>colliderThickness</code></td>
+            
+            
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+            
+            </td>
+            
+            
+                <td class="default">
+                
+                    1
+                
+                </td>
+            
+            
+            <td class="description last">
+                
+                    
+                        <span class="optional"> 可选</span>
+                    
+                    
+                        
+                    
+                
+                <p>碰撞盒边框检测厚度。</p></td>
         </tr>
 	
 	
@@ -414,7 +472,7 @@
                         
                     
                 
-                <p>最大可通过高度(单位米)</p></td>
+                <p>发生碰撞后允许自动抬升通过的最大高度，单位为米。</p></td>
         </tr>
 	
 	
@@ -450,9 +508,7 @@
                         
                     
                 
-                <p>是否开启高精度碰撞检测
-<br/><br/>
-基于性能考虑默认不开启高精度碰撞检测。非高精度状态下只检测碰撞盒的边框所覆盖的区域，高精度状态下对碰撞盒覆盖的整个区域做检测。</p></td>
+                <p>是否开启高精度模式。关闭时仅检测碰撞盒边框，开启后检测整个盒体覆盖区域。</p></td>
         </tr>
 	
 	
@@ -488,7 +544,7 @@
                         
                     
                 
-                <p>检查深度图(debug模式)</p></td>
+                <p>是否显示深度图调试结果。</p></td>
         </tr>
 	
 	
@@ -524,12 +580,7 @@
                         
                     
                 
-                <p>检查碰撞盒(debug模式)
-<br/><br/>
-debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果，所以并不能精确的表示碰撞盒与场景的碰撞关系。<br/>
-深度图中可查看到较为精确的碰撞关系。<br/>
-开启碰撞盒检查主要是为了方便调整碰撞盒与模型相匹配。<br/>
-相机做为碰撞对象时，开启碰撞盒检查，相机会被碰撞盒包在里面。</p></td>
+                <p>是否显示碰撞盒调试结果。</p></td>
         </tr>
 	
 	
@@ -580,11 +631,127 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
     
     
     
-        <h5>Example</h5>
+        <h5>Examples</h5>
         
-
-    
-    <pre class="prettyprint"><code>const { CollisionDetectionByRender } = zondy.cesium
    camera.setView({
        destination: result.computedPosition,
        orientation: {
            heading: camera.heading,
            pitch: camera.pitch,
            roll: 0.0
        }
    });
    maximumScreenSpaceError: 0,
    autoReset: false,
    loaded: function(layer) {
        m3d = layer;
        collisionDetection = new CollisionDetectionByRender(viewer, layer._root, {
            colliderLength: 0.8, // 设置碰撞盒长
            colliderWidth: 0.6, // 设置碰撞盒宽
            colliderHeight: 1, // 设置碰撞盒高
            colliderPositionOffset: new Cesium.Cartesian3(0, 0, 0.5), // 设置碰撞盒偏移
            debugShowCollider: true, // 打开debug模式，碰撞盒检查
            debugShowDepthMap: true // 打开debug模式，深度图检查
        });
    }
     // 获取模型变换矩阵
     let modelMatrix = m3d.tileset.modelMatrix;
     // 求模型变换矩阵的逆
     Cesium.Matrix4.inverse(modelMatrix, invModelMat);
     // 未碰撞移动到该位置
     Cesium.Matrix4.setTranslation(transform, result.computedPosition, newTransform);
     // 乘上模型变换矩阵的逆矩阵
     Cesium.Matrix4.multiply(invModelMat, newTransform, newTransform);
     // 设置新的变换矩阵
     m3d.transform = Cesium.Matrix4.clone(newTransform);
    name: url,
    position: position,
    orientation: orientation,
    model: {
        uri: url,
        minimumPixelSize: 32,
        maximumScale: 20000,
    },
    colliderLength: 2,
    colliderWidth: 0.6,
    colliderHeight: 0.6,
    colliderPositionOffset: new Cesium.Cartesian3(0, 0, 0.6)
    entity.position = result.computedPosition;
    debugShowCollider: false, // 相机做为碰撞检测对象时不打开碰撞盒检查
    debugShowDepthMap: true, // 打开debug模式，深度图检查
+        <p class="code-caption"><h7 id='example1'>相机碰撞检测</h7></p>
+    
+
+    
+    <pre class="prettyprint"><code>// ES5引入方式
+const { CollisionDetectionByRender } = zondy.cesium
+
+// ES6引入方式
+import { CollisionDetectionByRender } from "@mapgis/webclient-cesium-plugin"
+
+const collisionDetection = new CollisionDetectionByRender(viewer, viewer.camera, {
+  colliderHeight: 1.7,
+  maxPassableHeight: 0.5
+})
+const result = collisionDetection.checkCollision(targetPosition, viewer.camera.heading)
+if (result.result !== 'collided') {
+  viewer.camera.setView({
+    destination: result.computedPosition,
+    orientation: {
+      heading: viewer.camera.heading,
+      pitch: viewer.camera.pitch,
+      roll: 0.0
+    }
+  })
+}</code></pre>
+    
+
+        <p class="code-caption"><h7 id='example2'>M3D 模型碰撞检测</h7></p>
+    
+
+    
+    <pre class="prettyprint"><code>// ES5引入方式
+const { CollisionDetectionByRender } = zondy.cesium
+
+// ES6引入方式
+import { CollisionDetectionByRender } from "@mapgis/webclient-cesium-plugin"
+
+let collisionDetection
+let m3d
+const url = 'http://192.168.82.89:8200/3DData/ModelCache/M3D/2.0/wujiangdizhiti/wujiangdizhiti.mcj'
+const options = {
+  maximumScreenSpaceError: 0,
+  autoReset: false,
+  loaded(layer) {
+    m3d = layer
+    collisionDetection = new CollisionDetectionByRender(viewer, layer._root, {
+      colliderLength: 0.8,
+      colliderWidth: 0.6,
+      colliderHeight: 1,
+      colliderPositionOffset: new Cesium.Cartesian3(0, 0, 0.5),
+      debugShowCollider: true,
+      debugShowDepthMap: true
+    })
+  }
+}
+viewer.scene.layers.appendM3DLayer(url, options)
+const result = collisionDetection.checkCollision(targetPosition, 0)
+const transform = m3d.computedTransform
+const newTransform = new Cesium.Matrix4()
+const invModelMat = new Cesium.Matrix4()
+if (result.result !== 'collided') {
+  const modelMatrix = m3d.tileset.modelMatrix
+  Cesium.Matrix4.inverse(modelMatrix, invModelMat)
+  Cesium.Matrix4.setTranslation(transform, result.computedPosition, newTransform)
+  Cesium.Matrix4.multiply(invModelMat, newTransform, newTransform)
+  m3d.transform = Cesium.Matrix4.clone(newTransform)
+}</code></pre>
+    
+
+        <p class="code-caption"><h7 id='example3'>Entity 模型碰撞检测</h7></p>
+    
+
+    
+    <pre class="prettyprint"><code>// ES5引入方式
+const { CollisionDetectionByRender } = zondy.cesium
+
+// ES6引入方式
+import { CollisionDetectionByRender } from "@mapgis/webclient-cesium-plugin"
+
+const url = '../../SampleData/models/GroundVehicle/GroundVehicle.glb'
+const position = Cesium.Cartesian3.fromDegrees(108.9594, 34.2186, 5)
+const hpr = new Cesium.HeadingPitchRoll(0, 0, 0)
+const orientation = Cesium.Transforms.headingPitchRollQuaternion(position, hpr)
+const entity = viewer.entities.add({
+  name: url,
+  position,
+  orientation,
+  model: {
+    uri: url,
+    minimumPixelSize: 32,
+    maximumScale: 20000
+  }
+})
+const collisionDetectionForEntity = new CollisionDetectionByRender(viewer, entity, {
+  colliderLength: 2,
+  colliderWidth: 0.6,
+  colliderHeight: 0.6,
+  colliderPositionOffset: new Cesium.Cartesian3(0, 0, 0.6)
+})
+const entityResult = collisionDetectionForEntity.checkCollision(positionWC, 0)
+if (entityResult.result !== 'collided') {
+  entity.position = entityResult.computedPosition
+}</code></pre>
+    
+
+        <p class="code-caption"><h7 id='example4'>调试模式</h7></p>
+    
+
+    
+    <pre class="prettyprint"><code>// ES5引入方式
+const { CollisionDetectionByRender } = zondy.cesium
+
+// ES6引入方式
+import { CollisionDetectionByRender } from "@mapgis/webclient-cesium-plugin"
+
+const debugCollisionDetection = new CollisionDetectionByRender(viewer, viewer.camera, {
+  debugShowCollider: false,
+  debugShowDepthMap: true
+})</code></pre>
     
 
     
@@ -955,7 +1122,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
     
         
         <div class="tag-source">
-            engineExtensions/analysis/CollisionDetectionByRender.js, line 1129
+            engineExtensions/analysis/CollisionDetectionByRender.js, line 907
         </div>
         
     </div>
@@ -966,7 +1133,9 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
     
     
     <div class="description">
-        <p>检测目标位置是否会碰撞，需要在场景渲染完成后即postRender事件中做检查。</p>
+        <p>检测目标位置是否会发生碰撞。</p>
+<p>调用时应确保场景已完成一帧渲染，通常适合在 <code>postRender</code> 之后或由内部实时检测流程触发。
+当 <code>heading</code> 为空时，仅执行俯视碰撞检查；传入航向后会同时执行正视方向检查。</p>
     </div>
     
 
@@ -1024,7 +1193,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>目标位置</p></td>
+                <p>待检测的目标位置。</p></td>
         </tr>
 	
 	
@@ -1059,9 +1228,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>碰撞体航向
-<br/><br/>
-置空时只做俯视图的检查。<br/></p></td>
+                <p>碰撞体航向角，单位为弧度。</p></td>
         </tr>
 	
 	
@@ -1097,7 +1264,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>可选参数</p>
+                <p>本次检测的覆写参数，未传入时使用实例属性。</p>
                 
 
 <table class="params">
@@ -1110,8 +1277,6 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
 		<th>Type</th>
 		
 		
-		<th>Default</th>
-		
 		
 		<th class="last">Description</th>
 	</tr>
@@ -1135,10 +1300,6 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
             </td>
             
             
-                <td class="default">
-                
-                </td>
-            
             
             <td class="description last">
                 
@@ -1149,7 +1310,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>碰撞盒长，默认值取实例的同名属性值</p></td>
+                <p>碰撞盒长度。</p></td>
         </tr>
 	
 	
@@ -1169,10 +1330,6 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
             </td>
             
             
-                <td class="default">
-                
-                </td>
-            
             
             <td class="description last">
                 
@@ -1183,7 +1340,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>碰撞盒宽，默认值取实例的同名属性值</p></td>
+                <p>碰撞盒宽度。</p></td>
         </tr>
 	
 	
@@ -1203,10 +1360,6 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
             </td>
             
             
-                <td class="default">
-                
-                </td>
-            
             
             <td class="description last">
                 
@@ -1217,7 +1370,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>碰撞盒高，默认值取实例的同名属性值</p></td>
+                <p>碰撞盒高度。</p></td>
         </tr>
 	
 	
@@ -1237,11 +1390,35 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
             </td>
             
             
-                <td class="default">
+            
+            <td class="description last">
                 
-                    (0,0,0)
+                    
+                        <span class="optional"> 可选</span>
+                    
+                    
+                        
+                    
                 
-                </td>
+                <p>碰撞盒位置偏移。</p></td>
+        </tr>
+	
+	
+	
+        <tr>
+            
+                <td class="name"><code>colliderThickness</code></td>
+            
+            
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+            
+            </td>
+            
             
             
             <td class="description last">
@@ -1253,7 +1430,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>碰撞盒的位置偏移，默认值取实例的同名属性值</p></td>
+                <p>碰撞盒边框检测厚度。</p></td>
         </tr>
 	
 	
@@ -1273,10 +1450,6 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
             </td>
             
             
-                <td class="default">
-                
-                </td>
-            
             
             <td class="description last">
                 
@@ -1287,7 +1460,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>最大可通过高度，默认值取实例的同名属性值</p></td>
+                <p>最大可抬升通过高度。</p></td>
         </tr>
 	
 	
@@ -1307,12 +1480,6 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
             </td>
             
             
-                <td class="default">
-                
-                    false
-                
-                </td>
-            
             
             <td class="description last">
                 
@@ -1323,7 +1490,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
                 
-                <p>是否开启高精度碰撞检测，默认值取实例的同名属性值</p></td>
+                <p>是否开启高精度模式。</p></td>
         </tr>
 	
 	
@@ -1394,21 +1561,11 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
                         
                     
             </td>
-            <td class="description last">碰撞检测结果数据结构说明：
- <table>
-  <tr>
-    <td>result</td>         <td>computedPosition</td>  <td></td>
-  </tr>
-  <tr>
-    <td>'collided'</td>     <td>targetPosition</td>    <td>发生了碰撞，返回传入的位置。</td>
-  </tr>
-  <tr>
-    <td>'noCollision'</td>  <td>targetPosition</td>    <td>没有发生碰撞，返回传入的位置。</td>
-  </tr>
-  <tr>
-    <td>'passable'</td>     <td>碰撞后抬高的位置</td>   <td>发生了碰撞但可以通过，计算新的位置。</td>
-  </tr>
-</table></td>
+            <td class="description last">碰撞检测结果对象。
+返回值说明：
+<code>result === 'collided'</code> 时表示发生碰撞，<code>computedPosition</code> 返回传入的 <code>targetPosition</code>。
+<code>result === 'noCollision'</code> 时表示未碰撞，<code>computedPosition</code> 返回传入的 <code>targetPosition</code>。
+<code>result === 'passable'</code> 时表示发生碰撞但可抬升通过，<code>computedPosition</code> 返回抬升后的建议位置。</td>
         </tr>
     
     </tbody>
@@ -1430,7 +1587,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
     
         
         <div class="tag-source">
-            engineExtensions/analysis/CollisionDetectionByRender.js, line 672
+            engineExtensions/analysis/CollisionDetectionByRender.js, line 574
         </div>
         
     </div>
@@ -1441,7 +1598,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
     
     
     <div class="description">
-        <p>销毁碰撞检测</p>
+        <p>销毁碰撞检测实例并释放内部帧缓冲与深度资源。</p>
     </div>
     
 
@@ -1504,7 +1661,7 @@ debug模式生成的碰撞盒所使用的位置是上一帧的碰撞检测结果
 
 
         <footer>
-            Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> on Wed Feb 04 2026 18:31:34 GMT+0800 (中国标准时间)
+            Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> on Sat Sep 12 2026 11:55:59 GMT+0800 (中国标准时间)
         </footer>
     </div>
 </div>