@mapgis/webclient-cesium-plugin 17.8.1 → 17.10.10

package/{documention → documentation}/TerrainExcavateTool.html

@@ -90,7 +90,7 @@
     
         
         <div class="tag-source">
-            engineExtensions/tools/TerrainExcavateTool.js, line 31
+            engineExtensions/tools/TerrainExcavateTool.js, line 32
         </div>
         
     </div>
@@ -605,6 +605,54 @@ terrainPlan.updateData(positions);</code></pre>
     
     
     
+    
+</dl>
+
+    
+    
+</dd>
+
+        
+            
+<dt>
+    <div class="nameContainer">
+        <h4 class="name" id="enableExtraction">enableExtraction<span class="type-signature type boolean">Boolean</span> </h4>
+    </div>
+    
+    
+</dt>
+<dd>
+    
+    <div class="description">
+        <p>是否启用地形开挖抽出功能</p>
+    </div>
+    
+    
+    
+<dl class="details">
+    
+        
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    <dt class="tag-default">Default Value:</dt>
+    false</li></ul></dd>
+    
+    
+    
+    
+    
+    
     
 </dl>
 
@@ -693,6 +741,54 @@ terrainPlan.updateData(positions);</code></pre>
     
     
     
+    <dt class="tag-default">Default Value:</dt>
+    0</li></ul></dd>
+    
+    
+    
+    
+    
+    
+    
+</dl>
+
+    
+    
+</dd>
+
+        
+            
+<dt>
+    <div class="nameContainer">
+        <h4 class="name" id="extractHeight">extractHeight<span class="type-signature type number">Number</span> </h4>
+    </div>
+    
+    
+</dt>
+<dd>
+    
+    <div class="description">
+        <p>地形开挖抽出高度</p>
+    </div>
+    
+    
+    
+<dl class="details">
+    
+        
+    
+    
+    
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
     <dt class="tag-default">Default Value:</dt>
     0</li></ul></dd>
     
@@ -967,7 +1063,7 @@ terrainPlan.updateData(positions);</code></pre>
     
         
         <div class="tag-source">
-            engineExtensions/tools/TerrainExcavateTool.js, line 77
+            engineExtensions/tools/TerrainExcavateTool.js, line 76
         </div>
         
     </div>
@@ -1109,7 +1205,7 @@ terrainPlan.updateData(positions);</code></pre>
 
 
         <footer>
-            Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> on Fri Feb 06 2026 14:59:55 GMT+0800 (中国标准时间)
+            Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> on Fri Sep 18 2026 14:59:31 GMT+0800 (中国标准时间)
         </footer>
     </div>
 </div>

package/{documention → documentation}/TerrainProfile.html

@@ -71,8 +71,6 @@
     
     </h2>
     
-        <div class="class-description"><p>TerrainProfile</p></div>
-    
 </header>  
 
 <article>
@@ -85,12 +83,12 @@
     <div class="nameContainer">
         <h4 class="name" id="TerrainProfile">
             
-            new TerrainProfile<span class="signature">(viewer, <span class="optional">options</span>)</span>
+            new TerrainProfile<span class="signature">(viewer, options)</span>
         </h4>
     
         
         <div class="tag-source">
-            engineExtensions/analysis/TerrainProfile.js, line 46
+            engineExtensions/analysis/TerrainProfile.js, line 10
         </div>
         
     </div>
@@ -100,6 +98,14 @@
 <dd>
     
     
+    <div class="description">
+        <p>三维地形剖面分析工具。</p>
+<p><code>TerrainProfile</code> 用于沿一条折线对地形或场景进行高程采样，并将采样结果以场景剖切面、
+贴地线和 echart 剖面图的形式展示出来。适用于地形高程趋势查看、线路断面分析以及模型与地形的联合剖面展示等场景。</p>
+<p>当未传入 <code>options.positions</code> 时，实例会通过内部绘制工具交互式获取剖面线；当传入 <code>options.positions</code> 时，
+调用 <code>profile</code> 后会直接使用给定坐标点集开始分析。若 <code>resultShowType</code> 为 <code>1</code> 或 <code>2</code>，则需要提前传入可用的 <code>options.echart</code> 图表对象。</p>
+    </div>
+    
 
     
     
@@ -134,7 +140,7 @@
             <td class="type">
             
                 
-<span class="param-type">Viewer</span>
+<span class="param-type"><a href="Cesium.Viewer.html">Cesium.Viewer</a></span>
 
 
             
@@ -144,12 +150,8 @@
             
             <td class="description last">
                 
