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

package/skills/anovgis-materials/SKILL.md

@@ -0,0 +1,635 @@
+---
+name: anovgis-materials
+description: '@anov/gis 材质（MaterialProperty 体系）。涵盖 18 个 *MaterialProperty（PolylineFlow/Trail/LightingTrail/Lighting/Glow/Gradient/ImageTrail/VFlywire/Flicker/DaoHang、Water、WallFlow/WallGradient/WallLineFlow/WallImg、CircleWave/CircleBlur/CircleScan）、通用构造模式（createPropertyDescriptor / getType / getValue / MaterialPropertyBase）、5 个典型 snippet、shader 注册机制（type/*.js 与 MaterialProperty 对应）。触发关键词：material、MaterialProperty、PolylineFlowMaterial、WaterMaterial、CircleWaveMaterial、WallFlowMaterial、getType、shader、uniform、parabola、抛物线、imgrader、图片扫描、WaterShadertoy、自定义 shadertoy、daohangLine 拐弯。Use when 配置流动线 / 水面 / 雷达 / 扩散波 / 导航线 / 渐变线材质、读 shader 注册路径、用 P5 陷阱排查"改值不生效"、做抛物线 / 图片雷达扫描 / 水面 shadertoy。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# anov-gis 材质速查（MaterialProperty 体系）
+
+> ⚠️ **优先级**：本 skill 优先于 SDK 源码 / `node_modules/@anov/gis/`。
+> 遇到 API 行为疑问先查本 skill 与 `anovgis-pitfalls`。**严禁**主动 Glob/Grep `node_modules/@anov/gis/src/...` / `dist/...`；除非用户明确要求并承担风险。
+> 调试流程见 `using-anovgis` § 默认调试流程（Chrome DevTools 仅第 5 级兜底）。
+>
+> **Cesium 入口（铁律）**：`const Cesium = window.Cesium`。`@anov/gis` 启动时已把 Cesium 挂到 `window`，**不存在** `ANOVGIS.Cesium` 写法；本 skill 所有 `Cesium.*` 均从此变量取。底层 Cesium API 细节查 `cesiumjs-skills` 对应 skill（API 名通用，`import` 写法换成 `const Cesium = window.Cesium`）。
+
+> SDK 路径：`src/material/`（仅作语义锚点）。所有 `*MaterialProperty` 类继承自 `MaterialPropertyBase`，构造时统一接收 `options = { color, speed, ... }`，内部用 `Cesium.createPropertyDescriptor` 暴露可订阅属性。锁定 `@anov/gis` **v1.8.6**（Cesium **1.143.0**）。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 Material 实例化 + 绑定 Entity 的完整代码 → 见 [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md) / [`anovgis-layers`](../anovgis-layers/SKILL.md)
+- ❌ 不要写 Primitive 自带材质版本（`ScanCirclePrimitive` / `DiffuseWallPrimitive` / `FlowLinePrimitive` / `WaterPrimitive` 等独立 Graphic） → [`anovgis-primitives`](../anovgis-primitives/SKILL.md)
+- ❌ 不要写自定义 GLSL shader 编写（`WaterShadertoy` 等） → v0.3.0 `anovgis-custom-primitive-worker`
+- ❌ 不要写 18 个 Property 之外的内部 Material（如 `Cesium.Material._materialCache` 直接注册） → 见 SDK 源码 `src/material/type/`
+>
+> **⚠️ P5 陷阱（务必先读）**：MaterialProperty 子字段（`.x` / `.rgb` / `.red` 等）赋值不会触发 setter，GPU uniform 不更新。**必须整体赋新对象**：`material.color = new Cesium.Color(...)`、`material.repeat = new Cesium.Cartesian2(...)`。
+>
+> 完整排查（为什么 / 排查信号 / 源码定位）见 [`anovgis-pitfalls` P5](../anovgis-pitfalls/SKILL.md#p5-materialproperty)。
+
+## 1. 速查表（按用途分组）
+
+### 1.1 线材质（Polyline 类）
+
+| 类名 | 文件 | 关键参数 | demo |
+|---|---|---|---|
+| `PolylineFlowMaterialProperty` | `property/polyline/` | `color, speed, percent, gradient` | `material/flowPolyline.html` |
+| `PolylineTrailMaterialProperty` | `property/polyline/` | `color, speed` | `material/polylineTrail.html` |
+| `PolylineLightingTrailMaterialProperty` | `property/polyline/` | `color, speed` | `material/PolylineLighting.html` |
+| `PolylineLightingMaterialProperty` | `property/polyline/` | `color, speed` | `material/PolylineLighting.html` |
+| `PolylineGlowMaterialProperty` | `property/polyline/` | `color, glowPower, taperPower` | （shader 注册） |
+| `PolylineGradientMaterialProperty` | `property/polyline/` | `duration`（`image` 内部硬编码 `linegradient.png`） | （shader 注册） |
+| `PolylineImageTrailMaterialProperty` | `property/polyline/` | `color, image, speed, repeat: {x, y}` | `material/ImageTrailPolyline.html` |
+| `PolylineVFlywireMaterialPoperty` | `property/polyline/` | `color, speed, percent, gradient` | `material/VFlywire.html` |
+| `PolylineFlickerMaterialProperty` | `property/polyline/` | `color, speed` | （shader 注册） |
+| `DaoHangLineMaterialProperty` | `property/polyline/` | `color1, color2, whiteLength, greenLength, lineWidth, speed, direction, arrowLengthRatio, arrowWidthRatio` | `material/daohangLine.html` |
+
+### 1.2 面材质（Polygon / Wall / Ellipse）
+
+| 类名 | 文件 | 关键参数 | demo |
+|---|---|---|---|
+| `WaterMaterialProperty` | `property/water/` | `baseWaterColor, blendColor, specularMap, normalMap, frequency, animationSpeed, amplitude, specularIntensity` | `material/water.html` |
+| `WallFlowMaterialProperty` | `property/wall/` | `color, image, speed, rep, brightness, duration` | `geojsonLayer/wallBuilds.html` |
+| `WallGradientMaterialProperty` | `property/wall/` | `color, image, direction, duration, brightness` | `geojsonLayer/wallBuilds.html` L108-111 |
+| `WallLineFlowMaterialProperty` | `property/wall/` | `color, image, speed, copy` | （shader 注册） |
+| `WallImgMaterialProperty` | `property/wall/` | `color, image, isTranslucent` | （shader 注册） |
+
+### 1.3 点 / 圆 / 球材质
+
+| 类名 | 文件 | 关键参数 | demo |
+|---|---|---|---|
+| `CircleWaveMaterialProperty` | `property/wave/` | `color, duration, count, gradient` | `material/circleWave.html` |
+| `CircleBlurMaterialProperty` | `property/circle/` | `color, speed` | `material/circleBlur.html` |
+| `CircleScanMaterialProperty` | `property/circle/` | `color, speed` | 无 demo（参考 `src/graphic/primitive/ScanCirclePrimitive.js`） |
+
+> 注：原始图元（`ScanCirclePrimitive` / `DiffuseWallPrimitive` / `FlowLinePrimitive`）无对应 MaterialProperty，是 `Graphic` 子类直接 `new ANOVGIS.XxxPrimitive(...)`，详见 [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md)。
+
+## 2. 通用构造模式
+
+所有 Property 子类都遵循：
+
+```js
+class XxxMaterialProperty extends MaterialPropertyBase {
+  constructor(options = {}) {
+    super(options)            // 统一处理 color / speed
+    this.字段A = options.字段A ?? 默认值
+  }
+  getType(time) { return 'CesiumType名' }   // 对应 src/material/type/*.js 注册
+  getValue(time, result) { /* 写 result.字段 */ }
+  equals(other) { /* 比较 */ }
+}
+Object.defineProperties(XxxMaterialProperty.prototype, {
+  color: Cesium.createPropertyDescriptor('color'),
+  字段A: Cesium.createPropertyDescriptor('字段A'),
+})
+```
+
+**关键点**：
+
+1. `getType()` 返回的字符串必须与 `src/material/type/*.js` 中 `Cesium.Material._materialCache.addMaterial(...)` 注册的 type 一致（如 SDK 自注册 `'PolylineFlow'`、`'CircleWaveMaterial'`、`'WallLineFlow'`、`'WallGradient'`，以及 Cesium 内建的 `'Water'`）。注：`Cesium.Material.PolylineFlowType` 的实际值是 `'PolylineFlow'`，常量名 ≠ 注册 type。
+2. `getValue(time, result)` 把当前 uniform 值写入 `result` 对象，由 Cesium 框架逐帧调用。
+3. `MaterialPropertyBase` 已在内部处理 `color` 与 `speed` 的默认值（cyan + 1），子类通常只需扩展自己的字段。
+
+## 3. 典型 Snippet
+
+<a id="flow"></a>
+### 3.1 Polyline + PolylineFlowMaterialProperty（流动线）
+
+来源：`examples/public/examples/html/material/flowPolyline.html` L55-64
+
+```js
+let polyline = new ANOVGIS.Polyline('116, 38; 119, 38').setOptions({
+  width: 5,
+  material: new ANOVGIS.PolylineFlowMaterialProperty({
+    color: Cesium.Color.RED, speed: 5, gradient: 0.6, percent: 0.5,
+  }),
+  clampToGround: false,
+})
+```
+
+<a id="water"></a>
+### 3.2 Polygon + WaterPrimitive（Primitive 版水面）
+
+来源：`src/graphic/primitive/WaterPrimitive.js`（封装 `GroundPrimitive` + `Cesium.Material.fromType('Water', ...)`）
+
+```js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const water = new ANOVGIS.WaterPrimitive('116.4, 39.9; 116.5, 39.9; 116.5, 40.0; 116.4, 40.0')
+water.setOptions({
+  height: 200, extrudedHeight: 100,
+  baseWaterColor: Cesium.Color.fromCssColorString('#006ab4').withAlpha(0.5),
+  blendColor: new Cesium.Color(1.0, 1.0, 1.0, 0.5),
+  specularIntensity: 0.8,
+  frequency: 800.0, animationSpeed: 0.02, amplitude: 15.0,
+})
+layer.addGraphic(water)
+```
+
+注：`WaterPrimitive` 继承 `Graphic`，用 `setOptions()` 改 uniform；与 `*MaterialProperty`（entity 的 `material` 字段）是两条平行体系。
+
+<a id="circle-wave"></a>
+### 3.3 Ellipse + CircleWaveMaterialProperty（扩散波）
+
+来源：`examples/public/examples/html/material/circleWave.html` L65-83
+
+```js
+viewer.entities.add({
+  id: 'circlewave1',
+  position: Cesium.Cartesian3.fromDegrees(116.397428, 39.90923, 0),
+  ellipse: {
+    semiMinorAxis: new Cesium.CallbackProperty(() => 800, false),
+    semiMajorAxis: new Cesium.CallbackProperty(() => 800, false),
+    material: new ANOVGIS.CircleWaveMaterialProperty({
+      duration: 3000, gradient: 0.5,
+      color: Cesium.Color.fromCssColorString('rgba(59,179,249,0.7)'),
+      count: 4,
+    }),
+  },
+})
+```
+
+### 3.4 雷达扫描（CircleScan / ScanCirclePrimitive）
+
+来源 A：`material/circleBlur.html`（结构同 3.3，换 `CircleScanMaterialProperty({ color, speed })`）
+
+来源 B：`examples/public/examples/html/model/cesium_three.html` L309-316
+
+```js
+const layer = new ANOVGIS.PrimitiveLayer().addTo(viewer)
+const scan = new ANOVGIS.ScanCirclePrimitive(
+  Cesium.Cartesian3.fromDegrees(119.506, 35.361), 1000)
+scan.setOptions({ speed: 5, color: new Cesium.Color(0.5, 0.8, 1.0, 1.0) })
+layer.addGraphic(scan)
+```
+
+### 3.5 Wall + WallFlowMaterialProperty（流动墙体）
+
+来源：`examples/public/examples/html/geojsonLayer/wallBuilds.html` L91-107
+
+```js
+viewer.entities.add({
+  name: entity.name,
+  wall: {
+    positions: Cesium.Cartesian3.fromDegreesArray(postion),
+    maximumHeights: new Array(cor.coordinates.length).fill(cor.height),
+    minimumHeights: new Array(cor.coordinates.length).fill(0),
+    material: new ANOVGIS.WallFlowMaterialProperty({
+      color: Cesium.Color.fromCssColorString(entity.color),
+      duration: 2500,
+    }),
+  },
+})
+```
+
+扩散墙效果改用 `new ANOVGIS.DiffuseWallPrimitive(center, radius, height)`（Primitive 而非 Property）。
+
+## 各 MaterialProperty 实战补充
+
+<a id="image-trail"></a>
+### 线材质
+
+#### PolylineTrailMaterialProperty（尾迹线，不发光）
+
+```js
+// 来源: polylineTrail.html L31-45
+const roads = new ANOVGIS.GeoJsonLayer('../modelData/json/road_shanghai.json')
+roads.eachGraphic((graphic) => {
+  if (!graphic.polyline) return
+  ANOVGIS.Util.merge(graphic.polyline, {
+    width: 3,
+    material: new ANOVGIS.PolylineTrailMaterialProperty({
+      color: ANOVGIS.Color.ORANGE.withAlpha(1),
+      speed: 6,
+    }),
+  })
+})
+viewer.addLayer(roads)
+```
+
+#### PolylineLightingTrailMaterialProperty（泛光尾迹）
+
+```js
+// 来源: PolylineLighting.html L142-158
+const lightingTrail = viewer.entities.add({
+  polyline: {
+    positions,
+    width: 15,
+    clampToGround: true,
+    material: new ANOVGIS.PolylineLightingTrailMaterialProperty({
+      color: Cesium.Color.fromCssColorString('#66e633'),
+      speed: 10,
+    }),
+  },
+})
+```
+
+#### PolylineGlowMaterialProperty / PolylineGradientMaterialProperty（渐变线）
+
+```js
+// 来源: PolylineLighting.html L69-80
+const glow = new ANOVGIS.PolylineGlowMaterialProperty({
+  color: new Cesium.Color(1, 0.27, 0, 0.9),
+  glowPower: 0.2,
+  taperPower: 1,
+})
+const gradient = new ANOVGIS.PolylineGradientMaterialProperty({
+  duration: 2000,
+})
+
+// 两种材质任选其一；切换时整体替换 material
+entity.polyline.width = 13
+entity.polyline.material = glow
+// entity.polyline.material = gradient
+```
+
+#### PolylineImageTrailMaterialProperty（图片纹理流动）
+
+```js
+// 来源: ImageTrailPolyline.html L137-151
+polyline.setOptions({
+  width: 10,
+  clampToGround: true,
+  material: new ANOVGIS.PolylineImageTrailMaterialProperty({
+    color: Cesium.Color.CYAN,
+    speed: 10,
+    image: './images/thumbs/material/arrow_1.png',
+    repeat: new Cesium.Cartesian2(40, 1),
+  }),
+})
+// 动态修改 repeat 时同样整体赋值：material.repeat = new Cesium.Cartesian2(20, 1)
+```
+
+<a id="circle-blur"></a>
+### 面材质
+
+#### WallLineFlowMaterialProperty / WallGradientMaterialProperty（墙体流光与渐变）
+
+```js
+// 来源: waterShadertoy.html L139-163
+const wallPositions = Cesium.Cartesian3.fromDegreesArrayHeights([
+  116.38, 39.98, 0, 116.38, 39.99, 800, 116.39, 39.98, 0,
+])
+const wall = viewer.entities.add({
+  wall: {
+    positions: wallPositions,
+    material: new ANOVGIS.WallLineFlowMaterialProperty({
+      color: Cesium.Color.CYAN,
+      speed: 100,
+      copy: new Cesium.Cartesian2(2, 1),
+    }),
+  },
+})
+
+// 渐变墙体：direction=1 表示从下往上
+// wall.wall.material = new ANOVGIS.WallGradientMaterialProperty({
+//   color: Cesium.Color.CYAN, direction: 1, duration: 2500, brightness: 1.5,
+// })
+```
+
+### 点 / 圆 / 球材质
+
+#### CircleBlurMaterialProperty（扩散模糊圆）
+
+```js
+// 来源: circleBlur.html L45-57
+const layer = new ANOVGIS.VectorLayer().addTo(viewer)
+const circle = new ANOVGIS.Circle(
+  ANOVGIS.Position.fromObject({ lng: 116, lat: 39 }),
+  2000,
+)
+circle.setOptions({
+  classificationType: 0,
+  material: new ANOVGIS.CircleBlurMaterialProperty({
+    color: Cesium.Color.YELLOW.withAlpha(0.2),
+    speed: 10,
+  }),
+})
+layer.addGraphic(circle)
+```
+
+#### CircleScanMaterialProperty（图片雷达）
+
+```js
+// 来源: imgrader.html L63-91
+const radar = viewer.entities.add({
+  position: Cesium.Cartesian3.fromDegrees(119.506, 35.361),
+  ellipse: {
+    semiMajorAxis: 500,
+    semiMinorAxis: 500,
+    material: new ANOVGIS.CircleScanMaterialProperty({
+      color: Cesium.Color.fromCssColorString('rgba(36,229,104,0.5)'),
+      speed: 1.5,
+    }),
+    height: 20,
+    heightReference: Cesium.HeightReference.RELATIVE_TO_GROUND,
+  },
+})
+```
+
+> 动态调色、重复次数或纹理缩放时，遵守顶部 P5：`color`、`repeat`、`copy` 等对象字段必须整体赋新对象，不能只改 `.red`、`.x` 等子字段。
+
+<a id="parabola"></a>
+### 流动抛物线 + V 型飞线（补充实战）
+
+#### FlowLinePrimitive + ANOVGIS.parabola(中心, 目标, 抛物线最大高度)
+
+```js
+// 来源: parabola.html L55-78
+let layer = new ANOVGIS.PrimitiveLayer({ id: 'layer' }).addTo(viewer);
+let center = ANOVGIS.Position.fromObject({ lng: 121.495, lat: 31.241 });
+
+let positions = [
+    { lng: 121.465, lat: 31.254 },
+    { lng: 121.481, lat: 31.227 },
+    // ...省略若干条
+];
+positions.forEach(item => {
+    // ANOVGIS.parabola(中心点, 目标点, 抛物线最大高度)
+    let line = new ANOVGIS.FlowLinePrimitive(ANOVGIS.parabola(center, item, 500), 5);
+    line.setOptions({
+        speed: 5 * Math.random(),
+        color: new Cesium.Color(0.5, 0.8, 1.0, 0.9),
+        gradient: 0.3,
+        percent: 0.1,
+    });
+    layer.addGraphic(line);
+});
+viewer.flyToPosition('121.495,31.241,3859,0,-28');
+```
+
+#### PolylineVFlywireMaterialPoperty(竖向流光, 注意 SDK 拼写: Poperty 少一个 r)
+
+```js
+// 来源: VFlywire.html L67-93
+// 注意: API 拼写是 SDK 既定 "Poperty" (少一个 r),不要纠正为 Property
+function showFlywire(centerLngLat, count) {
+    const positions = generateRandomPosition(centerLngLat, count);  // [[lng, lat], ...]
+    positions.forEach(([lng, lat]) => {
+        const start = Cesium.Cartesian3.fromDegrees(lng, lat, 0);
+        const end   = Cesium.Cartesian3.fromDegrees(lng, lat, 20000);  // 20km 高空
+        viewer.entities.add({
+            polyline: {
+                positions: [start, end],
+                material: new ANOVGIS.PolylineVFlywireMaterialPoperty({
+                    color: Cesium.Color.fromCssColorString('rgba(63,140,255,0.8)'),
+                    speed: Math.round(Math.random() * 15),
+                    percent: 0.1,
+                    gradient: 0.01,
+                }),
+            },
+        });
+    });
+}
+```
+
+<a id="daohang"></a>
+### 导航线(DaoHangLine)拐弯效果
+
+```js
+// 来源: daohangLineTest.html L54-86(单条最简版)
+// 关键字段: color1(头色) / color2(尾色) / whiteLength / greenLength /
+//            lineWidth / speed / direction(-1=正, 1=反) /
+//            arrowLengthRatio / arrowWidthRatio
+const line = viewer.entities.add({
+    polyline: {
+        positions: Cesium.Cartesian3.fromDegreesArrayHeights([
+            117.332, 31.870, 17,
+            117.310, 31.870, 14,
+            117.282, 31.863, 23,
+            // ...省略中间控制点
+            117.139, 31.837, 39,
+        ]),
+        width: 7,
+        material: new ANOVGIS.DaoHangLineMaterialProperty({
+            color1: Cesium.Color.WHITE,
+            color2: Cesium.Color.fromCssColorString('#0aed8b'),
+            whiteLength: 10.0,
+            greenLength: 40.0,
+            lineWidth: 0.45,
+            speed: 0,
+        }),
+    },
+});
+viewer.flyTo(line);
+
+// 动态调参: 用 Object.assign 整体更新字段(不是重建 material)
+apply(mat) {
+    Object.assign(line.polyline.material, {
+        color1: mat.color1, color2: mat.color2,
+        whiteLength: mat.whiteLength, greenLength: mat.greenLength,
+        lineWidth: mat.lineWidth, speed: mat.speed,
+        direction: mat.direction,
+        arrowLengthRatio: mat.arrowLengthRatio,
+        arrowWidthRatio: mat.arrowWidthRatio,
+    });
+}
+```
+
+<a id="water-shadertoy"></a>
+### 水面 + 自定义 shadertoy(基于 Cesium 原生 Material)
+
+> ⚠️ water 系列 4 个 demo **不是 ANOVGIS 自定义材质**,是 **Cesium 原生** `Cesium.Material` + `Cesium.GroundPrimitive`。开发者想自己写 GLSL 时参考。
+
+#### water.html — 内置 Water Material
+
+```js
+// 来源: water.html L67-115
+const coords = `116,39; 117,39; 117,40; 116,40; 116,39`;
+ANOVGIS.LocateUtil.flyToPositions(viewer, coords, 0, -20, 1.0, 2, null);
+
+const waterPrimitive = new Cesium.GroundPrimitive({
+    geometryInstances: new Cesium.GeometryInstance({ geometry: {} }),
+    asynchronous: true,
+});
+viewer.scene.groundPrimitives.add(waterPrimitive);
+waterPrimitive.geometryInstances.geometry = new Cesium.PolygonGeometry({
+    polygonHierarchy: new Cesium.PolygonHierarchy(
+        ANOVGIS.Transform.transformWGS84ArrayToCartesianArray(ANOVGIS.Parse.parsePositions(coords)),
+        []
+    ),
+    height: 200, extrudedHeight: 100,
+    vertexFormat: Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+});
+waterPrimitive.appearance = new Cesium.EllipsoidSurfaceAppearance({
+    translucent: true,
+    material: Cesium.Material.fromType('Water', {
+        normalMap: '../modelData/images/waterNormalsSmall.jpg',
+        frequency: 800.0, animationSpeed: 0.02, amplitude: 15.0,
+        specularIntensity: 0.8,
+        baseWaterColor: Cesium.Color.fromCssColorString('#006ab4').withAlpha(0.5),
+        blendColor: new Cesium.Color(1, 1, 1, 0.5),
+    }),
+});
+```
+
+#### waterShadertoy.html — 自定义 fabric GLSL
+
+```js
+// 来源: waterShadertoy.html L53-195
+// 关键: 自定义 uniform 命名带后缀(frequency_1 / baseWaterColor_4 等),
+//       且配合自定义 fragmentShaderSource
+ANOVGIS.LayerControlUitl.setSelectedTerrain(viewer, 2);
+
+const wm = new Cesium.Material({
+    fabric: {
+        uniforms: {
+            specularMap_6: Cesium.Material.DefaultImageId,
+            normalMap_0: Cesium.buildModuleUrl('Assets/Textures/waterNormalsSmall.jpg'),
+            frequency_1: 1.0, animationSpeed_2: 0.01, amplitude_3: 10.0,
+            baseWaterColor_4: { x: 0, y: 0, z: 0.5, w: 1 },
+            blendColor_5:    { x: 0, y: 0, z: 0.5, w: 0.5 },
+            specularIntensity_7: 1, fadeFactor_8: 1,
+        },
+        source: `
+            uniform sampler2D specularMap_6;
+            uniform sampler2D normalMap_0;
+            uniform vec4 baseWaterColor_4;
+            uniform vec4 blendColor_5;
+            uniform float frequency_1;
+            uniform float animationSpeed_2;
+            uniform float amplitude_3;
+            uniform float specularIntensity_7;
+            uniform float fadeFactor_8;
+
+            czm_material czm_getMaterial(czm_materialInput materialInput) {
+                czm_material material = czm_getDefaultMaterial(materialInput);
+                float time = czm_frameNumber * animationSpeed_2;
+                vec4 noise = czm_getWaterNoise(normalMap_0, materialInput.st * frequency_1, time, 0.0);
+                vec3 normalTangentSpace = noise.xyz * vec3(1, 1, (1.0 / amplitude_3));
+                material.diffuse = mix(blendColor_5.rgb, baseWaterColor_4.rgb, noise.x);
+                material.alpha = mix(blendColor_5.a, baseWaterColor_4.a, noise.x);
+                material.specular = specularIntensity_7;
+                material.shininess = 10.0;
+                return material;
+            }
+        `,
+    },
+});
+
+viewer.scene.primitives.add(new Cesium.GroundPrimitive({
+    show: true,
+    classificationType: Cesium.ClassificationType.TERRAIN,
+    geometryInstances: new Cesium.GeometryInstance({
+        geometry: new Cesium.PolygonGeometry({
+            polygonHierarchy: new Cesium.PolygonHierarchy(
+                Cesium.Cartesian3.fromDegreesArrayHeights([116.383, 39.978, 100, 116.373, 39.977, 102, ...])
+            ),
+            perPositionHeight: true, extrudedHeight: 100,
+        }),
+    }),
+    appearance: new Cesium.EllipsoidSurfaceAppearance({ material: wm }),
+}));
+```
+
+### cloud.html(Water Material 复用做云)
+
+```js
+// 来源: cloud.html L62-100
+// 思路: Water Material 的"波纹 + 反射"恰好模拟云层外观,换不规则 coords 即可
+const coords = `116.3879,40.0005; 116.3893,40.0006; 116.3900,39.9969;
+               116.3890,39.9968; 116.3883,39.9986; 116.3879,40.0005;`;
+ANOVGIS.LocateUtil.flyToPositions(viewer, coords, 260, -20, 1.5, 3, null);
+
+const waterPrimitive = new Cesium.GroundPrimitive({
+    geometryInstances: new Cesium.GeometryInstance({ geometry: {} }),
+    asynchronous: true,
+});
+viewer.scene.groundPrimitives.add(waterPrimitive);
+waterPrimitive.geometryInstances.geometry = new Cesium.PolygonGeometry({
+    polygonHierarchy: new Cesium.PolygonHierarchy(
+        ANOVGIS.Transform.transformWGS84ArrayToCartesianArray(ANOVGIS.Parse.parsePositions(coords)), []
+    ),
+    height: 0.1, vertexFormat: Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+});
+waterPrimitive.appearance = new Cesium.EllipsoidSurfaceAppearance({
+    material: Cesium.Material.fromType('Water', {
+        baseWaterColor: new Cesium.Color(0.2, 0.3, 0.6, 1),
+        blendColor: new Cesium.Color(0, 1, 0.7, 1),
+        specularMap: Cesium.Material.DefaultImageId,
+        normalMap: 'http://example.com/waterNormalsSmall.jpg',
+        frequency: 1000, animationSpeed: 0.01, amplitude: 10, specularIntensity: 10,
+    }),
+});
+```
+
+### waterShadertoy 变体 1(反射纹理) — `material/waterShadertoy1.html` L99-L174
+
+```js
+// 来源: waterShadertoy1.html L99-174
+// 关键: 用 viewer.scene.captureSceneToFramebuffer() 抓取场景作为反射纹理 camT
+//       + 自定义 Material fabric uniforms
+const miniMapTexture = viewer.scene.captureSceneToFramebuffer();
+const wm = new Cesium.Material({
+    fabric: {
+        uniforms: {
+            camT: 'miniMapTexture',                              // 反射纹理
+            depthW: '../modelData/building/water/color.png',    // 水深混合色
+            normalMap_0: 'http://.../water/waterNormalsSmall.jpg',
+            frequency_1: 1000.0, animationSpeed_2: 0.01, amplitude_3: 10.0,
+            baseWaterColor_4: { x: 0, y: 0, z: 0.5, w: 1 },
+            blendColor_5:    { x: 0, y: 0, z: 0, w: 0.5 },
+            specularMap_6: '',
+            specularIntensity_7: 1, fadeFactor_8: 1,
+            C_position: BeijingPosition, C_normal: BeijingNormal,
+        },
+        source: `
+            uniform sampler2D camT;
+            uniform sampler2D depthW;
+            czm_material czm_getMaterial(czm_materialInput materialInput) {
+                czm_material material = czm_getDefaultMaterial(materialInput);
+                vec2 reflectCoord = gl_FragCoord.xy / czm_viewport.zw;
+                vec2 reflectionTexcoord = vec2(1.0 - reflectCoord.x, reflectCoord.y);
+                material.diffuse = texture(camT, materialInput.st).rgb;
+                material.specular = specularIntensity_7;
+                material.shininess = 10.0;
+                return material;
+            }
+        `,
+    }
+});
+// 演示用 Primitive(非 GroundPrimitive) + EllipsoidSurfaceAppearance + 自定义 vertexShaderSource
+```
+
+### waterShadertoy 变体 2(Blinn-Phong Specular) — `material/waterShadertoy2.html` L59-L107
+
+```js
+// 来源: waterShadertoy2.html L59-107
+// 关键: 自定义 fabric type:'Specular',GLSL 实现 Blinn-Phong 漫反射 + 镜面反射
+//       套到 entity.ellipsoid.material(球体 Entity)做演示
+const specularMaterial = new Cesium.Material({
+    fabric: {
+        type: 'Specular',
+        uniforms: {
+            u_lightDirection: new Cesium.Cartesian3(0.5, 0.5, 0.5),
+            u_shininess: 50.0,
+            u_specularColor: new Cesium.Color(1, 1, 1, 1),
+            u_diffuseColor:  new Cesium.Color(0.2, 0.2, 0.2, 1),
+        },
+        source: `
+            czm_material czm_getMaterial(czm_materialInput materialInput) {
+                vec3 normal   = normalize(materialInput.normalEC);
+                vec3 viewDir  = normalize(-materialInput.positionToEyeEC);
+                vec3 lightDir = normalize(u_lightDirection);
+                float diffuse = max(dot(lightDir, normal), 0.0);
+                vec3 reflectDir = reflect(-lightDir, normal);
+                float spec = pow(max(dot(viewDir, reflectDir), 0.0), u_shininess);
+                czm_material material = czm_getDefaultMaterial(materialInput);
+                material.diffuse = u_diffuseColor.rgb * diffuse + u_specularColor.rgb * spec;
+                material.alpha = 1.0;
+                return material;
+            }
+        `
+    }
+});
+const ellipsoid = viewer.entities.add({
+    position: Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883),
+    ellipsoid: { radii: new Cesium.Cartesian3(10000, 10000, 10000), material: specularMaterial },
+});
+viewer.zoomTo(viewer.entities);
+```
+
+## 4. 关联阅读
+
+- [`anovgis-pitfalls` P5](../anovgis-pitfalls/SKILL.md#p5-materialproperty) — MaterialProperty setter 模式（权威排查）
+- [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md) — `Vector` / `Primitive` / 原始图元体系（含 `ScanCirclePrimitive` / `DiffuseWallPrimitive` / `FlowLinePrimitive`）
+- SDK `shader/` 目录：每个 Property 对应一个 `.glsl` 片段，shader 端改动后必须同步 `type/*.js` 注册