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

package/skills/anovgis-imagery-terrain/SKILL.md

@@ -0,0 +1,505 @@
+---
+name: anovgis-imagery-terrain
+description: '@anov/gis 影像与地形模块。涵盖 ImageryLayerFactory（TDT/AMAP/BAIDU/TENCENT/GOOGLE/ARCGIS/WMS/WMTS/XYZ/SingleTile/Mapbox/TMS/Grid/Coord）、TerrainFactory（Ellipsoid/Url/Arcgis/Google/VR，1.143 异步语义）、SplitImageLayer 卷帘、**ImageryThemeGL 暗色/反色主题(常用 invert:true)**、Cesium World Terrain、MultiKeyTdtImageryProvider 多 key 天地图（v1.8.6 新增）。触发关键词：imagery、imageryLayers、底图、天地图、高德、百度、ArcGIS、WMS、WMTS、地形、terrainProvider、setTerrain、卷帘、SplitImage、**暗色、夜间、反色、invert、theme、ImageryThemeGL**、deployConfig、离线部署、内网、本地瓦片、4490。Use when 加载 / 切换影像底图、配置天地图 key、做 WMS/WMTS 接入、做 Cesium World Terrain 或自定义 URL 地形、做卷帘对比、**切暗色 / 夜间 / 反色主题**、离线部署底图。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# anovgis-imagery-terrain
+
+> ⚠️ **优先级**：本 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`）。
+
+锁定 `@anov/gis` **v1.8.6**（Cesium **1.143.0**）。v1.8.6 新增 `MultiKeyTdtImageryProvider`（多 key 天地图）。所有 snippet 基于 v1.8.6 SDK 公开 API 行为锁定（仅作语义锚点）。
+
+要素图层（GeoJSON/3D Tiles/Cluster 等）见 `anovgis-layers`；离线部署清单见 v0.3.0 `anovgis-offline-deployment`。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 14 个要素图层（VectorLayer / GeoJsonLayer / ...） → [`anovgis-layers`](../anovgis-layers/SKILL.md)
+- ❌ 不要写离线部署清单 / `deployConfig.js` 模板 → v0.3.0 `anovgis-offline-deployment`
+- ❌ 不要写 Viewer 构造 / flyTo → [`anovgis-viewer`](../anovgis-viewer/SKILL.md)
+- ❌ 不要写 `ImageryLayer` 之外的 entity / primitive → [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md) / [`anovgis-primitives`](../anovgis-primitives/SKILL.md)
+- ❌ 不要写特效 → [`anovgis-effects`](../anovgis-effects/SKILL.md)
+
+<a id="factory"></a>
+## 1. ImageryLayerFactory
+
+类路径 `src/layer/imagery/ImageryLayerFactory.js`。`createXxxImageryLayer(options)` 同步返回 `Cesium.ImageryProvider`（非 Promise），需 `viewer.imageryLayers.addImageryProvider(provider)` 接入。
+
+| 方法 | 用途 | 关键 options |
+|---|---|---|
+| `createTdtImageryLayer(opts)` | 天地图影像/注记/地形 | `style: 'img'\|'cva'\|'ter'`, `key` |
+| `createAmapImageryLayer(opts)` | 高德影像/注记/电子 | `style: 'img'\|'cva'`, `crs: 'WGS84'` |
+| `createBaiduImageryLayer(opts)` | 百度电子/卫星/路况 | `crs: 'WGS84'`, `style: 'traffic'` |
+| `createTencentImageryLayer(opts)` | 腾讯影像 | `style: '1'\|'2'` |
+| `createGoogleImageryImageryLayer(opts)` | 谷歌影像（自实现） | — |
+| `createArcGisImageryLayer(opts)` | ArcGIS 影像 | `style: 'dark'` 暗色 |
+| `createSingleTileImageryLayer(opts)` | 单张图片 | `url`, `rectangle` |
+| `createWMSImageryLayer(opts)` | WMS | `url`, `layers`, `parameters` |
+| `createWMTSImageryLayer(opts)` | WMTS | `url`, `layer`, `tileMatrixSetID` |
+| `createXYZImageryLayer(opts)` | XYZ 瓦片 | `url` 模板 |
+| `createUrlTemplateImageryLayer(opts)` | XYZ 别名 | 同上 |
+| `createTMSImageryLayer(opts)` | TMS 服务 | `url` |
+| `createMapboxImageryLayer(opts)` | Mapbox | `mapId`, `accessToken` |
+| `createGridImageryLayer()` | 调试格网 | `color`, `cells` |
+| `createCoordImageryLayer()` | 调试瓦片坐标 | — |
+| `createImageryLayer(type, opts)` | 通用入口（自动绑 Popup/Highlight） | 按 `ImageryType` 分发 |
+
+`ImageryType` 枚举（`src/layer/imagery/ImageryType.js`）：`TDT / AMAP / BAIDU / TENCENT / Google / ARCGIS / SINGLE_TILE / WMS / WMTS / XYZ / COORD / GRID / TMS / MAPBOX / MAPBOX_STYLE`。
+
+## 2. TerrainFactory
+
+类路径 `src/layer/terrain/TerrainFactory.js`。**Cesium 1.143 异步语义**：`XYZ` / `ARCGIS` 返回 `Promise<TerrainProvider>`，必须 `await`；`NONE / GOOGLE / VR` 同步返回 `EllipsoidTerrainProvider`（GOOGLE/VR 已移除官方支持，降级 + warn）。
+
+| 方法 | 是否 Promise | 说明 |
+|---|---|---|
+| `createEllipsoidTerrain(opts)` | 否 | 椭球面无高程 |
+| `createUrlTerrain(opts)` | **是** | `Cesium.CesiumTerrainProvider.fromUrl(url, opts)` |
+| `createArcgisTerrain(opts)` | **是** | `ArcGISTiledElevationTerrainProvider.fromUrl(url, opts)` |
+| `createGoogleTerrain(opts)` | 否 | 1.117+ 已移除 `GoogleEarthEnterpriseTerrainProvider` |
+| `createVRTerrain(opts)` | 否 | 1.117+ 已移除 `VRTheWorldTerrainProvider` |
+| `createTerrain(type, opts)` | 类型决定 | 按 `TerrainType` 分发 |
+
+`TerrainType`（`src/layer/terrain/TerrainType.js`）：`NONE / XYZ / ARCGIS / GOOGLE / VR`。
+
+**Cesium World Terrain（1.143 推荐写法）**：
+```js
+viewer.scene.setTerrain(Cesium.Terrain.fromWorldTerrain());
+```
+旧式 `viewer.terrainProvider = new Cesium.CesiumTerrainProvider({...})` 在 1.143 已无效。
+
+## 3. Snippets
+
+<a id="s1"></a>
+### S1. 天地图影像 + 注记 — `examples/public/examples/html/basemap/tdtSatelliteImage.html` L78-L105
+```js
+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 }));
+```
+
+<a id="s2"></a>
+### S2. 高德影像 — `examples/public/examples/html/basemap/geodeSatelliteImage.html` L70-L90
+```js
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createAmapImageryLayer({ style: 'img', crs: 'WGS84' }));
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createAmapImageryLayer({ style: 'cva', crs: 'WGS84' }));
+```
+
+<a id="s3"></a>
+### S3. Cesium World Terrain — `examples/public/examples/html/basemap/CesiumTerrain.html` L53-L55
+```js
+viewer.scene.setTerrain(Cesium.Terrain.fromWorldTerrain());
+viewer.flyToPosition('115.3950, 39.9058, 18500,0,-9', 3);
+```
+
+<a id="s4"></a>
+### S4. ArcGIS 地形 — `examples/public/examples/html/basemap/ArcGISTerrain.html` L51-L56
+```js
+const provider = await Cesium.ArcGISTiledElevationTerrainProvider.fromUrl(
+    'https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer');
+viewer.terrainProvider = provider;
+viewer.flyToPosition('115.3950, 39.9058, 18500,0,-9', 3);
+```
+
+### S7. WMS — `examples/public/examples/html/offlinemap/geoServerWms.html` L46-L88
+```js
+const wms = ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.WMS, {
+    url: 'http://server.mars3d.cn/geoserver/mars/wms',
+    layers: 'mars:hf',
+    parameters: { transparent: true, format: 'image/png' },
+    rectangle: Cesium.Rectangle.fromDegrees(116.85, 31.53, 117.63, 32.16),
+    getFeatureInfoParameters: { feature_count: 10 },
+    selectedHighlight: { material: 'rgba(255,255,0,0.6)', height: 0.01 }
+});
+wms.bindPopup({ viewer, showTitle: true, useDefaultHtmlTemplate: true });
+wms.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    wms.popup.show(e.position, { title: 'wms', fieldsMap: [{
+        nameC: '名称', value: e.feature.data.properties['用地名称'] || '未知' }] });
+});
+viewer.imageryLayers.addImageryProvider(wms);
+```
+
+### S8. WMTS — `examples/public/examples/html/offlinemap/geoServerWmts.html` L40-L69
+```js
+const provider = new Cesium.WebMapTileServiceImageryProvider({
+    url: 'http://server.mars3d.cn/geoserver/gwc/service/wmts/rest/mars:hfgh/polygon/EPSG:4326/{TileMatrix}/{TileRow}/{TileCol}?format=image/png',
+    layer: 'mars:hfgh', style: 'polygon', tileMatrixSetID: 'EPSG:4326',
+    tilingScheme: new Cesium.GeographicTilingScheme(),
+    tileMatrixLabels: Array.from({ length: 22 }, (_, i) => `EPSG:4326:${i}`),
+    minimumLevel: 0, maximumLevel: 21,
+    rectangle: Cesium.Rectangle.fromDegrees(116.85, 31.53, 117.63, 32.16),
+    format: 'image/png', credit: new Cesium.Credit('合肥规划图') });
+viewer.imageryLayers.addImageryProvider(provider);
+```
+
+<a id="s9"></a>
+### S9. 卷帘对比 — `src/layer/imagery/SplitImageLayer.js` L8-L86
+```js
+const left = ANOVGIS.ImageryLayerFactory.createArcGisImageryLayer();
+const right = ANOVGIS.ImageryLayerFactory.createTdtImageryLayer({ style: 'img', key: globalConfig.tdtKey });
+const split = new ANOVGIS.SplitImageLayer(viewer, [left, right]);
+split.changeLeftRight();
+// split.destroy();  // 移除 slider 与 handler
+```
+
+<a id="s10"></a>
+### S10. 暗色主题 — `examples/public/examples/html/basemap/maptheme.html` L61-L78
+
+> ⚠️ **常见误区**:暗色 / 夜间 / 反色**不能**用 `layer.brightness = -1` / `layer.saturation = 0` 这种野路子——这是对图层属性的瞎调,不是 SDK 设计的暗色方案。SDK 专门有 `ImageryThemeGL` 做这件事。
+
+```js
+// 来源: examples/public/examples/html/basemap/maptheme.html L61-L78
+// 关键参数:invert=true(反色)+ bgColor=BLACK(背景)+ alpha(前景透明度)
+const theme = new ANOVGIS.ImageryThemeGL();
+theme.setTheme({
+    layer: viewer.imageryLayers.get(0),
+    bgColor: Cesium.Color.BLACK, alpha: 0.1,
+    invert: true, preMultiplyAlpha: true });
+// ⚠️ 改参必须 layer.show=false → setTheme → setTimeout(show=true, 100) 刷新
+```
+
+**setTheme 全部参数**:
+
+| 参数 | 含义 | 暗色系推荐 |
+|---|---|---|
+| `layer` | 目标 ImageryLayer | 第 0 层(底图) |
+| `invert` | 颜色反转(关键,反色成暗) | `true` |
+| `bgColor` | 背景色填充 | `Cesium.Color.BLACK` |
+| `alpha` | 前景透明度 0-1 | `0.1`(0=完全隐藏底图,1=原色) |
+| `preMultiplyAlpha` | 预乘 Alpha | `true` |
+
+## 4. 实战最佳实践
+
+1. **`createImageryLayer(type, opts)` 优先**：自动绑 Popup/Highlight；WMS/WMTS 走此路省事。
+2. **地形 1.143 必须 `await`**：`fromUrl` 是 Promise；`setTerrain` 是正确现代写法；不要用 `viewer.terrainProvider = new ArcGISTiledElevationTerrainProvider(...)`。
+
+## 5. 补充用法（snippet 续）
+
+<a id="s11"></a>
+### S11. WMS 接入 — `examples/public/examples/html/offlinemap/geoServerWms.html` L46-L64
+```js
+// 方式 A：通用入口（推荐，自动绑 Popup/Highlight）
+const wms = ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.WMS, {
+    url: 'http://server.mars3d.cn/geoserver/mars/wms',
+    layers: 'mars:hf',
+    parameters: { transparent: true, format: 'image/png' },
+    rectangle: Cesium.Rectangle.fromDegrees(116.85, 31.53, 117.63, 32.16)
+});
+viewer.imageryLayers.addImageryProvider(wms);
+// 方式 B：直接拿 Provider（不绑 Popup）
+const provider = ANOVGIS.ImageryLayerFactory.createWMSImageryLayer({
+    url, layers, parameters, rectangle,
+    getFeatureInfoParameters: { feature_count: 10 } });
+viewer.imageryLayers.addImageryProvider(provider);
+```
+
+<a id="s12"></a>
+### S12. WMTS 接入（tileMatrixLabels + style）— `examples/public/examples/html/offlinemap/geoServerWmts.html` L40-L67
+```js
+const wmts = ANOVGIS.ImageryLayerFactory.createWMTSImageryLayer({
+    url: 'http://server.mars3d.cn/geoserver/gwc/service/wmts/rest/mars:hfgh/polygon/EPSG:4326/{TileMatrix}/{TileRow}/{TileCol}?format=image/png',
+    layer: 'mars:hfgh',
+    style: 'polygon',
+    tileMatrixSetID: 'EPSG:4326',
+    tilingScheme: new Cesium.GeographicTilingScheme(),
+    // 关键：tileMatrixLabels 必须匹配服务的命名格式 "EPSG:4326:{z}"
+    tileMatrixLabels: Array.from({ length: 22 }, (_, i) => `EPSG:4326:${i}`),
+    minimumLevel: 0, maximumLevel: 21,
+    rectangle: Cesium.Rectangle.fromDegrees(116.85, 31.53, 117.63, 32.16),
+    format: 'image/png',
+    credit: new Cesium.Credit('合肥规划图')
+});
+viewer.imageryLayers.addImageryProvider(wmts);
+```
+
+<a id="s13"></a>
+### S13. XYZ 切片（含 subdomains 多子域）— `examples/public/examples/html/offlinemap/xyz.html` L54-L57
+```js
+// 方式 A：本地瓦片
+const xyz = ANOVGIS.ImageryLayerFactory.createXYZImageryLayer({
+    url: 'http://192.168.11.164:9000/anov-gis/geo3dstatic/imagery/tiles/{z}/{x}/{y}.png',
+    rectangle: Cesium.Rectangle.fromDegrees(116.38, 39.98, 117.39, 40.99)
+});
+// 方式 B：多子域（{s} 占位 + subdomains）— SDK 透传给 Cesium.UrlTemplateImageryProvider
+const provider = ANOVGIS.ImageryLayerFactory.createUrlTemplateImageryLayer({
+    url: 'http://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png',
+    subdomains: ['a', 'b', 'c', 'd'],
+    credit: 'CartoDB / OSM'
+});
+viewer.imageryLayers.addImageryProvider(xyz);
+```
+
+<a id="s14"></a>
+### S14. SingleTileImageryLayer 单张图片覆盖 — `examples/public/examples/html/offlinemap/image.html` L57-L62
+```js
+// 截图 / 离线静态图，按 rectangle 贴到地表
+const imglayer = ANOVGIS.ImageryLayerFactory.createSingleTileImageryLayer({
+    rectangle: Cesium.Rectangle.fromDegrees(116.3809, 39.9868, 116.3949, 39.9965),
+    url: 'http://192.168.11.164:9000/anov-gis/geo3dstatic/static/trees/tree.png'
+});
+const img = viewer.imageryLayers.addImageryProvider(imglayer);
+viewer.flyTo(img, 2, 0, -90, 4945000);
+```
+
+### S15. 影像 Provider 切换（增删 / 顺序 / alpha）— 通用 Cesium API
+```js
+// 增：addImageryProvider 返回 SDK 包装的 ImageryLayer 实例
+const base = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createTdtImageryLayer({ style: 'img', key: globalConfig.tdtKey }));
+const label = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createTdtImageryLayer({ style: 'cva', key: globalConfig.tdtKey }));
+// 顺序：底层 0，向上叠加；通过 viewer.imageryLayers 操作（SDK 包装对象本身没有 raiseToTop）
+viewer.imageryLayers.raiseToTop(label);   // ✅ 正确：透传到底层 Cesium 对象
+// ❌ label.raiseToTop() 会报 TypeError: label.raiseToTop is not a function
+// 透明度（常用属性 SDK 已包装透出）
+label.alpha = 0.6;
+// 显隐
+label.show = false;
+// 删
+viewer.imageryLayers.remove(base);
+// 清空（慎用）
+// viewer.imageryLayers.removeAll();
+```
+
+> ⚠️ SDK 包装的 ImageryLayer 不透出 `Cesium.ImageryLayer` 的所有方法（仅透出常用属性 `show` / `alpha` / `brightness` / `contrast` / `hue` / `saturation` / `gamma` / `splitDirection`）。其他方法必须通过 `viewer.imageryLayers.*` 调用。详见 [`anovgis-pitfalls` § P8](../anovgis-pitfalls/SKILL.md#p8-sdk-包装的-imagerylayer-不透出-cesium-原生方法)。
+
+### S16. TerrainProvider 异步 + setTerrain（模式 A 世界地形 / 模式 B 自定义 URL）— `examples/public/examples/html/basemap/CesiumTerrain.html` L53-L55、`offlinemap/terrain.html` L49-L54
+```js
+// 模式 A：Cesium World Terrain（推荐写法，1.143）
+viewer.scene.setTerrain(Cesium.Terrain.fromWorldTerrain());
+// 模式 B：自定义 URL（必须 await，fromUrl 返回 Promise）
+Cesium.CesiumTerrainProvider.fromUrl(
+    'http://192.168.11.164:9000/anov-gis/geo3dstatic/terrain/beijing_cesium2',
+    { requestVertexNormals: true }
+).then(provider => {
+    viewer.scene.setTerrain(new Cesium.Terrain(provider));
+});
+// 模式 B 走 ANOVGIS 工厂（同样返回 Promise）
+const provider = await ANOVGIS.TerrainFactory.createUrlTerrain({
+    url: 'http://host/terrain', requestVertexNormals: true
+});
+viewer.scene.setTerrain(new Cesium.Terrain(provider));
+```
+
+### S17. Viewer 地形渲染参数（深度测试 / 夸大地形）— Cesium 官方文档
+```js
+// 启用基于地形深度的测试（默认开启）：地形遮挡更准确，性能略降
+viewer.scene.globe.depthTestAgainstTerrain = true;
+// 关闭（默认）：entity/label 始终绘制在最上层，不被地形遮挡
+// viewer.scene.globe.depthTestAgainstTerrain = false;
+// 夸大地形倍数：拉大山体视觉效果（>=1.0）
+viewer.scene.verticalExaggeration = 2.0;          // 1.143+
+viewer.scene.verticalExaggerationRelativeHeight = 0.0;
+// 参考 Cesium 文档：https://cesium.com/learn/cesiumjs/ref-doc/Globe.html
+```
+
+### S18. 矢量瓦片(实为 XYZ raster) — `basemap/vectorTile.html` L25-L40
+
+```js
+// 来源: vectorTile.html L29-39
+// 题图虽叫 vectorTile,实际是 raster XYZ 切片加载 + LocateUtil.flyToPoint 定位
+window.viewer = new ANOVGIS.Viewer('cesiumContainer');
+const layer = new ANOVGIS.ImageryLayerFactory.createXYZImageryLayer({
+    url: 'http://your-server/tile/{z}/{x}/{y}',              // 自定义瓦片服务
+});
+viewer.imageryLayers.addImageryProvider(layer);
+// LocateUtil.flyToPoint(viewer, center, heading, pitch, range, duration)
+const center = Cesium.Cartesian3.fromDegrees(116.5, 40, 0);
+ANOVGIS.LocateUtil.flyToPoint(viewer, center, 0, -70, 5000000, 2);
+```
+
+### S19. 滤镜着色 + 抬高图层 — `basemap/test.html` L22-L137
+
+```js
+// 来源: test.html L39-136
+// 自定义 fragment shader 注入 czm_saturation 之后,实现反相/滤镜/对比度调整
+// ⚠️ 此 demo 用 Cesium 原生 UrlTemplateImageryProvider(因 SDK 没包装滤镜功能)
+viewer.imageryLayers.removeAll();
+viewer.imageryLayers.addImageryProvider(new Cesium.UrlTemplateImageryProvider({
+    url: 'https://webrd02.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=2&style=8&x={x}&y={y}&z={z}',
+    maximumLevel: 18,
+}));
+setViewerTheme(viewer, {
+    invertColor: false,                                      // 反相
+    filterColor: Cesium.Color.fromCssColorString('#4e70a6'),// 滤镜色
+    brightness: 0.6, contrast: 1.8, gamma: 0.3,
+    hue: 1, saturation: 0,
+});
+// 叠加 SDK 的 XYZ 切片
+const layer = new ANOVGIS.ImageryLayerFactory.createXYZImageryLayer({
+    url: '/tiles/{z}/{x}/{y}.png',
+});
+viewer.imageryLayers.addImageryProvider(layer);
+// 抬高(不置顶,仅 raise)
+viewer.imageryLayers.raise(layer);
+```
+
+### S20. 跨实例通信(父端 iframe 控子端 viewer) — `basemap/remote.html` L31-L101
+
+```js
+// 来源: remote.html L41-99
+// 关键 API: ANOVGIS.createInstance() + sendMessage / receiveMessage
+// 用于父页面统一控制子 iframe / webview 中的 viewer
+window.instance = ANOVGIS.createInstance();
+top.instance = window.instance;
+
+// 远端初始化 viewer
+instance.sendMessage({
+    name: 'ANOVGIS.init',
+    id: '1',
+    params: {
+        container: 'cesiumContainer',
+        geocoderType: ANOVGIS.GeocoderType.TIANDITU,
+        vrButton: false, baseLayerPicker: true, fullscreenButton: true,
+        homeButton: true, sceneModePicker: true, navigationHelpButton: true,
+        copyRight: false,
+    },
+});
+instance.receiveMessage((res) => { console.log(res); });
+
+// 监听远端相机
+instance.viewer.scene.camera.changed.addEventListener(() => {
+    if (!instance.viewer.scene.camera.isFlying) {
+        const position = instance.viewer.camera.positionWC.clone();
+        // ...做主从同步
+    }
+});
+
+// 远端聚焦
+instance.sendMessage({
+    name: 'viewer.scene.camera.focus', id: '2',
+    params: {
+        position: { x: -2178587.75, y: 4397006.30, z: 4075799.50 },
+        direction: { x: 0.3411047, y: -0.6884458, z: -0.6400703 },
+        up: { x: 0.2841681, y: -0.5735316, z: 0.7683164 },
+    },
+});
+```
+
+### S21. ArcGIS 卫星影像 — `basemap/ArcGISSatelliteImage.html` L62-L75
+
+```js
+// 来源: ArcGISSatelliteImage.html L62-L75
+// 关键 API: ANOVGIS.ImageryLayerFactory.createArcGisImageryLayer
+// ArcGIS World_Imagery(默认)
+const arcgis = viewer.imageryLayers.addImageryProvider(
+    await ANOVGIS.ImageryLayerFactory.createArcGisImageryLayer()
+);
+// 蓝黑暗色变体
+const arcgisDark = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createArcGisImageryLayer({ style: 'dark' })
+);
+```
+
+<a id="s22"></a>
+### S22. Google 卫星影像 — `basemap/GoogleSatelliteImage.html` L60-L70
+
+```js
+// 来源: GoogleSatelliteImage.html L60-L70
+// 关键 API: ANOVGIS.ImageryLayerFactory.createGoogleImageryImageryLayer
+const googleImg = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createGoogleImageryImageryLayer()
+);
+// 注记层(lyrs='h' = hybrid/标注层)
+const googleLbl = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createGoogleImageryImageryLayer({ lyrs: 'h' })
+);
+```
+
+### S23. 百度卫星影像 — `basemap/baiduSatelliteImage.html` L62-L75
+
+```js
+// 来源: baiduSatelliteImage.html L62-L75
+// 关键 API: ANOVGIS.ImageryLayerFactory.createBaiduImageryLayer(crs:'WGS84')
+// ⚠️ 必须传 crs:'WGS84'(百度默认是 BD09,不传会偏)
+const baidu = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createBaiduImageryLayer({ crs: 'WGS84' })
+);
+// 百度路况
+const baiduTraffic = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createBaiduImageryLayer({ crs: 'WGS84', style: 'traffic' })
+);
+```
+
+### S24. 腾讯卫星影像 — `basemap/tencentSatelliteImage.html` L61-L79
+
+```js
+// 来源: tencentSatelliteImage.html L61-L79
+// 关键 API: ANOVGIS.ImageryLayerFactory.createTencentImageryLayer
+// style:'img' = 卫星 / style:'2' = 注记 / 不传 style = 矢量电子地图
+const tencentImg = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createTencentImageryLayer({ style: 'img' })
+);
+const tencentLbl = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createTencentImageryLayer({ style: '2' })
+);
+const tencentMap = viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createTencentImageryLayer()       // 不传 style = 矢量电子地图
+);
+```
+
+<a id="s25"></a>
+### S25. terrainRGB 地形(⚠️ SDK 未包装,P0 反例) — `basemap/terrainrgb.html` L52-L123
+
+```js
+// 来源: terrainrgb.html L52-L123
+// ⚠️ P0 SDK 优先级铁律反例:terrainRGB SDK 没包装,需自己继承 Cesium.WebMapTileServiceImageryProvider
+//      推荐 SDK 后续补 ANOVGIS.ImageryLayerFactory.createTdtTerrainRgbImageryLayer({tk, layer})
+class GrayscaleImageryProvider extends Cesium.WebMapTileServiceImageryProvider {
+    constructor(options) {
+        super(options);
+        this._tilingScheme = new Cesium.WebMercatorTilingScheme();
+        this.maxHeight = -10000;
+        this.minHeight = 10000;
+    }
+    get tilingScheme() { return this._tilingScheme; }
+    async requestImage(x, y, level, request) {
+        const image = await super.requestImage(x, y, level, request);
+        return await this.convertToGrayscale(image);              // RGB -> height = -10000 + (r*65536 + g*256 + b) * 0.1
+    }
+}
+const shadedRelief1 = new GrayscaleImageryProvider({
+    url: 'https://lcdata.tianditu.gov.cn/terrain-rgb_w/wmts?tk=YOUR_TDT_KEY',
+    layer: 'terrain-rgb',
+    style: 'default',
+    format: 'tiles',
+    tileMatrixSetID: 'w',
+    maximumLevel: 19
+});
+viewer.imageryLayers.addImageryProvider(shadedRelief1);
+```
+
+<a id="s26"></a>
+### S26. EPSG:4490 矢量瓦片(CGCS2000 地理坐标) — `offlinemap/loadVectorTiles_4490.html` L36-L56
+
+```js
+// 来源: loadVectorTiles_4490.html L36-L56
+// 关键 API: ANOVGIS.ImageryLayerFactory.createWMTSImageryLayer
+// 关键参数: tileMatrixSetID:'EPSG:4490' + tilingScheme: new Cesium.GeographicTilingScheme()
+//          (区别于 WebMercator,4490 是地理坐标)
+window.viewer = new ANOVGIS.Viewer('cesiumContainer');
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.TDT, {
+        style: 'img', key: globalConfig.tdtKey
+    })
+);
+const layer = ANOVGIS.ImageryLayerFactory.createWMTSImageryLayer({
+    rectangle: Cesium.Rectangle.fromDegrees(113.07, 35.34, 113.56, 35.74),
+    url: 'http://icenter.geovis.online/tilecache/service/wmts/rest/GF1-PNG-4490/{style}/{TileMatrixSet}/{TileMatrix}/{TileRow}/{TileCol}?format=image/png',
+    layer: 'wmts', format: 'image/png', style: '',
+    tileMatrixSetID: 'EPSG:4490',                                // 关键:4490 矩阵集 ID
+    tilingScheme: new Cesium.GeographicTilingScheme(),            // 关键:地理坐标切片方案
+});
+viewer.imageryLayers.addImageryProvider(layer);
+viewer.flyTo(layer);
+```