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

package/skills/anovgis-models-3dtiles/SKILL.md

@@ -0,0 +1,448 @@
+---
+name: anovgis-models-3dtiles
+description: '@anov/gis 3D Tiles / glTF 模型模块。涵盖 ANOVGIS.Model（单 glTF）、ANOVGIS.Tileset（3D Tiles 容器）、Cesium3DTileStyle 条件样式、ready 异步回调、clampToGround 贴地、TilesetLayer 容器 + bindPopup 拾取、viewer.flyToTileset 定位、抽壳（quShouBengZhan）、倾斜摄影（qingxieTileset）、自定义 GLSL shader（customshader）、vectortiles 矢量瓦片、PostFog 体积雾、rainSnowPlane 雨雪平面。v1.8.6 新增 `PositonEditor` / `TilesetEditor` 位姿编辑工具、`viewer.flyTo` 可直接传 SDK Primitive/Tileset 用 boundingSphere 兜底、15 个 Primitive 类新增 boundingSphere getter。触发关键词：Model、Tileset、3D Tiles、3dtiles、tileset.json、glTF、GLB、loadGlb、customshader、自定义 shader、GLSL、qingxieTileset、倾斜摄影、quShouBengZhan、抽壳、vectortiles、矢量瓦片、PostFog、rainSnowPlane、雨雪平面、TilesetEditor、PositonEditor、pointShadowing、Cesium3DTileStyle、tileset.ready、tileset.setStyle、tileset.flyTo、tileset.clampToGround、boundingSphere、tilesetpopup、imagerylayerpopup、model.html、loadSnow。Use when 加载单 glTF / 加载 3D Tiles 模型、对 Tileset 做条件样式（按属性着色）、抽壳倾斜摄影、用 PositonEditor / TilesetEditor 编辑模型位姿、给模型绑定 Popup 拾取、加载自定义 shader 模型、批量加载多个 tileset.json。'
+anov-gis-baseline: 1.8.6
+cesium-baseline: 1.143.0
+---
+
+# anovgis-models-3dtiles — @anov/gis 3D Tiles / Model 模块
+
+> ⚠️ **优先级**：本 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` 中所有"模型"都通过 `Model`（单 glTF）或 `Tileset`（3D Tiles）加载。本 skill 涵盖两者 + `Cesium3DTileStyle` 条件样式 + `TilesetLayer` 容器 + 拾取 + v1.8.6 新增的位姿编辑工具。
+>
+> 源码根：`src/graphic/model/`（Model / Tileset）；`src/analysis/transformHelper/PositonEditor.js`（v1.8.6 新增 ~1029 行）；`src/analysis/transformHelper/TilesetEditor.js`（v1.8.6 新增 ~1034 行）（仅作语义锚点）。
+>
+> **版本基线**：`@anov/gis` v1.8.6；本文档 snippet 基于该版本 SDK 公开 API 行为锁定。
+
+---
+
+## Out-of-scope（v0.2.0 短版）
+
+- ❌ 不要写 Vector 16 类（Point / Polyline / Polygon / ...） → `anovgis-vector-graphics`
+- ❌ 不要写 Primitive 19 类（Cloud / FlowLine / ScanCircle / ...） → `anovgis-primitives`
+- ❌ 不要写 `viewer.clock` 时间播放 / `CzmlLayer` playback 完整用法 → v0.3.0 `anovgis-roaming-editor-time`
+- ❌ 不要写 `Cesium3DTileset` 原生 API 完整文档（仅覆盖 SDK 封装部分） → 见 Cesium 文档
+- ❌ 不要写 `PositonEditor` 的非模型编辑用法（如单纯点位编辑控件） → `anovgis-analysis`
+
+---
+
+## 1. 类速查表
+
+| 类 | 构造签名 | 用途 | 关键 options |
+|---|---|---|---|
+| `Model` | `new ANOVGIS.Model(options)` | 单 glTF/GLB 模型 | `url, position, scale, minimumPixelSize, maximumScale, color, silhouetteColor, colorBlendMode, colorBlendAmount` |
+| `Tileset` | `new ANOVGIS.Tileset(options)` | 3D Tiles 容器（异步）| `url, maximumScreenSpaceError, skipLevels, highlight, selectedHighlight, pointShadowing` |
+| `Cesium3DTileStyle` | `new ANOVGIS.Cesium3DTileStyle({ color: { conditions: [...] } })` | Tileset 条件样式 | `color, show, meta` |
+| `TilesetLayer` | `new ANOVGIS.TilesetLayer()` | Tileset 容器（必须 addGraphic 才能 popup/事件）| — |
+| `PositonEditor`（v1.8.6）| `new ANOVGIS.PositonEditor(opts)` | 点位/模型平移旋转缩放三轴 gizmo | `translateEnabled, rotateEnabled, scaleEnabled, xAxisLength, rotatePlaneRadius, sizeInPixel, originOffset` |
+| `TilesetEditor`（v1.8.6）| `new ANOVGIS.TilesetEditor(opts)` | Tileset 模型编辑器（继承 PositonEditor + Tileset 特有操作）| 同 PositonEditor + Tileset 属性 |
+
+> v1.8.6 起 `PositonEditor` 从 v1.8.4 的 800 行左右扩充到 1029 行；`TilesetEditor` 是 1034 行全新工具。
+
+---
+
+## 2. Snippet（18 个，覆盖 Model / Tileset / Style / 编辑）
+
+<a id="s1"></a>
+### S1. 单 glTF 模型加载
+
+```js
+// 来源: examples/public/examples/html/model/cesium_three.html L447
+const layer = new ANOVGIS.VectorLayer().addTo(viewer);  // Model 也走 Entity 体系
+const model = new ANOVGIS.Model({
+    position: [116.40, 39.90, 0],
+    url: '/data/tree.glb',
+    scale: 2.0,
+    minimumPixelSize: 64,
+    maximumScale: 100
+});
+layer.addGraphic(model);
+viewer.flyTo(model);
+```
+
+> ⚠️ **`Model` 构造只收一个 options 对象**（`position` / `url` 都在里面），不是 `(url, options)` —— 源码 `src/graphic/model/Model.js:7` 是 `constructor(options)`。
+> 同理 `Tileset` / `Cesium3DTileStyle` / `PositonEditor` 也都是单 options 对象。
+> **注意与 `Point` / `Label` / `Billboard` 不同** —— 那三个是 `(position, options)` 双参数（源码 `src/graphic/vector/Point.js:41`）。
+
+### S2. 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: buildConfig.gisStatic + 'beijingchouxi/tileset.json',
+    maximumScreenSpaceError: 6,
+    skipLevels: true,
+    highlight: { color: '#ff0000' },                       // 鼠标悬停样式
+    selectedHighlight: { color: 'rgba(255,0,255,0.8)' }    // 选中样式
+});
+
+// 异步加载完成（Cesium 1.143 fromUrl → Promise）
+tileset.ready((t) => {
+    t.pointShadowing.enabled = true;                       // 阴影
+    console.log('tileset ready', t);
+});
+layer.addGraphic(tileset);
+```
+
+### S3. Cesium3DTileStyle 条件样式（按楼层着色）
+
+```js
+// 来源: examples/public/examples/html/event/tilesetpopup.html
+tileset.setStyle(new ANOVGIS.Cesium3DTileStyle({
+    color: {
+        conditions: [
+            ['Number(${floor}) >= 40', 'rgba(45,0,75,0.5)'],
+            ['Number(${floor}) >= 20', 'rgba(125,75,150,0.5)'],
+            ['Number(${floor}) >= 10', 'rgb(248,176,87)'],
+            ['true', 'rgb(127,59,8)']
+        ]
+    },
+    show: '${floor} >= 0'                                  // 全部显示
+}));
+```
+
+### S4. Tileset 拾取 + Popup（tilesetpopup 模式）
+
+```js
+// 来源: examples/public/examples/html/event/tilesetpopup.html
+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('name1') },
+            { nameC: '楼层', value: e.feature.getProperty('floor') }
+        ]
+    });
+});
+viewer.flyToTileset(tileset, 2, 0.5, -35);                  // pitch=2, range=0.5, heading=-35
+```
+
+### S5. Tileset 贴地 clampToGround
+
+```js
+// 来源: src/graphic/model/Tileset.js
+tileset.clampToGround();
+// Cesium 1.143：调用后内部把所有 tile 投影到 terrain 上
+// 注意：仅当 viewer.scene.globe.depthTestAgainstTerrain=true 时效果可见
+```
+
+<a id="s6"></a>
+### S6. 倾斜摄影（qingxieTileset）
+
+```js
+// 来源: examples/public/examples/html/model/qingxieTileset.html
+const tileset = new ANOVGIS.Tileset({
+    url: '/data/qingxie_photogrammetry/tileset.json',
+    maximumScreenSpaceError: 6
+});
+const layer = new ANOVGIS.TilesetLayer();
+viewer.addLayer(layer);
+layer.addGraphic(tileset);
+tileset.ready(() => {
+    viewer.flyToTileset(tileset, 2, 0.5, -45);
+});
+```
+
+<a id="s7"></a>
+### S7. 抽壳模式（quShouBengZhan）
+
+```js
+// 来源: examples/public/examples/html/model/quShouBengZhan.html
+// 通过自定义 shader 抽壳（只显示模型表面）
+const tileset = new ANOVGIS.Tileset({
+    url: '/data/pump_station/tileset.json',
+    customShader: new ANOVGIS.CustomShader({
+        fragmentShaderText: `
+            void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
+                // 抽壳：只显示模型外表面
+                material.diffuse = vec3(0.8, 0.9, 1.0);
+            }
+        `
+    })
+});
+const layer = new ANOVGIS.TilesetLayer();
+viewer.addLayer(layer);
+layer.addGraphic(tileset);
+```
+
+<a id="s8"></a>
+### S8. 自定义 GLSL Shader（customshader 完整示例）
+
+```js
+// 来源: examples/public/examples/html/model/customshader.html
+const tileset = new ANOVGIS.Tileset({
+    url: '/data/model/tileset.json',
+    customShader: new ANOVGIS.CustomShader({
+        vertexShaderText: `
+            void vertexMain(VertexInput vsInput, inout vec3 positionMC) {
+                // 顶点位移（沿法线凸起）
+                positionMC += vsInput.attributes.normalMC * 10.0;
+            }
+        `,
+        fragmentShaderText: `
+            void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
+                material.diffuse = vec3(0.0, 1.0, 1.0);
+                material.alpha = 0.8;
+            }
+        `
+    })
+});
+```
+
+<a id="s9"></a>
+### S9. 矢量瓦片（vectortiles）
+
+```js
+// 来源: examples/public/examples/html/model/vectortiles.html
+const layer = new ANOVGIS.VectorLayer().addTo(viewer);
+// vectortiles 实际是 GeoJSON 形式，通过 VectorLayer 加载
+fetch('/data/vectortiles.json').then(r => r.json()).then(geojson => {
+    const ds = Cesium.GeoJsonDataSource.load(geojson, {
+        stroke: Cesium.Color.fromCssColorString('#2e91e5'),
+        fill: Cesium.Color.fromCssColorString('rgba(46,145,229,0.3)'),
+        strokeWidth: 2
+    });
+    viewer.dataSources.add(ds);
+});
+```
+
+<a id="s10"></a>
+### S10. 体积雾（PostFog）
+
+```js
+// 来源: examples/public/examples/html/model/PostFog.html
+viewer.scene.fog.enabled = true;
+viewer.scene.fog.density = 0.0002;        // 雾浓度
+viewer.scene.fog.minimumBrightness = 0.03; // 远处最暗
+// PostRender 加自定义体积雾（基于 GLSL PostProcessStage）
+viewer.scene.postProcessStages.add(new Cesium.PostProcessStage({
+    fragmentShader: `
+        void main() {
+            vec4 color = texture(czm_sceneColor, v_textureCoordinates);
+            float depth = czm_readDepth(czm_sceneDepthTexture, v_textureCoordinates);
+            // 深度相关雾化
+            float fogAmount = clamp(depth * 0.0001, 0.0, 1.0);
+            gl_FragColor = mix(color, vec4(0.7, 0.75, 0.8, 1.0), fogAmount);
+        }
+    `
+}));
+```
+
+<a id="s11"></a>
+### S11. 雨雪平面（rainSnowPlane）
+
+```js
+// 来源: examples/public/examples/html/model/rainSnowPlane.html
+// 用 ParticleSystem 实现大面积雨雪
+const rainEntity = viewer.entities.add({
+    position: Cesium.Cartesian3.fromDegrees(116.40, 39.90, 500),
+    particleSystem: new Cesium.ParticleSystem({
+        image: '/assets/rain.png',
+        startScale: 1.0,
+        endScale: 0.0,
+        particleLife: 1.5,
+        speed: 50.0,
+        imageSize: new Cesium.Cartesian2(10, 50),
+        emissionRate: 1000,
+        lifetime: 16.0,
+        loop: true,
+        emitter: new Cesium.ConeEmitter(Cesium.Math.toRadians(15.0))
+    })
+});
+```
+
+### S12. Model + Snow 天气联动
+
+```js
+// 来源: examples/public/examples/html/analysis/locateTest.html L230（Model 用法）
+//      + examples/public/examples/html/model/loadSnow.html（天气 API）
+const model = new ANOVGIS.Model({
+    position: [116.360, 39.930, 80],
+    url: '/data/tree.glb',
+    scale: 1
+});
+layer.addGraphic(model);
+// 同步开雪
+const weather = new ANOVGIS.Weather(viewer);
+viewer.weather.snow.enable = true;
+viewer.weather.snow.speed = 8;
+```
+
+### S13. TilesetEditor（v1.8.6 新增 1034 行）位姿编辑
+
+```js
+// 来源: src/analysis/transformHelper/TilesetEditor.js
+const editor = new ANOVGIS.TilesetEditor({
+    translateEnabled: true,
+    rotateEnabled: true,
+    scaleEnabled: true,
+    xAxisLength: 100,
+    rotatePlaneRadius: 80,
+    sizeInPixel: false,
+    originOffset: 0
+});
+editor.addTo(viewer);
+editor.bind(tileset);                                     // 绑定 Tileset
+// 编辑完成后通过 editor.getTransform() 拿到 modelMatrix
+const modelMatrix = editor.getTransform();
+console.log('tileset moved to:', ANOVGIS.Transform.transformCartesianToWGS84(
+    Cesium.Matrix4.getTranslation(modelMatrix, new Cesium.Cartesian3())
+));
+// editor.detach();  // 解绑
+```
+
+### S14. PositonEditor 三轴 gizmo（v1.8.6 扩充到 1029 行）
+
+```js
+// 来源: src/analysis/transformHelper/PositonEditor.js
+const editor = new ANOVGIS.PositonEditor({
+    translateEnabled: true, rotateEnabled: true, scaleEnabled: true,
+    xAxisLength: 80, yAxisLength: 80, zAxisLength: 80
+});
+editor.addTo(viewer);
+editor.bind(model);                                        // 绑定 Model 或 Entity
+// 事件订阅
+editor.addEventListener('postTransformEvent', (e) => {
+    console.log('transform changed:', e.matrix);
+});
+```
+
+### S15. viewer.flyToTileset 4 参数签名
+
+```js
+// 来源: examples/public/examples/html/event/tilesetpopup.html L93
+// 签名: viewer.flyToTileset(tileset, duration, range, pitch)
+// v1.8.6+ 起也支持 flyTo(tileset, duration, heading, pitch, range=0) 用 boundingSphere 兜底
+viewer.flyToTileset(tileset, 2.0, 0.5, -35);
+
+// v1.8.6+ 等价写法（统一 6 参数）：
+viewer.flyTo(tileset.nativeObjCesium || tileset, 2.0, 0, Cesium.Math.toRadians(-35), 0);
+```
+
+### S16. 多 Tileset 加载（数字城市）
+
+```js
+// 来源: examples/public/examples/html/demos/digitalCity.html
+const layer = new ANOVGIS.TilesetLayer();
+viewer.addLayer(layer);
+['buildings', 'roads', 'trees'].forEach(name => {
+    const ts = new ANOVGIS.Tileset({
+        url: `/data/city/${name}/tileset.json`,
+        maximumScreenSpaceError: 6
+    });
+    ts.ready(t => console.log(`${name} loaded`));
+    layer.addGraphic(ts);
+});
+viewer.flyTo(layer);
+```
+
+### S17. Tileset 颜色混合 + 高亮
+
+```js
+// 来源: src/graphic/model/Tileset.js
+const tileset = new ANOVGIS.Tileset({
+    url: '/data/tileset.json',
+    color: Cesium.Color.fromCssColorString('rgba(100,200,255,0.8)'),
+    colorBlendMode: Cesium.Cesium3DTileColorBlendMode.HIGHLIGHT,
+    colorBlendAmount: 0.5,
+    highlight: { color: '#ff0000' },
+    selectedHighlight: { color: 'rgba(255,0,255,0.8)' }
+});
+```
+
+### S18. Tileset 销毁与内存释放
+
+```js
+// 来源: SDK 通用模式
+layer.removeGraphic(tileset);     // 从 layer 移除
+tileset.destroy();                 // 释放 WebGL 资源（重要！避免内存泄漏）
+// 或直接 viewer.removeLayer(layer) 一次性销毁
+```
+
+---
+
+## 3. 反模式
+
+| 错误 | 后果 | 正确做法 |
+|---|---|---|
+| `new ANOVGIS.Tileset(url)` 后立即 `tileset.nativeObjCesium` | 拿到 undefined（异步加载未完成） | `tileset.ready(cb)` 或 `await tileset.readyPromise` |
+| `viewer.flyTo(tileset, 2, 0, -45, 0)` range 写 0 但 v1.8.5 之前 | 黑屏（无 boundingSphere） | 升级 SDK 到 v1.8.6+ 或手动算 range |
+| `tileset.destroy()` 不调 | WebGL 资源泄漏（多次切换后帧率下降） | layer.removeGraphic(tileset) → tileset.destroy() |
+| 加载 `tileset.json` 但 Cesium Ion 鉴权未配 | 401/403 | 用 Cesium ION 默认 token 或自托管 tileset.json |
+| `setStyle` 频繁调用（每帧） | 重建 shader，帧率骤降 | 改 `tileset.style = newStyle`（setter 内部 diff） |
+| Tileset 路径使用 `file://` | Workers 404 | 必须 HTTP 服务打开（`http-server` / `vite dev`） |
+
+---
+
+## 4. v1.8.6 关键变化
+
+| 变化 | 影响 | 迁移建议 |
+|---|---|---|
+| 15 个 Primitive 类新增 `boundingSphere` getter | `viewer.flyTo(primitive, ...)` 自动定位 | 升级后 range=0 自动生效，无需改 snippet |
+| `Viewer.flyTo` / `zoomTo` / `flyToTileset` 支持 SDK Primitive / Tileset | 之前需传 `nativeObjCesium` | 现在两种写法都生效，推荐直接传 SDK 实例 |
+| `PositonEditor` 增强（800 → 1029 行） | 支持更精细的编辑控件 | 新增 `originOffset` / `sizeInPixel` 等参数 |
+| `TilesetEditor` 全新工具（1034 行） | Tileset 专用位姿编辑 | 用于倾斜摄影调位姿、3D Tiles 微调 |
+| `ModelPrimitive.position` null 防御 | 不再崩溃 | 自动 fallback 到默认位置 |
+
+### S19. 建筑白模样式(`buildMaterial` + dat.GUI 切换) — `model/vectortiles1.html` L73-L196
+
+> 注:`vectortiles1.html` 文件名误导,实际是 `buildMaterial` 建筑白模 + dat.GUI 切换 5 种样式(原始 / 高度 / 科技 / 夜景 / 单色)。矢量瓦片用法见 [`anovgis-imagery-terrain` § S26](../anovgis-imagery-terrain/SKILL.md#s26-epsg4490-矢量瓦片cgcs2000-地理坐标--offlinemaploadvectortiles_4490html-l36-l56)。
+
+```js
+// 来源: vectortiles1.html L73-L86 + L161-L196
+// 关键 API: ANOVGIS.TilesetLayer + ANOVGIS.Tileset + buildMaterial.setXxxStyle
+const layer = new ANOVGIS.TilesetLayer();
+viewer.addLayer(layer);
+const build = new ANOVGIS.Tileset({
+    url: 'beijing_zhf_oldversion_nomaterial/tileset.json',
+    skipLevels: true,
+    shadows: Cesium.ShadowMode.ENABLED,
+    maximumScreenSpaceError: 6,
+    enableModelExperimental: true,
+});
+layer.addGraphic(build);
+ANOVGIS.LocateUtil.flyToPosition(viewer, '116.3866336,40.0135969', 0, -26, 8000, 2, null, Cesium.EasingFunction.QUADRATIC_IN_OUT);
+
+// dat.GUI 切换 5 种样式:
+buildMaterial.setNoStyle();                              // 原始样式
+buildMaterial.setHeightStyle();                          // 按高度着色
+buildMaterial.setTechnologyStyle();                      // 科技风
+buildMaterial.setNightStyle();                           // 夜景风
+buildMaterial.setOneColor();                             // 单色
+```
+
+---
+
+## 5. 关联阅读
+
+- SDK 源码：
+  - `src/graphic/model/Model.js` — 单 glTF
+  - `src/graphic/model/Tileset.js` — 3D Tiles
+  - `src/analysis/transformHelper/PositonEditor.js` — v1.8.6
+  - `src/analysis/transformHelper/TilesetEditor.js` — v1.8.6
+- 容器：`src/layer/graphic/TilesetLayer.js`
+- 兄弟 skill：
+  - [`anovgis-vector-graphics`](../anovgis-vector-graphics/SKILL.md) — Model 基础 + Tileset 简版
+  - [`anovgis-layers`](../anovgis-layers/SKILL.md) — TilesetLayer 容器
+  - [`anovgis-analysis`](../anovgis-analysis/SKILL.md) — PositonEditor 标绘模式
+  - [`anovgis-popup-widget`](../anovgis-popup-widget/SKILL.md) — tilesetpopup 拾取
+  - v0.3.0 `anovgis-roaming-editor-time` — TilesetEditor + viewer.clock
+  - v0.3.0 `anovgis-custom-primitive-worker` — 自定义 shader 编写
+- 关键 demo：
+  - `examples/public/examples/html/model/loadGlb.html`
+  - `examples/public/examples/html/model/qingxieTileset.html`
+  - `examples/public/examples/html/model/quShouBengZhan.html`
+  - `examples/public/examples/html/model/customshader.html`
+  - `examples/public/examples/html/event/tilesetpopup.html`
+  - `examples/public/examples/html/analysis/tools/positonEditor.html`
+- DOMAINS.md：`#1.1-graphic/`、`#1.4-analysis/`
+- DEMO-SKILL-MAP.md：`#5-model/`、`#7-analysis/`、`#8-event/`