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

package/skills/anovgis-effects/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: anovgis-effects
+description: '@anov/gis 特效模块。涵盖 Weather（Rain/Snow/Fog/Cloud）、RoamingController / RoamingPath / KeyboardRoaming、GlobeRotate 全球自转 / AroundPoint 相机环绕 / FlyManager 航线、Effect 7 个后期 stage（Bloom/LensFlare/DepthOfField/Brightness/NightVision/Silhouette/BlackAndWhite）、skybox 天空盒。触发关键词：weather、rain、snow、fog、cloud、roaming、漫游、RoamingPath、KeyboardRoaming、AroundPoint、FlyManager、bloom、lensFlare、depthOfField、nightVision、blackAndWhite、后期、PostFog、rainSnowPlane、雨雪平面、Plane、跟随、dog、键盘漫游、第一人称、firstPerson、GlobeRotate、全球自转、自转、flyTo、航线、skybox、天空盒。Use when 下雨/下雪/起雾/卷云、做路径漫游或键盘漫游、做相机环绕、做航线 FlyManager、配置泛光/景深/夜视/黑白/亮度/轮廓等后期、做全球自转动画、加载雨雪平面粒子、切换天空盒。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+---
+
+# 06 - 特效（effect 模块）
+
+> ⚠️ **优先级**：本 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`）。
+
+> `src/effect/` 下四大子模块：天气（weather）、漫游（roaming）、动画（animation）、后期处理（type/）（仅作语义锚点）。锁定 `@anov/gis` **v1.8.6**（Cesium **1.143.0**）。
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 Cesium 官方 post-process stage 完整 API（仅覆盖 Effect 7 stage） → 见 Cesium 文档
+- ❌ 不要写 CustomShader / 自定义 GLSL → v0.3.0 `anovgis-custom-primitive-worker`
+- ❌ 不要写 viewer.clock 时间播放 + CZML playback 完整用法 → v0.3.0 `anovgis-roaming-editor-time`
+- ❌ 不要写雨雪平面粒子（ParticleSystem） → [`anovgis-models-3dtiles`](../anovgis-models-3dtiles/SKILL.md)（rainSnowPlane）
+- ❌ 不要写 Camera API 详细用法 → [`anovgis-viewer`](../anovgis-viewer/SKILL.md)
+
+## 1. 类速查表
+
+<a id="weather"></a>
+### 1.1 天气 `ANOVGIS.Weather`
+
+通过 `new Weather(viewer)` 一键初始化，自动把 fog/rain/snow/cloud 四个组件挂到 `viewer.weather.*`。每个子组件均带 `enable` 布尔 + 可调 uniform。
+
+| 子类 | src | 关键字段 |
+|---|---|---|
+| `Weather` | `src/effect/weather/Weather.js` | `install(viewer)` 后 `viewer.weather` 可用 |
+| `Rain` | `src/effect/weather/type/Rain.js` | `enable`、`speed`、`mixNum` |
+| `Snow` | `src/effect/weather/type/Snow.js` | `enable`、`speed`、`mixNum` |
+| `Fog` | `src/effect/weather/type/Fog.js` | `enable`、`fogByDistance`、`color`（构造时可传 options） |
+| `Cloud` | `src/effect/weather/type/Cloud.js` | `enable`、`rotateAmount` |
+
+构造期属性示例：`new Fog({ fogByDistance: { near: 20, far: 20000, nearValue: 0, farValue: 1.0 }, color: new Cesium.Color(0,0,0,0.3) })`。
+
+<a id="roaming"></a>
+### 1.2 漫游 `ANOVGIS.Roaming*`
+
+| 类 | src | 用途 |
+|---|---|---|
+| `RoamingController` | `src/effect/roaming/RoamingController.js` | 多路径容器，`addPath / start(path, viewOption) / stop / clear` |
+| `RoamingPath` | `src/effect/roaming/RoamingPath.js` | 单条路径 `new RoamingPath(positions, duration, pathMode)`，pathMode: `'speed' \| 'time'` |
+| `KeyboardRoaming` | `src/effect/roaming/KeyboardRoaming.js` | W/S/A/D + Q/E 键盘漫游，`enable = true` 即生效 |
+
+事件：`ANOVGIS.PathEventType.{ADD,REMOVE,POST_RENDER,RESET_TIME_LINE,END}` 监听路径生命周期。
+
+<a id="animation"></a>
+### 1.3 动画 `ANOVGIS.Animation*`
+
+入口：直接 `new`，均继承自 `src/effect/animation/Animation.js`。
+
+| 类 | src | 用途 |
+|---|---|---|
+| `GlobeRotate` | `src/effect/animation/type/GlobeRotate.js` | 整球自转（基于 ICRF），`start()` + `options.duration` 回调 |
+| `AroundPoint` | `src/effect/animation/type/AroundPoint.js` | 相机环绕目标点，`aroundAmount`（度/帧）控制速度 |
+| `FlyManager` | `src/effect/animation/type/FlyManager.js` | 多站点航线，`routeStops[]` + `loop` + `start/pause/continueFly` |
+
+事件：`ANOVGIS.FlyEventType.{FLYING,STOP_STAY}` 订阅航线状态。
+
+`viewer.flyTo`/`flyToPosition`/`flyToPoint` 是 Viewer 上的相机方法（详见 `01-base.md`），不属于 Animation 子类。
+
+<a id="effect"></a>
+### 1.4 后期处理 `ANOVGIS.Effect`
+
+`new Effect(viewer)` 在 viewer 上实例化 7 个后期 stage，统一通过 getter 访问：
+
+| 字段（getter） | 类型 | 关键 uniform / 行为 | src |
+|---|---|---|---|
+| `viewer.effect.bloom` | Bloom | `contrast / brightness / glowOnly / delta / sigma / stepSize / selected` | `src/effect/type/Bloom.js` |
+| `viewer.effect.lensFlare` | LensFlare | 镜头光晕（太阳眩光） | `src/effect/type/LensFlare.js` |
+| `viewer.effect.depthOfField` | DepthOfField | 景深 | `src/effect/type/DepthOfField.js` |
+| `viewer.effect.brightness` | Brightness | 全局亮度调节 | `src/effect/type/Brightness.js` |
+| `viewer.effect.night` | NightVision | 夜视（绿），`selected` 可仅作用于指定对象 | `src/effect/type/NightVision.js` |
+| `viewer.effect.silhouette` | Silhouette | 描边轮廓 | `src/effect/type/Silhouette.js` |
+| `viewer.effect.blackAndWhite` | BlackAndWhite | 黑白化，`gradations` 控制灰度级数 | `src/effect/type/BlackAndWhite.js` |
+
+每个 stage 公共接口：`stage.enable = true / false`；调 uniform 直接 `stage.contrast = 128`（setter 写穿到 native 的 `uniforms.x`）。
+
+注意：`new ANOVGIS.Effect(viewer)` 必须在 viewer 构造完成后调用，且 skyBox/globe 等选项可先关闭（如 demo dog.html）。
+
+---
+
+## 2. 5 个 snippet
+
+### S1. 下雨 + 雾
+
+```js
+// 来源: examples/public/examples/html/effect/weather.html (L80-96)
+// 一行创建，自动挂 fog/rain/snow/cloud
+const weather = new ANOVGIS.Weather(viewer)
+viewer.weather.rain.enable = true        // 开雨
+viewer.weather.rain.speed = 20           // 雨速
+viewer.weather.fog.enable = true         // 开雾
+viewer.weather.fog.color = new Cesium.Color(0.6, 0.6, 0.7, 0.4)
+viewer.weather.fog.fogByDistance = { near: 100, nearValue: 0.0, far: 8000, farValue: 1.0 }
+viewer.weather.cloud.enable = true       // 云
+viewer.weather.cloud.rotateAmount = 0.04
+```
+
+### S2. 路径漫游（positions + duration）
+
+```js
+// 来源: examples/public/examples/html/effect/roaming.html (L67-90)
+const rc = new ANOVGIS.RoamingController(viewer)
+const pathPos = [
+  [121.46978931, 31.07444714, 0],
+  [121.45930009, 31.10311962, 0],
+  [121.46385981, 31.16208416, 0],
+]
+const path = new ANOVGIS.RoamingPath(pathPos, 20)       // duration=20s, pathMode='speed' 默认
+rc.addPath(path)
+path.pathEvent.addEventListener(ANOVGIS.PathEventType.END, (endPos) => {
+  console.log('path ended at', endPos)
+})
+rc.start(path, { pitch: -45, height: 3000 })          // 俯角/相机高度
+// rc.stop()
+```
+
+<a id="s3"></a>
+### S3. 相机环绕（AroundPoint）
+
+```js
+// 来源: src/effect/animation/type/AroundPoint.js（demo 中通常配合选中实体）
+// 环绕当前屏幕中心目标；aroundAmount 单位 度/帧
+const around = new ANOVGIS.AroundPoint(viewer)
+around.aroundAmount = 0.3     // 每帧旋转 0.3 度
+around.start()                // 自动取屏幕中心坐标作为环绕点
+// around.stop()
+```
+
+### S4. 泛光（Bloom）后期
+
+```js
+// 来源: src/effect/type/Bloom.js；demo 见 examples/public/examples/html/effect/dog.html L226
+new ANOVGIS.Effect(viewer)                       // 一次性挂载 7 个 stage
+const bloom = viewer.effect.bloom
+bloom.enable = true
+bloom.contrast = 128        // 0-255
+bloom.brightness = -0.3
+bloom.glowOnly = false      // true=仅高亮部分发光
+bloom.sigma = 3.8
+bloom.stepSize = 5
+```
+
+### S5. 夜视 / 黑白
+
+```js
+// 来源: src/effect/type/NightVision.js、BlackAndWhite.js
+new ANOVGIS.Effect(viewer)
+
+// 夜视（绿色滤镜）
+viewer.effect.night.enable = true
+viewer.effect.night.selected = []          // 空数组=全场景；传入 entity 数组可仅作用于选中对象
+
+// 黑白
+viewer.effect.blackAndWhite.enable = true
+viewer.effect.blackAndWhite.gradations = 1 // 灰度级数，越大越分层明显
+```
+---
+## 2.1 各特效类实战补充（天气 / 漫游 / 动画 / 后期）
+
+### S6. Rain 下雨（独立开关）
+
+```js
+// 来源: src/effect/weather/type/Rain.js L20-49；demo 见 examples/public/examples/html/effect/weather.html L88-90
+const weather = new ANOVGIS.Weather(viewer)
+viewer.weather.rain.enable = true       // 开雨
+viewer.weather.rain.speed = 25          // 雨速（默认 10）
+viewer.weather.rain.mixNum = 0.6        // 雨纹混合度 0-1（默认 0.5）
+// viewer.weather.rain.enable = false   // 关
+```
+
+### S7. Snow 下雪
+
+```js
+// 来源: src/effect/weather/type/Snow.js L20-37；demo 见 weather.html L91-93
+const weather = new ANOVGIS.Weather(viewer)
+viewer.weather.snow.enable = true
+viewer.weather.snow.speed = 8           // 雪速（默认 10；Snow 只有 speed，没有 mixNum）
+// viewer.weather.snow.enable = false
+```
+
+### S8. Cloud 卷云（球面贴图旋转）
+
+```js
+// 来源: src/effect/weather/type/Cloud.js L19-41；demo 见 weather.html L85-87
+const weather = new ANOVGIS.Weather(viewer)
+viewer.weather.cloud.enable = true
+viewer.weather.cloud.rotateAmount = 0.04 // 弧度/帧，0=静止（默认 0.04）
+// 注意：仅 SceneMode.SCENE3D 生效，setter 里硬校验
+```
+
+### S9. Fog 起雾（深度雾）
+
+```js
+// 来源: src/effect/weather/type/Fog.js L32-53；demo 见 weather.html L94-96
+// Weather() 安装后直接用 viewer.weather.fog；fogByDistance 是 setter 会拆成 Cartesian4 写入
+const weather = new ANOVGIS.Weather(viewer)
+viewer.weather.fog.enable = true
+viewer.weather.fog.color = new Cesium.Color(0.6, 0.6, 0.7, 0.4)   // 雾色（默认 0,0,0,0.3）
+viewer.weather.fog.fogByDistance = {                               // 整对象赋值，setter 内拆 Cartesian4
+  near: 100, nearValue: 0.0,
+  far: 8000, farValue: 1.0,
+}
+// viewer.weather.fog.enable = false
+```
+
+### S10. LensFlare 镜头光晕（太阳眩光）
+
+```js
+// 来源: src/effect/type/LensFlare.js L34-77
+new ANOVGIS.Effect(viewer)
+const flare = viewer.effect.lensFlare
+flare.enable = true
+flare.intensity = 6       // 强度 0-10（默认 6）
+flare.distortion = 61     // 形变程度（默认 61）
+flare.dirtAmount = 0.4    // 屏幕脏污叠加 0-1（默认 0.4）
+flare.haloWidth = 0.4     // 光晕宽度 0-1（默认 0.4）
+// flare.selected = []    // 空数组=全场景；可传入 entity 数组只作用于选中对象
+```
+
+### S11. DepthOfField 景深
+
+```js
+// 来源: src/effect/type/DepthOfField.js L39-77
+new ANOVGIS.Effect(viewer)
+const dof = viewer.effect.depthOfField
+dof.enable = true
+dof.focalDistance = 87    // 对焦距离（米），前景清晰
+dof.delta = 1             // 焦外模糊增量（默认 1）
+dof.sigma = 3.8           // 模糊半径（默认 3.8）
+dof.stepSize = 2.5        // 采样步长（默认 2.5）
+// dof.selected = []       // 留空=全场景；可指定 entity 数组
+// 关闭：dof.enable = false（注意需 Cesium.PostProcessStageLibrary.isDepthOfFieldSupported）
+```
+
+---
+## 3. 速查小结
+- 天气：构造一次后 `viewer.weather.{rain,snow,fog,cloud}.enable` 切换；uniform 改字段即可。
+  - `Rain` 字段：`enable` / `speed` / `mixNum`
+  - `Snow` 字段：`enable` / `speed`（无 mixNum）
+  - `Cloud` 字段：`enable` / `rotateAmount`（仅 3D 模式）
+  - `Fog` 字段：`enable` / `color` / `fogByDistance`（setter 内会拆成 Cartesian4 写入）
+- 漫游：`RoamingController` 必传；`RoamingPath` 可独立 `actived = true`，但要自己挂 `POST_RENDER`，建议走 Controller。
+- 动画：`GlobeRotate`/`AroundPoint`/`FlyManager` 独立 new 后 `start()`；`FlyManager.routeStops` 必传（含 position/stopStayTime/duration）。
+- 后期：`new Effect(viewer)` 创建 7 个 stage，`viewer.effect.<name>.enable` 开关，setter 写穿到 native uniforms。
+  - `Bloom`：`contrast` / `brightness` / `glowOnly` / `delta` / `sigma` / `stepSize` / `selected`
+  - `LensFlare`：`intensity` / `distortion` / `dirtAmount` / `haloWidth` / `selected`
+  - `DepthOfField`：`focalDistance` / `delta` / `sigma` / `stepSize` / `selected`
+  - `NightVision`：`selected`（绿滤镜，无 intensity 字段）
+  - `BlackAndWhite`：`gradations`（灰度级数）
+  - `Brightness` / `Silhouette`：基础 enable + 各自 uniform。