diff --git a/VERSION b/VERSION index 73f8a5ac..b51b5439 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.44.1 +0.44.2 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 2217e48e..af41451f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,15 @@ This project follows the repository versioning rule: - `improvement` -> `+0.0.1`(bugfix + 小功能混合) - `bugfix` -> `+0.0.1` +## [0.44.2] — 2026-04-29 + +### 📝 Documentation +- 补充 Earth 船只图层技术文档,记录分桶 `THREE.Points` 批量渲染、同尺寸交互 overlay 和屏幕空间 picking 的设计约束。 +- 同步 Earth 渲染图层顺序和样式参考,明确 AIS 船只 renderOrder、depthTest、图标尺寸、航向分桶与 hover 命中半径。 +- 更新船只渲染性能计划状态,标注 `0.44.1` 已落地的实现与后续全球 AIS / LOD 演进方向。 + +--- + ## [0.44.1] — 2026-04-29 ### 🐛 Fixes diff --git a/docs/plans/earth-vessel-rendering-performance-plan.md b/docs/plans/earth-vessel-rendering-performance-plan.md index ddeec25f..7db14adc 100644 --- a/docs/plans/earth-vessel-rendering-performance-plan.md +++ b/docs/plans/earth-vessel-rendering-performance-plan.md @@ -1,5 +1,17 @@ # Earth Vessel Rendering Performance Plan +## 当前状态 + +该计划的前端核心部分已经在 `0.44.1` 落地,但最终实现不是原文设想的 `InstancedBufferGeometry` quad,而是更稳的分桶 `THREE.Points` 方案: + +- 普通船只按 moving / anchored 和 `VESSEL_COURSE_BINS` 航向分桶,使用 `PointsMaterial` 批量绘制。 +- 航行船只仍是带方向的三角形,停泊或低速船只仍是圆点。 +- hover / locked 不再放大成世界尺寸 Sprite,而是在原点位叠加同尺寸单点 glow overlay。 +- picking 改为屏幕空间命中,拖动和惯性期间跳过 hover picking。 +- 普通态关闭 glow,交互态才显示 glow,降低 overdraw 并让默认地图更干净。 + +后续如果需要全球 AIS 或更高船只密度,再评估是否从分桶 `Points` 升级到真正 instanced quad 或视口 bbox / LOD。 + ## 背景 Earth 船只图层已经形成了一套较好的视觉语言: @@ -8,10 +20,10 @@ Earth 船只图层已经形成了一套较好的视觉语言: - 标记按航向旋转 - 停泊或低速船只使用圆点 - 不同船型使用不同颜色 -- hover / locked 状态有放大、透明度和聚焦反馈 +- hover / locked 状态有 glow、透明度和聚焦反馈 - 标记带有轻微 glow / soft edge,和 Earth HUD 的观感一致 -当前性能问题不应通过降级成普通 `Points` 来解决。目标是在保留现有观赏性的前提下,把底层从“每艘船一个 Sprite 对象”优化为批量绘制和轻量交互。 +当前性能问题不应通过降级成无方向、无船型语义的普通小点来解决。目标是在保留现有观赏性的前提下,把底层从“每艘船一个 Sprite 对象”优化为批量绘制和轻量交互。 ## 当前问题判断 @@ -106,11 +118,18 @@ Earth 船只图层已经形成了一套较好的视觉语言: 目标是减少屏幕空间重叠面积,而不是改变符号设计。 -## Phase 3:保留视觉的批量渲染 +## Phase 3:保留视觉的批量渲染(已落地为分桶 Points) -正式方案是把每艘船的视觉从 `THREE.Sprite` 迁移为 instanced sprite batch。 +原设想是把每艘船的视觉从 `THREE.Sprite` 迁移为 instanced sprite batch。实际落地时选择了更稳的分桶 `THREE.Points`: -### 1. 使用 instanced quad +- 不依赖自定义 shader。 +- 不依赖 `Points` 自带 raycaster。 +- 用 canvas 纹理保留三角、圆点、船型颜色和航向。 +- 用 hover / locked 单点 overlay 保留交互 glow。 + +如果未来全球 AIS 导致分桶 `Points` 仍不够,再升级到 instanced quad。 + +### 1. 原候选方案:instanced quad 每艘船仍然显示为带贴图/软边的 billboard,但底层使用: @@ -130,7 +149,7 @@ Earth 船只图层已经形成了一套较好的视觉语言: 这样 draw call 从“每艘船一个”变为“每类船只一个”。 -### 2. per-instance attributes +### 2. 原候选方案:per-instance attributes 每个 instance 存: @@ -142,9 +161,21 @@ Earth 船只图层已经形成了一套较好的视觉语言: - state - mmsi / data index -hover、locked、dimmed 通过更新少量 instance attribute 实现,不再逐个修改 material。 +hover、locked、dimmed 可通过更新少量 instance attribute 实现,不再逐个修改 material。 -### 3. 复刻当前视觉 +### 3. 当前落地方案:分桶 `THREE.Points` + +当前实现按以下方式复刻视觉: + +- moving 船只按 `VESSEL_COURSE_BINS` 做航向分桶。 +- anchored / slow 船只使用圆点分桶。 +- 每个分桶生成一组 `THREE.Points`,共享 `PointsMaterial` 和 canvas 点纹理。 +- `VESSEL_CONFIG.colors` 仍通过 vertex colors 表示船型颜色。 +- hover / locked 在原位置叠加同尺寸单点 overlay,普通态不带 glow,交互态才带 glow。 + +这样 draw call 从“每艘船一个”变为“每个形状 / 航向分桶一组”,同时避免自定义 shader 的兼容风险。 + +### 4. 复刻当前视觉 视觉上继续使用当前 canvas texture 或等效 shader: @@ -213,5 +244,6 @@ hover、locked、dimmed 通过更新少量 instance attribute 实现,不再逐 1. 先做 Phase 1,快速恢复地球拖动手感。 2. 再做 Phase 2,减少每帧 JS 写操作。 -3. 最后做 Phase 3 和 Phase 4,把船只迁移到 instanced sprite batch。 +3. Phase 3 和 Phase 4 已按分桶 `THREE.Points` + 屏幕空间 picking 落地。 4. Phase 5 等全球船只数据或数量压力出现后再推进。 +5. 如果分桶 `THREE.Points` 达到瓶颈,再评估 instanced quad。 diff --git a/docs/technical/zh/earth-frontend-context.md b/docs/technical/zh/earth-frontend-context.md index 42235f74..2690cb36 100644 --- a/docs/technical/zh/earth-frontend-context.md +++ b/docs/technical/zh/earth-frontend-context.md @@ -253,11 +253,34 @@ AIS 船只图层入口: 船只图层当前负责: - 请求 `/api/v1/visualization/geo/vessels` -- 将 BarentsWatch AIS GeoJSON 转为 Three.js sprite +- 将 BarentsWatch AIS GeoJSON 转为地球局部坐标 marker 数据 +- 用按航向分桶的 `THREE.Points` 批量渲染普通船只 marker - 按船型映射颜色 - 根据航行/停泊状态绘制三角形或圆点纹理 +- 用单点 `THREE.Points` overlay 承载 hover / locked glow - 支持 hover、lock、轨迹加载和视觉聚焦 +船只图层不再是“每艘船一个 `THREE.Sprite`”。原始 Sprite 方案在拖动地球时会把透明对象排序、draw call 和对象级 raycast 成本全部放到主交互路径上;即使 BarentsWatch 免费 AIS 当前只覆盖挪威周边,也会让地球拖动明显不跟手。 + +当前设计把普通船只拆成少量批次: + +- moving / anchored 分开。 +- moving 船只按 `VESSEL_COURSE_BINS` 做航向分桶。 +- 每个批次是一组 `THREE.PointsMaterial`,位置和颜色写入 `BufferGeometry` attribute。 +- 普通态不带 glow;hover / locked 时才在相同点位叠加带 glow 的单点 overlay。 + +方向标准以 AIS `course / cog` 为准:从正北开始顺时针。普通态和交互态都通过同一套 canvas 旋转规则生成纹理,避免 hover 后箭头方向和原 marker 不一致。 + +船只 hover / click 也不再对渲染对象做 `raycaster.intersectObjects()`。`main.js` 会: + +1. 拖动地球或惯性旋转时跳过 hover picking。 +2. 对 hover picking 做轻量节流。 +3. 只保留正面船只作为候选。 +4. 将候选船只投影到屏幕坐标。 +5. 用 `VESSEL_POINTER_RADIUS_PX` 做像素距离命中,并取最近船只。 + +这样 picking 位置和用户看到的屏幕 marker 对齐,也避免 `Points` 自带 raycaster 在固定屏幕尺寸图标上的命中半径错位。 + 图例系统已经注册 `vessels` 模式: - [legend.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/legend.js) diff --git a/docs/technical/zh/earth-layer-style-reference.md b/docs/technical/zh/earth-layer-style-reference.md index bcfe969a..369ef053 100644 --- a/docs/technical/zh/earth-layer-style-reference.md +++ b/docs/technical/zh/earth-layer-style-reference.md @@ -186,6 +186,27 @@ | footprint renderOrder | local `GROUND_FOOTPRINT_RENDER_ORDER` | `3` | footprint fill | | footprint group renderOrder | inline | `0` | 避免 Group 排序盖过卫星点 | +## AIS 船只 + +| 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 | +| --- | --- | --- | --- | +| 船只半径偏移 | `VESSEL_CONFIG.altitudeOffset` | `0.56` | 普通 marker 位置 | +| 船只轨迹半径偏移 | `VESSEL_CONFIG.track.altitudeOffset` | `0.7` | 选中船只轨迹线 | +| 船只 renderOrder | local `VESSEL_RENDER_ORDER` | `4.4` | 普通 marker 和交互 overlay | +| 船只轨迹 renderOrder | `VESSEL_RENDER_ORDER - 0.1` | `4.3` | 低于船只 marker | +| 船只点像素尺寸 | local `VESSEL_POINT_SIZE` | `34` | 普通 marker 与 hover / locked overlay 共享尺寸 | +| 船只纹理画布尺寸 | local `VESSEL_ATLAS_CELL_SIZE` | `128` | canvas 点纹理 | +| 航向分桶数 | local `VESSEL_COURSE_BINS` | `32` | moving 船只按 COG 分桶,降低 draw call 同时保留方向 | +| 船只 hover 拾取节流 | local `VESSEL_HOVER_PICK_INTERVAL_MS` | `100` | `main.js` hover picking | +| 船只屏幕命中半径 | local `VESSEL_POINTER_RADIUS_PX` | `22` | `main.js` 屏幕空间 picking | +| 普通船只透明度 | `VESSEL_CONFIG.marker.baseOpacity` | `0.88` | 普通 `PointsMaterial.opacity` | +| dimmed 船只透明度 | `VESSEL_CONFIG.marker.dimmedOpacity` | `0.26` | 锁定某艘船后其他批次透明度 | +| hover 船只透明度 | inline | `0.98` | hover overlay | +| locked 船只透明度 | inline | `1` | locked overlay | +| 船型颜色 | `VESSEL_CONFIG.colors.*` | cargo / tanker / passenger / fishing / military / other | `PointsMaterial.vertexColors` 和 overlay texture | + +AIS 船只普通态使用批量 `THREE.Points`,不是逐船 `THREE.Sprite`。航行船只保持三角形,停泊或低速船只保持圆点;普通态不带 glow,hover / locked 时在同一屏幕尺寸上叠加带 glow 的单点 overlay。AIS 航向按 `course / cog` 从正北顺时针解释,普通态和交互态必须使用同一套 canvas 旋转规则。 + ## 算力中心 | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 | diff --git a/docs/technical/zh/earth-render-layer-order.md b/docs/technical/zh/earth-render-layer-order.md index 66a90f4c..d83485d6 100644 --- a/docs/technical/zh/earth-render-layer-order.md +++ b/docs/technical/zh/earth-render-layer-order.md @@ -30,7 +30,7 @@ | 3 | 卫星 footprint 填充 | `satellites.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested,Group renderOrder 保持 0 | Footprint 在国界线之上,但在算力中心和卫星之下。 | | 3-5 | BGP 标记和覆盖层 | `bgp.js` | 各 marker 自身 renderOrder | BGP 拾取路径 | 保持现有 BGP 视觉层级。 | | 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`;`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐,不单独参与拾取 | 选中船只后显示最近轨迹,低于船只 marker。 | -| 4.4 | AIS 船只 marker | `vessels.js` | `VESSEL_RENDER_ORDER`;`CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset` | 船只拾取路径;只取正面 marker | 航行船只用三角 sprite,停泊/低速用圆点;低于算力中心 `4.5`。 | +| 4.4 | AIS 船只 marker | `vessels.js` | `VESSEL_RENDER_ORDER`;`CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`;普通 marker 为分桶 `THREE.Points`,hover / locked 为单点 `THREE.Points` overlay | `depthTest: true`;`main.js` 使用屏幕空间 picking,只取正面 marker | 航行船只用三角点纹理,停泊/低速用圆点;普通态无 glow,交互态叠加同尺寸 glow;低于算力中心 `4.5`。 | | 4.5 | 算力中心 | `compute-centers.js` | `COMPUTE_CENTER_RENDER_ORDER` | 算力中心拾取路径 | 地表设施,保持在卫星下方。 | | 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 位于卫星点下方。 | | 6 | 卫星点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 | @@ -57,4 +57,4 @@ | 中国 / 台湾 hover | `CHN` 和 `TWN` 被归到同一个 hover 高亮组;tooltip 仍显示鼠标实际命中的 feature。 | | 地形 | 只作为视觉层参与,`terrain.raycast` 已禁用。 | | 卫星 | 使用屏幕空间卫星拾取,避免 footprint 或地表层挡住卫星点击。 | -| 船只 | 使用 sprite marker 拾取,并在 `main.js` 中先过滤正面船只;点击后可加载轨迹线。 | +| 船只 | 不使用对象级 sprite raycast。`main.js` 会在拖动 / 惯性期间跳过 hover picking,平时将正面船只投影到屏幕坐标,用像素半径命中最近船只;点击后可加载轨迹线。 | diff --git a/docs/version-history.md b/docs/version-history.md index af89d5ba..b1606a90 100644 --- a/docs/version-history.md +++ b/docs/version-history.md @@ -16,12 +16,13 @@ ## Current Version - `main` 当前主线历史推导到:`0.16.5` -- `dev` 当前开发分支历史推导到:`0.44.1` +- `dev` 当前开发分支历史推导到:`0.44.2` ## Timeline | Version | Type | Branch | Commit | Summary | | --- | --- | --- | --- | --- | +| `0.44.2` | bugfix | `dev` | `pending` | 补充 Earth 船只批量渲染、屏幕拾取、图层顺序、样式参考和性能计划状态文档 | | `0.44.1` | bugfix | `dev` | `pending` | 优化 Earth 船只批量渲染性能,修复拖动卡顿、拾取错位、交互态方向/尺寸和地表压盖问题 | | `0.44.0` | feature | `dev` | `pending` | 重构数据源目录与采集器设置,新增 BarentsWatch AIS 连接教程、Earth 船只/缩放体验优化和仪表盘前端重启 | | `0.43.1` | bugfix | `dev` | `pending` | 修正全量 restart 后 AI Provider 启动提示语义,避免把预期未就绪描述成异常 | diff --git a/frontend/package.json b/frontend/package.json index 1bff4b32..f859dd92 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,6 +1,6 @@ { "name": "planet-frontend", - "version": "0.44.1", + "version": "0.44.2", "private": true, "packageManager": "bun@1", "dependencies": { diff --git a/pyproject.toml b/pyproject.toml index c8969648..591a9c46 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "planet" -version = "0.44.1" +version = "0.44.2" description = "智能星球计划 - 态势感知系统" requires-python = ">=3.14" dependencies = [ diff --git a/uv.lock b/uv.lock index 64d2e4b6..50fb13fb 100644 --- a/uv.lock +++ b/uv.lock @@ -475,7 +475,7 @@ wheels = [ [[package]] name = "planet" -version = "0.44.1" +version = "0.44.2" source = { virtual = "." } dependencies = [ { name = "aiofiles" },