cesium-multi-target-framework 0.1.0

package/doc//346/270/262/346/237/223/344/270/232/345/212/241/351/200/273/350/276/221.md

@@ -0,0 +1,202 @@
+# 渲染业务逻辑
+
+本文档记录当前目标渲染链路，用于排查点模式、低模模式、高模模式、视口裁剪、合并、统计口径之间的关系。
+
+## 总体流程
+
+1. 主线程接收目标数据，写入 `MultiTargetScene`。
+2. `MultiTargetScene` 根据相机视口、相机高度、配置项向 worker 请求当前渲染 packet。
+3. worker 根据视口、缓冲区、合并层级、距离裁剪和最大渲染上限选出一批渲染项。
+4. worker 给每个渲染项写入 LOD 标记：点、低模或高模。
+5. 主线程收到 packet 后分发给三条渲染链路：
+   - `ModelPoolRenderer`：渲染低模和高模模型。
+   - `PointCloudRenderer`：渲染点图标、发光效果、姓名版。
+   - `SelectionOverlayRenderer` / `TrackManager`：渲染选中态和轨迹相关效果。
+
+## LOD 切换规则
+
+当前基础 LOD 由相机高度决定：
+
+| 条件 | 基础模式 |
+| --- | --- |
+| `cameraHeight > lod.pointAbove` | 点模式 |
+| `lod.animatedBelow < cameraHeight <= lod.pointAbove` | 低模模式 |
+| `cameraHeight <= lod.animatedBelow` | 高模模式 |
+
+demo 当前配置大致是：
+
+| 配置 | 值 | 含义 |
+| --- | --- | --- |
+| `pointAbove` | `150_000` | 高于 150km 使用点模式 |
+| `animatedBelow` | `10_000` | 低于等于 10km 使用高模模式 |
+
+因此相机高度 14.9km 时，基础模式应该是低模模式。
+
+## 强制高模规则
+
+低模模式下，部分目标类型可以强制使用高模。
+
+规则在 worker 的 `lodKindForCategory` 中：
+
+```ts
+if (baseLodKind !== 1) return baseLodKind;
+return cfg?.forceHighModelInLowLod ? 2 : 1;
+```
+
+也就是说：
+
+| 基础模式 | `forceHighModelInLowLod` | 最终渲染 |
+| --- | --- | --- |
+| 点模式 | 任意 | 点 |
+| 低模模式 | `false` | 低模 |
+| 低模模式 | `true` | 高模 |
+| 高模模式 | 任意 | 高模 |
+
+配置解析时，空中目标默认会开启 `forceHighModelInLowLod`。所以在 14.9km 低模阶段看到少量高模是合理的，例如低空目标、无人机等。
+
+## 视口与缓冲区
+
+worker 会同时选择两类渲染项：
+
+| 类型 | 来源 | 标记 | 目的 |
+| --- | --- | --- | --- |
+| 视口内项 | 当前视口范围内 | `FLAG_IN_VIEWPORT` | 主要可见目标 |
+| 缓冲区项 | 扩展视口范围内但不在视口内 | 无 `FLAG_IN_VIEWPORT` | 减少移动、缩放时边缘空白 |
+
+当前 packet 中会同时包含视口内项和缓冲区项。左上角的“视野内目标”和“缓冲区目标”来自 worker 对原始数据范围的统计；packet 的实际长度可能更大，因为还会受到合并层级、内外预算、全局缓存等影响。
+
+## 模型渲染规则
+
+`ModelPoolRenderer` 不会直接渲染 packet 里的所有模型 LOD 项，它还会做二次过滤：
+
+1. 跳过点模式项。
+2. 跳过合并簇。
+3. 跳过没有 `FLAG_IN_VIEWPORT` 的项。
+4. 跳过没有模型资源配置的项。
+5. 再分别按低模池和高模池容量截断。
+
+因此当前结论是：
+
+**视口外/缓冲区目标不会实际渲染成低模或高模模型。**
+
+如果面板上看到低模或高模数量，这个数量应该来自模型渲染器实际接收并通过过滤后的候选项。
+
+## 点渲染规则
+
+`PointCloudRenderer` 当前会接收 packet 全量项，包括视口内项和缓冲区项。
+
+在模型模式下，点和模型之间有 handoff 逻辑：
+
+1. `ModelPoolRenderer.setPacket()` 返回实际进入模型渲染的目标 id。
+2. `PointCloudRenderer.setModelTargetIds()` 记录这些模型目标。
+3. 点渲染器仍然创建或更新对应点 billboard，但如果目标已经由模型渲染，会把该点逐步缩放到接近 0。
+
+这意味着：
+
+- 进入模型渲染的视口内目标，点会被隐藏或缩小。
+- 没有进入模型渲染的 packet 项，仍然会以点形式存在。
+- 缓冲区项目前不会被模型渲染，但仍可能作为点渲染。
+
+所以如果出现“视野内目标 136，但实际渲染点 4000”的情况，主要原因不是低模视口外渲染，而是点渲染器仍在消费 packet 中的大量非模型项或缓冲项。
+
+## 合并规则
+
+合并发生在 worker 侧，输出的合并簇会表现为 `count > 1` 的渲染项，并写入 `FLAG_MERGED`。
+
+当前模型渲染器会跳过所有合并簇，所以：
+
+- 合并簇不会渲染低模。
+- 合并簇不会渲染高模。
+- 合并簇主要由点渲染器表现。
+
+当相机高度较低、视口内数量未超过上限时，合并可能不触发，此时面板会显示“未触发”或合并数量为 0。
+
+## 统计口径
+
+当前左上角面板里的统计需要区分两个口径：
+
+| 统计 | 含义 |
+| --- | --- |
+| `视野内目标` | worker 对当前视口范围内原始目标的统计 |
+| `缓冲区目标` | worker 对扩展视口范围内原始目标的统计 |
+| `实际渲染` | 当前 packet 内渲染项数量，可能包含视口内、缓冲区、合并层级结果 |
+| `LOD统计 点` | 点渲染器口径下仍作为点存在的数量 |
+| `LOD统计 低模` | 模型渲染器实际进入低模渲染队列的数量 |
+| `LOD统计 高模` | 模型渲染器实际进入高模渲染队列的数量 |
+| `合并` | 当前实际合并渲染项数量 |
+
+需要注意：worker 侧的 LOD 统计是“计划口径”，模型渲染器侧的 LOD 统计是“实际模型渲染口径”。面板应该优先展示实际口径，避免把被模型渲染器过滤掉的项误认为已经渲染。
+
+## 对当前打印的解释
+
+示例：
+
+```text
+目标总数：50000（船舶 49000 / 低空 1000）
+视野内目标：136 · 缓冲区目标：89 · 实际渲染：4225（上限 10000）
+相机高度：14.9 km · 当前渲染：低模合批
+LOD统计：实际渲染 点 4000 / 低模 218 / 高模 7
+```
+
+解释：
+
+1. 14.9km 小于 25km 且大于 5km，所以基础 LOD 是低模。
+2. 高模 7 个来自低空目标或其他开启 `forceHighModelInLowLod` 的类型，这是预期行为。
+3. 低模 218 个是模型渲染器实际通过视口内、非合并、有模型资源等过滤后的数量。
+4. 点 4000 个说明 packet 中仍有大量目标没有进入模型渲染，点渲染器仍然在渲染它们。
+5. 这不是“视口外低模渲染很多”，而是“低模模式下仍保留了大量点渲染项”。
+
+## 当前结论
+
+1. 高度 LOD 判断本身没有明显错误。
+2. 低模阶段出现少量高模，是由低空目标强制高模规则导致，符合当前配置。
+3. 模型渲染器已经过滤视口外项，视口外目标不会实际渲染成低模或高模。
+4. 低模阶段仍然渲染大量点，是当前点渲染器消费 packet 全量项导致。
+5. 如果目标是“低模阶段只渲染近距离/视口内必要目标”，下一步应重点调整 packet 选择策略或点渲染器过滤策略，而不是模型渲染器。
+
+## 后续可优化方向
+
+### 方案一：低模/高模阶段限制点渲染范围
+
+在 `PointCloudRenderer` 中按 LOD 和 `FLAG_IN_VIEWPORT` 过滤点：
+
+- 模型模式下只渲染视口内点。
+- 或者只保留缓冲区中少量点，避免边缘空白。
+- 对已经进入模型渲染的目标继续使用 handoff 缩放隐藏。
+
+优点：实现直接，能快速降低点数量。
+
+风险：相机移动、缩放时边缘可能更容易出现短暂空白。
+
+### 方案二：worker 侧在低模/高模阶段减少 outer budget
+
+在低模/高模阶段降低或关闭缓冲区项预算：
+
+- 点模式保留较大缓冲。
+- 低模模式减少缓冲。
+- 高模模式进一步减少缓冲。
+
+优点：从源头减少 packet 数量，主线程压力更低。
+
+风险：需要重新评估移动体验和边缘补偿。
+
+### 方案三：按距离或屏幕尺寸决定点/低模/高模
+
+当前 LOD 是全局相机高度驱动。后续可以改为：
+
+- 近距离：高模。
+- 中距离：低模。
+- 远距离：点。
+- 超远距离：不进入 packet。
+
+优点：更符合真实可见性和性能预期。
+
+风险：改动更大，需要统一统计、拾取、姓名版、轨迹、动画 handoff 的口径。
+
+### 推荐下一步
+
+如果当前主要问题是低模阶段点数量过多，建议优先做“方案二 + 小范围方案一”：
+
+1. 先让 worker 在低模/高模阶段降低缓冲区预算。
+2. 再让点渲染器在模型模式下只保留视口内点或有限缓冲点。
+3. 面板统计拆分为“视口内实际渲染”和“含缓冲实际渲染”，方便继续排查。

