cesium-multi-target-framework 0.1.0

package/doc//345/244/232/347/233/256/346/240/207/344/274/230/345/214/226/344/270/216/351/242/204/346/265/213/346/270/262/346/237/223/350/257/264/346/230/216.md

@@ -0,0 +1,186 @@
+# cesiumScene 多目标优化、预测与渲染说明
+
+> 梳理对象：`低空基线/baseFrontend/src/components/cesiumScene`
+> 关注点：海量目标如何不卡、目标位置如何预测、预测结果如何平滑渲染。
+
+## 一、整体分层（数据怎么变成画面）
+
+整条链路是单向流动，每一层只做一件事：
+
+```
+业务数据(JSON / WebSocket)
+   │  全量 setData / 增量 applyIncremental
+   ▼
+DataManager          差分：算出 新增/更新/删除，并预处理坐标
+   │  dirty 事件 (onPointsDirty / onPathsDirty / onAreasDirty)
+   ▼
+NodeManager          维护每个目标的"逻辑态"：位置、航向、速度、历史点、预测点、交互态
+   │  把节点投影成 RenderItem（渲染协议对象）
+   ▼
+InstanceManager      归一化预制体，转交渲染层
+   │
+   ▼
+RenderManager        按 renderKind 分发：model / polyline / point
+   │
+   ▼
+ModelRenderer 等     真正画出来：实例化合批 + 动画对象池
+```
+
+关键分界：
+
+- **逻辑位（logicalPosition）**：服务端给的权威位置，代表"目标真实在哪"。
+- **渲染位（renderPosition）**：当前这一帧实际画在屏幕上的位置，由预测+插值算出来，代表"现在画在哪"。
+
+两者分开，是整个预测与平滑渲染的设计基石。
+
+---
+
+## 二、多目标性能优化
+
+海量目标（数千架无人机/船舶）同时渲染的瓶颈在于 Cesium 单模型的 draw call。这里用了五个手段叠加。
+
+### 1. 实例化合批（默认主路径）
+
+同类型 + 同模型文件的目标，被归到同一个"桶"（bucket），整桶用一个 `ModelInstanceCollection`（MIC）渲染。
+
+- 分桶规则：`类型|模型URI`，例如 `uav|/model/model_wrj.glb` 一个桶，船舶圆柱体另一个桶。
+- 一桶内不管有多少目标，本质上是一次合批提交，draw call 大幅下降。
+- 桶有 `dirty` 标记，只有增删目标或显隐变化才触发整桶重建；单纯位置移动只改矩阵，不重建。
+
+```
+桶(bucket)
+ ├─ items: Map<id, {matrix, scale, show}>   每个目标一条
+ └─ collection: ModelInstanceCollection      整桶一次渲染
+```
+
+### 2. 动画对象池（近处增强路径）
+
+合批模型不能各自播放动画。所以另设一个**固定大小的动画模型池**（默认 38 个槽位），只给"看得最清楚"的少数目标用带动画的独立模型。
+
+工作方式：
+
+- 每 200ms 评估一次（`evalIntervalMs`），从所有无人机里筛出候选，按优先级排序取 `topN`。
+- 命中 topN 的目标：从池里借一个槽位，绑定独立动画模型，**同时隐藏它在合批里的实例**（避免重影）。
+- 退出 topN 的目标：归还槽位，恢复合批实例显示。
+- 同一时刻一个目标只走一种承载，可理解为"近处高表现、远处高性能"。
+
+候选筛选条件（层层过滤）：
+
+| 维度 | 作用 |
+| --- | --- |
+| 相机高度区间 | 超出范围直接整体跳过 |
+| 距离 / maxDistance | 太远不进池 |
+| 朝向 dot | 在相机背后的剔除 |
+| 屏幕坐标 | 不在画布内的剔除 |
+| 视锥 + 包围球 | 不在视野内的剔除 |
+| 近距放宽 | 很近的目标放宽侧向/边缘判定，避免"明明在眼前却没动画" |
+
+排序优先级：先屏幕内 → 再离相机最近 → 再靠近屏幕中心 → 再正对朝向。
+
+### 3. 选中/悬停优先抢占
+
+被点击或悬停的目标，通过 `setUavAnimationPriorityIds` 插队到候选队列最前面，并跳过常规过滤，保证"我点中的目标一定在动"。还有**近距锁定回差**（enter 200m / exit 300m），避免目标在阈值附近反复进出池导致动画闪烁。
+
+### 4. 相机高度分级（逻辑缩放 + 总开关）
+
+`NodeManager` 监听相机变化（合并到每帧最多一次 rAF）：
+
+- 按相机离地高度算一个**缩放乘子**，下发给模型、选中环、投影圆面、地面点，让目标在不同视高下保持合适的视觉大小。最终乘子 = 高度倍率 × 角度倍率（顶视=1，平视=3）。
+- 相机高于 `masterHideHeight`（当前默认 **150km**）时，隐藏模型内容（点模式仍保留），高空不渲染海量模型。
+
+### 5. 帧批处理栅栏（commitFrame）
+
+所有增删改先收集，最后调用一次 `commitFrame()` 统一落帧，避免每条消息都触发重建。`commitFrame` 内部顺序：先 tick 动画池绑定切换，再重建 dirty 的桶。
+
+> 兜底：MIC 创建失败时自动 `_fallbackToSingleModels()` 退化为单模型，保证可用性。
+
+---
+
+## 三、预测逻辑（目标下一刻在哪）
+
+当前实现采用 worker 侧预测状态机。每个目标按 id 维护一份 `PredictionMotionState`：
+
+```
+运动状态(per target)
+ ├─ base      : 最新权威经纬度、高度、航向、水平速度、垂直速度
+ ├─ renderStart : 新数据到达时，上一段预测在当前时刻的实际渲染位置
+ ├─ fit       : 航线拟合秒数，默认 2 秒
+ └─ predict   : 预测窗口秒数，默认 10 秒；窗口后继续匀速外推
+```
+
+状态只在目标数据新增或更新时重建。重建前先用旧状态计算“此刻应该画在哪”，再把这个位置作为新航线的拟合起点，因此不会在新权威包到达时跳到权威点或远端预测点。
+
+### 预测启用条件
+
+预测只发生在 worker 输出渲染包时，满足以下条件才会计算预测坐标：
+
+- 目标位于 buffered viewport 内，即视口内 + 缓冲区。
+- 当前是单目标，`count === 1`；聚合簇不预测。
+- 类型配置开启 `predictMove`。
+- 相机高度处于低模 LOD 高度区间内：`cameraHeight <= pointAbove`。
+- 相机高度不高于类型级 `predictMinCameraHeight`。
+
+类型级 `predictSeconds` / `predictFitSeconds` 优先于全局配置；未配置时使用全局默认 `10` 和 `2`。
+
+### 预测点怎么算
+
+- 前 `predictFitSeconds` 秒：从 `renderStart` 用 easeInOutCubic 插值到“新权威点沿最新速度和航向走 fit 秒”的位置，航向同步按最短角插值。
+- `predictFitSeconds` 后：以最新权威点为基准，按 `speedH`、`speedV`、`heading` 匀速外推。
+- 超过 `predictSeconds` 后不停止，继续沿最新航线外推，避免数据中断时目标停顿。
+
+---
+
+## 四、渲染逻辑（预测怎么平滑地画出来）
+
+worker 直接把预测后的 `lon/lat/height/heading` 写入 `RenderPacket`，并打上 `FLAG_PREDICT_MOVE`。渲染层不再自行外推，不再维护 anchor/correction/blend 状态。
+
+renderer 只做一层很短的模型位置平滑：
+
+- 预测目标 `moveDurationMs = 80ms`，避免渲染缓动和 worker 拟合叠加成明显滞后。
+- 低模预测目标会从合批低模中拆出来用独立模型渲染，保证每帧位置可以平滑更新。
+- 强制高模显示的目标在低模 LOD 高度内同样消费 worker 预测坐标。
+- `predictMove: false` 的目标继续使用原 `smoothMoveDurationMs` 平滑行为。
+
+### 高度显示曲线
+
+真实高度低的目标贴地不好看，写入渲染高度时统一过一条曲线 `scaleHeightForDisplay`：真实越低显示倍率越高，但显示高度始终随真实高度单调递增。**逻辑位仍保留原始米值**，业务读真实高度用 `logicalPosition.height`。
+
+### 另一条插值入口
+
+`applyPointRenderSample` 是给"外部已经算好样本"的场景用的（如回放、`TargetPositionInterpolator` 每帧 postRender 批量回调），只更新渲染位与矩阵，不动逻辑位。`TargetPositionInterpolator` 走的是经纬度线性插值 + 航向 slerp，按固定时长（默认 500ms）从当前姿态过渡到新航迹。
+
+---
+
+## 五、关键数据流闭环（运行时）
+
+```
+业务数据 / mock 数据到达
+  → MultiTargetScene stage-packed / incremental / realtime-upsert
+  → renderWorker 更新 Store，并按目标 id 更新 PredictionMotionState
+  → viewport 请求到达:
+      buffered viewport 选目标 → 单目标预测 → 写 RenderPacket
+  → renderer 消费 RenderPacket:
+      点云/低模/高模按 worker 输出坐标渲染
+  → 若上一包包含预测目标:
+      MultiTargetScene 在 rAF 中按 updateFps 继续请求 viewport，驱动预测坐标连续刷新
+```
+
+- 预测只在 worker 内部维护；公开的 `RenderPacket` 坐标协议不变。
+- renderer 不再做预测外推；预测目标直接采样 worker 每帧输出的位置，2 秒拟合完全由 worker 状态机负责。
+- 目标删除、全量替换、实时删除会同步清理预测状态。
+
+---
+
+## 六、调参速查
+
+| 参数 | 位置 | 含义 |
+| --- | --- | --- |
+| `predictSeconds=10` | worker/config | 预测窗口秒数；窗口后仍持续外推 |
+| `predictFitSeconds=2` | worker/config | 新权威数据到达后的航线拟合秒数 |
+| `predictMinCameraHeight` | type config | 类型级预测最大相机高度 |
+| `PREDICT_MOVE_DURATION_MS=80` | ModelPoolRenderer | 预测目标的 renderer 短平滑时长 |
+| `masterHideHeight=150000` | SceneConfig | 高空隐藏模型阈值 |
+| `poolSize=38 / topN=38` | ModelRenderer | 动画池容量与同时动画上限 |
+| `evalIntervalMs=200` | ModelRenderer | 动画池评估间隔 |
+| `nearLockEnter/Exit=200/300` | ModelRenderer | 近距锁定回差 |
+| `UPDATE_FPS` | CesiumDemo | 帧循环频率 |

