447 lines
20 KiB
Markdown
447 lines
20 KiB
Markdown
# Preview：Cesium 预览层
|
||
|
||
> 覆盖浏览器运行时 `scripts/lib/cesium-preview.js`（672 行）与
|
||
> `cesium-preview.css`（230 行），以及 Node 侧的 `scripts/lib/area-preview.js`。
|
||
> 运行时：浏览器。全仓唯一的 DOM 环境。
|
||
|
||
---
|
||
|
||
## 定位
|
||
|
||
预览层是**验证性的，不是产物本身**。它加载 `package/manifest.json`，用来确认已发布资产
|
||
在真实 Cesium 里的样子。改这一层**不会**改变 package 内的 Blender/GLB 静态资产。
|
||
|
||
车辆巡航同理——README 里写明它是"用于验证高精度巡航可用性的预览层功能"。
|
||
|
||
---
|
||
|
||
## 没有构建步骤
|
||
|
||
```
|
||
scripts/lib/cesium-preview.js ─── 原样 copyFileSync ──▶ outputs/<area>/cesium-preview.js
|
||
scripts/lib/cesium-preview.css ─── 原样 copyFileSync ──▶ outputs/<area>/cesium-preview.css
|
||
（area-preview.js:writeCesiumPreviewSupportFiles）
|
||
<area>-cesium-preview.html ─── 模板字符串生成 ────▶ 同目录
|
||
（area-preview.js:cesiumPreviewHtml）
|
||
```
|
||
|
||
所以：**没有打包、没有转译、没有 npm 依赖、没有模块系统**。浏览器直接吃。
|
||
写代码时只能用目标浏览器原生支持的语法，`Cesium` 从 CDN 全局引入。
|
||
|
||
整个文件是一个 IIFE + `"use strict"`（`cesium-preview.js:1-2`）。
|
||
|
||
---
|
||
|
||
## 参数注入
|
||
|
||
JS 不硬编码任何文件名，全部从 HTML 注入的全局对象读：
|
||
|
||
```js
|
||
const config = window.OSM_ASSET_PREVIEW_CONFIG || {}; // :4
|
||
// config.areaId / .glbName / .metadataName / .routeName / .vehicleModelName
|
||
```
|
||
|
||
生成侧在 `scripts/lib/area-preview.js` 的 `cesiumPreviewHtml()`，注入时**必须转义**：
|
||
|
||
| 场景 | 用 |
|
||
|---|---|
|
||
| HTML 文本/属性 | `escapeHtml()` |
|
||
| `<script>` 里的 JSON | `escapeScriptJson()` |
|
||
|
||
`|| {}` 的兜底不能删——它让 JS 在没有配置块时也不至于在第一行就崩。
|
||
|
||
**加一个新的可配置项**：`cesiumPreviewHtml()` 里加进注入的 JSON，JS 侧从 `config` 读，
|
||
两边都要动。
|
||
|
||
`glbName` 与 `metadataName` 都是 `package/manifest.json`。浏览器读取 package manifest 后，
|
||
每个 `assets[*].uri` 必须相对**manifest 文件**解析，绝不能相对 preview HTML 解析；否则将
|
||
错误请求 `outputs/<area>/models/...` 而不是 `outputs/<area>/package/models/...`。
|
||
|
||
`build-area.js` 只保留已发布 package / 动态输入的依赖检查、写入顺序和 preview manifest ownership；
|
||
不要把 HTML 模板、runtime copy 或转义实现移回阶段调度器。路线 JSON 与车辆 glTF 分别由
|
||
`vehicle-route.js` 和 `vehicle-model.js` 生成，二者都是不启动外部工具的 Node 模块。
|
||
交通信号灯 runtime 则从 package manifest 的 `runtime` 读取；预览只负责驱动其状态，不拥有这些文件。
|
||
|
||
---
|
||
|
||
## 加载流程
|
||
|
||
`main()`（`:30-52`）的顺序是刻意的：
|
||
|
||
```
|
||
setLoadingMessage("Loading scene")
|
||
→ fetchJson(metadata) 必需，失败即终止
|
||
→ fetchOptionalJson(route) 可选，失败降级
|
||
→ scenePlacement(metadata)
|
||
→ createViewer()
|
||
setLoadingMessage("Loading model")
|
||
→ loadSceneAssets() 逐个资产加载，失败收集不中断
|
||
→ addVehicleCruises() / createCameraPresets()
|
||
→ buildAssetToggles() / bindRuntimeControls() / startDiagnostics()
|
||
→ cameras.overview()
|
||
→ baseStatus = summaryText(...)
|
||
setLoadingMessage("Preparing view")
|
||
→ await waitForStableFrames() 等画面稳定
|
||
→ document.body.classList.add("scene-ready") ← CSS 靠这个类收起遮罩
|
||
→ window.osmPreview = {...}
|
||
```
|
||
|
||
### 三档失败语义
|
||
|
||
这一层的错误处理分得很清楚，**新增加载逻辑时要先想清楚落在哪一档**：
|
||
|
||
| 档 | 做法 | 出处 |
|
||
|---|---|---|
|
||
| **必需** | `fetchJson` 直接抛，预览起不来 | `:55-62` |
|
||
| **可选** | `fetchOptionalJson` 捕获 → `console.warn` → 返回 `null` | `:63-73` |
|
||
| **部分** | 逐条收集失败，汇总到诊断面板，其余照常显示 | `:163-165` |
|
||
|
||
两段注释把理由写清楚了：
|
||
|
||
> The route file is an extra on top of the scene, not a precondition for it.
|
||
> A missing or unreadable route costs the cruise controls, not the preview.
|
||
|
||
> One broken entry in metadata.assets should not blank the whole preview, so
|
||
> failures are collected and surfaced in the diagnostics panel instead.
|
||
|
||
### `scene-ready` 是加载态的唯一开关
|
||
|
||
`waitForStableFrames()`（`:107`）等若干帧稳定后才加 `scene-ready` 类，CSS 据此
|
||
收起遮罩。**不要改成定时器或 `load` 事件**——材质编译完成之前画面是花的。
|
||
|
||
### `window.osmPreview` 是唯一对外句柄
|
||
|
||
```js
|
||
// Handle for the browser console and for headless checks: everything else
|
||
// in here is closed over by the IIFE and unreachable from outside. :50-51
|
||
window.osmPreview = { viewer, metadata, placement, assets, cruise, cameras };
|
||
```
|
||
|
||
预览加载的生成式 JSON（路线和交通信号）使用 `fetch(..., { cache: "no-store" })`，因为
|
||
这些文件保持稳定文件名但会被单独重生成；浏览器不得继续显示旧的巡航路线。
|
||
|
||
调试和无头检查都靠它。**加新的顶层对象就往这里挂**，不要再开新全局。
|
||
|
||
---
|
||
|
||
## Viewer 配置：一切都关掉
|
||
|
||
`createViewer()`（`:74-97`）把 Cesium 的默认 UI 和地球全部关闭：
|
||
|
||
```js
|
||
animation, timeline, baseLayerPicker, geocoder,
|
||
navigationHelpButton, sceneModePicker, infoBox,
|
||
selectionIndicator, baseLayer ← 全 false
|
||
globe.show = false ← 不显示地球
|
||
skyAtmosphere / skyBox / sun / moon ← 全 false
|
||
backgroundColor = globe.baseColor = "#d9e0e2" ← PREVIEW_BACKGROUND
|
||
```
|
||
|
||
理由：这是**看单个园区资产**的预览，不是地图应用。留着地球和大气会干扰对
|
||
材质与几何的判断，也让背景色不可控。
|
||
|
||
`depthTestAgainstTerrain = false` —— 没有地形，开着只会让模型被裁。
|
||
|
||
保留的只有 `homeButton` 和 `fullscreenButton`。
|
||
|
||
---
|
||
|
||
## DOM 与状态
|
||
|
||
### DOM 句柄集中在顶部
|
||
|
||
`:5-20` 一次性取完全部元素引用，**不在函数里现查**。新增控件时加在这一批里。
|
||
|
||
### status 的两类消息
|
||
|
||
```js
|
||
// Status carries two kinds of message: the scene summary, which is what the
|
||
// panel should read whenever nothing else is going on, and transient notes
|
||
// from a control the user just touched. Keep the summary so the transient
|
||
// note can be replaced instead of destroying it. :21-24
|
||
let baseStatus = "";
|
||
```
|
||
|
||
`baseStatus` 存场景摘要，瞬时提示用完要能回到它。**加新的瞬时提示时不要直接覆写
|
||
`baseStatus`**。
|
||
|
||
### 诊断读数跟渲染循环，不跟定时器
|
||
|
||
```js
|
||
// Camera-dependent readouts have to track the camera, so refresh off the
|
||
// render loop rather than a fixed timer, throttled to stay off the hot path. :589-590
|
||
```
|
||
|
||
相机相关的读数必须跟着渲染循环刷新并**做节流**。用 `setInterval` 会在相机快速移动时
|
||
读到过期值，不节流会拖慢帧率。
|
||
|
||
### 车辆巡航热路径要少分配
|
||
|
||
车辆巡航是预览层里唯一持续动画的功能。`scripts/lib/cesium-preview.js` 的
|
||
`routeOrientation()` 和 `createChaseFollow()` 每帧都会运行，里面的 `JulianDate`、
|
||
`HeadingPitchRoll`、`Quaternion`、`Matrix4` 等临时对象必须在闭包外复用，不要在
|
||
`CallbackProperty` 或 `viewer.clock.onTick` 回调里 `new`。
|
||
|
||
预览页面加载的是 30MB+ GLB，动画时 GPU 已经很忙；巡航辅助线也要避免额外透明合成。
|
||
路线 polyline 使用不透明 `Color` 和 `arcType: Cesium.ArcType.NONE`，不要为了视觉效果
|
||
随手改回半透明 geodesic 线。
|
||
|
||
不要默认降低 `viewer.resolutionScale` 或关闭 antialias/MSAA 来换取巡航流畅度。
|
||
这会让用户误判材质和模型质量。若确实需要性能模式，应做成显式开关，而不是默认牺牲
|
||
预览清晰度。
|
||
|
||
### 车辆事件仅属于预览会话
|
||
|
||
点击车辆的信息卡可在 `normal`、`breakdown`、`accident` 三态间切换。这是验证交互，
|
||
不得写入 `package/`、路线 JSON 或 OSM。状态必须附着在 `addCruiseVehicle()` 返回的记录上；
|
||
`createTrafficAwarePositions()` 只在状态为 `normal` 时推进已有的 route distance，恢复正常从
|
||
当前停点继续。
|
||
|
||
- `breakdown`：黄色扳手 label，路线保留原色。
|
||
- `accident`：红色警示 label，路线设为红色。
|
||
- `normal`：隐藏 label，恢复原路线颜色。
|
||
|
||
车辆实体以 `properties.vehicleId` 标识；点击拾取必须只处理此属性，不能把静态模型、路线或
|
||
信号灯当作车辆。Cesium InfoBox 在本预览中关闭，信息卡必须使用 HTML/CSS，并把新增 DOM 句柄
|
||
集中在 `cesium-preview.js` 顶部。
|
||
|
||
### 单资产 vs 多资产的开关
|
||
|
||
```js
|
||
// A single-asset scene keeps the plain "Scene" checkbox; a multi-asset one
|
||
// gets a child checkbox per model with "Scene" acting as the master. :194-195
|
||
```
|
||
|
||
`buildAssetToggles()` 按资产数量决定 UI 形态，`syncSceneMaster()` 维护主从关系。
|
||
|
||
---
|
||
|
||
## 坐标系
|
||
|
||
GLB 停留在**局部 ENU 坐标系**（X 东、Y 北、Z 上），靠伴生 JSON 的放置信息配合
|
||
`Cesium.Transforms.eastNorthUpToFixedFrame` 摆到地球上
|
||
（`blender/export_cesium.py:8-9`）。
|
||
|
||
`scenePlacement(metadata)`（`:131`）负责这一步。**改动导出侧的坐标约定必须同步改这里。**
|
||
|
||
## 交通信号动态覆盖层
|
||
|
||
metadata 的动态资产契约如下：
|
||
|
||
- `category="dynamic"`：灯珠节点，继续按相位切换红/黄/绿 lens 的 `show`。
|
||
- `category="countdown"` 且 `phaseGroup` 为 `0` 或 `1`：对应相位组的倒计时模型；模型内
|
||
共享 20 个数字节点，不按每个信号复制数字。
|
||
|
||
三个模型必须使用完全相同的 `placement.modelMatrix`。倒计时颜色只能通过模型级
|
||
`model.color` 配合 `Cesium.ColorBlendMode.REPLACE` 设置；普通 glTF PBR 材质的
|
||
`getMaterial().setValue()` 在本项目验证中不能可靠修改运行时字色，禁止作为实现路径。
|
||
倒计时数字的显示逻辑只改变当前数字节点的 `show`，颜色由该 phase group 的当前灯色
|
||
统一设置。加载失败属于部分资产失败：应进入诊断而不清空主场景。
|
||
|
||
## 语义检查资产
|
||
|
||
### 1. 范围与触发条件
|
||
|
||
`cesium` 阶段除完整主 GLB 外，会按 Blender 顶层集合导出可选检查资产：道路、建筑、
|
||
绿化与设施、水体。它们只服务于预览检查；主 GLB 仍是下游兼容基线，不能被替换。
|
||
|
||
### 2. 调用形式
|
||
|
||
不新增 CLI 参数。正常运行 Cesium 阶段即可：
|
||
|
||
```bash
|
||
npm run build:area -- --config config/areas/<area>.json --stages cesium
|
||
```
|
||
|
||
### 3. 契约
|
||
|
||
- `blender/export_cesium.py:SEMANTIC_ASSETS` 是集合名、稳定资产 ID 与展示名的唯一映射：
|
||
`03_Roads → roads`、`04_Buildings → buildings`、`02_Green + 05_Props → vegetation`、
|
||
`01_Water → water`。
|
||
- 每个有几何的类别额外写 `<stem>-<id>.glb`，且必须保留与主 GLB 相同的局部 ENU 坐标和
|
||
已处理的 Cesium 材质。
|
||
- metadata 的主资产保持 `id="main"`、`enabled=true`；辅助项设
|
||
`category="semantic"`、`enabled=false`，并提供 `id`、`label`、`type="model"`、`url`。
|
||
- `build-area.js:semanticAssetRecords()` 必须验证 metadata 声明的每个语义文件存在后才写
|
||
Cesium manifest。
|
||
- 浏览器先加载非语义资产；只有点 `Inspect` 才加载辅助 GLB。检查模式必须隐藏主场景，
|
||
返回 `Scene` 必须隐藏辅助模型，禁止两套几何重叠渲染。
|
||
- 没有 `category="semantic"` 的旧 metadata 仍按单资产预览打开，`Inspect` 按钮禁用。
|
||
|
||
### 4. 校验与错误矩阵
|
||
|
||
| 条件 | 结果 |
|
||
|---|---|
|
||
| 类别集合没有可导出 mesh | metadata 不声明该类别，预览不显示该开关 |
|
||
| metadata 声明语义资产但文件不存在 | Cesium 阶段失败，不能写成功 manifest |
|
||
| 辅助 GLB 浏览器加载失败 | 该开关禁用并写入诊断；主场景继续可用 |
|
||
| 旧 metadata 没有语义项 | 完整场景照常显示，`Inspect` 不可点击 |
|
||
|
||
### 5. 正常、基础与错误示例
|
||
|
||
- 正常：进入 `Inspect` 后道路、建筑、绿化与设施、水体全部显示，再单独取消任一类别。
|
||
- 基础：旧的只有 `main` 资产的 metadata 不展示分类控件，所有原有控制仍可用。
|
||
- 错误：主 GLB 和语义 GLB 同时可见，导致道路、建筑等重复渲染和闪烁。
|
||
|
||
### 6. 必需测试
|
||
|
||
- `node scripts/test-preview-assets.js`：断言生成页包含模式切换与语义开关挂载点。
|
||
- `node --check scripts/build-area.js`、`node --check scripts/lib/area-preview.js`、
|
||
`node --check scripts/lib/cesium-preview.js`。
|
||
- 目标区域运行 `--stages cesium`，确认 metadata 的语义 `assets` 与同名辅助 GLB 一一对应。
|
||
- 浏览器在桌面及窄屏分别切换 `Scene` / `Inspect`，确认不重叠且控制不溢出。
|
||
|
||
### 7. 错误与正确写法
|
||
|
||
错误：把辅助模型标为默认启用，页面加载时把它们与主 GLB 一起绘制。
|
||
|
||
```json
|
||
{ "id": "roads", "enabled": true, "category": "semantic" }
|
||
```
|
||
|
||
正确：默认关闭并在检查模式按需加载。
|
||
|
||
```json
|
||
{ "id": "roads", "enabled": false, "category": "semantic" }
|
||
```
|
||
|
||
---
|
||
|
||
## 实时 V2X 车辆仅数据源
|
||
|
||
### 1. Scope / Trigger
|
||
|
||
适用于开启 `v2xPreview.enabled` 的 Cesium 运营预览。触发：修改
|
||
`v2x-cesium-overlay.js`、preview descriptor 的 `routeName`、或实时车辆展示。
|
||
|
||
### 2. Signatures
|
||
|
||
```text
|
||
WS /network/ws/network/signal?authorization=<token>
|
||
WS /network/ws/network/obuPosition?authorization=<token>
|
||
WS /network/ws/network/targetPosition?authorization=<token>
|
||
```
|
||
|
||
OBU 消息使用 `carCode|obuCode`、`lon`、`lat`、`angle`、`speed`；目标识别消息使用
|
||
`data[deviceId][]` 内的 `id`、`longitude`、`latitude`、`type`、`subType`、`angle`、`speed`。
|
||
两类车辆消息的根部还带 `interval`（推送间隔，`0` 视为 `500`）。
|
||
信号灯消息使用 `lamps[]` 内的 `phaseNo`、`status`、`countDown`。
|
||
|
||
### 3. Contracts
|
||
|
||
- 两条车辆流均为 GCJ-02，必须在实体创建前恰好调用一次 `gcj02ToWgs84`。
|
||
- 本预览的 `routeName` 必须为 `null`，且不得生成 `trafficSimulation` 描述符。
|
||
真正的不变量是**不得有生成路线或交通仿真**，而不是「没有车模型」——
|
||
实时 V2X 车辆需要打包的车模型才能渲染，故 `vehicleModelNames` 由
|
||
`writeVehicleModel(area)` 正常写出（`build-area.js:writeCesiumPreview`），
|
||
`vehicleModelName` 取其首项。早期版本靠清空模型列表来阻止仿真车辆，
|
||
该机制已不适用，不要再用它作为约束手段。
|
||
- 每辆实时车保留最多 24 个已转换的位置作为实际轨迹；轨迹不是推测路径。
|
||
- **灯色码字典只有一份**，取自源看板 `HologramCross/components/utils.ts`：
|
||
`11=灭 21=红 22=黄 23=绿 31=其他`，未知码归入「其他」，**不得**落到红色。
|
||
overlay 归一化为 `{nodeKeys, color, countDown}` 后单向传给 `cesium-preview.js`；
|
||
预览层不得自带第二份字典。
|
||
- **三条 socket 必须发心跳** `{"heartBeat":"ping"}` / 30000ms，并在断线后退避重连，
|
||
且**重连后重放订阅帧**（signal 发 `junctionId`，obu 发 bounds，target 发 `deviceId`）。
|
||
缺心跳会被服务端断开，画面在一分钟后静默变空。
|
||
- **相位到原生灯头靠几何绑定**：`traffic-signals.json` 无 `phaseNo`，用 link 末段停止线点与
|
||
航向匹配原生 `stopLongitude/stopLatitude` 与行车方向；行车方向 =
|
||
`faceHeadingDegrees + 180`（生成侧 `scripts/lib/traffic-signals.js` 定义
|
||
`mast = travel - 90`、`face = travel + 180`）。
|
||
一相位可点亮多条进口道，一条 link 可点亮同进口道多个灯头，两侧都取并集。
|
||
未绑定相位须计数上报，可用 `v2xPreview.phaseSignalMap` 显式覆盖。
|
||
- **车辆生命周期**：超过 `interval * 1.5` 未更新即隐藏（不删除），隐藏项作为同模型的可复用槽位；
|
||
socket 断开清空车辆。OBU 数据 hook 标记为 `car_obu.glb`，但 dashboard 的最终
|
||
`CrossCars` 模板实际渲染 `11.glb`，预览必须以 `11.glb` 为准；目标车为
|
||
`${type}${subType}.glb`。`11/12/13/14/15/16/17/31/221/222.glb` 必须打入
|
||
`_preview/v2x-vehicles/`。
|
||
- **可见性是运行时契约**：有效推送创建的模型必须在路口概览下至少为 `28px`，并允许最大
|
||
`8x` 放大；位置高度须高于静态道路表面。首次有效车辆推送应聚焦到车群附近，标签须不受
|
||
静态 GLB 的深度遮挡。仅验证 WS 收包或 registry 条数不算通过。
|
||
- 车辆推送体解析必须容忍非严格 JSON（源看板用 `saferEval`），失败须计数并在面板可见，
|
||
**不得**静默丢弃；实现不得使用 `eval` / `new Function`。
|
||
- 周流量比 `FlowTravelRatio/queryListWeek` **不属于**实时路口范围。
|
||
|
||
### 4. Validation & Error Matrix
|
||
|
||
| 条件 | 结果 |
|
||
|---|---|
|
||
| 未登录、令牌失效、REST/WS 不可用 | 静态路口继续显示，车辆层为空，并显示实时数据不可用状态 |
|
||
| 消息不是 JSON、心跳、坐标无效 | 忽略该消息，不创建车辆；非心跳的解析失败须计数 |
|
||
| 收到有效车辆坐标 | 创建或更新真实车辆与实际轨迹 |
|
||
| 车辆超过 `interval * 1.5` 未更新 | 隐藏该车并保留槽位，不得堆积幽灵车 |
|
||
| 相机视野变化 | 节流后向 obu socket 发送 GCJ-02 四角 `bounds` |
|
||
| 视野矩形不可用 | 发空帧（等于不过滤），不得跳过发送导致空场景 |
|
||
| 相位一个都没绑定 | 面板显性提示并建议配置 `phaseSignalMap` |
|
||
|
||
### 5. Good / Base / Bad Cases
|
||
|
||
- Good：OBU 和感知目标连续推送，页面只显示对应车辆的实际行驶轨迹。
|
||
- Base：服务无数据，页面没有车辆或线路。
|
||
- Bad：将旧路线 JSON 或 `native-preview-traffic-simulation` 用作回退展示。
|
||
|
||
### 6. Tests Required
|
||
|
||
- `npm run test:v2x-cesium-preview`：校验灯色字典（含 `2`/`3` 不再是黄/绿的回归断言）、
|
||
宽松解析、几何相位绑定（对真实 `traffic-signals.json` 须达成精确一对一）、
|
||
同相位多进口道并集、车辆超时与槽位复用、心跳间隔与重连重放订阅帧、bounds 报文。
|
||
- `npm run test:preview-assets`：断言三条 WebSocket 存在，runtime 不调用
|
||
`addVehicleCruises`、不显示 simulation 诊断，且预览层**不再自带** `lampColorName`
|
||
或 `Number(status) === 3` 判断；断言实时车辆最小像素尺寸和诊断可见数量读数存在。
|
||
- 对目标区域运行 `npm run build:area -- --config config/areas/<area>.json --stages preview`，
|
||
检查 descriptor 中 `routeName` 为空、不存在 traffic-simulation 文件，
|
||
且 `vehicleModelNames` 已写出（实时车辆渲染需要）。
|
||
|
||
### 7. Wrong vs Correct
|
||
|
||
错误：接口不可用时恢复构造路线。
|
||
|
||
```js
|
||
const cruise = addVehicleCruises(viewer, routeData, signalData, start);
|
||
```
|
||
|
||
正确：保持空车辆层，等待真实流。
|
||
|
||
```js
|
||
const cruise = createLiveVehicleState();
|
||
```
|
||
|
||
## 本地预览必须走 HTTP
|
||
|
||
```bash
|
||
cd outputs/<area-id>
|
||
python3 -m http.server 8765
|
||
# → http://localhost:8765/<area-id>-cesium-preview.html
|
||
```
|
||
|
||
`file://` 会被浏览器的同源策略拦掉 `fetch`，页面停在加载遮罩上。
|
||
|
||
---
|
||
|
||
## 反模式
|
||
|
||
| 反模式 | 后果 |
|
||
|---|---|
|
||
| 引入需要打包/转译的语法或 npm 依赖 | 没有构建步骤，直接跑不起来 |
|
||
| 在 JS 里硬编码 `.glb` / `.json` 文件名 | 换区域就失效，绕过 config 注入 |
|
||
| 注入 HTML 时不转义 | 区域名带特殊字符就破页面 |
|
||
| 把可选资源当必需资源加载 | 缺一个路线文件整个预览打不开 |
|
||
| 单个资产加载失败就中断全部 | 一条坏 metadata 让预览全白 |
|
||
| 用定时器代替 `waitForStableFrames` | 遮罩在材质编译完成前就收起，画面是花的 |
|
||
| 相机读数用 `setInterval` | 快速移动时读到过期值 |
|
||
| 诊断刷新不节流 | 拖慢帧率 |
|
||
| 在车辆每帧回调里创建 `JulianDate` / HPR / 矩阵对象 | 巡航时触发 GC 抖动 |
|
||
| 默认打开半透明路线辅助线 | 增加透明合成成本，主场景可见时车辆更不顺 |
|
||
| 默认降低 `resolutionScale` 或关抗锯齿 | 预览变糊，无法判断材质/模型质量 |
|
||
| 再开一个全局变量 | 已有 `window.osmPreview` |
|
||
| 用 `file://` 打开 | fetch 被拦，卡在加载中 |
|
||
|
||
---
|
||
|
||
## 相关
|
||
|
||
- [CLI 与阶段](../pipeline/cli-and-stages.md)：`cesium` / `preview` 阶段如何生成这些文件
|
||
- [资产生成](../blender/asset-generation.md)：GLB 里的材质为什么要单独调色
|
||
- [车辆连续路线](vehicle-routes.md)：路线 JSON、转向选择与预览标签契约
|
||
- README「实验：车辆巡航」节：面向使用者的说明
|