package/doc//347/253/231/347/202/271/346/270/262/346/237/223/344/270/216/345/217/263/351/224/256/350/217/234/345/215/225/345/256/236/347/216/260/350/257/264/346/230/216.md

@@ -0,0 +1,49 @@
+# 站点渲染与右键菜单实现说明
+
+## Summary
+
+本次在多目标框架内接入两个独立能力：
+
+- `SiteLayer`：用于渲染光电站、雷达站、AIS 站等站点数据，只提供图标和低模渲染，不参与目标预测、高模动画和目标聚合。
+- 右键菜单：由框架统一创建 DOM 菜单，业务通过 `registerContextMenuItem` 注册菜单项，支持按目标类型、空地等上下文控制显示。
+
+## 站点渲染
+
+- 新增 `src/site/*`：
+  - `SiteLayer` 负责站点数据入口、视口筛选、LOD 切换和统计。
+  - `SiteSpatialIndex` 使用经纬度网格索引，只查询当前视口内站点，避免全量遍历。
+  - `SiteIconRenderer` 使用 Cesium `BillboardCollection` 渲染图标。
+  - `SiteLowModelRenderer` 复用现有 `LowModelInstancedRenderer` 渲染低模。
+- 站点类型通过 `SiteTypeConfig` 注册：
+  - `type`、`category`、`iconPath` 必填。
+  - `lowModel` 可选；未配置低模的站点在低模高度下仍显示图标。
+- 渲染策略：
+  - 相机高度高于 `modelSwitchHeight`：只渲染图标。
+  - 相机高度低于/等于 `modelSwitchHeight`：视口内可用低模的站点进入低模，数量受 `maxVisibleLowModels` 限制，其余继续显示图标。
+  - 站点只筛选视口内目标，不使用预测、回滚、聚合簇。
+- demo 中创建了 720 个 mock 站点，并在面板展示 `siteLayer.stats`。
+
+## 右键菜单
+
+- `MultiTargetScene` 新增 `contextmenu` 事件：
+  - 右键目标时输出 `kind: "target"`，包含目标快照和当前渲染坐标。
+  - 右键空地时输出 `kind: "ground"`，包含经纬高。
+- `MultiTargetFramework` 新增：
+  - `registerContextMenuItem(item): () => void`
+  - `showContextMenu(ctx): Promise<void>`
+  - `closeContextMenu(): void`
+- 菜单项参数：
+  - `key`：唯一标识。
+  - `label`：菜单文案。
+  - `targetKinds`：可选，默认 `["target"]`。
+  - `visible(ctx)`：可选，返回 `false` 时本次右键不显示。
+  - `onClick(ctx)`：点击回调，执行前菜单会自动关闭。
+- DOM 由框架创建，白底黑字、8px 圆角、固定定位，会自动避免溢出窗口；点击外部或按 Escape 会关闭。
+- `SiteLayer` 会在右键站点时发出 `contextmenu` 事件，demo 通过 `showContextMenu` 转成统一菜单。
+- `showContextMenu` 是给后续其他组件使用的扩展口子：组件只需要构造 `ContextMenuContext`，即可复用框架统一 DOM 菜单和注册项筛选逻辑。
+
+## Verification
+
+- `npm run typecheck`
+- `npm run build:demo`
+- `git diff --check`

