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

package/skills/anovgis-layers/SKILL.md

@@ -0,0 +1,627 @@
+---
+name: anovgis-layers
+description: '@anov/gis 要素图层（14 个）。涵盖 VectorLayer / GeoJsonLayer / TopoJsonLayer / CzmlLayer / KmlLayer / GpxLayer / TilesetLayer / PrimitiveLayer / HtmlLayer / LabelLayer / ClusterLayer / GroundPrimitiveLayer / FeatureGridLayer / DynamicLayer，统一 viewer.addLayer / removeLayer / bindPopup / bindTooltip / addEventListener。触发关键词：图层、layer、GeoJSON、3D Tiles、CZML、KML、GPX、TopoJSON、ClusterLayer、HtmlLayer、FeatureGridLayer、addLayer、removeLayer、矢量瓦片、VectorTile、4490、切片加载、cluster 聚合、HTML 图层、CZML 时间轴、czml、playback、矢量瓦片 4490。Use when 加载 GeoJSON 行政区 / 3D Tiles 模型 / CZML 时序数据 / KML 标注 / 聚合点位 / DOM 叠加层 / 网格请求图层 / 4490 矢量瓦片 / 切片按视野分片加载。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# ANOVGIS 要素图层
+
+> ⚠️ **优先级**：本 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` 的 14 个要素图层类，负责矢量数据、模型、标注、聚合与 DOM 叠加。锁定 `@anov/gis` **v1.8.6**（Cesium **1.143.0**）。
+
+影像底图 / 地形请用 `anovgis-imagery-terrain`；单个 Entity 图元（Point/Polyline/Polygon 等）请用 `anovgis-vector-graphics`；3D Tiles / Model 加载 + 抽壳 + 调色请用 `anovgis-models-3dtiles`。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 `Tileset` 模型加载 + 拾取 + 抽壳 + 调色 → [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md)
+- ❌ 不要写离线 / WFS / 4490 / 内网 / 透明底图 / iServer 部署清单 → v0.3.0 `anovgis-offline-deployment`
+- ❌ 不要写 Vector 16 类（Point / Polyline / ...）用法 → [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md)
+- ❌ 不要写 Primitive 19 类 → [`anovgis-primitives`](../anovgis-primitives/SKILL.md)
+- ❌ 不要写 Popup / Tooltip 完整用法 → [`anovgis-popup-widget`](../anovgis-popup-widget/SKILL.md)
+
+## 统一生命周期
+
+类路径均在 `src/layer/graphic/`，全部继承 `Layer`（`src/layer/Layer.js`）：
+
+```js
+const layer = new ANOVGIS.VectorLayer();
+viewer.addLayer(layer);              // 接入
+layer.bindPopup({ viewer });         // 绑定弹窗
+layer.bindTooltip({ viewer });       // 绑定悬浮提示
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, e => {});
+layer.clear();                       // 清空内容
+viewer.removeLayer(layer);           // 移除（传 layer 实例，不是 layer.id）
+```
+
+> ⚠️ **`removeLayer` 必须传 layer 实例**：源码 `src/base/viewer/Viewer.js:662` → `_removeLayer(layer)` 内部取 `layer.type` 和 `layer.id`（`Viewer.js:585`）。
+> 传 `layer.id`（字符串）不会报错，但**层静默删不掉** —— `layer.type` 是 `undefined`，直接被 `hasOwnProperty` 挡掉。
+
+## 图层速查表
+
+| 类 | 构造函数 | 关键方法 | 备注 |
+|---|---|---|---|
+| `VectorLayer(opts?)` | `new VectorLayer()` | `addGraphic`, `eachGraphic`, `clear` | 最常用，自定义 Entity 容器（`CustomDataSource`） |
+| `GeoJsonLayer(data, opts)` | `data` = url/对象/TopoJSON | `toVectorLayer()`, `toModelLayer(url)`, `eachGraphic(cb)` | 加载远端 URL 后可转 `VectorLayer` |
+| `TopoJsonLayer(data, opts)` | 同上 | 继承 `GeoJsonLayer` | TopoJSON 格式 |
+| `CzmlLayer(opts)` | `{ url, ... }` | `eachGraphic(cb)` | CZML 时序数据 |
+| `KmlLayer(data, opts)` | `data` = url/对象 | `eachGraphic(cb)` | KML |
+| `GpxLayer(opts)` | `{ url }` | `eachGraphic(cb)` | GPS 轨迹 |
+| `TilesetLayer()` | 无参 | `addGraphic(tileset)`, `flyTo(...)` | 3D Tiles 容器；配合 `ANOVGIS.Tileset(url, opts)` |
+| `PrimitiveLayer()` | 无参 | `.points` / `.labels` / `.billboards` / `.polylines` / `.primitives` / `.clouds` | 暴露 `Cesium.PrimitiveCollection` 子集 |
+| `HtmlLayer(opts)` | `{ id }` | `addGraphic`, `flyTo`, `clear` | DOM 叠加层（`postRender` 同步位置） |
+| `LabelLayer(opts)` | `{ url }` | 自动从 GeoJSON 抽 `entity.name` 转 `Label` | 大量 Label 优化 |
+| `ClusterLayer(opts)` | `{ pixelRange, gradient, style, ... }` | `enableCluster`, `setHeight`, `clear` | 自动聚合；`style: 'circle' \| 'custom' \| 其他` |
+| `GroundPrimitiveLayer()` | 无参 | `clear` | 贴地形 PrimitiveCollection |
+| `FeatureGridLayer(opts)` | `{ url, tilingScheme, count, dataProperty, callback, maximumLevel }` | `clear`, `requestImage(x,y,lvl)` | 按瓦片请求后台拉数据并绘图 |
+| `DynamicLayer(opts?)` | `{}` | `clear` | 通用动态 `CustomDataSource` |
+
+## Snippets
+
+<a id="s1"></a>
+### S1. GeoJSON 行政区 + 样式
+
+```js
+// 来源: examples/public/examples/html/geojsonLayer/polygon.html (L106-L116)
+const style = {
+    stroke: Cesium.Color.fromCssColorString('rgba(46,145,229,1)'),
+    fill: Cesium.Color.fromCssColorString('rgba(46,145,229,0.3)'),
+    strokeWidth: 4, markerSize: 5, markerColor: Cesium.Color.CYAN
+};
+Cesium.GeoJsonDataSource.load(bj, style).then(ds => {
+    viewer.dataSources.add(ds);
+});
+```
+
+> `ANOVGIS.ApplyApi.createPolygonLayer` 提供业务封装（高亮 / 悬浮 / 文字标注），详见 `src/applyfn/applyBase.js`。
+
+### S2. 3D Tiles + 鼠标拾取
+
+```js
+// 来源: examples/public/examples/html/event/tilesetpopup.html (L48-L93)
+const layer = new ANOVGIS.TilesetLayer();
+viewer.addLayer(layer);
+
+const tileset = new ANOVGIS.Tileset({
+    url: buildConfig.gisStatic + 'beijingchouxi/tileset.json',
+    highlight: { color: '#ff0000' },
+    selectedHighlight: { color: 'rgba(255,0,255,0.8)' }
+});
+tileset.setStyle(new ANOVGIS.Cesium3DTileStyle({
+    color: { conditions: [
+        ['Number(${floor}) >= 40', 'rgba(45,0,75,0.5)'],
+        ['true', 'rgb(127,59,8)']
+    ]}
+}));
+layer.addGraphic(tileset);
+
+layer.bindPopup({ viewer, showTitle: true, useDefaultHtmlTemplate: true });
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    layer.popup.show(e.position, {
+        title: e.feature.getProperty('name1'),
+        fieldsMap: [{ nameC: '楼层', value: e.feature.getProperty('floor') }]
+    });
+});
+viewer.flyToTileset(tileset, 2, 0.5, -35);
+```
+
+### S3. VectorLayer 创建空容器 + addGraphic
+
+```js
+// 来源: examples/public/examples/html/event/popup.html (L48-L92)
+const layer = new ANOVGIS.VectorLayer({ id: 'pt-layer' });
+viewer.addLayer(layer);
+
+// 单个 Point + Popup
+const v = new ANOVGIS.Point(position, {
+    color: ANOVGIS.Color.WHITE,
+    pixelSize: 12,
+    outlineColor: ANOVGIS.Color.BLUE,
+    outlineWidth: 2,
+    label: { text: '文字标签', font: '25px sans-serif', color: '#ffff00',
+             clampToGround: true, verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+             pixelOffset: new Cesium.Cartesian2(0, -12) }
+});
+v.bindPopup({ viewer, showTitle: true, useDefaultHtmlTemplate: true });
+v.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    v.popup.show(e.position, e.graphic.infoData);
+});
+layer.addGraphic(v);
+
+viewer.flyTo(layer);
+```
+
+> `VectorLayer` 本质是 `CustomDataSource`，可与 Cesium 原生 Entity 混用；可加 `Point` / `Polyline` / `Polygon` / `Model` / `Billboard` / `Label`。
+
+### S4. GeoJsonLayer.toVectorLayer() 完整链
+
+```js
+// 来源: examples/public/examples/html/geojsonLayer/cluster.html (L36-L60)
+//        + graphics/divInfo2.html (L269-L294)
+let layer = new ANOVGIS.GeoJsonLayer('../modelData/json/shanxi2.json');
+layer = await layer.toVectorLayer();           // 拿到统一 VectorLayer
+viewer.addLayer(layer);
+viewer.flyTo(layer);
+
+layer.eachGraphic(v => {                        // v 是 Polygon / Polyline / Billboard
+    let poss = [].concat(...v.positions, v.positions[0]);   // 闭合环
+    v.setOptions({
+        material: Cesium.Color.fromCssColorString('#1b3377'),
+        fill: true,
+        polyline: { positions: poss, width: 1,
+                    material: Cesium.Color.fromCssColorString('#52b3f0') }
+    });
+});
+```
+
+> `toVectorLayer()` 内部按 entity 类型分派 `Billboard / Point / Polyline / Polygon / Label`；模型点位用 `toModelLayer(modelUrl)` 替身。
+
+### S5. VectorLayer bindPopup / highlight / tooltip 三件套
+
+```js
+// 来源: examples/public/examples/html/event/highlight.html (L60-L132)
+const layer = new ANOVGIS.VectorLayer({ id: 'layer' });
+viewer.addLayer(layer);
+
+const pointOption = {
+    color: ANOVGIS.Color.WHITE, pixelSize: 12,
+    outlineColor: ANOVGIS.Color.BLUE, outlineWidth: 2,
+    label: { text: '文字标签', font: '25px sans-serif', color: '#ffff00',
+             clampToGround: true, verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+             pixelOffset: new Cesium.Cartesian2(0, -12) },
+    infoData: { title: '标题',
+        fieldsMap: [{ nameC: '编号', value: 123 },
+                    { nameC: '姓名', value: '单位名称' }] },
+    highlight: { pixelSize: 17, outlineColor: '#ff0000', outlineWidth: 3 }  // 滑过样式
+};
+
+positions.forEach((p, i) => {
+    const opt = Cesium.clone(pointOption, true);
+    opt.infoData.title = `第${i}个标题`;
+    const point = new ANOVGIS.Point(p, opt);
+    point.bindTooltip({ viewer, showTitle: true, offsetY: '-10', useDefaultHtmlTemplate: true });
+    point.addEventListener(ANOVGIS.MouseEventType.MOUSE_MOVE, (e) => {
+        point.tooltip.show(e.position, e.graphic.infoData);
+    });
+    layer.addGraphic(point);
+});
+
+layer.bindPopup({ viewer, showTitle: true });
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    layer.popup.show(e.position, e.graphic.infoData);
+});
+viewer.flyTo(layer);
+```
+
+> `infoData` 字段是默认 Popup / Tooltip 模板的输入；非默认模板时 `popup.show(pos, '<html-string>')`。
+
+### S6. CzmlLayer 时序数据 + clock 配置
+
+```js
+// 来源: SDK src/layer/graphic/CzmlLayer.js (L1-L43) + Cesium CzmlDataSource 标准用法
+const layer = new ANOVGIS.CzmlLayer({ url: '/data/path.czml' });
+viewer.addLayer(layer);
+
+// 时序播放：把数据自带 clock 设到 viewer
+layer.eachGraphic(() => {});   // 先触发 load 解析（可选）
+viewer.clock.shouldAnimate = true;
+viewer.clock.multiplier = 2;                       // 2× 速
+viewer.timeline.zoomTo(layer._nativeObjCesium     // Cesium Promise CzmlDataSource
+    ? layer._nativeObjCesium.clock.startTime
+    : Cesium.JulianDate.now(),
+    layer._nativeObjCesium.clock.stopTime);
+```
+
+> CZML 自带 `availability` / `epoch` 字段，会自动生成 `Clock`；加载完成后 `viewer.dataSources` 内已注册，无需手动播放控制；若想停表动画 `viewer.clock.shouldAnimate = false`。
+
+### S7. TilesetLayer 3D Tiles + ready 回调 + click 拾取
+
+```js
+// 来源: examples/public/examples/html/event/tilesetpopup.html (L48-L108) + src/graphic/model/Tileset.js
+const layer = new ANOVGIS.TilesetLayer();
+viewer.addLayer(layer);
+
+const tileset = new ANOVGIS.Tileset({
+    url: buildConfig.gisStatic + 'model/tileset.json',
+    highlight: { color: '#ff0000' },                       // 滑过
+    selectedHighlight: { color: 'rgba(255,0,255,0.8)' }    // 选中
+});
+tileset.ready(ts => {                                      // 加载完成回调
+    ts.pointShadowing.enabled = true;
+    console.log('tileset ready', ts);
+});
+layer.addGraphic(tileset);
+
+layer.bindPopup({ viewer, showTitle: true, useDefaultHtmlTemplate: true });
+layer.bindTooltip({ viewer, showTitle: false, offsetY: '-10', useDefaultHtmlTemplate: true });
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    layer.popup.show(e.position, {
+        title: e.feature.getProperty('name1'),
+        fieldsMap: [{ nameC: '楼层', value: e.feature.getProperty('floor') }]
+    });
+});
+layer.addEventListener(ANOVGIS.MouseEventType.MOUSE_MOVE, (e) => {
+    layer.tooltip.show(e.position, e.feature.getProperty('name1'));
+});
+viewer.flyToTileset(tileset, 2, 0.5, -35);
+```
+
+> Cesium 1.143 已删除 `readyEvent`，统一 `Cesium3DTileset.fromUrl()` 返回 Promise；SDK 用 `tileset.ready(cb)` 兜底。
+
+<a id="s8"></a>
+### S8. ClusterLayer 聚合 + 自定义图标
+
+```js
+// 来源: examples/public/examples/html/geojsonLayer/cluster.html (L87-L153)
+//        + SDK src/layer/graphic/ClusterLayer.js
+const layer = new ANOVGIS.ClusterLayer({
+    style: 'circle',                                       // 'circle' | 'custom' | 其他(蛛网)
+    pixelRange: 40,
+    gradient: { 0.0001: Cesium.Color.fromCssColorString('#928875'),
+                0.001:  Cesium.Color.fromCssColorString('#928875'),
+                0.01:   Cesium.Color.fromCssColorString('#928875'),
+                0.1:    Cesium.Color.fromCssColorString('#928875') },
+    fontColor: Cesium.Color.fromCssColorString('#f0f0f0'),
+    boderColor: Cesium.Color.fromCssColorString('#ffd673'),
+    outColor: Cesium.Color.fromCssColorString('#ffd673').withAlpha(0.2),
+});
+viewer.addLayer(layer);
+
+data.forEach(v => {
+    const pos = `${v.longitude},${v.latitude},0`;
+    layer.addGraphic(new ANOVGIS.Billboard(pos, { image: './assets/camera.png' }));
+});
+
+layer.bindPopup({ viewer, showTitle: false, useDefaultHtmlTemplate: true });
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    layer.popup.show(e.position, e.graphic.name);
+});
+// 聚合点点击：缩放到子项
+viewer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    const ce = e.clusterEntity;
+    if (ce) {
+        const target = ce.id || ce.label?.id;
+        if (target) viewer.flyTo(target, 2, 0, -90, 0);
+    }
+});
+```
+
+> `style: 'custom'` 时 `gradient` 的 value 直接当 `image` 字符串（base64 dataURL 或 URL）；`enableCluster = false` 可关聚合。
+
+<a id="s9"></a>
+### S9. HtmlLayer DOM 叠加 + 绝对定位 div
+
+```js
+// 来源: examples/public/examples/html/graphics/divInfo.html (L111-L135)
+//        + graphics/divInfo2.html (L165-L268)
+const layer = new ANOVGIS.HtmlLayer({ layerName: 'info' });
+viewer.addLayer(layer);
+
+const div = new ANOVGIS.DivIcon(
+    new ANOVGIS.Position(116.38105869, 39.10115627, 1),
+    `<div class="boxbg">
+        <img class="div-img" src="../modelData/images/gyqy.png" />
+        <div class="div-right">天然纤维是自然界原有的...</div>
+        <div class="div-bottom">
+            <div class="div-info">河北棉花</div>
+            <div class="div-info">新疆棉花</div>
+        </div>
+    </div>`
+);
+div.setOptions({
+    horizontalOrigin: 'CENTER', verticalOrigin: 'TOP',  // 对齐锚点
+    offsetX: 0, offsetY: -60,
+    pointerEvents: true,                                // 开启后 DOM 可交互
+    scaleByDistance: { near: 0, nearValue: 1.0, far: 10000, farValue: 0.0 }
+});
+div.addEventListener(ANOVGIS.MouseEventType.CLICK, () => alert('点击了'));
+layer.addGraphic(div);
+
+viewer.flyTo(layer, 3, 0, -60, 100);   // 自动取所有 graphic 位置 flyTo
+```
+
+> `HtmlLayer` 通过 `scene.postRender` 每帧把 `cartesianToCanvasCoordinates` 写到 DOM `transform`；DOM 节点建议 < 1000，否则掉帧。`pointerEvents:false` 时 DOM 不接收事件，鼠标穿透到 Cesium 拾取。
+
+### S10. Primitive 版海量点 marker — `geojsonLayer/primitiveMarker.html` L23-L227
+
+```js
+// 来源: primitiveMarker.html L171-217
+// 用 Cesium 原生 PointPrimitiveCollection 做海量点(不走 SDK Entity,性能更好)
+const collection = viewer.scene.primitives.add(new Cesium.PointPrimitiveCollection());
+function addPoint([lng, lat, height], style) {
+    collection.add({
+        position: Cesium.Cartesian3.fromDegrees(lng, lat, height || 0),
+        color:    Cesium.Color.fromCssColorString(style.color),
+        pixelSize: style.pixelSize,
+        outlineColor: Cesium.Color.fromCssColorString(style.outlineColor),
+        outlineWidth: style.outlineWidth,
+    });
+}
+// 备选(被注释): ANOVGIS.ApplyApi.createClusterLayer / createPointLayer
+// ANOVGIS.ApplyApi.createClusterLayer(viewer).createCluster({
+//     pointList, gradient: ['rgba(186,53,0,0.8)', ...], infoHtml,
+//     isHover, isClick, pointClick
+// });
+```
+
+### S11. 矢量墙体(Wall) — `geojsonLayer/wall.html` L23-L84
+
+```js
+// 来源: wall.html L35-66
+// 用 viewer.entities 原生 + WallFlowMaterialProperty 流光
+const wallEntity = viewer.entities.add({
+    name: '矢量墙体',
+    wall: {
+        positions: Cesium.Cartesian3.fromDegreesArray(position),
+        maximumHeights: new Array(positions.length).fill(1000),
+        minimumHeights: new Array(positions.length).fill(0),
+        material: Cesium.Color.fromCssColorString('rgba(255,255,0,0.5)'),
+        outline: true,
+        outlineColor: Cesium.Color.fromCssColorString('rgba(255,255,0,1)'),
+    },
+});
+viewer.flyTo(wallEntity);
+```
+
+### S12. 墙体楼块(双层渲染) — `geojsonLayer/wallBuilds.html` L23-L180
+
+```js
+// 来源: wallBuilds.html L72-L177
+// 演示墙体(Entity + WallFlowMaterialProperty) + 楼顶(GeoJsonDataSource) 双层
+function addWall(positions, entity) {
+    for (let cor of positions) {
+        const wallObj = {
+            name: entity.name,
+            wall: {
+                positions: Cesium.Cartesian3.fromDegreesArray(handleCoordinates(cor.coordinates)),
+                maximumHeights: new Array(cor.coordinates.length).fill(cor.height),
+                minimumHeights: new Array(cor.coordinates.length).fill(0),
+            }
+        };
+        if (entity.isCustomMaterial && entity.material) {
+            wallObj.wall.material = entity.material;
+        } else if (!entity.isGradient) {
+            wallObj.wall.material = Cesium.Color.fromCssColorString(entity.color);
+        } else {
+            wallObj.wall.material = new ANOVGIS.WallFlowMaterialProperty({
+                color: Cesium.Color.fromCssColorString(entity.color),
+                duration: 2500
+            });
+        }
+        viewer.entities.add(wallObj);
+    }
+}
+function addRoof(geojson, buildObj) {
+    Cesium.GeoJsonDataSource.load(geojson).then((datasource) => {
+        viewer.dataSources.add(datasource);
+        for (let entity of datasource.entities.values) {
+            const height = entity.properties['height'].getValue();
+            entity.polygon.height = height * floorHeight;
+            entity.polygon.material = Cesium.Color.fromCssColorString(buildObj.color);
+            entity.polygon.outline = buildObj.isOutline;
+            entity.polygon.outlineColor = Cesium.Color.fromCssColorString(buildObj.outlineColor);
+        }
+    });
+}
+```
+
+<a id="s13"></a>
+### S13. 天地图 WFS GeoJSON — `offlinemap/wfs.html` L29-L82
+
+```js
+// 来源: wfs.html L42-82
+// 直接 Cesium.GeoJsonDataSource.load(不走 SDK helper),适合"想上色时仍可用原生 API"
+window.viewer = new ANOVGIS.Viewer('cesiumContainer');
+viewer.imageryLayers.addImageryProvider(
+    ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.TDT, {
+        style: 'img', key: globalConfig.tdtKey
+    })
+);
+
+function buildWfsUrl(config) {
+    const params = new URLSearchParams({
+        service: 'WFS', version: config.version, request: 'GetFeature',
+        typeName: config.layers, outputFormat: config.outputFormat, srsName: 'EPSG:4326',
+    });
+    return `${config.url}?${params.toString()}`;
+}
+const wfsConfig = {
+    url: 'http://gisserver.tianditu.gov.cn/TDTService/wfs',
+    layers: 'LRRL',                                          // LRRL=铁路, LRDL=公路
+    version: '1.1.0', outputFormat: 'application/json',
+};
+const geoJsonData = await (await fetch(buildWfsUrl(wfsConfig))).json();
+const dataSource = await Cesium.GeoJsonDataSource.load(geoJsonData, {
+    stroke: Cesium.Color.BLUE, strokeWidth: 2, strokeOpacity: 0.8
+});
+viewer.dataSources.add(dataSource);
+```
+
+### S14. 河南高铁(虚实线 + layer 级 popup) — `offlinemap/railway.html` L116-L299
+
+```js
+// 来源: railway.html L127-L285
+// 关键: dashPattern 区分隧道(虚线) / 市区 / 山区 / 平原 + layer 级 bindPopup
+const railLayer = new ANOVGIS.VectorLayer();
+viewer.addLayer(railLayer);
+railLayer.bindPopup({ viewer, showTitle: true, horizontalOrigin: 'CENTER', verticalOrigin: 'TOP', useDefaultHtmlTemplate: true });
+railLayer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    if (e.graphic) railLayer.popup.show(e.position, e.graphic.infoData);
+});
+
+geoJsonData.features.forEach(feature => {
+    const props = feature.properties;
+    const isTunnel = props.tunnel === 'yes';
+    const lineDash = isTunnel ? [20, 10] : undefined;          // 虚线 = 隧道
+    const infoData = {
+        title: '高铁线路信息',
+        fieldsMap: [
+            { nameC: '线路名称：', value: props.name || '高铁线' },
+            { nameC: '距市区：',    value: props.distance + '米' },
+        ],
+    };
+    coords.forEach(seg => {
+        const polyline = new ANOVGIS.Polyline(seg, {
+            material: lineColor, width: lineWidth,
+            dashPattern: lineDash,                             // 虚实线
+            infoData,
+        });
+        railLayer.addGraphic(polyline);
+    });
+});
+viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(113.5, 34.0, 900000) });
+```
+
+### S15. SuperMap iServer WMS + bindPopup — `offlinemap/iServerWmsCGI.html` L24-L90
+
+```js
+// 来源: iServerWmsCGI.html L27-89
+// 关键: getFeatureInfoParameters 触发 GetFeatureInfo,selectedHighlight 点击高亮 + 弹字段表
+const wms = ANOVGIS.ImageryLayerFactory.createImageryLayer(ANOVGIS.ImageryType.WMS, {
+    url: 'http://110.6.113.2:8090/iserver/services/map-nongda2608/wms111/CGI',
+    layers: '0',
+    parameters: { transparent: true, format: 'image/png' },
+    rectangle: Cesium.Rectangle.fromDegrees(119.799, 49.270, 120.110, 49.503),
+    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: 'CGI 点击查询',
+        fieldsMap: Object.keys(e.feature.data.properties || {}).map(key => ({
+            nameC: key + '：', value: e.feature.data.properties[key] || '未知',
+        })),
+    });
+});
+viewer.imageryLayers.addImageryProvider(wms);
+viewer.flyTo(wms);
+```
+
+### S16. GeoJSON 点位 billboard(交替图片) — `geojsonLayer/billboard.html` L65-L101
+
+```js
+// 来源: billboard.html L65-L101
+// 注:本 demo 未用 GeoJsonLayer,直接遍历 points 数组 + viewer.entities.add
+function showPoints(points) {
+    const billboard1 = { image: '../modelData/images/upRule.png' };
+    const billboard2 = { image: '../modelData/images/underRule.png' };
+    let i = 1;
+    for (let position of points) {
+        if (i > 1000) break;
+        let lng = +position.lnglat[0], lat = +position.lnglat[1];
+        const entity = viewer.entities.add({
+            position: Cesium.Cartesian3.fromDegrees(lng, lat),
+            billboard: i % 2 === 0 ? billboard2 : billboard1,    // 交替图片
+        });
+        i++;
+    }
+}
+```
+
+### S17. GeoJSON 折线(原生命码) — `geojsonLayer/marker.html` L63-L74
+
+```js
+// 来源: marker.html L63-L74
+// 注:文件名 marker.html 但内容是 polyline 演示
+Cesium.GeoJsonDataSource.load(geojson).then((datasource) => {
+    viewer.dataSources.add(datasource);
+    for (let entity of datasource.entities.values) {
+        entity.polyline.width = 1;
+        entity.polyline.material = Cesium.Color.fromCssColorString('rgba(255,255,0,0.5)');
+    }
+});
+```
+
+### S18. GeoJSON 多边形楼块(基础版,绝对高度) — `geojsonLayer/polygonBuilds.html` L233-L264
+
+```js
+// 来源: polygonBuilds.html L233-L264
+// 关键: 绝对高度(不贴地),适合无地形场景避免建筑漂移
+Cesium.GeoJsonDataSource.load(geojson).then((datasource) => {
+    viewer.dataSources.add(datasource);
+    for (let entity of datasource.entities.values) {
+        let height = 0;
+        entity.polygon.height = 0;                               // 距椭球面 0 米
+        if (entity.properties.hasOwnProperty('height')) {
+            const val = entity.properties['height'].getValue();
+            if (!isNaN(val)) height = val - 0;
+        }
+        entity.polygon.extrudedHeight = height;                   // 从属性读拉伸高度
+        entity.polygon.outline = true;
+        entity.polygon.material = Cesium.Color.fromCssColorString('rgba(62,171,107,0.8)');
+        entity.polygon.outlineColor = Cesium.Color.fromCssColorString('rgba(62,171,107,0.4)');
+    }
+});
+```
+
+### S19. GeoJSON 多边形楼块(贴地 + floorHeight 倍率) — `geojsonLayer/polygonBuildsMaterial.html` L64-L89
+
+```js
+// 来源: polygonBuildsMaterial.html L64-89
+// 关键: HeightReference.RELATIVE_TO_GROUND + extrudedHeight = height * 3(floorHeight)
+const floorHeight = 3;
+Cesium.GeoJsonDataSource.load(geojson).then((datasource) => {
+    viewer.dataSources.add(datasource);
+    for (let entity of datasource.entities.values) {
+        let height = 0;
+        entity.polygon.heightReference = Cesium.HeightReference.RELATIVE_TO_GROUND;
+        entity.polygon.height = 0;
+        entity.polygon.extrudedHeightReference = Cesium.HeightReference.RELATIVE_TO_GROUND;
+        if (entity.properties.hasOwnProperty('height')) {
+            const val = entity.properties['height'].getValue();
+            if (!isNaN(val)) height = val - 0;
+        }
+        entity.polygon.extrudedHeight = height * floorHeight;    // 按层高 3 米拉伸
+        entity.polygon.outline = true;
+        entity.polygon.material = Cesium.Color.fromCssColorString('rgba(62,171,107,0.8)');
+        entity.polygon.outlineColor = Cesium.Color.fromCssColorString('rgba(62,171,107,0.4)');
+    }
+});
+```
+
+### S20. GeoJSON 多边形楼块(自定义 GLSL 材质) — `geojsonLayer/polygonBuildsMaterial.html` L83-L122
+
+```js
+// 来源: polygonBuildsMaterial.html L83-L122
+// 关键: 给每个 polygon 应用自定义 Cesium.Material,fabric 内嵌 GLSL 按 UV 输出颜色
+entity.polygon.outline = false;                                  // 关闭 outline
+entity.polygon.material = new Cesium.Material({
+    translucent: false,
+    fabric: {
+        uniforms: {
+            // image / gradient / decoration 三个图片 uniform 按需填
+        },
+        source: `
+            czm_material czm_getMaterial(czm_materialInput materialInput) {
+                czm_material material = czm_getDefaultMaterial(materialInput);
+                // 按立面 UV 输出颜色(st ∈ [0,1])
+                material.diffuse = vec3(materialInput.st, 1.0);
+                material.alpha = 1.0;
+                return material;
+            }
+        `,
+    },
+});
+```
+
+## 实战最佳实践
+
+1. **`TilesetLayer` 容器 + `Tileset` 实例**：必须 `layer.addGraphic(tileset)` 之后才有 popup / 事件；定位用 `viewer.flyToTileset(tileset, duration, offsetX, pitch)`。
+2. **GeoJSON 转 `VectorLayer`**：`geoJsonLayer.toVectorLayer()` 拿到统一容器；模型点位用 `toModelLayer(modelUrl)`。
+3. **`ClusterLayer` 配色**：`gradient: { 阈值: 颜色, ... }` 按"占比"分档；`style: 'custom'` 时 value 直接当图片。
+4. **`HtmlLayer` 性能**：DOM 节点 < 1000 较稳；大量点位改用 `LabelLayer` 或 `PrimitiveLayer.labels`。
+5. **`FeatureGridLayer` 适用场景**：海量点位按视野瓦片分片拉取，`callback` 里自行绘制，避免一次性加载全量。
+
+## 参考
+
+- 图层基类：`src/layer/Layer.js`
+- 要素图层：`src/layer/graphic/`
+- 3D Tiles 封装：`ANOVGIS.Tileset` (`src/graphic/model/Tileset.js`)
+- 业务封装：`src/applyfn/applyBase.js`