package/doc//345/244/232/347/273/204/344/273/266/344/272/213/344/273/266/346/226/271/346/241/210.md

@@ -0,0 +1,410 @@
+# 多组件事件方案
+
+本文档定义一套面向业务组件的全局通信方案，用于地图、列表、详情面板、轨迹面板、告警面板等组件之间互相调用能力和同步状态。
+
+核心目标：
+
+- 每个组件使用唯一命名空间注册能力，例如 `cesium-map`、`target-table`、`alarm-panel`。
+- 组件之间通过统一总线通信，避免互相直接持有实例。
+- 区分“让某个组件做事”的命令调用，以及“某个状态发生变化”的事件广播。
+- 所有注册都能注销，方便组件卸载、页面切换和热更新。
+
+## 一、基本概念
+
+### 命名空间
+
+`namespace` 是组件在全局通信系统中的唯一名字。
+
+推荐命名：
+
+| 组件 | namespace |
+| --- | --- |
+| Cesium 多目标地图 | `cesium-map` |
+| 目标列表 | `target-table` |
+| 目标详情 | `target-detail` |
+| 轨迹面板 | `track-panel` |
+| 告警面板 | `alarm-panel` |
+
+约束：
+
+- 一个 namespace 同一时间只允许一个 owner 注册命令。
+- 事件名也建议带 namespace，例如 `cesium-map:selectionChanged`。
+- namespace 使用短横线命名，不使用中文、不使用空格。
+
+### 命令调用
+
+命令调用表示“点名让某个组件执行一个动作”，通常有返回值或失败原因。
+
+例如：
+
+```ts
+await componentBus.call("cesium-map", "selectTarget", {
+  targetId: "ship-001",
+  clearBefore: true,
+});
+```
+
+含义：
+
+> 找到命名空间为 `cesium-map` 的组件，调用它注册的 `selectTarget` 动作，并传入参数。
+
+适合命令调用的动作：
+
+- 选中目标
+- 定位目标
+- 设置目标颜色
+- 隐藏/显示目标
+- 打开轨迹
+- 清空选择
+
+### 事件广播
+
+事件广播表示“某个事情发生了”，所有感兴趣的组件都可以监听。
+
+例如：
+
+```ts
+componentBus.emit("cesium-map:selectionChanged", {
+  targets,
+});
+```
+
+适合事件广播的状态：
+
+- 地图选中目标变化
+- 鼠标悬停目标变化
+- 目标被点击
+- 右键菜单触发
+- 轨迹点 hover
+- 统计指标变化
+
+## 二、推荐依赖
+
+推荐使用 `mitt` 作为事件发布订阅底座，再自行封装命名空间命令协议。
+
+理由：
+
+- `mitt` 很小，API 简单，只有 `on/off/emit`。
+- 支持 TypeScript。
+- 不绑定框架，可在 Vue、React、原生 JS 中使用。
+- 我们需要的 `namespace + action + params + return` 不属于普通事件库职责，自己薄封一层更清楚。
+
+不建议第一版直接使用 `rxjs`。除非后续需要复杂的数据流操作，例如节流、合并、重放、状态流、跨多个数据源组合。
+
+## 三、总线 API 设计
+
+建议总线暴露四类方法：
+
+```ts
+export interface ComponentBus {
+  register(namespace: string, actions: ComponentActionMap): DisposeFn;
+  call<Result = unknown>(namespace: string, action: string, params?: unknown): Promise<Result>;
+
+  on<Payload = unknown>(event: string, handler: ComponentEventHandler<Payload>): DisposeFn;
+  emit<Payload = unknown>(event: string, payload?: Payload): void;
+}
+
+export type DisposeFn = () => void;
+
+export type ComponentActionMap = Record<
+  string,
+  (params?: unknown, ctx?: ComponentActionContext) => unknown | Promise<unknown>
+>;
+
+export interface ComponentActionContext {
+  namespace: string;
+  action: string;
+  requestId: string;
+  at: number;
+}
+
+export type ComponentEventHandler<Payload = unknown> = (payload: Payload) => void;
+```
+
+### 为什么叫 `call`
+
+`call(namespace, action, params)` 比 `emit` 更适合命令：
+
+- 它会找到明确的目标组件。
+- 它可以返回结果。
+- 它可以抛出错误。
+- 它表达的是“调用能力”，不是“广播事件”。
+
+如果团队更喜欢，也可以命名为 `invoke` 或 `execute`。本文统一使用 `call`。
+
+## 四、最小实现示例
+
+```ts
+import mitt from "mitt";
+
+type DisposeFn = () => void;
+type ActionHandler = (params?: unknown, ctx?: ActionContext) => unknown | Promise<unknown>;
+type ActionMap = Record<string, ActionHandler>;
+
+interface ActionContext {
+  namespace: string;
+  action: string;
+  requestId: string;
+  at: number;
+}
+
+const emitter = mitt<Record<string, unknown>>();
+const registry = new Map<string, ActionMap>();
+
+export const componentBus = {
+  register(namespace: string, actions: ActionMap): DisposeFn {
+    if (!namespace) throw new Error("component namespace is required.");
+    if (registry.has(namespace)) {
+      throw new Error(`component namespace already registered: ${namespace}`);
+    }
+    registry.set(namespace, actions);
+    return () => {
+      const current = registry.get(namespace);
+      if (current === actions) registry.delete(namespace);
+    };
+  },
+
+  async call<Result = unknown>(namespace: string, action: string, params?: unknown): Promise<Result> {
+    const actions = registry.get(namespace);
+    if (!actions) throw new Error(`component namespace not found: ${namespace}`);
+
+    const handler = actions[action];
+    if (!handler) throw new Error(`component action not found: ${namespace}.${action}`);
+
+    const ctx: ActionContext = {
+      namespace,
+      action,
+      requestId: `${Date.now()}-${Math.random().toString(16).slice(2)}`,
+      at: Date.now(),
+    };
+    return await handler(params, ctx) as Result;
+  },
+
+  on<Payload = unknown>(event: string, handler: (payload: Payload) => void): DisposeFn {
+    emitter.on(event, handler as (payload: unknown) => void);
+    return () => emitter.off(event, handler as (payload: unknown) => void);
+  },
+
+  emit<Payload = unknown>(event: string, payload?: Payload): void {
+    emitter.emit(event, payload);
+  },
+};
+```
+
+## 五、`cesium-map` 第一版命令
+
+Cesium 多目标框架初始化后注册命名空间：
+
+```ts
+const disposeCesiumMap = componentBus.register("cesium-map", {
+  selectTarget: async (params) => {
+    const p = params as { targetId: string; clearBefore?: boolean };
+    return framework.selectTarget(p.targetId, { clearBefore: p.clearBefore });
+  },
+
+  selectTargets: async (params) => {
+    const p = params as { targetIds: string[]; clearBefore?: boolean };
+    return framework.selectTargets(p.targetIds, { clearBefore: p.clearBefore });
+  },
+
+  locateTarget: async (params) => {
+    const p = params as { targetId: string; options?: LocateTargetOptions };
+    return framework.locateTarget(p.targetId, p.options);
+  },
+
+  clearSelection: () => {
+    framework.clearSelection();
+  },
+
+  setTargetColor: (params) => {
+    const p = params as { targetId: string | string[]; color: string; clearBefore?: boolean };
+    framework.setTargetColor(p.targetId, p.color, { clearBefore: p.clearBefore });
+  },
+
+  setTargetGlow: (params) => {
+    const p = params as { targetId: string | string[]; enabled: boolean; color?: string; clearBefore?: boolean };
+    framework.setTargetGlow(p.targetId, p.enabled, p.color, { clearBefore: p.clearBefore });
+  },
+
+  hideTarget: (params) => {
+    const p = params as { targetId: string | string[]; clearBefore?: boolean };
+    framework.hideTarget(p.targetId, { clearBefore: p.clearBefore });
+  },
+
+  showTarget: (params) => {
+    const p = params as { targetId: string | string[]; clearBefore?: boolean };
+    framework.showTarget(p.targetId, { clearBefore: p.clearBefore });
+  },
+
+  boxTarget: (params) => {
+    const p = params as { targetId: string | string[]; enabled?: boolean; clearBefore?: boolean };
+    framework.boxTarget(p.targetId, p.enabled, { clearBefore: p.clearBefore });
+  },
+
+  unboxTarget: (params) => {
+    const p = params as { targetId: string | string[]; clearBefore?: boolean };
+    framework.unboxTarget(p.targetId, { clearBefore: p.clearBefore });
+  },
+
+  setTracks: (params) => {
+    const p = params as { tracks: TrackRecord[] };
+    framework.tracks.setTracks(p.tracks);
+  },
+
+  showTracks: (params) => {
+    const p = params as { targetIds: string[] };
+    framework.tracks.showTracks(p.targetIds);
+  },
+
+  hideTracks: (params) => {
+    const p = params as { targetIds: string[] };
+    framework.tracks.hideTracks(p.targetIds);
+  },
+
+  clearTracks: () => {
+    framework.tracks.clearTracks();
+  },
+});
+```
+
+调用方示例：
+
+```ts
+await componentBus.call("cesium-map", "selectTarget", {
+  targetId: "ship-001",
+  clearBefore: true,
+});
+
+await componentBus.call("cesium-map", "locateTarget", {
+  targetId: "ship-001",
+  options: { range: 12000, duration: 0.8 },
+});
+```
+
+## 六、`cesium-map` 第一版事件
+
+Cesium 组件把内部事件转成全局事件：
+
+```ts
+const disposers = [
+  framework.scene.on("pick", (target) => {
+    componentBus.emit("cesium-map:targetPicked", { target });
+  }),
+
+  framework.scene.on("hover", (target) => {
+    componentBus.emit("cesium-map:targetHovered", { target });
+  }),
+
+  framework.scene.on("selection", (targets) => {
+    componentBus.emit("cesium-map:selectionChanged", { targets });
+  }),
+
+  framework.scene.on("contextmenu", (context) => {
+    componentBus.emit("cesium-map:contextMenu", { context });
+  }),
+
+  framework.tracks.on("hover", (hover) => {
+    componentBus.emit("cesium-map:trackHover", { hover });
+  }),
+];
+```
+
+其他组件监听：
+
+```ts
+const dispose = componentBus.on("cesium-map:selectionChanged", (payload) => {
+  const p = payload as { targets: TargetSnapshot[] };
+  // 更新详情面板或列表选中态
+});
+```
+
+推荐事件清单：
+
+| 事件 | 说明 |
+| --- | --- |
+| `cesium-map:targetPicked` | 地图点击目标变化 |
+| `cesium-map:targetHovered` | 地图 hover 目标变化 |
+| `cesium-map:selectionChanged` | 地图选中集合变化 |
+| `cesium-map:contextMenu` | 地图右键上下文 |
+| `cesium-map:trackHover` | 轨迹点 hover |
+| `cesium-map:statsChanged` | 地图统计变化，后续可按需增加 |
+
+## 七、参数规范
+
+参数统一使用对象，不使用 JSON 字符串。
+
+推荐：
+
+```ts
+componentBus.call("cesium-map", "selectTarget", {
+  targetId: "ship-001",
+});
+```
+
+不推荐：
+
+```ts
+componentBus.call("cesium-map", "selectTarget", "{\"targetId\":\"ship-001\"}");
+```
+
+原因：
+
+- 对象能保留类型。
+- 不需要反复 `JSON.parse`。
+- 后续可以接 TypeScript 类型和运行时校验。
+- 错误更早暴露。
+
+## 八、错误处理
+
+命令调用建议直接抛错，由调用方决定是否提示用户。
+
+常见错误：
+
+| 错误 | 说明 |
+| --- | --- |
+| namespace 未注册 | 目标组件还没加载或已卸载 |
+| action 未注册 | 调用了不存在的动作 |
+| 参数错误 | 缺少 id、颜色格式错误等 |
+| 业务失败 | 目标不存在、定位失败等 |
+
+调用方示例：
+
+```ts
+try {
+  await componentBus.call("cesium-map", "locateTarget", { targetId });
+} catch (error) {
+  console.warn("[target-table] locate target failed", error);
+}
+```
+
+## 九、生命周期
+
+所有注册和监听都必须在组件卸载时注销。
+
+```ts
+const disposers = [
+  componentBus.register("target-table", actions),
+  componentBus.on("cesium-map:selectionChanged", handleSelectionChanged),
+];
+
+function dispose() {
+  for (const fn of disposers) fn();
+}
+```
+
+注意：
+
+- 地图销毁时要注销 `cesium-map` 命令。
+- 页面切换时要注销本页面所有事件监听。
+- 同一个 namespace 重复注册应直接报错，避免多个 owner 抢同一组命令。
+
+## 十、后续增强
+
+第一版先保持轻量，后续可逐步加入：
+
+- TypeScript 泛型协议：为 `cesium-map.selectTarget` 绑定参数和返回值类型。
+- 运行时参数校验：例如接入 `zod` 或手写轻量校验。
+- 调用日志：记录 `namespace/action/requestId/duration/error`。
+- 权限控制：限制某些组件不能调用危险命令。
+- 异步超时：防止某个命令 Promise 长时间不返回。
+- wildcard 事件：例如监听 `cesium-map:*` 做统一调试。