@anov/gis-skills-cli 0.0.0-stage → 0.3.3

package/skills/anovgis-analysis/SKILL.md

@@ -0,0 +1,585 @@
+---
+name: anovgis-analysis
+description: '@anov/gis 分析与标绘模块。涵盖 Draw*（DrawPoint/DrawPolyLine/DrawPolygon/DrawRectangle/DrawCircle，统一 justDraw 区分测量/标绘）、TerrainClipping 地形开挖与剖切、CesiumWaterAnalysis 水淹分析、CesiumHeatMap + HeatMapLayer 两套热力图、WindLayer 风场粒子、DamWaterRelease 水坝开闸放水、PositonEditor 三轴平移旋转缩放编辑控件（v1.8.6 增强）、Geocoder 地名搜索。触发关键词：标绘、测量、draw、measure、DrawPolyLine、DrawPolygon、地形剖切、TerrainClipping、热力图、HeatMap、风场、WindLayer、水淹、WaterAnalysis、水坝、DamWaterRelease、编辑控件、PositonEditor、positonEditor、damWaterRelease、wfs、WFS、iServerWfs、geocoder、地理编码。Use when 标绘图形 / 测距测面积 / 地形开挖 / 剖切 / 热力图 / 风场粒子 / 水淹分析 / 三轴编辑控件、地名搜索。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# 05 — 分析与标绘速查
+
+> ⚠️ **优先级**：本 skill 优先于 SDK 源码 / `node_modules/@anov/gis/`。
+> 遇到 API 行为疑问先查本 skill 与 `anovgis-pitfalls`。**严禁**主动 Glob/Grep `node_modules/@anov/gis/src/...` / `dist/...`；除非用户明确要求并承担风险。
+> 调试流程见 `using-anovgis` § 默认调试流程（Chrome DevTools 仅第 5 级兜底）。
+>
+> **Cesium 入口（铁律）**：`const Cesium = window.Cesium`。`@anov/gis` 启动时已把 Cesium 挂到 `window`，**不存在** `ANOVGIS.Cesium` 写法；本 skill 所有 `Cesium.*` 均从此变量取。底层 Cesium API 细节查 `cesiumjs-skills` 对应 skill（API 名通用，`import` 写法换成 `const Cesium = window.Cesium`）。
+
+> SDK 路径：`src/analysis/`，通过 `src/ANOVGIS.js` 的 `export * from './analysis'` 全部挂到 `ANOVGIS` 顶层命名空间（仅作语义锚点）。锁定 `@anov/gis` **v1.8.6**（Cesium **1.143.0**）；v1.8.6 新增 `TilesetEditor`（~1034 行）/ `PositonEditor` 增强（~1029 行）。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 `PositonEditor` 用于编辑 `Tileset` 模型的位姿 → [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md)（`TilesetEditor` 完整用法）
+- ❌ 不要写 WFS / iServer WFS 完整用法 → v0.3.0 `anovgis-offline-deployment`
+- ❌ 不要写 Cesium 原生 `ClippingPlanesCollection`（地形剖切底层） → 见 Cesium 文档
+- ❌ 不要写 Draw* 之外的几何交互（如拾取编辑 Entity 顶点） → Cesium 文档
+- ❌ 不要写 Imagery / Terrain → [`anovgis-imagery-terrain`](../anovgis-imagery-terrain/SKILL.md)
+- ❌ 不要写特效 → [`anovgis-effects`](../anovgis-effects/SKILL.md)
+> **命名警告**：本模块没有 `DrawController` / `DrawType` / `MeasureTool` / `ClippingPlanesEditor` / `TerrainProfile` / `CoordEditor` 这些类。测量与标绘是**同一套 Draw* 类**（`options.justDraw` 区分：`false` 显示长度/面积标签即测量，`true` 仅画图形）。写代码前先核对下表类名。
+
+## 1. 速查表
+
+<a id="draw"></a>
+### 1.1 标绘 / 测量 `src/analysis/draw/`
+
+| 类名 | 图形 | 说明 |
+|---|---|---|
+| `DrawBase` | — | 基类，提供 `startDraw()` / `end()` / `clear()` / `clearAll()` |
+| `DrawPoint` | 点 | 标签显示经纬度高程 |
+| `DrawPolyLine` | 折线 | `justDraw:false` 时显示分段长度 + 总长（即距离测量） |
+| `DrawPolygon` | 多边形 | `justDraw:false` 时显示面积（即面积测量） |
+| `DrawRectangle` | 矩形 | 两点拉框 |
+| `DrawCircle` | 圆 | 圆心 + 半径，显示面积 |
+| `NoDepthTestPolylineCollection` | — | 内部用，无深度测试线集合（穿透地形显示） |
+
+构造签名统一为 `new ANOVGIS.DrawXxx(viewer, options)`，`viewer` 可传 ANOVGIS Viewer 或原生（内部 `viewer.nativeObjCesium || viewer`）。
+
+### 1.2 其余分析类
+
+| 类名 | 子目录 | 用途 |
+|---|---|---|
+| `TerrainClipping` | `clipping/` | 地形开挖 / 剖切（底面 + 侧墙贴图） |
+| `CesiumWaterAnalysis` | `waterAnalysis/` | 水淹分析（多边形按水位升高拉伸） |
+| `CesiumHeatMap` | `heatmap/` | 热力图（Canvas 引擎 + Entity 贴图，静态工厂 `create`） |
+| `HeatMapLayer` | `heatmap/` | 热力图（WebGL 引擎，继承 `Layer`，走 `viewer.addLayer`） |
+| `WindLayer` | `wind/` | 风场粒子（继承 `Layer`） |
+| `DamWaterRelease` | `damWaterRelease/` | 水坝开闸放水粒子仿真（多闸门） |
+| `PositonEditor` | `transformHelper/` | 模型 / 点位平移旋转缩放编辑控件（三轴 gizmo） |
+
+`Clipping`（基类）与 `ClippingDirection`（方向枚举）**未从 index 导出**，只能通过 `TerrainClipping` 继承链间接使用。
+
+## 2. 关键 API
+
+### 2.1 Draw* 公共 options（`DrawBase.js:10-24`）
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `justDraw` | `false` | `true` = 纯标绘不显示量算标签 |
+| `showToolTip` | `true` | 鼠标跟随提示 |
+| `clampToGround` | `false` | 贴地 |
+| `pointColor` / `pointSize` | `RED` / `6` | 节点样式 |
+| `outlineColor` / `outlineWidth` | `CHARTREUSE` / `3` | 轮廓 |
+| `lineColor` / `lineWidth` | `CHARTREUSE` / `3` | 线样式 |
+| `tempPoint_size` / `tempPoint_color` / `tempPoint_show` / `tempPoint_showLabel` | `10` / `YELLOW` / `true` / `false` | 浮动跟随点 |
+| `billboard` | `undefined` | 节点图标 |
+| `onCompleted(positions)` | — | 完成回调，返回 `Cartesian3[]` |
+
+方法：`startDraw()` 开始（内部先 `end()` 复位）、`end()` 结束交互、`clear()` 清除本类实体、`clearAll()` 清全部 + 结束。
+
+<a id="terrain-clipping"></a>
+### 2.2 TerrainClipping
+
+`new TerrainClipping(viewer, { lerpInterval=50, bottomImage='', sideImage='' })`
+
+属性（均为 setter）：`positions`（`Cartesian3[]` 或经纬度数组，赋值即重建裁剪面）、`direction`（单向裁剪，用 `'up'|'down'|'left'|'right'|'front'|'back'`）、`distance`、`angle`、`enable`、`height`（开挖深度，默认 5）。`positions` 与 `direction` 互斥，后设者生效。
+
+<a id="water-analysis"></a>
+### 2.3 CesiumWaterAnalysis
+
+`new CesiumWaterAnalysis(viewer, { minHeight=0, maxHeight=2000, speed=10, intervalStep=500 })`
+
+`start(cartesians, cb)` 定时抬升水位并回调当前高程 / `pause()` / `stop()`（移除多边形）/ `resetParas({minHeight,maxHeight,setpHeight})` / `show`。注意 `resetParas` 读的是 `setpHeight` 而非 `speed`（`CesiumWaterAnalysis.js:137`）。
+
+<a id="heatmap"></a>
+### 2.4 热力图两套引擎
+
+- `CesiumHeatMap.create(viewer, bounds, options)` → 实例；`setWGS84Data(min, max, [{x,y,value}])`、`setData(min,max,data)`、`show(bool)`。`bounds = {west,south,east,north}` 需自行按数据算。options 走 heatmap.js：`radius`、`maxOpacity`、`minOpacity`、`blur`、`backgroundColor`。
+- `new HeatMapLayer({ radius=30, height=0, gradient, useGround=false, classificationType=2 })` → `viewer.addLayer(layer)` 后 `setPoints(points)` / `clear()`。`useGround:true` 走 `GroundPrimitive` 贴地。
+
+<a id="wind"></a>
+### 2.5 WindLayer
+
+`new WindLayer({ globalAlpha=0.9, lineWidth=1, colorScale='#fff', velocityScale=1/25, maxAge=90, paths=800, frameRate=20, useCoordsDraw=true, gpet=true })`，`setData(data, options)` / `setOptions(options)` / `show`。数据是标准 grib-json（u/v 两个 component 的 `{header, data}` 数组）。
+
+<a id="dam-water"></a>
+### 2.6 DamWaterRelease
+
+`new DamWaterRelease(viewer, options)`，options 见 `DamWaterRelease.js:18-37`（`damCenter`、`gateCount=13`、`gatePositions`、`gateHeight`、`gateSpacing`、`sprayHeading/sprayPitch`、`emitterType`、`coneAngle`、`flowPreset`）。方法：`addToScene()`、`openGate(i)` / `closeGate(i)` / `setGateOpen(i,open)` / `openAllGates()` / `closeAllGates()`、`setFlowLevel('light'|'medium'|'heavy'|'flood')`、`updateSprayDirection(h,p)`、`updateEmitterShape()`、`updateAppearance()`、`removeFromScene()`、`destroy()`。枚举 `DamWaterRelease.EmitterType` / `FLOW_PRESETS`。
+
+<a id="positon-editor"></a>
+### 2.7 PositonEditor
+
+`new PositonEditor({ translateEnabled=true, rotateEnabled=false, scaleEnabled=false, xAxisLength, ..., rotatePlaneRadius, sizeInPixel=false, originOffset })`，然后 `addTo(viewer)` + `bind(model)` 或 `bindPosition(position)`。事件：`preTranformEvent` / `postTransformEvent` / `postRoatationEvent` / `postScaleEvent`。旋转与缩放仅对模型有效。
+
+## 3. Snippet
+
+### 3.1 标绘 Polyline（`examples/public/examples/html/analysis/draw.html:157-163, 230-231`）
+
+```js
+// justDraw:true = 纯标绘，不显示长度标签
+const drawLine = new ANOVGIS.DrawPolyLine(viewer, {
+  lineColor: Cesium.Color.YELLOW,
+  justDraw: true,
+  onCompleted(positions) {
+    console.log(positions); // Cartesian3[]
+  }
+});
+drawLine.startDraw();       // 左键加点，右键/双击结束
+// drawLine.end();          // 中断交互
+// drawLine.clear();        // 清除已绘图形
+```
+
+### 3.2 距离测量（`examples/public/examples/html/analysis/measure.html:111-115, 167-168`）
+
+```js
+// 同一个类，justDraw 缺省(false) 即自动显示分段长度 + 总长
+const measureLine = new ANOVGIS.DrawPolyLine(viewer, {
+  lineColor: Cesium.Color.YELLOW,
+  onCompleted(positions) { console.log(positions); }
+});
+measureLine.startDraw();
+
+// 面积测量同理，换成 DrawPolygon
+const measureArea = new ANOVGIS.DrawPolygon(viewer, {
+  onCompleted(positions) { console.log(positions); }
+});
+```
+
+### 3.3 地形剖切 / 开挖（`examples/public/examples/html/analysis/terraincliping.html:108-142`）
+
+```js
+const clipping = new ANOVGIS.TerrainClipping(viewer, {
+  lerpInterval: 200,
+  bottomImage: './images/excavate_bottom.jpeg',
+  sideImage: './images/excavate_side.png'
+});
+clipping.enable = true;
+clipping.height = 100;        // 开挖深度（米）
+
+// 用标绘取范围，回调里直接赋 positions 即完成裁剪
+new ANOVGIS.DrawPolygon(viewer, {
+  justDraw: true, clampToGround: true, fill: false,
+  onCompleted(positions) { clipping.positions = positions; }
+}).startDraw();
+
+// clipping.positions = [];   // 还原地形
+// clipping.direction = 'up'; // 单向裁剪（与 positions 互斥）
+```
+
+### 3.4 热力图（`examples/public/examples/html/analysis/cesiumHeatMap.html:76-97`）
+
+```js
+// GeoJSON / 数组 → 先算 bounds，再建热力图
+const bounds = features.reduce((b, f) => ({
+  west:  Math.min(b.west,  f.X), south: Math.min(b.south, f.Y),
+  east:  Math.max(b.east,  f.X), north: Math.max(b.north, f.Y)
+}), { west: 180, south: 90, east: -180, north: -90 });
+
+const heatMap = ANOVGIS.CesiumHeatMap.create(viewer, bounds, {
+  backgroundColor: 'rgba(0,0,0,0)',
+  radius: 50, maxOpacity: 0.5, minOpacity: 0, blur: 0.7
+});
+// min / max 为值域，data 为 [{x, y, value}]
+heatMap.setWGS84Data(0, 100, features.map(f => ({ x: +f.X, y: +f.Y, value: f.value })));
+// heatMap.show(false);
+
+// WebGL 引擎版本（贴地、走图层体系）
+const heatLayer = new ANOVGIS.HeatMapLayer({ radius: 30, useGround: true });
+viewer.addLayer(heatLayer);
+heatLayer.setPoints([{ x: 119.29, y: 32.24, value: 39 }]);
+```
+
+### 3.5 风场（`examples/public/examples/html/analysis/windlayer.html:65-109`，参数调节 `windlayer2.html:86-136`）
+
+```js
+// data 为 grib-json：u/v 两个 component 的 [{header, data}]
+const data = await fetch('./json/beijing_wind.json').then(r => r.json());
+
+const windLayer = new ANOVGIS.WindLayer({
+  colorScale: ['rgb(255,255,255)'],
+  frameRate: 16,
+  maxAge: 60,           // 粒子存活时间
+  globalAlpha: 0.9,     // 拖尾透明度
+  velocityScale: 1 / 30,// 移动速度
+  paths: 2000           // 粒子数
+});
+windLayer.setData(data);
+viewer.addLayer(windLayer);
+
+windLayer.setOptions({ paths: 3000, lineWidth: 2 }); // 运行时改参数
+windLayer.show = false;
+```
+
+### 3.6 水淹分析（`examples/public/examples/html/analysis/waterAanalysis.html:293-351`，`noAuto` 见 `:244`）
+
+```js
+const water = new ANOVGIS.CesiumWaterAnalysis(viewer, {
+  minHeight: 990,     // 起始水位
+  maxHeight: 1440,    // 终止水位
+  speed: 10,          // 每步抬升高度
+  intervalStep: 300   // 定时器间隔 ms
+});
+
+// 绘范围（贴地、不填充），拿到 Cartesian3[]
+let positions;
+new ANOVGIS.DrawPolygon(viewer, {
+  justDraw: true, fill: false, clampToGround: true,
+  onCompleted(ps) { positions = ps; }
+}).startDraw();
+
+water.start(positions, h => console.log('当前水位', h));
+// water.pause();
+// water.stop();
+// 注意 resetParas 的速度字段叫 setpHeight，不是 speed
+water.resetParas({ minHeight: 990, maxHeight: 1440, setpHeight: 5 });
+// 固定水位（不动画）：water.noAuto(positions, 1200);
+```
+
+## 各 Draw / 分析工具实战补充
+
+### 3.7 单点标绘（`examples/public/examples/html/analysis/draw.html:146-156, 224-228`）
+
+```js
+// 来源: draw.html L146-156
+// DrawPoint 显示经纬度高程标签；justDraw:false 仍带提示，区别于其他类
+const pointTool = new ANOVGIS.DrawPoint(viewer, {
+  justDraw: false,
+  pointSize: 12,
+  pointColor: Cesium.Color.YELLOW,
+  tempPoint_show: true,         // 浮动跟随点
+  tempPoint_color: Cesium.Color.YELLOW,
+  showToolTip: false,
+  onCompleted(positions) {
+    // positions 是长度为 1 的 Cartesian3[]
+    const c = positions[0];
+    const carto = Cesium.Cartographic.fromCartesian(c);
+    console.log(Cesium.Math.toDegrees(carto.longitude),
+                Cesium.Math.toDegrees(carto.latitude),
+                carto.height);
+  }
+});
+pointTool.startDraw();          // 单击落点，自动结束
+// pointTool.end();             // 中断
+// pointTool.clear();           // 清除已绘点
+```
+
+### 3.8 矩形标绘（`examples/public/examples/html/analysis/draw.html:172-177, 244-248`）
+
+```js
+// 来源: draw.html L172-177
+// DrawRectangle 两点拉框；justDraw:false 自动显示面积标签
+const rectTool = new ANOVGIS.DrawRectangle(viewer, {
+  justDraw: false,
+  onCompleted(positions) {
+    // positions 为 4 个角点（首尾相同 = 5 个）的 Cartesian3[]
+    console.log('rectangle corners:', positions.length);
+  }
+});
+rectTool.startDraw();           // 鼠标按下拖动 → 抬起完成
+```
+
+### 3.9 圆形标绘与测面积（`examples/public/examples/html/analysis/draw.html:178-188, 249-253`）
+
+```js
+// 来源: draw.html L178-188
+// 圆心 + 半径绘制；justDraw:true = 纯标绘，:false = 自动显示面积
+const circleTool = new ANOVGIS.DrawCircle(viewer, {
+  justDraw: true,                // 纯标绘，不带面积标签
+  fill: false,                   // 不填充
+  outline: true,                 // 显示轮廓
+  outlineWidth: 4,
+  outlineColor: ANOVGIS.Color.YELLOW,
+  clampToGround: true,           // 贴地
+  onCompleted(positions) {
+    console.log('circle done', positions);  // 中心 + 圆周点
+  }
+});
+circleTool.startDraw();
+
+// 测面积：justDraw 留空（默认 false）即显示面积 + 半径
+const measureCircle = new ANOVGIS.DrawCircle(viewer, {
+  onCompleted(positions) { console.log(positions); }
+});
+measureCircle.startDraw();
+```
+
+### 3.10 数据驱动热力图（`examples/public/examples/html/analysis/cesiumHeatMap.html:65-97`）
+
+```js
+// 来源: cesiumHeatMap.html L65-97
+// CesiumHeatMap = Canvas 引擎 + Entity 贴图，依赖外部 bounds
+// HeatMapLayer = WebGL 引擎 + Layer 体系，可贴地
+// 两者并存，按场景选其一，不要混用同一份数据
+
+// 1) Canvas 版：自己先 reduce 算 bounds
+const data = [{ X: 119.29, Y: 32.24, value: 39 }, /* ... */];
+const bounds = data.reduce((b, r) => ({
+  west:  Math.min(b.west,  r.X), south: Math.min(b.south, r.Y),
+  east:  Math.max(b.east,  r.X), north: Math.max(b.north, r.Y)
+}), { west: 180, south: 90, east: -180, north: -90 });
+
+const canvasHeat = ANOVGIS.CesiumHeatMap.create(viewer, bounds, {
+  backgroundColor: 'rgba(0,0,0,0)',
+  radius: 50, maxOpacity: 0.5, minOpacity: 0, blur: 0.7
+});
+canvasHeat.setWGS84Data(0, 100, data.map(r => ({ x: +r.X, y: +r.Y, value: r.value })));
+
+// 2) WebGL 版：直接喂点，自动贴地
+const webglHeat = new ANOVGIS.HeatMapLayer({ radius: 30, useGround: true });
+viewer.addLayer(webglHeat);
+webglHeat.setPoints([{ x: 119.29, y: 32.24, value: 39 }]);
+// webglHeat.clear();
+```
+
+### 3.11 地形剖切 / 开挖（`examples/public/examples/html/analysis/terraincliping.html:108-176`）
+
+```js
+// 来源: terraincliping.html L108-176
+// TerrainClipping = 底面 + 侧墙贴图；positions 与 direction 互斥
+const clipping = new ANOVGIS.TerrainClipping(viewer, {
+  lerpInterval: 200,                                 // 侧墙贴图过渡间隔
+  bottomImage: '../modelData/images/clipping/excavate_bottom.jpeg',
+  sideImage:   '../modelData/images/clipping/excavate_side.png'
+});
+clipping.enable = true;
+clipping.height = 100;                               // 开挖深度（米）
+
+// 任意 Draw* 工具拿到 Cartesian3[] 后直接赋给 positions
+new ANOVGIS.DrawPolygon(viewer, {
+  justDraw: true, clampToGround: true, fill: false,
+  onCompleted(positions) { clipping.positions = positions; }
+}).startDraw();
+
+// 也支持 DrawPolyLine / DrawRectangle / DrawCircle 任意一种
+// 还原：clipping.positions = [];
+// 单向裁剪（与 positions 互斥，后设者生效）：
+// clipping.direction = 'up';         // up|down|left|right|front|back
+```
+
+### 3.12 风场粒子（`examples/public/examples/html/analysis/windlayer.html:65-109, 118-134`）
+
+```js
+// 来源: windlayer.html L65-109
+// data 为 grib-json：含 u/v 两个 component 的 [{ header, data }]
+const data = await fetch('../modelData/json/beijing_wind.json').then(r => r.json());
+
+const windLayer = new ANOVGIS.WindLayer({
+  colorScale: ['rgb(255,255,255)'],   // 单色；多色可填色阶数组
+  frameRate: 16,                      // 帧率
+  maxAge: 60,                         // 粒子存活帧
+  globalAlpha: 0.9,                   // 拖尾透明度
+  velocityScale: 1 / 30,              // 速度缩放
+  paths: 2000                         // 粒子数量
+});
+windLayer.setData(data);
+viewer.addLayer(windLayer);
+
+// 运行时调参（按相机高度动态速度示例：windlayer.html:111-134）
+viewer.camera.changed.addEventListener(() => {
+  const h = viewer.camera.positionCartographic.height;
+  windLayer.setOptions({ velocityScale: h < 5000 ? 0.001 : 0.03 });
+});
+// windLayer.show = false;            // 显隐
+// windLayer.setOptions({ paths: 3000, lineWidth: 2 });
+```
+
+### 3.13 水坝开闸放水 — `examples/public/examples/html/analysis/damWaterRelease.html` L189-L293
+
+```js
+// 来源: damWaterRelease.html L222-L293
+// 关键 API: ANOVGIS.DamWaterRelease
+// 13 个闸门位置 × 流量档次(light/medium/heavy/flood) × 喷射形状(锥/圆/矩形)
+this.damRelease = new ANOVGIS.DamWaterRelease(viewer, {
+    damCenter: [115.602, 32.432],
+    gatePositions: gatePositions,                              // [[lng, lat, height], ...] × 13
+    gateHeight: 28,
+    sprayHeading: this.sprayParams.heading,
+    sprayPitch:   this.sprayParams.pitch,
+    emitterType:  this.emitterType,                           // 'cone' | 'circle' | 'box'
+    coneAngle:    this.shapeParams.coneAngle,
+    flowPreset:   this.flowLevel,                              // 'light' | 'medium' | 'heavy' | 'flood'
+    particleImageSize: 24,
+    startScale: 0.8,
+});
+this.damRelease.addToScene();                                 // 加入场景
+
+// 单闸控制
+onGateToggle(idx) { this.damRelease.setGateOpen(idx, this.gates[idx].open); }
+openAll()  { this.damRelease.openAllGates(); }
+closeAll() { this.damRelease.closeAllGates(); }
+setFlow(level) { this.damRelease.setFlowLevel(level); }
+setEmitterShape(type) {
+    this.damRelease.updateEmitterShape({
+        emitterType: type, coneAngle: this.shapeParams.coneAngle,
+        circleRadius: this.shapeParams.circleRadius,
+        boxWidth: this.shapeParams.boxWidth, boxHeight: this.shapeParams.boxHeight,
+    });
+}
+onSprayChange() { this.damRelease.updateSprayDirection(this.sprayParams.heading, this.sprayParams.pitch); }
+```
+
+### 3.14 定位测试(全图元覆盖) — `examples/public/examples/html/analysis/locateTest.html` L116-L399
+
+```js
+// 来源: locateTest.html L116-L360
+// 关键 API: VectorLayer / PrimitiveLayer / TilesetLayer / HtmlLayer
+//           30+ 各类图元 + viewer.flyTo / zoomTo / flyToTileset
+window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    defaultView: [116.2, 39.7, 116.7, 40.1],
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+});
+const vectorLayer    = new ANOVGIS.VectorLayer();
+const primitiveLayer = new ANOVGIS.PrimitiveLayer();
+const tilesetLayer   = new ANOVGIS.TilesetLayer();
+const htmlLayer      = new ANOVGIS.HtmlLayer();
+viewer.addLayer(vectorLayer);
+viewer.addLayer(primitiveLayer);
+viewer.addLayer(tilesetLayer);
+viewer.addLayer(htmlLayer);
+
+// Vector 图元(挂到 vectorLayer)
+new ANOVGIS.Point([116.390, 39.900], { color: Cesium.Color.WHITE, pixelSize: 12 });
+new ANOVGIS.Polyline([[116.392,39.902],[116.398,39.908],[116.404,39.902]], { width: 6, material: Cesium.Color.RED });
+new ANOVGIS.Polygon([[116.406,39.900],[116.412,39.900],[116.412,39.906],[116.406,39.906]], { material: 'rgba(255,165,0,0.6)' });
+new ANOVGIS.Circle([116.414, 39.900], 300);
+new ANOVGIS.Ellipse([116.420, 39.900], 400, 200);
+new ANOVGIS.Wall([[116.390,39.910],[116.396,39.914],[116.402,39.910]], { minimumHeight: 0, maximumHeight: 80 });
+new ANOVGIS.Box([116.406, 39.910], 80, 80, 80);
+new ANOVGIS.Cylinder([116.412, 39.910], 120, 30, 30);
+new ANOVGIS.Ellipsoid([116.418, 39.910], { x: 50, y: 50, z: 60 });
+new ANOVGIS.Billboard([116.408, 39.920], { image: '../modelData/images/biaozhu1.png' });
+new ANOVGIS.Label([116.414, 39.920], { text: 'Label 文字', font: '24px sans-serif', color: '#00ffff' });
+new ANOVGIS.Model({ position: [116.360, 39.930, 80], url: '../modelData/gltf/Cesium_Air.glb', scale: 1 });
+new ANOVGIS.Tileset({ url: '../modelData/3dtiles/topchaoyangbuilding3dtiles/tileset.json' });
+
+// Primitive 图元(挂到 primitiveLayer)
+new ANOVGIS.BillboardPrimitive([116.440, 39.870], '../modelData/images/biaozhu1.png');
+new ANOVGIS.BounceBillboardPrimitive([116.444, 39.872], '../modelData/images/biaozhu1.png');
+new ANOVGIS.ScanCirclePrimitive([116.462, 39.852], 500);
+new ANOVGIS.TrailLinePrimitive([[116.466,39.856],[116.470,39.860],[116.472,39.856]], 3);
+new ANOVGIS.WaterPrimitive([[116.448,39.842],[116.452,39.842],[116.452,39.846],[116.448,39.846]]);
+layer.addGraphic(g);
+
+// 定位 API
+viewer.flyTo(t, 2.2, 0, -45, 0, () => console.log('flyTo 完成'));
+viewer.zoomTo(t);
+viewer.flyToTileset(t, 2, 0.5, -35);  // 3D Tiles 专用
+```
+
+### 3.15 天地图地名搜索 — `examples/public/examples/html/analysis/geocoder.html` L160-L295
+
+```js
+// 来源: geocoder.html L161-L293
+// 关键 API: ANOVGIS.TiandituGeocoderService + Cesium.Geocoder + viewModel._searchCommand
+window.viewer = new ANOVGIS.Viewer("cesiumContainer", { vrButton: false });
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.TDT, {
+        style: "img", key: globalConfig.tdtKey
+    })
+);
+
+let tinadituService = new ANOVGIS.TiandituGeocoderService(
+    'https://api.tianditu.gov.cn/v2/search',
+    globalConfig.tdtKey,                                       // tk 天地图 key
+    {}
+);
+let geocoder = new Cesium.Geocoder({
+    container: 'geocoder', scene: viewer.scene,
+    geocoderServices: [tinadituService]
+});
+let geocoderViewModel = geocoder.viewModel;
+let translateLocal = new ANOVGIS.TranslateLocal(viewer);
+translateLocal && translateLocal.toChinese();                  // 控件中文化
+
+// 解析纯经纬度输入(lng, lat[, height]) 直接飞过去
+if (splitQuery.length === 2 || splitQuery.length === 3) {
+    let longitude = +splitQuery[0], latitude = +splitQuery[1];
+    let height = splitQuery.length === 3 ? +splitQuery[2] : 1000;
+    ANOVGIS.LocateUtil.flyToPosition(viewer, [longitude, latitude], 0, -70, height, 3, null);
+}
+// 否则走天地图 API 模糊匹配: postStr = { 'keyWord': query, 'level': 11, 'mapBound': '-180,-90,180,90', 'queryType': 4, ... }
+// result.data.suggests[] → viewModel.suggestions.push({displayName, destination, gbCode})
+// 点选条目 → viewModel.destinationFound(viewModel, destination) 触发飞行
+```
+
+### 3.16 旧版 geocoder — `examples/public/examples/html/analysis/geocoderOld.html` L105-L174
+
+```js
+// 来源: geocoderOld.html L106-L132
+// 关键 API: ANOVGIS.TiandituGeocoderService 实例化 + Viewer.geocoderType=TIANDITU
+let tinadituService = new ANOVGIS.TiandituGeocoderService(
+    'https://api.tianditu.gov.cn/v2/search',
+    globalConfig.tdtKey,
+    {}
+);
+window.viewer = new ANOVGIS.Viewer("cesiumContainer", {
+    navigationHelpButton: true,
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,               // 让 viewer 用天地图 geocoder
+    copyRight: false
+});
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.TDT, {
+        style: "img", key: globalConfig.tdtKey
+    })
+);
+// 注: ANOVGIS.TiandituGeocoder + container:'toolbar' 的写法在本 demo 被全部注释,
+// 生产代码请参考 3.15 (geocoder.html) 用 Cesium.Geocoder + TiandituGeocoderService 的完整接法。
+```
+
+### 3.17 山西限定 geocoder — `examples/public/examples/html/analysis/geocoder_shanxi.html` L105-L143
+
+```js
+// 来源: geocoder_shanxi.html L105-L125
+// 关键 API: ANOVGIS.TiandituGeocoderService_shanxi + GeocoderType.TIANDITU_SHANXI
+let tinadituService = new ANOVGIS.TiandituGeocoderService_shanxi(
+    null,
+    '04x-Fu5nGOnU7RY7',                                       // 山西专用 tk
+    {}
+);
+window.viewer = new ANOVGIS.Viewer("cesiumContainer", {
+    navigationHelpButton: true,
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU_SHANXI,       // 限定为山西数据源
+});
+// 山西 影像底图 + 山西 注记底图 双层
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.TDT, { style: "img", key: globalConfig.tdtKey })
+);
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.TDT, { style: "cva", key: globalConfig.tdtKey })
+);
+```
+
+### 3.18 自定义 Shader 注入 — `examples/public/examples/html/analysis/test.html` L46-L99
+
+```js
+// 来源: test.html L46-L99
+// 关键 API: Cesium.CustomShader + Cesium.Model.fromGltfAsync + ANOVGIS.LocateUtil.flyToPosition
+// 注意: 此 demo 用了 Cesium.ExperimentalFeatures.enableModelExperimental = true (生产慎用)
+window.viewer = new ANOVGIS.Viewer("cesiumContainer", {
+    orderIndependentTranslucency: false,
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+});
+viewer.scene.screenSpaceCameraController.enableCollisionDetection = false;
+
+let textureUniformShader = this.getCustomShader();
+Cesium.ExperimentalFeatures.enableModelExperimental = true;
+Cesium.Model.fromGltfAsync({
+    url: '../modelData/weather/skyDome.glb',
+    customShader: textureUniformShader,
+    modelMatrix: this.generateModelMatrix([116.40969, 39.951964, 20000], [0, 0, 0], [50000, 50000, 50000])
+}).then(function(model) {
+    window.viewer.scene.primitives.add(model);
+});
+
+// 每帧推进 u_time
+const startTime = performance.now();
+viewer.scene.postUpdate.addEventListener(function () {
+    textureUniformShader.setUniform("u_time", (performance.now() - startTime) / 1000);
+});
+ANOVGIS.LocateUtil.flyToPosition(viewer, '116.40969, 39.951964', 0, -4, 3000, 3, null);
+// 签名: (viewer, "lng,lat", heading, pitch, height, duration, callback)
+```
+
+### 3.19 windlayer2.html — ⚠️ 开发中版本,不推荐
+
+> `windlayer2.html` 引用了未声明的全局 `data` 和 `flow`(ReferenceError),**不适合作为生产推荐用法**。
+> 生产环境请使用 **3.12 windlayer.html**,这是已跑通的稳定版本。