package/doc//350/247/206/345/217/243/351/251/261/345/212/250/346/225/260/346/215/256/346/265/201/347/250/213/344/277/256/346/224/271/350/256/241/345/210/222.md

@@ -0,0 +1,69 @@
+# 视口驱动数据流程修改计划
+
+## 当前结论
+
+项目主链路现在是“外部高频输入先收集，按周期提交总数据；视口变化即时重整渲染集合”：
+
+1. 外部通过 `setData` / `applyIncremental` 高频推送全量或增量目标。
+2. `DataManager` 在入口层合并同一周期内的变化，同一 id 只保留最新状态。
+3. 到达 `data.commitIntervalMs` 后，`DataManager` 把本批数据提交给 Web Worker，由 Worker 统一归一化并生成一次 diff。
+4. `NodeManager` 消费 diff，维护总数据节点与分桶索引。
+5. 每次视口变化后，基于当前视口和已提交总数据整理命中桶、聚合并生成 `RenderItem`。
+
+也就是说，数据总整理和视口整理是两个节奏：数据默认 2 秒一批，视口变化则即时整理渲染集合。
+
+## 已处理
+
+1. 新增 `data.commitIntervalMs`，默认 2000ms；设为 0 可恢复为每次写入立即提交。
+2. 新增 `data.leading`，默认 true；第一批数据立即提交，避免初始化空等一个周期。
+3. 新增 `data.worker`，默认 true；周期性总数据归一化与 diff 由 Web Worker 完成。
+4. `DataManager` 改为先收集、合并，再按周期提交 diff；Worker 忙时继续累计入口数据，不丢批次。
+5. 视口状态从 reindex 轮次中拆出，改为每帧基于当前相机刷新。
+6. 相机稳定判定同时检查位置、朝向和 up 向量，避免原地旋转/俯仰时视口变化却不重整。
+7. 新增 `mergeDirty` 标记，视口、数据、分帧摄入、桶索引任一变化都会触发显示集合重整。
+8. 重整条件改为“有脏标记且相机稳定”，不再强依赖完整 reindex 一轮完成。
+
+调整后的内部链路：
+
+```text
+外部高频数据 -> DataManager 收集/合并 -> 每 2s 提交 Worker -> 生成 diff -> NodeManager 入桶
+                                                                            |
+当前视口变化 ---------------------------------------------------------------+-> 整理命中桶/聚合 -> 渲染
+```
+
+配置示例：
+
+```ts
+const scene = createMultiTargetScene(viewer, {
+  nodeTypes,
+  data: {
+    commitIntervalMs: 2000,
+    leading: true,
+    worker: true,
+  },
+});
+```
+
+## 后续建议
+
+如果后续要做到“视口变换 -> 向服务端重新获取视口数据”，建议再增加一个可选数据源接口：
+
+```ts
+interface ViewportDataSource {
+  load(bounds: ViewportBounds, signal: AbortSignal): Promise<IncrementalPayload | TargetData[]>;
+}
+```
+
+接入位置建议放在 `MultiTargetScene`：
+
+1. `NodeManager` 暴露当前视口 bounds 和版本号。
+2. `MultiTargetScene` 监听相机稳定后的视口版本变化。
+3. 发起 `dataSource.load(bounds, signal)`，新视口请求采用 last-wins，取消旧请求。
+4. 返回全量视口数据时调用 `setData`，返回增量时调用 `applyIncremental`。
+5. 给视口 bounds 增加缓冲和最小变化阈值，避免拖拽时频繁打接口。
+
+优先级建议：
+
+1. 先稳定当前内部视口重整逻辑。
+2. 再设计 `ViewportDataSource` 的 API 和请求取消策略。
+3. 最后根据后端协议决定是“视口全量替换”还是“视口增量合并”。