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

package/skills/anovgis-viewer/SKILL.md

@@ -0,0 +1,618 @@
+---
+name: anovgis-viewer
+description: '@anov/gis Viewer 与基础模块。涵盖 Viewer 构造扩展选项（geocoderType/baseLayer/showFPS/drillPick 等）、坐标系工具（CoordUtil / WktUtil / ShapeUtil / ThreeCoordTransform / Transform / LocateUtil）、事件枚举（MouseEventType / ViewerEventType / SceneEventType / LayerEventType / GraphicEventType）、flyTo 系列签名、skybox 天空盒切换、defaultView 默认视角、frustum 视锥。触发关键词：Viewer、options、contextOptions、坐标系、事件、flyTo、LocateUtil、ThreeCoordTransform、Transform、applicationApi、createInstance、skybox、天空盒、defaultView、默认视角、frustum。Use when 配置 Viewer 构造参数、做 WGS84↔GCJ02↔BD09 转换、做 Cartesian↔WGS84 互转、用 ShapeUtil.drawCanvalCircle 生成 billboard 贴图、订阅鼠标事件、调用 viewer.flyTo / flyToPosition / flyToTileset、初始化 application 消息通道、切换天空盒 / 默认视角。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# ANOVGIS Viewer 与基础模块
+
+> `@anov/gis` **v1.8.6**（Cesium **1.143.0**）。`base/` 子包在 `src/base/index.js` 聚合 controls/event/math/position/state/transform/utils/viewer/anovCesiumBind/frameState。本 skill snippet 行号基于 v1.8.6 SDK 公开 API 行为锁定，跨版本仅作语义锚点。
+
+> ⚠️ **优先级**：本 skill 优先于 SDK 源码 / `node_modules/@anov/gis/`。
+> 遇到 API 行为疑问先查本 skill 与 `anovgis-pitfalls`。**严禁**主动 Glob/Grep `node_modules/@anov/gis/src/...` / `dist/...`；除非用户明确要求并承担风险。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 19 类 Primitive（Cloud / FlowLine / ScanCircle / Water / ...） → [`anovgis-primitives`](../anovgis-primitives/SKILL.md)
+- ❌ 不要写 `Model` / `Tileset` 加载 + 调色 + 抽壳 → [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md)
+- ❌ 不要写 `bindPopup` / `bindTooltip` 完整用法 → [`anovgis-popup-widget`](../anovgis-popup-widget/SKILL.md)
+- ❌ 不要写 5 个 Util（Util / DomUtil / WktUtil / CoordUtil / ShapeUtil）完整 API — 本 skill 仅按需引用，见 SDK `src/base/utils/`
+- ❌ 不要写 Imagery / Terrain → [`anovgis-imagery-terrain`](../anovgis-imagery-terrain/SKILL.md)
+- ❌ 不要写天气 / 漫游 / 后期特效 → [`anovgis-effects`](../anovgis-effects/SKILL.md)
+
+---
+
+## 1. 命名空间速查
+
+| 名称 | 来源 | 用途 |
+|---|---|---|
+| `ANOVGIS.Viewer` | `src/base/viewer/Viewer.js` | 主入口；包裹 Cesium 原生 `Viewer` |
+| **Cesium 入口（唯一推荐）** | SDK 启动时主动挂载 | `const Cesium = window.Cesium`（CDN/UMD/ESM 全场景通用） |
+| `ANOVGIS.CoordUtil` | `src/base/utils/CoordUtil.js` | 多边形相交 / 包含等几何判断 |
+| `ANOVGIS.WktUtil` | `src/base/utils/WktUtil.js` | WKT ↔ GeoJSON |
+| `ANOVGIS.ShapeUtil` | `src/base/utils/ShapeUtil.js` | Canvas 贴图（`drawCanvalCircle` 等） |
+| `ANOVGIS.ThreeCoordTransform` | `src/base/transform/ThreeCoordTransform.js` | WGS-84 / GCJ-02 / BD-09 三系互转 |
+| `ANOVGIS.LocateUtil` | `src/base/utils/LocateUtil.js` | `flyToPoint` / `flyToPosition` 等定位静态方法 |
+| `ANOVGIS.FeatureInfoUtil` | `src/base/utils/FeatureInfoUtil.js` | 要素属性信息 |
+| `ANOVGIS.Util` | `src/base/utils/Util.js` | 通用（uuid、merge、深拷贝） |
+| `ANOVGIS.DomUtil` | `src/base/utils/DomUtil.js` | DOM 操作 |
+| `ANOVGIS.Transform` | `src/base/transform/Transform.js` | `Cartesian ↔ WGS84 ↔ Cartographic` 转换 |
+| `ANOVGIS.GeocoderType` | `src/base/controls/geocoder` | 地名搜索类型枚举 |
+
+**注意**：`ANOVGIS.PlotUtil` 在 `src/base/utils/PlotUtil.js` 中存在但**未在 `utils/index.js` re-export**，因此 demo 中并未通过 `ANOVGIS.*` 访问。若需要标绘算法，应自行 `import` 该文件内部类，或在仓库内提 PR 补全 re-export。
+
+**Cesium 入口写法（铁律）**：
+
+```js
+// ✅ 唯一推荐（CDN/UMD/ESM 全场景通用）
+const Cesium = window.Cesium  // @anov/gis 启动时主动 window.Cesium = Cesium
+
+// ❌ 不要写（v1.8.6 SDK 未把 Cesium 对象本身挂到 ANOVGIS 顶层，undefined）
+const Cesium = ANOVGIS.Cesium
+
+// ❌ 不要写（@anov/gis 已封装 Cesium，不需要重复装包）
+import Cesium from 'cesium'
+```
+
+**Cesium 私有成员（`_` 开头）**：`@anov/gis` 不会挂到 `ANOVGIS` 上，必须走 `window.Cesium`。例如 `window.Cesium.ArcType.GEODESIC`。
+
+---
+
+<a id="viewer-params"></a>
+## 2. Viewer 扩展参数（17 个）
+
+`ANOVGIS.Viewer` 在 Cesium 原生构造选项之上额外识别下列字段（默认值见 `Viewer.js` 中 `DEF_OPTS`，L22-56）。完整 Cesium 原生字段语义见 `Viewer.js` L58-109 的 JSDoc。
+
+| 字段 | 类型 / 默认值 | 说明 |
+|---|---|---|
+| `geocoderType` | `ANOVGIS.GeocoderType.{TIANDITU,GAODE,TENCENT,BAIDU}` | 右上角地名搜索控件的数据源 |
+| `baseLayer` | `ANOVGIS.ImageryType.*` | 简写，等价于 `ImageryLayerFactory.createImageryLayer(...)`。⚠️ **v1.8.6 实测有 bug**（枚举是字符串，如 `TDT` === `'tdt'`，构造传会报 `_layerIndex on string 'tdt'`）——不要用，底图走构造后 `addImageryProvider` |
+| `baseLayerPicker` | `false` | 是否显示底图切换控件（`true` 时加载 LayerControlUitl） |
+| `copyRight` | `false` | 控制台输出版权信息（`CopyRight.consoleOut()`） |
+| `showMapInfo` | `false` | 加载 `MapInfo` 信息栏（鼠标经纬度 / 海拔） |
+| `showFPS` | `false` | `scene.debugShowFramesPerSecond = true` |
+| `flyDuration` | `3` | 初始定位飞行总秒数 |
+| `language` | `'chinese'` \| `'english'` | `'chinese'` 时加载 `TranslateLocal.toChinese()` |
+| `scaleRatio` | `1.0` | 屏幕分辨率缩放（影响高 DPI） |
+| `drillPick` | `false` | 穿透拾取；同步写入 `nativeObjCesium.drillPick` |
+| `minZoom` / `maxZoom` | `0` / `20` | 相机最小 / 最大缩放级别 |
+| `minPitch` / `maxPitch` | `-90` / `0` | 相机最小 / 最大俯仰角（度） |
+| `pitch` | `-90` | 默认俯仰角 |
+| `zoom` | `undefined` | 默认缩放级别 |
+| `center` | `undefined` | 默认中心点（`{lng, lat, alt, heading, pitch}`）；提供时启动 `LocateUtil.flyToPosition` |
+
+Cesium 原生字段会被 `this._options = { ...DEF_OPTS, ...options, geocoder: false }` 覆盖；ANOVGIS 强制关闭 `geocoder`（自实现地名搜索）。其余 Cesium 原生构造选项如 `contextOptions`、`sceneMode`、`terrainProvider`、`requestRenderMode` 等照常可用。
+
+---
+
+## 3. 事件枚举
+
+所有事件枚举集中在 `src/base/event/EventType.js` 一个文件内（不要去 `event/type/*Type.js` 找，没有）。
+
+### `MouseEventType`（Viewer 全局鼠标事件）
+
+```text
+LEFT_DOWN, LEFT_UP, CLICK, RIGHT_DOWN, RIGHT_UP, RIGHT_CLICK,
+DB_CLICK, MOUSE_MOVE, WHEEL, MOUSE_OVER, MOUSE_OUT
+```
+
+### `ViewerEventType`（Viewer 实例生命周期 + 鼠标）
+
+```text
+ADD_LAYER, REMOVE_LAYER, ADD_EFFECT, REMOVE_EFFECT,
+LEFT_DOWN, LEFT_UP, CLICK, RIGHT_DOWN, RIGHT_UP, RIGHT_CLICK,
+DB_CLICK, MOUSE_MOVE, WHEEL,
+FLY_COMPLETE
+```
+
+### `SceneEventType`（`scene` 渲染循环事件）
+
+```text
+CAMERA_MOVE_END, CAMERA_CHANGED,
+PRE_UPDATE, POST_UPDATE, PRE_RENDER, POST_RENDER,
+MORPH_COMPLETE, CLOCK_TICK, RENDER_ERROR
+```
+
+### `LayerEventType`（图层容器事件）
+
+```text
+ADD, REMOVE,                      // 来自 BaseEventType
+LEFT_DOWN, LEFT_UP, CLICK, MOUSE_MOVE,
+RIGHT_DOWN, RIGHT_UP, RIGHT_CLICK, DB_CLICK, MOUSE_OUT
+```
+
+### `GraphicEventType`（Graphic / Entity 事件）
+
+```text
+ADD, REMOVE,
+LEFT_DOWN, LEFT_UP, CLICK, RIGHT_DOWN, RIGHT_UP, RIGHT_CLICK,
+DB_CLICK, MOUSE_MOVE, MOUSE_OVER, MOUSE_OUT,
+POSITION_UPDATE, BIND_POPUP
+```
+
+### 其他枚举（同样从 `EventType.js` 导出）
+
+- `LayerGroupEventType = BaseEventType`：`ADD / REMOVE`
+- `TrackEventType`：`ADD, REMOVE, POST_RENDER, ACTIVATE, DEACTIVATE, RESET_TIME_LINE`
+- `PathEventType`：`ADD, REMOVE, POST_RENDER, RESET_TIME_LINE, END, STOP_STAY`
+- `PlotEventType`：`DRAW_START, DRAW_STOP, EDIT_START, EDIT_STOP, DRAW_ANCHOR, CREATE_ANCHOR, UPDATE_ANCHOR, ANCHOR_MOVING, EDIT_ANCHOR_STOP, CLEAR_ANCHOR`
+- `FlyEventType`：`BEGIN, END, STOP_STAY, FLYING`
+- `WidgetEventType`：`OPEN, CLOSE`（信息框面板）
+
+### 典型用法
+
+```js
+// 来源: examples/public/examples/html/graphics/billboard.html L96-101
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, () => {
+    alert('点击了');
+});
+layer.addEventListener(ANOVGIS.MouseEventType.MOUSE_MOVE, () => {
+    console.log('MOUSE_MOVE');
+});
+```
+
+---
+
+## 4. 5 个 snippet
+
+### Snippet 1：坐标系转换（WGS-84 ↔ GCJ-02 ↔ BD-09）
+
+`CoordUtil` 不做坐标系转换；正确入口是 `ANOVGIS.ThreeCoordTransform`，所有方法接受 `(lng, lat)`，返回 `[lng, lat]` 数组。
+
+```js
+// 来源: src/base/transform/ThreeCoordTransform.js L57-85
+const [gcjLng, gcjLat] = ANOVGIS.ThreeCoordTransform.WGS84ToGCJ02(116.404, 39.915);
+const [wgsLng, wgsLat] = ANOVGIS.ThreeCoordTransform.GCJ02ToWGS84(gcjLng, gcjLat);
+const [bdLng, bdLat]   = ANOVGIS.ThreeCoordTransform.GCJ02ToBD09(gcjLng, gcjLat);
+const [back2GcjLng, back2GcjLat] = ANOVGIS.ThreeCoordTransform.BD09ToGCJ02(bdLng, bdLat);
+```
+
+### Snippet 2：`ShapeUtil.drawCanvalCircle` 用作 billboard 贴图
+
+方法名拼写是 `drawCanvalCircle`（SDK 历史拼写错误，注意不是 `drawCanvasCircle`）。返回 dataURL 字符串，可直接塞进 `billboard.image`。
+
+```js
+// 来源: examples/public/examples/html/graphics/billboard.html L79-93
+v.setOptions({
+    billboard: {
+        image: ANOVGIS.ShapeUtil.drawCanvalCircle(
+            Cesium.Color.BLUE.toCssColorString(),  // 颜色或 Cesium.Color
+            60,                                     // 像素尺寸（正方形）
+            [v.attr.name, Math.floor(Math.random() * 300)] // 中心文字 1-2 行
+        ),
+        verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+        disableDepthTestDistance: Number.POSITIVE_INFINITY,
+        scaleByDistance: { near: 1000000, nearValue: 1.0, far: 10000000, farValue: 0.0 }
+    }
+});
+```
+
+### Snippet 3：`Transform` 笛卡尔 ↔ WGS84 转换
+
+`Transform` 提供 `Cartesian ↔ WGS84 ↔ Cartographic` 互转，也封装了屏幕坐标 → 世界坐标的便捷方法。`pickPosition`（Cesium 原生）适合命中 Entity / Primitive；屏幕 → WGS84 / Cartesian3 走 SDK 自带方法即可。
+
+```js
+// 来源: src/base/transform/Transform.js L19-99
+// Position 对象形如 { lng, lat, alt }
+const cartesian = ANOVGIS.Transform.transformWGS84ToCartesian({ lng: 116.404, lat: 39.915, alt: 100 });
+const wgs84     = ANOVGIS.Transform.transformCartesianToWGS84(cartesian);
+// wgs84 -> Position 实例: { lng, lat, alt }
+
+// 屏幕坐标 -> 世界坐标（SDK 自带，3D 模式走 globe.pick，2D 走 ellipsoid）
+// 来源: src/base/transform/Transform.js L172-194
+const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
+handler.setInputAction((movement) => {
+    const wgs = ANOVGIS.Transform.transformWindowToWGS84(movement.position, viewer);
+    console.log(wgs.lng, wgs.lat, wgs.alt);
+
+    const cartesian3 = ANOVGIS.Transform.transformWindowToCartesian3(movement.position, viewer);
+}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+
+// 需要命中 Entity / Primitive 时，落到 Cesium 原生 pickPosition：
+handler.setInputAction((movement) => {
+    const picked = viewer.scene.pickPosition(movement.position);
+    if (picked) {
+        const wgs = ANOVGIS.Transform.transformCartesianToWGS84(picked);
+        console.log('命中实体:', wgs.lng, wgs.lat, wgs.alt);
+    }
+}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+```
+
+### Snippet 4：`viewer.addLayer / viewer.removeLayer`
+
+`addLayer` / `removeLayer` 是**链式 API**（返回 `this`）。`removeLayer` 接受 layer 实例（不是 id 字符串）。
+
+```js
+// 来源: examples/public/examples/html/material/flowPolyline.html L52-100
+let layer = new ANOVGIS.VectorLayer();
+viewer.addLayer(layer);   // 链式返回 viewer
+
+// layer.addGraphic(...) 等操作完成后
+
+viewer.removeLayer(layer); // 接受 layer 实例，不是 id
+```
+
+### Snippet 5：`viewer.flyTo`
+
+签名是 6 参数：`flyTo(target, duration, heading, pitch, range, completeCallback)`，不是 spec 简写的 `(target, opts)`。`target` 可以是 `Layer`（自动调 `layer.flyTo`）或任何 Cesium 原生可飞对象（Entity / DataSource / Tileset）。
+
+```js
+// 来源: examples/public/examples/html/material/flowPolyline.html L99-100
+layer.addGraphic(polyline).addGraphic(polyline1).addGraphic(polyline2).addGraphic(polyline3);
+viewer.flyTo(layer);  // target=Layer, duration 默认 2.2s, heading/pitch/range 用默认
+
+// 飞到单个 Entity 或 Tileset（严格 6 参数形式）：
+viewer.flyTo(
+    tileset.nativeObjCesium || tileset,
+    2.0,                                          // duration（秒）
+    0.0,                                          // heading（弧度）
+    Cesium.Math.toRadians(-45),                   // pitch（弧度）
+    0,                                            // range（0 = SDK 自动取值）
+    () => console.log('fly complete')             // completeCallback
+);
+```
+
+---
+
+## 4.5 补充 snippet（7 个）
+
+### Snippet 6：`viewer.scene.pickPosition` 鼠标拾取世界坐标
+
+`pickPosition`（Cesium 原生）返回 `Cesium.Cartesian3`。需要在命中 Entity / Primitive / 地形时取世界坐标。拾取失败（如点到天空）时返回 `undefined`，务必 `Cesium.defined` 判空。
+
+```js
+// 来源: examples/public/examples/html/analysis/terraincliping2.html L125-136
+const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
+const positions = [];
+handler.setInputAction((movement) => {
+    const worldPosition = viewer.scene.pickPosition(movement.position);
+    if (Cesium.defined(worldPosition)) {
+        const carto = Cesium.Cartographic.fromCartesian(worldPosition);
+        positions.push(worldPosition);
+        // 转 WGS84 展示：
+        const wgs = ANOVGIS.Transform.transformCartesianToWGS84(worldPosition);
+        console.log('命中:', wgs.lng, wgs.lat, wgs.alt);
+    }
+}, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+```
+
+### Snippet 7：`viewer.flyTo` 完整 6 参数签名
+
+签名是 `flyTo(target, duration, heading, pitch, range, completeCallback)`。`target` 可以是 `Layer`（自动调 `layer.flyTo`）或 Cesium 原生可飞对象（Entity / DataSource / Tileset）。`heading / pitch / range` 用 0 让 SDK 自行计算。`range = 0` 时 SDK 根据 target boundingSphere 自动取值。
+
+```js
+// 来源: examples/public/examples/html/material/flowPolyline.html L100
+// 简单用法：target = Layer，duration 默认 2.2s
+viewer.flyTo(layer);
+
+// 完整 6 参数：target = Tileset / Entity / DataSource
+viewer.flyTo(
+    tileset.nativeObjCesium || tileset,  // target
+    2.0,                                 // duration（秒）
+    0.0,                                 // heading（弧度，正北=0）
+    Cesium.Math.toRadians(-45),          // pitch（弧度，-90=俯视）
+    0,                                   // range（0 = SDK 自动取 boundingSphere）
+    () => console.log('fly complete')    // completeCallback
+);
+```
+
+### Snippet 8：`viewer.camera.flyToBoundingSphere` 飞到包围球
+
+先用 `Cesium.BoundingSphere.fromPoints(allPositions)` 算出所有点的包围球，再用 `flyToBoundingSphere` 飞行。offset 中 heading/pitch/range 控制飞行姿态。
+
+```js
+// 来源: examples/public/examples/html/effect/dog2.html L353-372
+const now = Cesium.JulianDate.now();
+const entities = dataSource.entities.values;
+const allPositions = [];
+entities.forEach(entity => {
+    if (entity.polygon) {
+        const h = entity.polygon.hierarchy.getValue(now);
+        if (h && h.positions) allPositions.push(...h.positions);
+    }
+});
+if (allPositions.length > 0) {
+    const boundingSphere = Cesium.BoundingSphere.fromPoints(allPositions);
+    window.viewer.camera.flyToBoundingSphere(boundingSphere, {
+        offset: {
+            heading: Cesium.Math.toRadians(0.96),
+            pitch: Cesium.Math.toRadians(-55),
+            range: boundingSphere.radius * 2.5   // 离中心点的距离（米）
+        },
+        duration: 2
+    });
+}
+```
+
+### Snippet 9：`viewer.scene.camera.setView` 直接定位（不走动画）
+
+`setView` 是**瞬时定位**（无飞行动画），`flyTo` 是动画飞行。`orientation` 字段有两种形式：
+
+1. `heading / pitch / roll`（欧拉角，弧度）—— 最常用
+2. `direction / up`（单位向量）—— 与 Three.js 同步相机姿态时使用
+
+```js
+// 来源: examples/public/examples/html/performance/js/ThreejsTransform.js L457-464
+// heading/pitch/roll 形式：
+viewer.camera.setView({
+    destination: Cesium.Cartesian3.fromDegrees(116.397, 39.916, 1000),
+    orientation: {
+        heading: 0.0,                            // 正北
+        pitch: Cesium.Math.toRadians(-90),       // 俯视
+        roll: 0.0
+    }
+});
+
+// 来源: examples/public/examples/html/performance/js/ThreejsTransform.js L359-366
+// direction/up 单位向量形式（同步 Three.js 相机时）：
+viewer.scene.camera.setView({
+    destination: cameraPosCesium,
+    orientation: {
+        direction: directionCesiumCamera,
+        up: upCesiumCamera
+    }
+});
+```
+
+### Snippet 10：`viewer.clock` 当前时间与 `Cesium.JulianDate` 转换
+
+`viewer.clock.currentTime` 控制场景时间，常用于动画、阴影、光照等时间敏感渲染。`Cesium.JulianDate.fromDate(new Date(...))` 把 JS `Date` 转为 JulianDate，`Cesium.JulianDate.now()` 取当前时刻。
+
+```js
+// 来源: examples/public/examples/html/effect/globalrotate.html L53
+viewer.clock.currentTime = Cesium.JulianDate.fromDate(new Date('2024,4,2 16:10:18'));
+
+// 来源: examples/public/examples/html/effect/dog2.html L353
+const now = Cesium.JulianDate.now();
+const h = entity.polygon.hierarchy.getValue(now);  // 取当前时刻属性
+
+// 暂停 / 继续 / 倍速：
+viewer.clock.shouldAnimate = false;            // 暂停
+viewer.clock.shouldAnimate = true;             // 继续
+viewer.clock.multiplier = 10;                  // 10x 倍速播放
+```
+
+### Snippet 11：`Transform` 双向 Cartesian ↔ WGS84 转换
+
+`Transform.transformCartesianToWGS84(cartesian)` 返回 `Position`（`{lng, lat, alt}`）；`Transform.transformWGS84ToCartesian(position)` 返回 `Cesium.Cartesian3`。双向是同步 SDK `Position` 对象的关键。
+
+```js
+// 来源: src/base/transform/Transform.js L19-78
+// Cartesian -> WGS84（Position）
+const cartesian = Cesium.Cartesian3.fromDegrees(116.404, 39.915, 100);
+const wgs = ANOVGIS.Transform.transformCartesianToWGS84(cartesian);
+console.log(wgs.lng, wgs.lat, wgs.alt);   // 116.404  39.915  100
+
+// WGS84 -> Cartesian
+const back = ANOVGIS.Transform.transformWGS84ToCartesian(
+    new ANOVGIS.Position(116.404, 39.915, 100)
+);
+console.log(back);  // Cesium.Cartesian3
+
+// 用途：从 pickPosition / 几何计算得到的 Cartesian3 一律先 transformCartesianToWGS84
+// 再传给 WKT / GeoJSON / ShapeUtil。
+```
+
+### Snippet 12：`viewer.scene.globe.depthTestAgainstTerrain` + `pickEllipsoid` 拾取地球椭球面
+
+`depthTestAgainstTerrain` 控制 entity / primitive 是否被地形遮挡。无地形（`EllipsoidTerrainProvider`）时默认 `false` 也不影响；有地形时若想让标注 / polygon 浮在地表以上就开 `true`。`pickEllipsoid` 用于无地形或无命中时拾取椭球面（射线和 WGS84 椭球的交点），返回 `Cartesian3`，与俯仰角无关。
+
+```js
+// 来源: examples/public/examples/html/analysis/draw.html L138-140
+// 深度测试开关（checkbox 切换）
+function depthTest(t) {
+    viewer.scene.globe.depthTestAgainstTerrain = t;
+}
+
+// 来源: src/base/viewer/Viewer.js L1144-1154
+// pickEllipsoid 拾取椭球面（无地形或拾取失败时兜底）：
+const ellipsoid = viewer.scene.globe
+    ? viewer.scene.globe.ellipsoid
+    : Cesium.Ellipsoid.WGS84;
+const center = new Cesium.Cartesian2(
+    viewer.scene.canvas.clientWidth / 2,
+    viewer.scene.canvas.clientHeight / 2
+);
+const cartesian = viewer.scene.camera.pickEllipsoid(center, ellipsoid);
+if (cartesian) {
+    const carto = ellipsoid.cartesianToCartographic(cartesian);
+    console.log(
+        Cesium.Math.toDegrees(carto.longitude),
+        Cesium.Math.toDegrees(carto.latitude),
+        carto.height
+    );
+}
+```
+
+---
+
+## 4.5 Viewer 一级相机状态机(`viewer.getCenter / setZoom / zoomIn / zoomOut`)— `effect/testzoom.html`
+
+> ⚠️ v0.2.6 新增。`testzoom.html` 揭示了一套完整的相机状态机 API,比 `viewer.flyTo` 更适合做"地图应用"级别的 zoom/pan 控制(mapbox / 高德地图那种风格)。**此前 v0.2.5 完全漏掉**。
+
+### 初始化选项
+
+```js
+// 来源: effect/testzoom.html L106-135
+new ANOVGIS.Viewer('cesiumContainer', {
+    defaultView: [250, 22, 330, 60],
+    center: { lng: 116.397, lat: 39.916 },           // 初始中心
+    zoom: 12,                                          // 初始缩放等级(类似 mapbox zoom)
+    pitch: -45,                                        // 初始俯仰角(度,负值=俯视)
+    minZoom: 3, maxZoom: 18,                           // zoom 范围限制
+    minPitch: -90, maxPitch: -30,                     // pitch 范围限制
+    flyDuration: 2,                                    // 默认飞行时长
+});
+```
+
+### 读状态
+
+```js
+const center = viewer.getCenter();                     // { lng, lat }
+const zoom   = viewer.getZoom();                       // float (类似 mapbox zoom)
+const pitch  = viewer.getPitch();                      // float (度)
+const { min, max } = viewer.getZoomRange();            // 当前 zoom 范围
+const { min, max } = viewer.getPitchRange();           // 当前 pitch 范围
+```
+
+### 写状态(瞬时,无动画)
+
+```js
+viewer.setCenter({ lng: 116.391, lat: 39.912 });
+viewer.setZoom(13);
+viewer.setCenterAndZoom({ lng: 116.397, lat: 39.916 }, 14);  // 同时设中心+缩放
+viewer.zoomIn();                                       // 缩放 +1
+viewer.zoomOut();                                      // 缩放 -1
+viewer.setPitch(-30);                                  // 俯仰角
+viewer.setZoomRange(5, 15);                            // 重设 zoom 范围
+```
+
+### 保存 / 恢复视图
+
+```js
+this.savedView = viewer.getView();                     // { center, zoom, heading, pitch }
+viewer.setView(this.savedView);                        // 瞬时恢复
+viewer.setView(this.savedView, 1.5);                   // 带动画恢复(1.5s)
+```
+
+> ⚠️ 这套 API 与 `viewer.flyTo(target, ...)` 的区别:
+> - `flyTo`: 飞到某个**目标实体**(point / tileset / layer),适合 POI 跳转
+> - `getCenter / setZoom`: 操作**相机状态机**(center + zoom + pitch),适合地图 UI 控件(滚轮缩放 / 拖拽平移 / 复位)
+
+---
+
+## 5. applicationApi：SDK 与业务消息通道
+
+`application` 模块仅实现 `ANOVGIS.init` 与 `viewer.scene.camera.focus` 两个 message name；其余 `name` 静默无响应。**真正的"开箱即用业务 API"位于已抽离的 `@anov/gis.applyfn` 子包，本 skill 不覆盖**（UI 在 `@anov/gis.ui`，Cesium 三方封装在 `@anov/gis.cesiumthreelib`）。
+
+### createInstance 真实用法
+
+```js
+import ANOVGIS from '@anov/gis';
+
+const app = ANOVGIS.createInstance();
+// 实际不做初始化（构造时 options 被丢弃），真正初始化走：
+app.sendMessage({
+    name: 'ANOVGIS.init',
+    params: { container: 'cesiumContainer', /* ...viewer options */ }
+});
+```
+
+> 路径说明：`createInstance` 在 `src/ANOVGIS.js:21` 通过 `export * from './application'` 导出，在 `src/index.js:83` 通过 `ANOVGIS.mixin(...)` 挂到默认导出。`@anov/gis` 包无 `exports` 字段且 `.npmignore` 排除 `/src`，故子路径 `@anov/gis/application` 在发布的 npm 包里解析不了——必须从主入口 `@anov/gis` 取默认导出再调用 `createInstance`。
+
+`options` 参数：`createInstance(options)` 调用时 `options` 会被构造器丢弃，真正的初始化通过后续 `sendMessage({ name: 'ANOVGIS.init'/'anovgis.init', params })` 触发。`params` 至少需含 `container`（DOM 容器）以及透传给 `Viewer` 的其他 Cesium 参数。
+
+### messageFn / messageStatus
+
+`application` 子包不主动执行业务，而是封装"消息分发"机制：
+
+- `messageFn.js`：`sendToMessage(messageType, name, status, id, res)` 构造统一响应结构（`id` / `name` / `code` / `msg` / `result`），并定义 `MessageType = { Event, Api }`。
+- `messageStatus.js`：`messageStatus`（含 `code`+`msg`）与 `EMessageStatus`（纯数字枚举）两套状态码表，涵盖 `Success / ModuleNotRegister / EventHandleFailed` 等。`codeMessageMap` 仅含 `200` 兜底映射。
+
+调用方通过 `app.sendMessage({ name, id, params })` 发送 API 调用；通过 `app.receiveMessage(cb)` 订阅 `Event` / `Api` 两类消息。`name === 'ANOVGIS.init'` 会创建 `Viewer`，`name === 'viewer.scene.camera.focus'` 会调用 `camera.flyTo`。
+
+**来源**：`src/application/index.js`、`src/application/applicationApi.js`、`src/application/messageFn.js`、`src/application/messageStatus.js`。
+
+---
+
+## Viewer 工具栏默认全开（v0.2.4 加）
+
+通用 demo / 教学 / 业务项目,Viewer 右上角工具栏**默认全部显示**,与 `examples/public/examples/html/basemap/tdtSatelliteImage.html` L96-101 对齐:
+
+```js
+// ✅ 推荐:默认全开
+new ANOVGIS.Viewer('cesiumContainer', {
+  // 全部 true(用户视角下默认就要显示)
+  baseLayerPicker: true,
+  fullscreenButton: true,
+  homeButton: true,
+  sceneModePicker: true,
+  navigationHelpButton: true,
+  // 与本约定无关的可以关(典型 demo 不需要)
+  timeline: false,        // 时间轴(只有 CZML/动画 demo 需要)
+  animation: false,       // 仿真时钟 UI(同上)
+  vrButton: false,        // VR(已淘汰)
+})
+```
+
+**为什么**:Cesium 右上角的工具栏是**用户预期的导航能力**(底图切换 / 主页 / 2D-3D 切换)。全关等于剥夺基本功能,用户会觉得"这地球怎么啥都没有"。**只有明确要纯净态**(截图、嵌入大屏、视频录制)才逐一关,且注释说明。
+
+**仅在以下场景才逐一关**:
+- 大屏嵌入 + 不需要导航 → `baseLayerPicker: false, homeButton: false`
+- 单页应用 + 业务 UI 接管 → `fullscreenButton: false`(自己的 fullscreen 控件)
+- 移动端嵌入 → 全部保留
+
+---
+
+
+---
+
+## 典型工作流（4 步）
+
+```js
+// 1. 设置静态资源 baseUrl（必须先于 new Viewer）
+ANOVGIS.setBaseUrl('/anov-gis-sdk/resources/');
+
+// 2. 创建 Viewer
+const viewer = new ANOVGIS.Viewer('cesiumContainer', {
+    contextOptions: { id: 'cesiumCanvas' },
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+    // ⚠️ 不要传 baseLayer（v0.2.10 实测 v1.8.6 会报 _layerIndex on string 错）——底图构造后 addImageryProvider
+});
+
+// 3. 加载图层
+viewer.addLayer(new ANOVGIS.GeoJsonLayer(url, opts));
+
+// 4. 监听事件
+viewer.getLayer(id).addEventListener(ANOVGIS.MouseEventType.CLICK, handler);
+```
+
+
+---
+
+### E. 多 Viewer 实例。每 Viewer 占独立 DOM + 独立 WebGL 上下文；`contextOptions.id` 必须不同（截图依赖 canvas id）。
+
+```js
+// 来源: examples/.../basemap/CesiumTerrain.html L31 + ArcGISTerrain.html L30
+const opts = (id) => ({
+    contextOptions: { id, webgl: { preserveDrawingBuffer: true }, showRenderLoopErrors: false },
+    geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+    baseLayerPicker: true, fullscreenButton: false, homeButton: true,
+    sceneModePicker: true, navigationHelpButton: true, copyRight: false, showMapInfo: true,
+});
+window.viewerLeft = new ANOVGIS.Viewer('cesiumLeft', opts('cesiumCanvasLeft'));
+viewerLeft.scene.setTerrain(Cesium.Terrain.fromWorldTerrain());
+const arcgis = await Cesium.ArcGISTiledElevationTerrainProvider.fromUrl(
+    'https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer'
+);
+window.viewerRight = new ANOVGIS.Viewer('cesiumRight', opts('cesiumCanvasRight'));
+viewerRight.terrainProvider = arcgis;
+```
+
+> WebGL 上下文有上限（同源约 16），多 Viewer 务必在 `beforeUnmount`/`destroy` 释放。
+
+
+---
+
+### F. iframe + `about:srcdoc`。`about:srcdoc` iframe 的 `window.location.href` 为 `"about:srcdoc"`，Cesium `isCrossOriginUrl()` 用 anchor 协议/host 比对会判同源 worker 为跨域。SDK `src/index.js` 已做：① 从 `<script src="/anov-gis-sdk/...">` 推断 baseUrl；② monkey-patch `HTMLAnchorElement.href` setter 把 `"about:srcdoc"` 重写为父页 href。
+
+```html
+<!-- 来源: src/index.js L89-135 -->
+<iframe srcdoc="
+<!DOCTYPE html><html><body style='margin:0'>
+<div id='cesiumContainer' style='width:100%;height:100vh'></div>
+<script src='https://unpkg.com/@anov/gis@1.7.7/dist/index.js'><\/script>
+<link rel='stylesheet' href='https://unpkg.com/@anov/gis@1.7.7/dist/index.css'>
+<script>
+  ANOVGIS.setBaseUrl('https://unpkg.com/@anov/gis@1.7.7/dist/resources/');
+  window.viewer = new ANOVGIS.Viewer('cesiumContainer', {
+      contextOptions: { id: 'cesiumCanvas', webgl: { preserveDrawingBuffer: true } },
+      geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+  });
+<\/script></body></html>"></iframe>
+```
+
+> 跨域 iframe 需父页 `document.domain` 一致或 CSP 显式放行 worker 资源。
+