-                    
-                    
-                        
-                    
-                
-                <p>场景视图对象</p></td>
+                <p>Cesium 三维场景视图对象。通常可通过 <code>new Cesium.Viewer(...)</code> 创建获得，
+也可在 <code>SceneView</code>的'底层引擎视图对象创建完毕事件（innerView-created）'回调的event.innerView参数中获取。</p></td>
         </tr>
 	
 	
@@ -172,14 +174,7 @@
             
             <td class="description last">
                 
-                    
-                        <span class="optional"> 可选</span>
-                    
-                    
-                        
-                    
-                
-                <p>包含以下属性的对象</p>
+                <p>初始化参数对象。可传入空对象 <code>{}</code> 以使用默认配置。</p>
                 
 
 <table class="params">
@@ -231,7 +226,7 @@
                         
                     
                 
-                <p>echart图表对象，如果resultShowType设置为1和2，则这个值必须传入</p></td>
+                <p>echart 图表对象。当 <code>resultShowType</code> 为 <code>1</code> 或 <code>2</code> 时必须传入，用于展示剖面图并驱动图表与场景联动。</p></td>
         </tr>
 	
 	
@@ -267,7 +262,7 @@
                         
                     
                 
-                <p>垂直面颜色</p></td>
+                <p>剖切垂直面的颜色，仅在启用垂直面显示时生效。</p></td>
         </tr>
 	
 	
@@ -289,7 +284,7 @@
             
                 <td class="default">
                 
-                    50
+                    500
                 
                 </td>
             
@@ -303,7 +298,7 @@
                         
                     
                 
-                <p>垂直面高度，相较于最大地形高程</p></td>
+                <p>剖切垂直面的附加高度，单位与场景高程一致，内部会在采样点高程基础上向上抬升该值。</p></td>
         </tr>
 	
 	
@@ -339,7 +334,7 @@
                         
                     
                 
-                <p>垂直线颜色</p></td>
+                <p>图表联动时场景中垂直指示线的颜色。</p></td>
         </tr>
 	
 	
@@ -375,7 +370,7 @@
                         
                     
                 
-                <p>贴地线颜色</p></td>
+                <p>场景中贴地剖面线的颜色。</p></td>
         </tr>
 	
 	
@@ -411,7 +406,7 @@
                         
                     
                 
-                <p>贴地点颜色</p></td>
+                <p>图表联动时场景中指示点的颜色。</p></td>
         </tr>
 	
 	
@@ -447,7 +442,7 @@
                         
                     
                 
-                <p>采样精度</p></td>
+                <p>插值采样精度。值越小，沿剖面线插入的采样点通常越密，分析耗时也可能更高。</p></td>
         </tr>
 	
 	
@@ -483,7 +478,7 @@
                         
                     
                 
-                <p>是否显示垂直面</p></td>
+                <p>是否在场景中显示剖切垂直面。</p></td>
         </tr>
 	
 	
@@ -519,7 +514,7 @@
                         
                     
                 
-                <p>分析类型.0代表地形,1代表地形和模型兼容</p></td>
+                <p>剖面分析类型。<code>0</code> 表示仅分析地形；<code>1</code> 表示对地形和模型场景进行兼容采样。</p></td>
         </tr>
 	
 	
@@ -555,7 +550,7 @@
                         
                     
                 
-                <p>地形采样级别.0代表采最精细级别,1-20为自定义采样级别，数值越大，越精细</p></td>
+                <p>地形采样级别。<code>0</code> 表示尽可能使用最精细级别；<code>1-20</code> 为自定义采样级别，数值越大通常越精细。</p></td>
         </tr>
 	
 	
@@ -591,7 +586,7 @@
                         
                     
                 
-                <p>是否对场景进行最精细的高程采样，默认为false，仅对当前场景深度进行采样，当值为true时，要求采样区域的模型缓存的叶子结点的数据不能全为空</p></td>
+                <p>在 <code>profileType</code> 为场景采样时，是否对场景执行最精细高程采样。设为 <code>true</code> 时要求采样区域对应模型缓存叶子节点数据可用。</p></td>
         </tr>
 	
 	
@@ -627,7 +622,7 @@
                         
                     
                 
-                <p>结果展示形式.0代表仅场景中展示结果(直接在地形上绘制结果),1表示仅echart图表中展示结果,2表示场景和图表都展示结果</p></td>
+                <p>结果展示方式。<code>0</code> 表示仅在场景中绘制结果；<code>1</code> 表示仅在 echart 图表中展示结果；<code>2</code> 表示同时在场景和图表中展示结果。</p></td>
         </tr>
 	
 	
@@ -640,7 +635,7 @@
             <td class="type">
             
                 
-<span class="param-type">Array</span>
+<span class="param-type">Array.&lt;Cesium.Cartesian3></span>
 
 
             
