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

package/skills/anovgis-vector-graphics/SKILL.md

@@ -0,0 +1,602 @@
+---
+name: anovgis-vector-graphics
+description: '@anov/gis 图元层（Graphic 体系）。涵盖 Graphic 抽象类 API、Vector 16 类（Point/Polyline/Polygon/Circle/Ellipse/Rect/Wall/Box/Cylinder/Ellipsoid/Corridor/PolylineVolume/Plane/Billboard/Label）、Model 2 类（Model / Tileset）、Primitive 17 类（Billboard/BounceBillboard/BounceLabel/Cloud/DiffuseWall/ElecEllipsoid/FlowLine/LabelPrimitive/LightCylinder/ModelPrimitive/PointPrimitive/PolylinePrimitive/ScanCircle/TrailLine/Video/Water）、8 个典型 snippet。触发关键词：graphic、Point、Polyline、Polygon、Billboard、Label、Tileset、Primitive、WaterPrimitive、ScanCirclePrimitive、TrailLinePrimitive、highlight、selectedHighlight、bindPopup、addEventListener、customshader、自定义 shader、GLSL、cesium_three、three.js 融合、ThreeLayer、div 弹窗、divInfo。Use when 创建点/线/面/图标/文字/立方体/球/圆柱、加载 3D Tiles 模型 + 鼠标拾取 popup、做扫描圆 / 雷达 / 尾迹线 / 动态水面 / 流动线 Primitive 版、绑定 Popup 或 Tooltip、div 弹窗。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# anovgis-vector-graphics — @anov/gis 图元层速查
+
+> ⚠️ **优先级**：本 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` 中所有"看得见的实体"都继承自抽象类 `Graphic`。本 skill 涵盖 Vector（16）、Model（2）、Primitive（17）共 35 个图元 + Graphic 基类 API + 8 个真实 snippet。锁定 `@anov/gis` **v1.8.6**（Cesium **1.143.0**）。
+>
+> 源码根：`src/graphic/index.js`；抽象类：`src/graphic/Graphic.js`（仅作语义锚点，不要去翻 `node_modules` 实物）。
+>
+> **与 material 体系的边界**：扫描圆 / 流动线 / 扩散墙有 *两套*——`ScanCirclePrimitive` / `FlowLinePrimitive` / `DiffuseWallPrimitive`（Primitive 版，独立 Graphic）与 `CircleScanMaterialProperty` / `PolylineFlowMaterialProperty` / `WallFlowMaterialProperty`（Property 版，挂 entity.material）。本文件只覆盖 Primitive 版；Property 版见 `anovgis-materials`。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 Primitive 19 类完整用法（本文件仅 §4 + §5 提到 17 类作为衔接，权威列表见 [`anovgis-primitives`](../anovgis-primitives/SKILL.md)）
+- ❌ 不要写 `Tileset` 加载 + 拾取 + 抽壳 + 调色 → [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md)
+- ❌ 不要写 `bindPopup` / `bindTooltip` / `highlight` 业务封装 + `tilesetpopup` / `imagerylayerpopup` → [`anovgis-popup-widget`](../anovgis-popup-widget/SKILL.md)
+- ❌ 不要写 `*MaterialProperty`（挂在 entity.material 上的版本） → [`anovgis-materials`](../anovgis-materials/SKILL.md)
+- ❌ 不要写 Draw / Measure / HeatMap / WindLayer → [`anovgis-analysis`](../anovgis-analysis/SKILL.md)
+- ❌ 不要写 `ThreeLayer` 桥接 → v0.3.0 `anovgis-three-layer`
+
+---
+
+## 1. Graphic 抽象类 API
+
+所有 Vector / Model / Primitive 子类都继承以下能力：
+
+```js
+// 属性
+graphic.graphicId        // 内部 uuid（只读）
+graphic.businessID       // 业务 id（set id(...) 等价）
+graphic.type             // 子类类型字符串（'polygon'/'billboard'/'tileset'/'water_primitive'...）
+graphic.nativeObjCesium  // 对应的 Cesium 原生对象（Entity / Primitive / Cesium3DTileset / Promise）
+graphic.attr             // 业务属性（任意 JSON）
+graphic.show = true      // 显隐（同步到 _nativeObjCesium.show）
+graphic.state            // 内部状态（INITIALIZED / ADDED / REMOVED）
+graphic.contextMenu      // 右键菜单数组
+
+// 行为
+graphic.setOptions(style)            // 修改样式（不同子类签名不同）
+graphic.addTo(layer)                 // 加入图层（layer.addGraphic 的别名）
+graphic.remove()                     // 从图层移除（layer.removeGraphic）
+graphic.addEventListener(type, fn)   // 订阅事件（MouseEventType / GraphicEventType）
+graphic.removeEventListener(type, fn)
+graphic.raiseEvent(type, params)     // 主动触发事件
+graphic.bindPopup(opts)              // 绑定 Popup（用于 click 时弹信息框）
+graphic.bindTooltip(opts)            // 绑定 Tooltip
+
+// 飞行（由 Viewer 提供，Graphic 本身不定义 flyTo）
+viewer.flyTo(graphic | layer | [lng,lat,height])
+viewer.flyToTileset(tileset, pitch, range, heading)   // Tileset 专用
+```
+
+事件枚举（`ANOVGIS.MouseEventType`）：`CLICK / RIGHT_CLICK / MOUSE_MOVE / MOUSE_OUT / LEFT_DOWN / LEFT_UP / WHEEL`。
+
+容器 Layer：`VectorLayer`（Point/Polyline/Polygon/...）/ `TilesetLayer`（Tileset）/ `PrimitiveLayer`（Primitive）。`layer.addGraphic(g)` 触发 `ADDED` 状态。
+
+---
+
+<a id="vector-table"></a>
+## 2. Vector 速查表（16 类，全部继承自 Graphic，内部用 `Cesium.Entity`）
+
+| 类 | 构造签名（简化） | 典型用途 |
+|---|---|---|
+| `Point` | `new Point(position, options)` | 单点；可挂 `label` 子图元 |
+| `Polyline` | `new Polyline(positions, options)` | 折线；至少 2 点 |
+| `Polygon` | `new Polygon(positions, options)` | 面；支持 `holes` |
+| `Circle` | `new Circle(center, options)` | 圆面 |
+| `Ellipse` | `new Ellipse(center, options)` | 椭圆面 |
+| `Rect` | `new Rect(west/south/east/north, options)` | 矩形面（Rectangle） |
+| `Wall` | `new Wall(positions, options)` | 墙（带高度的面） |
+| `Box` | `new Box(position, options)` | 立方体 |
+| `Cylinder` | `new Cylinder(position, options)` | 圆柱 |
+| `Ellipsoid` | `new Ellipsoid(position, options)` | 球 |
+| `Corridor` | `new Corridor(positions, options)` | 走廊 |
+| `PolylineVolume` | `new PolylineVolume(positions, profile, options)` | 沿线拉伸体 |
+| `Plane` | `new Plane(origin, options)` | 平面 |
+| `Billboard` | `new Billboard(position, options)` | 图标；支持 `image` URL/Canvas |
+| `Label` | `new Label(position, options)` | 文字；`font` 字段可指定自定义字体 |
+| `DivIcon` | `new DivIcon(options)` | DOM 图标（与 Billboard 平行） |
+
+通用 options：`material / outline / outlineColor / outlineWidth / height / heightReference / clampToGround / classificationType / label（Point/Polygon 内嵌）/ billboard（Polygon 内嵌）/ highlight / selectedHighlight / infoData`。
+
+**高亮机制**：构造时传 `highlight: { material: ..., width: ... }`，鼠标悬停时自动切换；`selectedHighlight` 用于 click 后保持高亮。
+
+---
+
+## 3. Model 速查表（2 类）
+
+```js
+new ANOVGIS.Model({ position, url, ... })   // 单 glTF 模型（单 options 对象）
+new ANOVGIS.Tileset(options)               // 3D Tiles
+```
+
+> ⚠️ `Model` 只收**一个 options 对象**（源码 `src/graphic/model/Model.js:7` 是 `constructor(options)`），`position` / `url` 都在里面 —— 不是 `(url, options)`。
+
+### `Tileset`（3D Tiles，重点）
+
+```js
+const tileset = new ANOVGIS.Tileset({
+    url: '...tileset.json',
+    maximumScreenSpaceError: 6,
+    skipLevels: true,
+    highlight: { color: '#ff0000' },           // 鼠标悬停样式
+    selectedHighlight: { color: 'rgba(255,0,255,0.8)' }
+})
+
+tileset.ready(t => console.log('loaded', t))   // 异步加载完成回调（Cesium 1.143 fromUrl → Promise）
+tileset.clampToGround()                        // 贴地
+tileset.setStyle(new ANOVGIS.Cesium3DTileStyle({ color: 'condition' }))
+tileset.setTileVisible(callback)               // 瓦片可见回调
+```
+
+> Cesium 1.143：`tileset._nativeObjCesium` 现在是 `Promise<Cesium3DTileset>`（来自 `Cesium3DTileset.fromUrl`）；SDK 内部已封装，请用 `tileset.ready(callback)` 替代旧的 `readyEvent`。
+
+`Model` 为单 glTF 模型；addTo 后用 `viewer.flyTo(graphic)` 定位。
+
+---
+
+## 4. Primitive 速查表（17 类，全部继承自 Graphic，内部用 `Cesium.Primitive` / `GroundPrimitive`）
+
+| 类 | 构造签名 | 用途 / 关键 options |
+|---|---|---|
+| `BillboardPrimitive` | `(position, options)` | 高性能图标（用 `BillboardCollection`） |
+| `BounceBillboardPrimitive` | `(position, options)` | 跳动图标 |
+| `BounceLabelPrimitive` | `(position, options)` | 跳动文字 |
+| `CloudPrimitive` | `(options)` | 云层 |
+| `DiffuseWallPrimitive` | `(positions, options)` | 扩散墙体（Primitive 版，非 WallFlowMaterialProperty） |
+| `ElecEllipsoidPrimitive` | `(position, options)` | 电磁球 |
+| `FlowLinePrimitive` | `(positions, width, options)` | 流动抛物线（`speed`/`color`/`percent`，Primitive 版） |
+| `LabelPrimitive` | `(position, options)` | 高性能 Label |
+| `LightCylinderPrimitive` | `(position, options)` | 光柱 |
+| `ModelPrimitive` | `(options)` | 自定义 Primitive 容器 |
+| `PointPrimitive` | `(position, options)` | 高性能点 |
+| `PolylinePrimitive` | `(positions, options)` | 高性能折线 |
+| `ScanCirclePrimitive` | `(position, radius)` | 雷达扫描圆（`color`/`speed`，Primitive 版） |
+| `TrailLinePrimitive` | `(positions, width=1)` | 尾迹线（`color`/`speed`） |
+| `VideoPrimitive` | `(options)` | 视频贴图 |
+| `WaterPrimitive` | `(positions, holes=[])` | 动态水面（`baseWaterColor`/`frequency`/`amplitude`/`animationSpeed`/`specularIntensity`） |
+
+> 容器：`new ANOVGIS.PrimitiveLayer().addTo(viewer)`。Primitive 版 ≠ MaterialProperty 版：扫描圆 / 流动线 / 扩散墙另有对应的 `*MaterialProperty`（挂在 entity.material 上），两者**不要混用**——见顶部边界说明。
+
+> §1.4 合并说明：以下 3 个原始图元来自 `04-material.md` §1.4（"非 MaterialProperty，自带 material"），归本 skill：ScanCirclePrimitive（雷达）/ DiffuseWallPrimitive（扩散墙）/ FlowLinePrimitive（流动线 Primitive 版）。它们都是独立 `Graphic`，构造时 `new XxxPrimitive(pos, ...)`，已并入上表。
+
+---
+
+## 5. 典型 snippet（8 个，全部可粘贴运行）
+
+### S1. 创建 Point + 加入 VectorLayer + 内嵌 label
+
+```js
+// 来源: examples/public/examples/html/graphics/point.html  L57-90
+const layer = new ANOVGIS.VectorLayer()
+viewer.addLayer(layer)
+
+const point = new ANOVGIS.Point([116.4, 39.9, 0], {
+    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.0, -12)
+    },
+    infoData: { title: '标题', fieldsMap: [{ nameC: '编号', value: 123 }] }
+})
+layer.addGraphic(point)
+viewer.flyTo(layer)
+```
+
+<a id="s2"></a>
+### S2. 创建 Polygon + 高亮 + 弹窗 Popup
+
+```js
+// 来源: examples/public/examples/html/graphics/polygon.html  L60-82
+//       + graphics/polyline.html  L57-71 (bindPopup 模式)
+const layer = new ANOVGIS.VectorLayer()
+viewer.addLayer(layer)
+layer.bindPopup({
+    viewer, showTitle: true,
+    useDefaultHtmlTemplate: true
+})
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    const g = e.graphic
+    if (g) layer.popup.show(e.position, g.infoData)
+})
+
+const polygon = new ANOVGIS.Polygon(
+    '116.0,42.0;112.0,42.0;118.0,40.0',
+    {
+        material: 'rgba(255,0,0,0.5)',
+        highlight: { material: 'rgba(255,255,0,0.6)' },    // 鼠标悬停变黄
+        label: { text: '这是多边形', clampToGround: true,
+                 verticalOrigin: Cesium.VerticalOrigin.BOTTOM }
+    }
+)
+polygon.setOptions({
+    polyline: {                                  // 自动补边界线
+        positions: [...polygon.positions, polygon.positions[0]],
+        width: 5, material: Cesium.Color.YELLOW
+    }
+})
+layer.addGraphic(polygon)
+viewer.flyTo(layer)
+```
+
+<a id="s3"></a>
+### S3. 创建 Billboard + 自定义 Canvas 图像
+
+```js
+// 来源: examples/public/examples/html/graphics/billboard.html  L79-94
+// 用 ANOVGIS.ShapeUtil.drawCanvalCircle 生成 canvas 贴图
+const billboard = new ANOVGIS.Billboard([116.4, 39.9], {
+    image: ANOVGIS.ShapeUtil.drawCanvalCircle(
+        Cesium.Color.BLUE.toCssColorString(),
+        60,
+        ['北京', 1234]                              // [line1, line2]
+    ),
+    verticalOrigin: Cesium.VerticalOrigin.BOTTOM,
+    disableDepthTestDistance: Number.POSITIVE_INFINITY,
+    scaleByDistance: { near: 1000000, nearValue: 1.0,
+                        far: 10000000, farValue: 0.0 }
+})
+const layer = new ANOVGIS.VectorLayer()
+viewer.addLayer(layer)
+layer.addGraphic(billboard)
+viewer.flyTo(billboard)
+```
+
+### S4. Tileset + ready 回调 + 鼠标拾取
+
+```js
+// 来源: examples/public/examples/html/event/tilesetpopup.html  L48-93
+const layer = new ANOVGIS.TilesetLayer()
+viewer.addLayer(layer)
+
+const tileset = new ANOVGIS.Tileset({
+    url: '/data/beijingchouxi/tileset.json',
+    highlight: { color: '#ff0000' },
+    selectedHighlight: { color: 'rgba(255,0,255,0.8)' }
+})
+tileset.ready((t) => console.log('3D Tiles loaded:', t))
+layer.addGraphic(tileset)
+
+// 条件样式（按属性着色）
+const style = new ANOVGIS.Cesium3DTileStyle({ color: {
+    conditions: [
+        ['Number(${floor}) >= 40', 'rgba(45,0,75,0.5)'],
+        ['Number(${floor}) >= 10', 'rgb(248,176,87)'],
+        ['true', 'rgb(127,59,8)']
+    ]
+}})
+tileset.setStyle(style)
+
+// 拾取 + Popup
+layer.bindPopup({ viewer, showTitle: true, useDefaultHtmlTemplate: true })
+layer.addEventListener(ANOVGIS.MouseEventType.CLICK, (e) => {
+    const infoData = {
+        title: e.feature.getProperty('name1'),
+        fieldsMap: [
+            { nameC: '名称', value: e.feature.getProperty('name1') },
+            { nameC: '楼层', value: e.feature.getProperty('floor') }
+        ]
+    }
+    layer.popup.show(e.position, infoData)
+})
+
+viewer.flyToTileset(tileset, 2, 0.5, -35)         // pitch=2, range=0.5, heading=-35
+```
+
+### S5. TrailLinePrimitive（尾迹线）
+
+```js
+// 来源: src/graphic/primitive/TrailLinePrimitive.js  L7-77 (无 examples HTML，按 src 推断)
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const trail = new ANOVGIS.TrailLinePrimitive(
+    [[116.3, 39.9], [116.4, 40.0], [116.5, 39.8]],  // positions
+    3                                                // width
+)
+trail.setOptions({
+    color: new Cesium.Color(1.0, 0.0, 0.0, 0.7),    // 红色半透明
+    speed: 5                                         // 流动速度
+})
+layer.addGraphic(trail)
+```
+
+### S6. ScanCirclePrimitive（扫描圆 / 雷达）
+
+```js
+// 来源: examples/public/examples/html/model/customshader.html  L309-326
+// 另见 04-material.md §3.4 来源 B：cesium_three.html L309-316（Primitive 正确写法）
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const circle = new ANOVGIS.ScanCirclePrimitive(
+    '121.49536592256028,31.241616722278213',        // 中心 [lng,lat]
+    5000                                             // 半径（米）
+)
+circle.setOptions({
+    speed: 5,
+    color: new ANOVGIS.Color(0.5, 0.8, 1.0, 1.0)
+})
+layer.addGraphic(circle)
+```
+
+### S7. WaterPrimitive（动态水面）
+
+```js
+// 来源: examples/public/examples/html/performance/wall_drawCommand2_Sci0.html  L145-170
+const layer = new ANOVGIS.PrimitiveLayer()
+viewer.addLayer(layer)
+
+// positions 为 Cesium.Cartesian3 数组（来自 GeoJsonDataSource 的 polygon hierarchy）
+const water = new ANOVGIS.WaterPrimitive(positionCartesian3, holes)
+water.setOptions({
+    baseWaterColor: ANOVGIS.Color.fromCssColorString('rgb(17,38,57)'),
+    frequency: 100.0,        // 波浪频率
+    animationSpeed: 0.01,    // 动画速度
+    amplitude: 10,           // 振幅
+    specularIntensity: 0.2   // 高光强度
+})
+layer.addGraphic(water)
+```
+
+<a id="s8"></a>
+### S8. Label + 自定义字体 + 按视距缩放
+
+```js
+// 来源: examples/public/examples/html/graphics/label.html  L80-105
+const layer = new ANOVGIS.VectorLayer()
+viewer.addLayer(layer)
+
+// 自定义字体（楷体）
+const v1 = new ANOVGIS.Label([116.4, 39.9], {
+    text: '数字科技',
+    font: '46px 楷体',                    // 浏览器/系统已安装的字体名
+    scale: 0.5,
+    color: '#00ffff',
+    outline: true,
+    outlineColor: '#000000',
+    outlineWidth: 2,
+    horizontalOrigin: ANOVGIS.HorizontalOrigin.CENTER,
+    verticalOrigin: ANOVGIS.VerticalOrigin.BOTTOM
+})
+
+// 按视距缩放
+const v2 = new ANOVGIS.Label([116.5, 39.9], {
+    text: '按视距缩放标签',
+    font: '70px 楷体',
+    color: '#00ff00',
+    scaleByDistance: new ANOVGIS.NearFarScalar(10000, 1.0, 500000, 0.1)
+})
+
+layer.addGraphic(v1)
+layer.addGraphic(v2)
+viewer.flyTo(layer)
+```
+
+---
+
+## 6. 关联文件
+
+- 抽象类：`src/graphic/Graphic.js`
+- 导出清单：`src/graphic/index.js`（Vector 16 + Model 2 + Primitive 17 = 35 个导出 + `Graphic` / `GraphicType` / `DivIcon`）
+- Layer 容器：`src/layer/graphic/VectorLayer.js`、`TilesetLayer.js`、`PrimitiveLayer.js`（用于 `addGraphic`，详见 `02-layer.md`）
+- MaterialProperty（给 Vector/Primitive 用）：`04-material.md` / `anovgis-material` skill
+- 真实 HTML demo：`examples/public/examples/html/graphics/`、`model/`、`event/`、`performance/`
+
+> ⚠️ **POI 样式铁律(v0.2.4 加)**:写 POI / graphic 样式前先查 `using-anovgis/REFERENCE.md` 速查表跳到对应章节,**严禁凭想象造"一个红圆点 + label"这种最简实现**。
+> - 至少三层叠:中心实心点(point) + 发光外环(billboard,canvas) + label(顶部偏移)
+> - 发光 canvas 用 `ANOVGIS.ShapeUtil.drawCanvalCircle` 生成(见本 skill § S5)
+> - 视距缩放统一用 `scaleByDistance: new ANOVGIS.NearFarScalar(near, scaleNear, far, scaleFar)`
+> - `disableDepthTestDistance: Number.POSITIVE_INFINITY` 防止被地形/楼块遮挡
+> - 选中态用 `selectedHighlight` 而不是手动改色
+>
+> SDK v1.8.6 `examples/public/examples/html/graphics/` 下的 `point.html` / `billboard.html` / `label.html` / `divInfo.html` 是原始参考 demo,本 skill § S5/S6/S9 已嵌入核心代码,无需读外部文件。
+
+---
+
+## 7. 各 Vector / Primitive 实战补充（11 个 snippet）
+
+> §5 8 个 snippet 覆盖了 Point / Polygon / Billboard / Label / Tileset / TrailLine / ScanCircle / Water。本节按 §2 Vector / §4 Primitive 速查表类顺序补全 **6 Vector + 5 Primitive**，共 11 个 snippet。字段名按 SDK 实际签名（核 `src/graphic/vector/*` 与 `src/graphic/primitive/*`）。
+
+<a id="s9"></a>
+### S9. Point 同时挂 label + billboard + 高亮 + Tooltip/Popup
+
+> ⚠️ **批量 POI 标绘先看选型**（v0.2.13）：本 snippet 是 **Billboard 路线**（`Point` 内嵌 `billboard` + `label`）。
+> 做 POI 标绘时**默认走 `DivIcon`（DOM 路线）**，`HtmlLayer` + `new ANOVGIS.DivIcon(position, html)`；
+> **POI 数量 > 100 才先问用户**选 DivIcon 还是 Billboard。完整选型规则 + 两套可粘贴代码见
+> [`using-anovgis` § POI 标绘选型（DivIcon 默认）](../using-anovgis/SKILL.md#poi-selection)。
+
+```js
+// 来源: examples/public/examples/html/graphics/point.html  L54-122
+// Point 是"一个位置叠 N 个 graphic"的容器；options 直接写 label / billboard 子图元
+const layer = new ANOVGIS.VectorLayer(); viewer.addLayer(layer)
+const positions = Array.from({length: 100}, () => [116+Math.random()*0.5, 39+Math.random()*0.5])
+positions.forEach((pos, i) => {
+    const p = new ANOVGIS.Point(pos, {
+        pixelSize: 12, color: ANOVGIS.Color.WHITE,
+        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) },
+        billboard: { image: ANOVGIS.ShapeUtil.drawCanvalCircle('#00ff00', 60, ['pt', i]),
+                     verticalOrigin: Cesium.VerticalOrigin.BOTTOM },
+        infoData: { title: `第${i}个`, fieldsMap: [{ nameC: '编号', value: i }] },
+        highlight: { pixelSize: 17, outlineColor: '#ff0000', outlineWidth: 3 }
+    })
+    p.bindTooltip({ viewer, showTitle: true, offsetY: '-10', useDefaultHtmlTemplate: true })
+    p.addEventListener(ANOVGIS.MouseEventType.MOUSE_MOVE, e => p.tooltip.show(e.position, e.graphic.infoData))
+    p.bindPopup({ viewer, showTitle: true })
+    p.addEventListener(ANOVGIS.MouseEventType.CLICK, e => p.popup.show(e.position, e.graphic.infoData))
+    layer.addGraphic(p)
+})
+viewer.flyTo(layer)
+```
+
+### S10. PolylineVolume 沿线拉伸（横截面 shape）
+
+```js
+// 来源: src/graphic/vector/PolylineVolume.js L7-77（构造 new PolylineVolume(positions, shape)）
+// shape 是二维 Cartesian2 数组（横截面多边形），按路径走生成管状体
+const layer = new ANOVGIS.VectorLayer(); viewer.addLayer(layer)
+const shape = [new Cesium.Cartesian2(-100, 0), new Cesium.Cartesian2(-100, 50),
+               new Cesium.Cartesian2( 100, 50), new Cesium.Cartesian2( 100, 0)]
+const tube = new ANOVGIS.PolylineVolume(
+    [[116.30, 39.90, 0], [116.40, 39.95, 200], [116.50, 39.92, 0]], shape)
+tube.setOptions({
+    material: 'rgba(255,140,0,0.7)', outline: true, outlineColor: Cesium.Color.RED,
+    cornerType: Cesium.CornerType.ROUNDED
+})
+layer.addGraphic(tube); viewer.flyTo(tube)
+```
+
+### S11. Wall 拉伸高度 + outline + 流向材质
+
+```js
+// 来源: examples/public/examples/html/performance/js/UIC.js L206-249
+//       + geojsonLayer/wall.html L54-66
+const layer = new ANOVGIS.VectorLayer(); viewer.addLayer(layer)
+const positions = [[116.30, 39.90], [116.35, 39.90], [116.35, 39.95],
+                   [116.30, 39.95], [116.30, 39.90]]           // 闭合矩形
+const wall = new ANOVGIS.Wall(positions, {
+    maximumHeights: new Array(positions.length).fill(200),    // 顶高 200m
+    minimumHeights: new Array(positions.length).fill(0),       // 底高 0
+    material: new ANOVGIS.WallFlowMaterialProperty({          // 流向材质
+        color: Cesium.Color.fromCssColorString('rgba(59,179,249,0.6)'),
+        duration: 1000 }),
+    outline: true,
+    outlineColor: Cesium.Color.fromCssColorString('rgba(255,255,0,1)')
+})
+layer.addGraphic(wall); viewer.flyTo(wall)
+```
+
+### S12. Cylinder 锥/柱 + heading/pitch/roll 朝向
+
+```js
+// 来源: src/graphic/vector/Cylinder.js L8-18（构造 new Cylinder(pos, length, topRadius, bottomRadius)）
+// pos 接受 ANOVGIS.Position 实例带 heading/pitch/roll，内部走 headingPitchRollQuaternion
+const layer = new ANOVGIS.VectorLayer(); viewer.addLayer(layer)
+// 灯塔：底径 60，顶径 30，高 400，航向 30°
+const tower = new ANOVGIS.Cylinder(
+    new ANOVGIS.Position(116.40, 39.90, 0, { heading: 30, pitch: 0, roll: 0 }),
+    400, 30, 60)
+tower.setOptions({ material: 'rgba(255,200,120,0.9)', outline: true,
+                   outlineColor: '#444', slicePartitions: 32 })
+layer.addGraphic(tower)
+// 圆锥（topRadius=0）
+const cone = new ANOVGIS.Cylinder(
+    new ANOVGIS.Position(116.42, 39.90, 0, { heading: 0, pitch: 0, roll: 0 }),
+    200, 0, 80)
+cone.setOptions({ material: Cesium.Color.DARKRED })
+layer.addGraphic(cone); viewer.flyTo(layer)
+```
+
+### S13. Box 阵列（per-instance + heading 不同）
+
+```js
+// 来源: src/graphic/vector/Box.js L7-25（构造 new Box(position, length, width, height)）
+// Box 接受 heading/pitch/roll；批量模拟建筑阵列
+const layer = new ANOVGIS.VectorLayer(); viewer.addLayer(layer)
+const bases = [
+    { lng: 116.40, lat: 39.90, h:  0, heading:  0 },
+    { lng: 116.41, lat: 39.90, h:  0, heading: 30 },
+    { lng: 116.40, lat: 39.91, h: 50, heading:  0 },
+    { lng: 116.41, lat: 39.91, h: 50, heading: 45 }
+]
+bases.forEach(b => {
+    const box = new ANOVGIS.Box(
+        new ANOVGIS.Position(b.lng, b.lat, b.h, { heading: b.heading, pitch: 0, roll: 0 }),
+        300, 200, 200)                                            // length, width, height
+    box.setOptions({ material: 'rgba(100,180,255,0.8)',
+                     outline: true, outlineColor: '#003366' })
+    layer.addGraphic(box)
+})
+viewer.flyTo(layer)
+```
+
+### S14. Plane 平面（自定义 normal + 距离）
+
+```js
+// 来源: src/graphic/vector/Plane.js L7-38（构造 new Plane(position, width, height, {normal, distance})）
+// normal: 'X' / 'Y' / 'Z' / Cartesian3；distance 是平面到 position 的偏移
+const layer = new ANOVGIS.VectorLayer(); viewer.addLayer(layer)
+// 水平（normal=Z）
+const ground = new ANOVGIS.Plane([116.40, 39.90, 100], 6000, 4000,
+                                 { normal: 'Z', distance: 0 })
+ground.setOptions({ material: 'rgba(0,200,255,0.4)', outline: true, outlineColor: '#0066aa' })
+layer.addGraphic(ground)
+// 倾斜（normal=UNIT_X，沿 Y 轴立起来）
+const tilted = new ANOVGIS.Plane([116.42, 39.90, 50], 3000, 2000,
+                                 { normal: Cesium.Cartesian3.UNIT_X, distance: 0 })
+tilted.setOptions({ material: 'rgba(255,200,0,0.5)' })
+layer.addGraphic(tilted); viewer.flyTo(layer)
+```
+
+### S15. BounceBillboardPrimitive 弹跳广告牌
+
+```js
+// 来源: src/graphic/primitive/BounceBillboardPrimitive.js L5-39（继承 BillboardPrimitive）
+// 构造 (position, icon)；setOptions 接受 maxOffsetY/offsetAmount
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const bb = new ANOVGIS.BounceBillboardPrimitive(
+    [116.40, 39.90],
+    ANOVGIS.ShapeUtil.drawCanvalCircle('#ff5500', 48, ['告警']))
+bb.size = [48, 48]
+bb.setOptions({ maxOffsetY: 12, offsetAmount: 0.6 })
+layer.addGraphic(bb)
+```
+
+### S16. BounceLabelPrimitive 弹跳文字
+
+```js
+// 来源: src/graphic/primitive/BounceLabelPrimitive.js L5-39（继承 LabelPrimitive）
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const lb = new ANOVGIS.BounceLabelPrimitive([116.40, 39.91], '弹跳标签')
+lb.setOptions({
+    maxOffsetY: 8, offsetAmount: 0.4,
+    font: '20px sans-serif', fillColor: Cesium.Color.YELLOW,
+    outlineColor: Cesium.Color.BLACK, outlineWidth: 2,
+    style: Cesium.LabelStyle.FILL_AND_OUTLINE
+})
+layer.addGraphic(lb)
+```
+
+### S17. CloudPrimitive 云层
+
+```js
+// 来源: src/graphic/primitive/CloudPrimitive.js L7-18（构造 new CloudPrimitive(position)）
+// nativeObjCesium 直接 {position, scale}，绕开 Entity 走 PrimitiveCollection
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const cloud = new ANOVGIS.CloudPrimitive([116.40, 39.90, 1500])
+cloud.setOptions({ scale: { x: 12, y: 8 } })         // 经向/纬向跨度（度）
+layer.addGraphic(cloud); viewer.flyTo(cloud)
+```
+
+### S18. ElecEllipsoidPrimitive 电磁球
+
+```js
+// 来源: src/graphic/primitive/ElecEllipsoidPrimitive.js L7-19
+// 构造 new ElecEllipsoidPrimitive(position, radius)；用 EllipsoidElectric material
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const elec = new ANOVGIS.ElecEllipsoidPrimitive(
+    [116.40, 39.90, 0], { x: 80, y: 80, z: 80 })    // 椭球半径
+elec.setOptions({
+    color: Cesium.Color.fromCssColorString('rgba(0,255,180,0.9)'),
+    speed: 5
+})
+layer.addGraphic(elec); viewer.flyTo(elec)
+```
+
+### S19. LightCylinderPrimitive 灯柱（底环+旋转圆+渐变柱+粒子）
+
+```js
+// 来源: src/graphic/primitive/LightCylinderPrimitive.js L14-25
+// 构造 new LightCylinderPrimitive(center, length, topRadius, bottomRadius)
+// alt=0 时贴地用 GroundPrimitive；alt>0 走 Primitive；内部异步加载粒子 PNG
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const beam = new ANOVGIS.LightCylinderPrimitive(
+    [116.40, 39.90, 0],         // center
+    500,                        // length
+    5,                          // topRadius
+    80                          // bottomRadius
+)
+beam.setOptions({ color: Cesium.Color.fromCssColorString('rgba(255,200,80,1)') })
+layer.addGraphic(beam); viewer.flyTo(beam)
+```
+```
+
+---