@@ -661,7 +656,7 @@
                         
                     
                 
-                <p>可选,Cartesian3数组，需要分析的坐标点集,数组内至少要有两个点.如果未传入positions,则接口内部调用绘制的接口,进行绘制获取点集</p></td>
+                <p>预设的剖面折线坐标数组，至少需要两个点。未传入时，<code>profile</code> 会启动交互绘制以获取坐标点集。</p></td>
         </tr>
 	
 	
@@ -697,7 +692,7 @@
                         
                     
                 
-                <p>可选,分析过程超时时间设置，超时后会调用分析失败函数，默认值为60，单位秒</p></td>
+                <p>单次分析超时时间，单位为秒。超时后会调用 <code>profile</code> 传入的失败回调，并屏蔽后续异步分析结果处理。</p></td>
         </tr>
 	
 	
@@ -750,21 +745,28 @@
     
         <h5>Example</h5>
         
+        <p class="code-caption">交互式地形剖面分析</p>
+    
 
     
-    <pre class="prettyprint"><code>// ES5引入方式
+    <pre class="prettyprint"><code>// ES5 引入方式
 const { TerrainProfile } = zondy.cesium
-// ES6引入方式
+
+// ES6 引入方式
 import { TerrainProfile } from "@mapgis/webclient-cesium-plugin"
 
 const webGlobe = new Cesium.WebSceneControl('cesiumContainer', {});
 const viewer = webGlobe.viewer;
-const terrainProfile
-if(!Cesium.defined(terrainProfile)){
-  terrainProfile = new TerrainProfile(viewer,{polygonColor:Cesium.Color.RED.withAlpha(0.5),polygonHeight:0,polyLineColor:Cesium.Color.BLUE.withAlpha(1)});
+let terrainProfile
+if (!Cesium.defined(terrainProfile)) {
+  terrainProfile = new TerrainProfile(viewer, {
+    polygonColor: Cesium.Color.RED.withAlpha(0.5),
+    polygonHeight: 0,
+    polyLineColor: Cesium.Color.BLUE.withAlpha(1),
+    resultShowType: 0
+  })
 }
-  terrainProfile.profile();
-}</code></pre>
+terrainProfile.profile()</code></pre>
     
 
     
@@ -796,12 +798,12 @@ if(!Cesium.defined(terrainProfile)){
     <div class="nameContainer">
         <h4 class="name" id="destroy">
             
-            destroy<span class="signature">()</span>
+            destroy<span class="signature">()</span><span class="glyphicon glyphicon-circle-arrow-right"></span><span class="type-signature returnType">{void}</span>
         </h4>
     
         
         <div class="tag-source">
-            engineExtensions/analysis/TerrainProfile.js, line 750
+            engineExtensions/analysis/TerrainProfile.js, line 724
         </div>
         
     </div>
@@ -812,7 +814,10 @@ if(!Cesium.defined(terrainProfile)){
     
     
     <div class="description">
-        <p>结束剖面分析，清除场景对象</p>
+        <p>销毁剖面分析实例并清理关联资源。</p>
+<p>该方法会销毁绘制句柄、提示框并移除场景中的贴地线；若当前实例配置了 echart，
+还会同步注销图表联动事件、隐藏图表容器，并清理图表联动指示线及相关分析实体。调用后当前实例会被标记为已销毁，
+后续异步采样返回时也不会再继续执行结果绘制逻辑。</p>
     </div>
     
 
@@ -857,6 +862,35 @@ if(!Cesium.defined(terrainProfile)){
     
     
     
+    <h5>Returns:</h5>
+    
+
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Type</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    
+        <tr>
+            
+            <td class="type">
+            
+                        void
+                        
+                    
+            </td>
+            <td class="description last"></td>
+        </tr>
+    
+    </tbody>
+</table>
+
+    
     
     
 </dd>
@@ -867,12 +901,12 @@ if(!Cesium.defined(terrainProfile)){
     <div class="nameContainer">
         <h4 class="name" id="profile">
             
-            profile<span class="signature">(start, success, fail)</span>
+            profile<span class="signature">(<span class="optional">start</span>, <span class="optional">success</span>, <span class="optional">fail</span>)</span><span class="glyphicon glyphicon-circle-arrow-right"></span><span class="type-signature returnType">{void}</span>
         </h4>
     
         
         <div class="tag-source">
-            engineExtensions/analysis/TerrainProfile.js, line 284
+            engineExtensions/analysis/TerrainProfile.js, line 270
         </div>
         
     </div>
@@ -883,7 +917,10 @@ if(!Cesium.defined(terrainProfile)){
     
     
     <div class="description">
-        <p>开启地形剖切功能接口，左键画线，右键停止</p>
+        <p>启动一次剖面分析。</p>
+<p>当初始化时未传入 <code>options.positions</code> 或点数不足两个时，该方法会先启动交互绘制以获取剖面线；
+否则会直接对预设坐标点集执行插值和高程采样。分析完成后可按配置在场景中绘制贴地线、垂直面，
+并在 echart 中展示剖面曲线；当采样超过 <code>options.timeout</code> 指定时长时，会触发失败回调。</p>
     </div>
     
 
@@ -930,7 +967,14 @@ if(!Cesium.defined(terrainProfile)){
             
             <td class="description last">
                 
-                <p>开始分析的回调函数</p></td>
+                    
+                        <span class="optional"> 可选</span>
+                    
+                    
+                        
+                    
+                
+                <p>开始分析前的回调函数。通常可用于更新界面状态或提示用户当前正在进行采样。</p></td>
         </tr>
 	
 	
@@ -953,7 +997,14 @@ if(!Cesium.defined(terrainProfile)){
             
             <td class="description last">
                 
-                <p>分析成功的回调函数</p></td>
+                    
+                        <span class="optional"> 可选</span>
+                    
+                    
+                        
+                    
+                
+                <p>分析成功后的回调函数。在采样完成且结果绘制结束后触发。</p></td>
         </tr>
 	
 	
@@ -976,7 +1027,14 @@ if(!Cesium.defined(terrainProfile)){
             
             <td class="description last">
                 
-                <p>分析失败的回调函数，分析超时后会调用</p></td>
+                    
+                        <span class="optional"> 可选</span>
+                    
+                    
+                        
+                    
+                
+                <p>分析失败回调函数。当前主要在分析超时时触发，建议在启用超时控制时始终传入。</p></td>
         </tr>
 	
 	
@@ -1019,7 +1077,61 @@ if(!Cesium.defined(terrainProfile)){
     
     
     
+    <h5>Returns:</h5>
+    
+
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Type</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    
+        <tr>
+            
+            <td class="type">
+            
+                        void
+                        
+                    
+            </td>
+            <td class="description last"></td>
+        </tr>
+    
+    </tbody>
+</table>
+
+    
+    
+    
+        <h5>Example</h5>
+        
+        <p class="code-caption">直接传入坐标点执行剖面分析</p>
+    
+
+    
+    <pre class="prettyprint"><code>const terrainProfile = new TerrainProfile(viewer, {
+  positions,
+  resultShowType: 0
+})
+
+terrainProfile.profile(
+  () => {
+    console.log('开始分析')
+  },
+  () => {
+    console.log('分析完成')
+  },
+  () => {
+    console.warn('分析超时')
+  }
+)</code></pre>
     
+
     
 </dd>
 
@@ -1029,12 +1141,12 @@ if(!Cesium.defined(terrainProfile)){
     <div class="nameContainer">
         <h4 class="name" id="stopDrawing">
             
-            stopDrawing<span class="signature">()</span>
+            stopDrawing<span class="signature">()</span><span class="glyphicon glyphicon-circle-arrow-right"></span><span class="type-signature returnType">{void}</span>
         </h4>
     
         
         <div class="tag-source">
-            engineExtensions/analysis/TerrainProfile.js, line 265
+            engineExtensions/analysis/TerrainProfile.js, line 248
         </div>
         
     </div>
@@ -1045,8 +1157,9 @@ if(!Cesium.defined(terrainProfile)){
     
     
     <div class="description">
-        <p>停止绘制
-解决绘制一半后需要停止绘制问题</p>
+        <p>停止当前剖面线绘制交互。</p>
+<p>当 <code>profile</code> 处于交互绘制阶段且尚未完成采样时，可调用该方法主动中断绘制流程。
+该方法只会清理当前绘制事件和提示框，不会销毁已经创建的分析实例，也不会清除已完成的剖面结果。</p>
     </div>
     
 
@@ -1091,6 +1204,35 @@ if(!Cesium.defined(terrainProfile)){
     
     
     
+    <h5>Returns:</h5>
+    
+
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Type</th>
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+    <tbody>
+    
+        <tr>
+            
+            <td class="type">
+            
+                        void
+                        
+                    
+            </td>
+            <td class="description last"></td>
+        </tr>
+    
+    </tbody>
+</table>
+
+    
     
     
 </dd>
@@ -1109,7 +1251,7 @@ if(!Cesium.defined(terrainProfile)){
 
 
         <footer>
-            Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> on Fri Feb 06 2026 14:59:55 GMT+0800 (中国标准时间)
+            Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> on Fri Sep 18 2026 14:59:31 GMT+0800 (中国标准时间)
         </footer>
     </div>
 </div>