cesium-multi-target-framework 0.1.0

package/doc//351/241/271/347/233/256/350/257/264/346/230/216/344/271/246.md

@@ -0,0 +1,729 @@
+# cesium-multi-target-framework
+
+高性能 Cesium 多目标渲染框架。传入一个 Cesium `Viewer`，返回一个**包装过的高性能实例**：它拥有原 Viewer 的全部能力，并叠加海量目标的对象池、均匀网格空间索引、分帧调度、运动预测与三级 LOD 渲染。
+
+- 兼容 Cesium 1.107.2 ~ 1.128.0（版本敏感 API 由适配层统一封装，当前依赖锁定 1.107.2）
+- 数据 → 节点逻辑态 → 渲染协议 → 三级渲染后端，单向数据流
+- 逻辑位（权威）与渲染位（插值）分离，支撑预测与平滑
+- 完整对外接口、事件、配置见本文下方「对外接口说明」
+
+## 安装与构建
+
+> 运行环境：Node.js 16.x（已通过 `engines` 与 `.nvmrc` 限定；工具链使用 Vite 4 以兼容 node16）。
+
+```bash
+npm install
+npm run dev        # 启动 demo（http://localhost:5173）
+npm run build      # 构建库，产出 dist/ 下 ESM + UMD + .d.ts
+npm run typecheck  # 仅类型检查
+```
+
+## 快速使用
+
+推荐新接入使用 `MultiTargetFramework` / `createMultiTargetFramework`。本包会转导 Cesium 能力，因此使用方可以像使用 `cesium` 包一样从这里导入 `Viewer`、`Cartesian3` 等对象；多目标能力由独立实例管理，不会往原始 `Viewer` 上挂字段。
+
+```ts
+import { Viewer, MultiTargetFramework } from "cesium-multi-target-framework";
+
+const viewer = new Viewer("cesiumContainer", {
+  animation: false,
+  timeline: false,
+});
+
+const multiTarget = new MultiTargetFramework(viewer, {
+  targetTypes: [
+    {
+      type: "ship",
+      name: "船舶",
+      iconPath: "/icons/target-ship-mask.png",
+      defaultColor: "#25e65c",
+      smoothMove: true,
+      smoothMoveMinCameraHeight: 25000,
+      predict: false,
+    },
+    {
+      type: "uav",
+      name: "无人机",
+      iconPath: "/icons/target-uav-mask.png",
+      defaultColor: "#22d2f2",
+      smoothMove: true,
+      predict: true,
+      predictMinCameraHeight: 25000,
+    },
+  ],
+  scene: {
+    data: { commitIntervalMs: 2000, leading: true, worker: true },
+    merge: { enabled: true, maxVisible: 30000, byType: true },
+  },
+});
+
+multiTarget.setTargetData([
+  {
+    id: "ship-001",
+    type: "ship",
+    lon: 121.5,
+    lat: 31.2,
+    height: 0,
+    speedH: 8,
+    speedV: 0,
+    heading: 45,
+    renderColor: "#f81282",
+    openAnimate: true,
+    animateType: "发光",
+    animateColor: "#f81282",
+  },
+]);
+
+viewer.camera.flyHome(0);               // 原 Cesium Viewer 正常使用
+const added = multiTarget.addTarget({
+  id: "manual-001",
+  type: "ship",
+  lon: 121.5,
+  lat: 31.2,
+  height: 0,
+  speedH: 0,
+  speedV: 0,
+  heading: 0,
+});
+multiTarget.setTargetColor(added.id, "#f81282");
+multiTarget.setTargetGlow(added.id, true, "#f81282");
+multiTarget.updateTarget({ ...added, heading: 45 });
+void multiTarget.locateTarget(added.id);
+multiTarget.upsertTargetData(nextTargets);  // 多目标框架能力走实例
+multiTarget.removeTargetData(["ship-001"]);
+multiTarget.scene.on("perf", console.log);
+```
+
+### 初始化就绪（作为依赖底座）
+
+框架内部会启动一个 Web Worker，`new` 同步返回时引擎尚未就绪。若本框架是其它组件的依赖底座，需要「等它就绪再加载后续组件」，用 `ready` 或异步工厂：
+
+```ts
+// 同步 new：可立即挂事件，需要就绪时再 await
+const multiTarget = new MultiTargetFramework(viewer, options);
+await multiTarget.ready;          // 引擎（Worker 握手）就绪
+loadOtherComponents(multiTarget);
+
+// 或异步工厂：拿到的实例已就绪
+const multiTarget2 = await MultiTargetFramework.create(viewer, options);
+// createMultiTargetFramework(viewer, options) 同样返回 Promise<实例>
+```
+
+> `ready` 只等引擎就绪；glTF 模型按需懒加载，不纳入就绪范围。
+
+## 数据标准（统一口径）
+
+所有进入框架的数据先满足 `TargetData`：速度单位 m/s，角度单位度，坐标 WGS84 经纬度 + 椭球高。
+
+| 字段 | 含义 |
+| --- | --- |
+| `id` | 唯一标识 |
+| `type` | 目标类型，对应某个 `NodeTypeConfig.type` |
+| `lon` / `lat` / `height` | 经度 / 纬度 / 高度 |
+| `speedH` / `speedV` | 水平速度 / 垂直速度（向上为正） |
+| `heading` | 航向（正北 0，顺时针） |
+| `renderColor` | 单目标渲染颜色，`#RRGGBB` 或 `#RRGGBBAA`（可选） |
+| `openAnimate` | 是否打开目标动画（可选） |
+| `animateType` | 动画类型，当前内置支持 `glow` / `发光`（可选） |
+| `animateColor` | 动画颜色，不传时沿用 `renderColor` 或类型默认色（可选） |
+| `track` | 轨迹点数组（每项含位置 / 时间 / 当时航向，可选） |
+| `secrecy` | 密级（可选，预留字段：当前仅随数据透传，未参与合并逻辑） |
+
+更多字段和 packed 数据入口见本文下方「对外接口说明」。
+
+## 节点类型配置 `NodeTypeConfig`
+
+`name`、`type`、`highModelUrl`、`lowModelUrl`、`pointIcon`、`scale`、`modelHeadingOffset`、`lod`（高/中/低切换高度）、`smoothMove`（是否平滑）、`predictMove`（是否按预测移动）。
+
+## 架构
+
+```
+业务数据 ── setData/upsert/applyIncremental ─→ MultiTargetScene
+   │  归一化 + 口径统一 + 差分（data.worker 开启时在 Web Worker，renderWorker.ts）
+   │  + 全局聚合树分级建簇 + 相机分级 + 预测协调
+   ▼
+渲染分发（按相机离地高度 LOD / renderKind）
+ ├─ PointCloudRenderer        点模式（BillboardCollection，三角贴图按 heading 旋转）
+ ├─ LowModelInstancedRenderer 低模合批（按模型 URL 分组的 GPU 实例化 glTF，静态网格）
+ ├─ ModelPoolRenderer         高模动画（Cesium Model 对象池，播放动画）
+ └─ InstancedSymbolRenderer   有向符号（自定义 DrawCommand GPU 实例化）
+```
+
+### 三级 LOD（相机离地高度驱动）
+
+- 高于 `pointAbove`：点模式
+- 介于两者之间：低模合批
+- 低于 `animatedBelow`：高模动画（受动画池容量约束，按距相机最近 + 选中/悬停优先取 topN）
+
+### 运动预测与平滑
+
+- 预测在 worker 内按目标 id 维护状态，只对 buffered viewport 内、低模 LOD 高度下、`predictMove: true` 的单目标启用。
+- 默认 `predictSeconds: 10`、`predictFitSeconds: 2`：新数据到达时先从当前渲染位置 2 秒拟合到新航线，之后沿最新速度、航向、垂直速度持续外推。
+- 聚合簇不参与预测；`predictMove: false` 的目标只保留原有平滑对齐权威位置行为。
+
+### 贴近稳定性（姓名版/高模抖动治理）
+
+相机贴近单目标（跟随、低空）时姓名版与高模会出现抖动，远处不可见、越近越明显。根因分三层，已逐层修复：
+
+1. **高模运动判定失效（阶梯抖动）**：`ModelPoolRenderer` 判断目标是否移动时误用 `Cartesian3.equalsEpsilon(a, b, 0.001)`——第三参是**相对** epsilon，对 ~6.3×10⁶ 量级的 ECEF 坐标会放大成公里级容差，使任何正常位移都被判为"没动"，高模逐帧 lerp 分支从不触发、直接逐包吸附成阶梯。改用绝对比较 `Cartesian3.distanceSquared(a, b) > 1e-4`（1cm 阈值）。
+2. **姓名版锚点与相机不同源**：相机跟随走 `getRenderedTargetFrame`（model ?? point ?? symbol），而姓名版曾锚定 point billboard。`groundSymbols` 开启时船是贴地符号渲染、point 被隐藏，两条位置源分叉 → 姓名版相对相机漂移。改为姓名版经 `setAnchorPositionResolver` 锚到与相机**完全相同**的渲染位置源。
+3. **billboard 大坐标 Float32 投影量化（RTC 治理）**：即便位置数值一致，billboard 走 GPU 路径用 Float32 投影 ~6.3×10⁶ 的绝对 ECEF 坐标，量化误差 ≈ 0.3~0.7m，贴近时（1px≈0.13m）放大成数像素抖动。`labelCollection` 改用 **RTC（相对相机中心）**：每帧把 `modelMatrix` 设为"相机位置丸到 100m 网格"的平移，billboard `position` 只存"锚点 − 参考点"的米级小偏移，GPU 不再对大坐标做 Float32 投影。参考点网格丸避免相机微动引入新抖源；绝对位置缓存（`labelPositionsById`）不变，其它逻辑仍按绝对坐标工作。
+
+> 验证手段：`demo/jitter-lab.html` 对照页用同一条匀速轨迹喂 6 种渲染方式（Billboard / Label / Entity / DOM 取整 / DOM 不取整 / Billboard+RTC），贴近肉眼对比即可定位抖动来源——DOM（CPU·Float64 投影）与 Billboard+RTC 不抖，普通 GPU 图元抖。
+
+### 交互拾取
+
+拾取用**屏幕像素均匀网格**（把可见目标投影到屏幕、按网格分桶，命中半径内取像素距离最近者）替代 Cesium 原生左键 `scene.pick`（海量目标下原生拾取很卡，框架会移除原生左键查找）。选中/悬停目标会被强制升级为高模并在动画池中优先占位。
+
+### 自适应递进合并
+
+当**视野内目标数超过 `merge.maxVisible`（缺省取对象池容量 `pool.size`）**时启用合并：沿半径阶梯 `merge.radii`（缺省 100m→200m→500m→1km→2km→3km→…→10km）**从小到大逐级试探**，对每个可见目标按 `floor(ECEF坐标 / 半径)` 落入均匀网格、**同网格 + 同类型**合成一簇，数出合并后簇数；第一个能把簇数压到 `maxVisible` 以内的半径即采用（都不达标则用最大半径尽力压缩）。每格第一个为簇心，其余 `mergedHidden=true` 不渲染，簇心 `node.mergedCount` 记录簇大小。
+
+逐级试探每级一遍 O(可见目标数) 网格哈希、不做逐点范围查询，并复用相机移动/最大间隔帧的降频重算，避免每帧抖动。场景内部 `lastMergeRadius` 暴露本次采用的半径（0 表示未触发）。
+
+> 网格法按格归并，相邻格子边界两侧即使物理很近也不并簇（固有近似），但对降低渲染总数足够，是海量点聚类的最快路径；目标拾取与站点范围查询另用屏幕像素 / 经纬度均匀网格索引完成。
+
+## 关键调参
+
+| 配置 | 默认 | 含义 |
+| --- | --- | --- |
+| `lod.pointAbove` | 150000 | 高于此高度走点模式（米） |
+| `lod.animatedBelow` | 12000 | 低于此高度走高模动画（米） |
+| `pool.size` | 30000 | 通用对象池容量 |
+| `animatedPool.size` | 64 | 高模动画同时并发上限 |
+| `updateFps` | 30 | 帧循环频率 |
+| `data.commitIntervalMs` | 2000 | 数据入口合并提交周期；设为 0 表示每次写入立即提交 |
+| `data.leading` | true | 第一批数据是否立即提交 |
+| `data.worker` | true | 周期性总数据归一化与 diff 是否放到 Web Worker |
+| `merge.mode` | `"global"` | 合并策略；全局层级树，低空也会结合视口查询 |
+| `merge.globalRootLimit` | 500 | global 模式下顶层根聚合点数量上限 |
+| `merge.globalRebuildIntervalMs` | 300000 | global 模式下全局树最短重建间隔 |
+| `frame.maxLowModelRenderItems` | 3000 | 同时进入低模后端的目标上限；超过则整批回退点云 |
+| `frame.maxModelRenderItems` | 2000 | 旧配置兼容项，建议改用 `frame.maxLowModelRenderItems` |
+| `predictSeconds` | 10 | 预测窗口秒数；无新数据时超过窗口仍沿最新航线持续外推 |
+| `predictFitSeconds` | 2 | 新权威数据到达后的航线拟合秒数 |
+| `masterHideHeight` | 150000 | 高于此高度隐藏所有模型（点保留） |
+| `pick.pixelThreshold` | 20 | 拾取命中像素阈值 |
+| `cull.viewportBufferMinMeters` | 500 | 视口裁剪缓冲的绝对下限（米）。相机贴近时视野矩形极小，单纯按 `viewportBufferRatio` 的相对缓冲不足以覆盖近处快速目标在一帧节流窗口内的位移，会被裁掉造成闪烁；实际缓冲取 `max(相对缓冲, 该下限)`，高空时相对缓冲远大于此值故不受影响 |
+
+完整 API、事件、站点层、轨迹、聚类工具和配置默认值见本文下方「对外接口说明」；设计原理详见 `doc/多目标优化与预测渲染说明.md`，实施记录见 `doc/工作计划.md`。
+
+## 对外接口说明
+
+本文档按 `src/index.ts` 的包根入口整理当前对外能力，适用于从 `cesium-multi-target-framework` 接入的业务方。
+
+### 一、包根导出
+
+```ts
+import {
+  Viewer,
+  MultiTargetFramework,
+  createMultiTargetFramework,
+  SiteLayer,
+  TrackManager,
+  createQuadClusterer,
+  clusterProgressive,
+  lonLatToLocalPlane,
+  createClusterWorkerClient,
+  bindFrameworkEventBus,
+  bindSiteLayerEventBus,
+  getFrameworkEventBus,
+} from "cesium-multi-target-framework";
+```
+
+包根导出分为七类：
+
+| 类别 | 导出 |
+| --- | --- |
+| Cesium | `export * from "cesium"`，可直接导入 `Viewer`、`Cartesian3` 等 Cesium API |
+| 高层目标框架 | `MultiTargetFramework`、`createMultiTargetFramework` |
+| 底层目标场景 | `MultiTargetScene` |
+| 轨迹和站点 | `TrackManager`、`SiteLayer` |
+| Web Event Bus | `bindFrameworkEventBus`、`bindSiteLayerEventBus`、`getFrameworkEventBus`、`tryGetFrameworkEventBus`、`createFrameworkEventBus` |
+| 聚类工具 | `createQuadClusterer`、`clusterProgressive`、`lonLatToLocalPlane`、`createClusterWorkerClient` |
+| 常量 | `VERSION`、`DEFAULT_LOD`、`DEFAULT_POOL`、`DEFAULT_ANIMATED_POOL`、`DEFAULT_SCENE`、`TARGET_DOMAINS` |
+
+常用类型包括：`TargetData`、`StandardTargetData`、`TrackPoint`、`IncrementalPayload`、`PackedTargetData`、`SceneConfig`、`MultiTargetFrameworkOptions`、`MultiTargetTypeConfig`、`TargetSnapshot`、`ContextMenuContext`、`SiteData`、`SiteLayerOptions`、`TrackRecord`、`ClusterWorkerClient`、`FrameworkEventBus`、`FrameworkBusActionMap`、`FrameworkBusEventMap` 等。
+
+### 二、高层入口 `MultiTargetFramework`
+
+推荐业务优先使用该入口。它不改写原始 `Viewer`，而是在内部持有 `scene`、`viewer`、`tracks`。
+
+#### 创建
+
+```ts
+const framework = new MultiTargetFramework(viewer, {
+  targetTypes: [
+    {
+      type: "ship",
+      name: "船舶",
+      iconPath: "/icons/target-ship-mask.png",
+      defaultColor: "#25e65c",
+      smoothMove: true,
+    },
+  ],
+  scene: {
+    data: { commitIntervalMs: 2000, leading: true, worker: true },
+    merge: { enabled: true, maxVisible: 30000 },
+  },
+});
+
+// 等价工厂（异步：等引擎就绪后 resolve）
+const framework2 = await createMultiTargetFramework(viewer, options);
+```
+
+`MultiTargetFramework` 内部会启动一个 Web Worker，构造函数同步返回时引擎尚未就绪。需要「初始化完成后再加载依赖底座的其它组件」时，有两种等价写法：
+
+```ts
+// 写法一：同步 new，可立即挂事件/调方法，需要就绪时再 await
+const framework = new MultiTargetFramework(viewer, options);
+framework.scene.on("perf", console.log);
+await framework.ready;        // 引擎（Worker 握手）就绪
+loadOtherComponents(framework);
+
+// 写法二：异步工厂，拿到的实例已就绪
+const framework3 = await MultiTargetFramework.create(viewer, options);
+loadOtherComponents(framework3);
+```
+
+> `ready` 只等引擎就绪（Worker init 握手完成）；glTF 模型按需懒加载，不纳入就绪范围。
+
+`MultiTargetFrameworkOptions`：
+
+| 字段 | 说明 |
+| --- | --- |
+| `targetTypes` | 必填，目标类型数组 |
+| `scene` | 可选，除 `nodeTypes` 之外的 `SceneConfig` |
+
+`MultiTargetTypeConfig` 重点字段：`type`、`name`、`targetDomain`、`iconPath`、`defaultColor`、`highModel`、`lowModel`、`highModelUrl`、`lowModelUrl`、`scale`、`modelHeadingOffset`、`modelPitchOffset`、`modelRollOffset`、`smoothMove`、`smoothMoveMinCameraHeight`、`smoothMoveDurationMs`、`predict`、`predictMove`、`predictMinCameraHeight`、`predictSeconds`、`predictFitSeconds`。
+
+#### 数据方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `setData(targets)` | `setTargetData` 的别名，全量替换目标数据 |
+| `upsert(targets)` | `upsertTargetData` 的别名，增量新增或更新 |
+| `remove(ids)` | `removeTargetData` 的别名，按 id 删除 |
+| `addTarget(target)` | 校验并实时 upsert 单目标，返回校验后的目标 |
+| `updateTarget(target)` | 校验并实时 upsert 单目标，返回校验后的目标 |
+| `setTargetData(targets)` | 全量替换目标数据 |
+| `upsertTargetData(targets)` | 增量新增或更新目标数据 |
+| `removeTargetData(ids)` | 实时删除目标 |
+| `applyTargetIncremental(payload)` | 应用 `{ upserts, removes }` 增量包 |
+
+`MultiTargetFramework` 会校验目标字段，只允许 `id`、`type`、`lon`、`lat`、`height`、`speedH`、`speedV`、`heading`、`renderColor`、`openAnimate`、`animateType`、`animateColor`、`nationality`、`customInfo`、`track`、`secrecy`、`extra`。
+
+#### 样式和显示
+
+| 方法 | 说明 |
+| --- | --- |
+| `setTargetColor(id, color, options?)` | 设置单个或多个目标颜色，颜色格式 `#RRGGBB` 或 `#RRGGBBAA` |
+| `setTargetGlow(id, enabled, color?, options?)` | 开关发光动画 |
+| `hideTarget(id, options?)` | 隐藏目标 |
+| `showTarget(id, options?)` | 显示目标 |
+| `disappearTarget(id, options?)` | `hideTarget` 别名 |
+| `appearTarget(id, options?)` | `showTarget` 别名 |
+| `setNameplateConfig(config)` | 动态更新名称牌/标签配置 |
+
+`id` 可传字符串或字符串数组。`TargetStyleOptions.clearBefore` 默认 `true`，表示本次样式补丁会先清理旧同类样式；`clearBefor` 为兼容旧拼写。
+
+#### 选择、框选和定位
+
+| 方法 | 说明 |
+| --- | --- |
+| `selectTarget(id, options?)` | 选中目标，返回 `TargetSnapshot | null` |
+| `selectTargets(ids, options?)` | 批量选中目标，返回存在的快照数组 |
+| `unselectTarget(id)` | 取消单目标选中 |
+| `clearSelection()` | 清空选中和框选状态 |
+| `boxTarget(id, enabled?, options?)` | 设置黄色框选覆盖层，`enabled` 默认 `true` |
+| `unboxTarget(id, options?)` | 取消框选 |
+| `locateTarget(id, options?)` | 飞行定位目标，返回目标快照 |
+
+`LocateTargetOptions`：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `range` | `18000` | 相机离目标距离，单位米 |
+| `height` | - | 兼容旧字段，低优先级 |
+| `duration` | `0.8` | 飞行时间，秒 |
+| `pitch` | `-65` | 俯仰角，度 |
+| `heading` | `0` | 航向角，度 |
+
+#### 右键菜单
+
+| 方法 | 说明 |
+| --- | --- |
+| `registerContextMenuItem(item)` | 注册菜单项，返回注销函数 |
+| `showContextMenu(ctx)` | 使用统一菜单 DOM 展示上下文 |
+| `closeContextMenu()` | 关闭菜单 |
+
+```ts
+const dispose = framework.registerContextMenuItem({
+  key: "locate",
+  label: "定位",
+  targetKinds: ["target", "site"],
+  order: 10,
+  visible: (ctx) => ctx.target.kind !== "ground",
+  onClick: async (ctx) => {
+    if (ctx.target.kind === "target") await ctx.framework.locateTarget(ctx.target.id);
+  },
+});
+```
+
+`ContextMenuContext.target.kind` 支持：
+
+| kind | 数据 |
+| --- | --- |
+| `"target"` | `id`、`type`、`data: TargetSnapshot` |
+| `"ground"` | `lon`、`lat`、`height` |
+| `"site"` | `id`、`siteType`、`data?` |
+
+#### 生命周期
+
+| 方法 | 说明 |
+| --- | --- |
+| `destroy()` | 销毁菜单 DOM、事件监听、底层场景和 worker |
+| `MultiTargetFramework.create(viewer, options)` | 静态异步工厂，构造后等 `ready` 就绪再 resolve，返回 `Promise<MultiTargetFramework>` |
+
+### 三、底层入口 `MultiTargetScene`
+
+`MultiTargetScene` 更接近渲染引擎本体，适合需要 packed 数据、底层事件或自定义封装的场景。高层 `MultiTargetFramework.scene` 即为此实例。
+
+#### 属性
+
+| 属性 | 说明 |
+| --- | --- |
+| `config` | 解析后的 `ResolvedConfig` |
+| `render` | 点云/图标渲染器 |
+| `models` | 低模/高模模型池渲染器 |
+| `symbols` | 可选，地表实例化有向符号渲染器 |
+| `selection` | 选中覆盖层渲染器 |
+| `tracks` | `TrackManager` |
+| `nodes` | `SceneNodeStats` 渲染统计 |
+| `quality` | 当前质量档，当前固定为 `{ tier: "high" }` |
+| `targetCount` | 当前 worker 内目标总数 |
+
+#### 数据和渲染方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `setData(targets)` | 全量目标数据 |
+| `applyIncremental(payload)` | 增量目标数据 |
+| `applyRealtimeUpsert(targets)` | 实时 upsert，不走周期提交等待 |
+| `applyRealtimeRemove(ids)` | 实时删除 |
+| `applyPacked(payload)` | 提交 typed array packed 数据，适合大批量高频输入 |
+| `applyTargetStyle(patches)` | 底层样式补丁 |
+| `setBoxedTargetIds(ids)` | 设置框选 id 集合 |
+| `setLabelConfig(config)` | 更新标签配置 |
+| `flushNow()` | 立即提交当前 staged 数据 |
+| `pause()` | 暂停提交和视口刷新 |
+| `resume()` | 恢复并刷新视口 |
+| `destroy()` | 销毁 worker、渲染器、事件和选择状态 |
+
+#### 查询和交互方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `selectTarget(id, clearBefore?)` | 选中目标，返回 `PickedNodeLike | null` |
+| `selectTargets(ids, clearBefore?)` | 批量选中，返回命中的目标数组 |
+| `unselectTarget(id)` | 取消选中 |
+| `clearSelection(emit?)` | 清空选择，`emit` 默认 `true` |
+| `getTargetSnapshot(id)` | 从 worker 查询目标逻辑快照 |
+| `getRenderedTargetFrame(id, result?)` | 查询当前实际渲染帧位置和航向 |
+| `getRenderedTargetPosition(id, result?)` | 查询当前 render packet 中的渲染坐标 |
+
+#### 事件
+
+`MultiTargetScene` 继承 `EventEmitter`，使用 `scene.on(event, handler)` 监听，返回取消监听函数。
+
+| 事件 | 载荷 |
+| --- | --- |
+| `perf` | 输入、worker、渲染慢帧等性能事件 |
+| `dirty` | `{ added, updated, removed }` 普通 diff |
+| `packedDirty` | packed diff |
+| `pick` | `PickedNodeLike | null` |
+| `hover` | `PickedNodeLike | null` |
+| `selection` | `PickedNodeLike[]` |
+| `contextmenu` | 目标或空地右键上下文 |
+
+### 四、目标数据类型
+
+`TargetData` / `StandardTargetData`：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | 唯一 id |
+| `type` | 是 | 目标类型，必须命中配置 |
+| `lon` / `lat` / `height` | 是 | WGS84 经纬度和高度 |
+| `speedH` / `speedV` | 是 | 水平/垂直速度，m/s |
+| `heading` | 是 | 航向角，度，正北 0 顺时针 |
+| `renderColor` | 否 | `#RRGGBB` 或 `#RRGGBBAA` |
+| `openAnimate` | 否 | 是否开启动画 |
+| `animateType` | 否 | 当前内置支持 `glow` / `发光` |
+| `animateColor` | 否 | 动画颜色 |
+| `nationality` | 否 | 国籍/归属字符串 |
+| `customInfo` | 否 | 自定义信息对象，可用于名称牌字段 |
+| `track` | 否 | `TrackPoint[]` |
+| `secrecy` | 否 | 密级（预留字段，当前仅透传，未参与聚合/合并逻辑） |
+| `extra` | 否 | 额外内部/业务状态 |
+
+`PackedTargetData` 用 typed array 表示大批量数据：`lon`、`lat` 必填；`ids`、`types`、`height`、`speedH`、`speedV`、`heading`、`secrecy`、`renderColor`、`animate`、`animateColor`、`removes` 可选。
+
+### 五、配置速查
+
+| 配置 | 当前默认 | 说明 |
+| --- | --- | --- |
+| `lod.pointAbove` | `150000` | 高于此高度走点模式 |
+| `lod.animatedBelow` | `10000` | 低于此高度允许高模动画 |
+| `pool.size` | `30000` | 通用目标池容量 |
+| `animatedPool.size` | `64` | 高模动画容量 |
+| `updateFps` | `30` | 渲染/刷新频率 |
+| `predictSeconds` | `10` | 预测窗口秒数 |
+| `predictFitSeconds` | `2` | 新权威数据到达后的拟合秒数 |
+| `fadeMs` | `350` | 显隐淡入淡出时间 |
+| `masterHideHeight` | `150000` | 高于此高度隐藏模型内容 |
+| `merge.mode` | `"global"` | 聚合模式 |
+| `merge.maxVisible` | `pool.size` | 最大渲染目标数 |
+| `merge.globalRootLimit` | `500` | global 顶层根聚合数量上限 |
+| `merge.globalMaxLevels` | `64` | global 最大层级 |
+| `merge.globalRebuildIntervalMs` | `300000` | global 缓存重建间隔 |
+| `merge.globalViewportHeight` | `450000` | 高于此高度按全球视口处理 |
+| `merge.cameraMergeBaseHeight` | `100000` | 低于/等于该高度不随相机增加合并半径 |
+| `merge.cameraMergeStepHeight` | `10000` | 相机高度每增一档的高度 |
+| `merge.cameraMergeStepRadius` | `100` | 每档半径增量 |
+| `pick.enabled` | `true` | 是否启用点击拾取 |
+| `pick.pixelThreshold` | `20` | 拾取像素阈值 |
+| `pick.hover` | `true` | 是否启用 hover |
+| `cull.viewportBufferRatio` | `0.15` | 视口缓冲比例 |
+| `label.enabled` | `true` | 是否显示名称牌 |
+| `label.maxCount` | `200` | 名称牌最多显示数量 |
+| `label.maxCameraHeight` | `5000` | 名称牌最大相机高度 |
+| `frame.maxLowModelRenderItems` | `3000` | 低模后端数量上限 |
+| `frame.maxModelRenderItems` | `2000` | 旧兼容项 |
+| `data.commitIntervalMs` | `2000` | 数据提交周期 |
+| `data.leading` | `true` | 首批数据是否立即提交 |
+| `data.worker` | `true` | 数据处理是否使用 worker |
+| `groundSymbols` | `false` | 点档单目标是否用地表实例化有向符号 |
+| `groundSymbolPixelSize` | `30` | 地表符号像素大小 |
+
+### 六、轨迹 `TrackManager`
+
+可通过 `framework.tracks` 或 `scene.tracks` 使用。
+
+| 方法 | 说明 |
+| --- | --- |
+| `on("hover", handler)` | 监听轨迹点 hover，载荷为 `TrackHoverInfo | null` |
+| `setTracks(tracks)` | 新增或更新轨迹 |
+| `getTracks(targetIds?)` | 查询轨迹，返回拷贝 |
+| `showTracks(targetIds)` | 显示轨迹 |
+| `hideTracks(targetIds)` | 隐藏轨迹 |
+| `removeTracks(targetIds)` | 删除指定轨迹 |
+| `clearTracks()` | 清空轨迹 |
+
+`TrackRecord` 支持 `pointList` 或 `trackLine`。`trackLine` 格式为 `LINESTRING (...)` 或 `LINESTRING Z (...)`。
+
+### 七、站点层 `SiteLayer`
+
+站点层独立于目标系统，用于光电、雷达、AIS 等固定站点图标/低模展示。
+
+```ts
+const siteLayer = new SiteLayer(viewer, {
+  modelSwitchHeight: 8000,
+  siteTypes: [
+    {
+      type: "radar",
+      category: "radar",
+      iconPath: "/icons/radar.png",
+      lowModel: { url: "/model/radar.glb" },
+    },
+  ],
+});
+
+siteLayer.setData([{ id: "radar-1", type: "radar", lon: 121, lat: 31, height: 0 }]);
+```
+
+#### 属性和方法
+
+| 方法/属性 | 说明 |
+| --- | --- |
+| `options` | 解析后的站点配置 |
+| `stats` | `{ total, inView, iconCount, lowModelCount, lowModelEligibleCount, mode }` |
+| `setData(sites)` | 全量设置站点 |
+| `pickAt(position, thresholdPx?)` | 按屏幕坐标拾取最近站点 |
+| `clear()` | 清空站点 |
+| `destroy()` | 销毁图标、低模和事件 |
+
+事件：
+
+| 事件 | 载荷 |
+| --- | --- |
+| `contextmenu` | `{ site, screenX, screenY, cartesian? }` |
+| `pick` | `SiteData | null` |
+
+`SiteLayer` 右键站点后可调用 `framework.showContextMenu(...)` 接入统一菜单。
+
+### 八、聚类工具
+
+#### 同步聚类
+
+| 方法 | 说明 |
+| --- | --- |
+| `lonLatToLocalPlane(lons, lats, count, lon0?, lat0?)` | 经纬度投影到本地平面米坐标 |
+| `clusterProgressive(xs, ys, count, options?)` | 一次性递进聚类，返回独立数组，适合低频 |
+| `createQuadClusterer(initialCapacity?)` | 创建复用缓冲的高频聚类器 |
+
+`ProgressiveClusterOptions`：`baseCellMeters` 默认 `200`、`maxClusters` 默认 `30000`、`maxLevels` 默认 `20`。
+
+#### Worker 聚类
+
+```ts
+const client = createClusterWorkerClient();
+const result = await client.run(lons, lats, count, { baseCellMeters: 200, maxClusters: 30000 });
+client.terminate();
+```
+
+`ClusterWorkerClient`：
+
+| 方法 | 说明 |
+| --- | --- |
+| `run(lons, lats, count, options?)` | 拷贝输入并在 worker 中聚类；忙时 last-wins，旧排队任务返回 `null` |
+| `inputBuffers(count)` | 借出内部输入缓冲 |
+| `runReusing(count, options?)` | 零拷贝提交内部输入缓冲 |
+| `terminate()` | 结束 worker |
+
+### 九、Web Event Bus 自动对外暴露能力
+
+本包集成 `web-event-bus`，用于把框架实例的对外方法和事件自动暴露到全局 bus。创建 `MultiTargetFramework` 后会自动注册 framework/tracks 相关 action 并桥接 scene/tracks 事件；创建 `SiteLayer` 后会自动注册 site 相关 action 并桥接站点事件。该能力不会修改 `scene.on(...)`、`siteLayer.on(...)`、`tracks.on(...)` 的原行为，实例 `destroy()` 时会自动解绑本实例注册的 action 和事件桥接。
+
+默认使用固定 action 名；如果页面上同时存在多个 `MultiTargetFramework` 或多个 `SiteLayer`，最后创建的同类实例会接管对应 action。旧实例销毁时不会注销已被新实例接管的 action。
+
+#### 使用方式
+
+```ts
+import {
+  getFrameworkEventBus,
+} from "cesium-multi-target-framework";
+
+const framework = new MultiTargetFramework(viewer, options);
+const siteLayer = new SiteLayer(viewer, siteOptions);
+const bus = getFrameworkEventBus();
+
+bus.on("mtf.scene.hover", (payload) => {
+  console.log("scene hover", payload);
+});
+
+await bus.invoke("mtf.framework.locateTarget", {
+  id: "ship-001",
+});
+```
+
+| 工具 | 说明 |
+| --- | --- |
+| `getFrameworkEventBus()` | 获取 `web-event-bus` 的浏览器全局 bus；非浏览器环境会抛错 |
+| `tryGetFrameworkEventBus()` | 获取全局 bus；不可用时返回 `null` |
+| `createFrameworkEventBus()` | 创建独立 bus 实例，不挂到全局 |
+| `bindFrameworkEventBus(framework, options?)` | 高级用法：手动把指定 `MultiTargetFramework` 绑定到自定义 bus 或自定义 owner |
+| `bindSiteLayerEventBus(siteLayer, options?)` | 高级用法：手动把指定 `SiteLayer` 绑定到自定义 bus 或自定义 owner |
+
+自动绑定内部也使用 `FrameworkBusBinding` 管理生命周期。手动调用 `bindFrameworkEventBus` / `bindSiteLayerEventBus` 时会返回该对象：
+
+| 字段/方法 | 说明 |
+| --- | --- |
+| `active` | 是否成功绑定；非浏览器环境且未传入自定义 bus 时为 `false` |
+| `owner` | 注册到 bus 的 owner 名 |
+| `dispose()` | 注销本次注册的 action，并取消事件桥接监听 |
+
+绑定选项：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `bus` | 全局 bus | 指定使用的 `FrameworkEventBus` |
+| `owner` | `"cesium-multi-target-framework"` | 注册 action 时写入的 owner |
+| `registerActions` | `true` | 是否注册方法 action |
+| `bridgeEvents` | `true` | 是否桥接框架事件到 bus |
+| `replaceExisting` | `false` | action 已存在时是否先 unregister 再注册 |
+
+#### 自动暴露的事件
+
+事件会在对应实例创建后自动桥接到 bus。bus listener 抛错由 `web-event-bus` 隔离，不影响原本 `.on()` 监听。
+
+| event 字符串 | 载荷 |
+| --- | --- |
+| `mtf.scene.perf` | `SceneEvents["perf"]` |
+| `mtf.scene.dirty` | `SceneEvents["dirty"]` |
+| `mtf.scene.packedDirty` | `SceneEvents["packedDirty"]` |
+| `mtf.scene.pick` | `PickedNodeLike \| null` |
+| `mtf.scene.hover` | `PickedNodeLike \| null` |
+| `mtf.scene.selection` | `PickedNodeLike[]` |
+| `mtf.scene.contextmenu` | `SceneContextMenuPayload \| null` |
+| `mtf.track.hover` | `TrackHoverInfo \| null` |
+| `mtf.site.contextmenu` | `SiteContextMenuPayload` |
+| `mtf.site.pick` | `SiteData \| null` |
+| `mtf.site.hover` | `SiteData \| null` |
+
+#### 自动暴露的方法 action
+
+创建 `MultiTargetFramework` 后自动注册 `framework` 和 `framework.tracks` 的对外方法：
+
+| action 字符串 | params | result |
+| --- | --- | --- |
+| `mtf.framework.addTarget` | `{ target }` | `StandardTargetData` |
+| `mtf.framework.updateTarget` | `{ target }` | `StandardTargetData` |
+| `mtf.framework.setTargetData` | `{ targets }` | `void` |
+| `mtf.framework.upsertTargetData` | `{ targets }` | `void` |
+| `mtf.framework.removeTargetData` | `{ ids }` | `void` |
+| `mtf.framework.applyTargetIncremental` | `{ payload }` | `void` |
+| `mtf.framework.setTargetColor` | `{ id, color, options? }` | `void` |
+| `mtf.framework.setTargetGlow` | `{ id, enabled, color?, options? }` | `void` |
+| `mtf.framework.hideTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.showTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.disappearTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.appearTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.setNameplateConfig` | `{ config }` | `void` |
+| `mtf.framework.selectTarget` | `{ id, options? }` | `TargetSnapshot \| null` |
+| `mtf.framework.selectTargets` | `{ ids, options? }` | `TargetSnapshot[]` |
+| `mtf.framework.unselectTarget` | `{ id }` | `void` |
+| `mtf.framework.clearSelection` | `undefined` | `void` |
+| `mtf.framework.boxTarget` | `{ id, enabled?, options? }` | `void` |
+| `mtf.framework.unboxTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.locateTarget` | `{ id, options? }` | `TargetSnapshot \| null` |
+| `mtf.framework.registerContextMenuItem` | `{ item }` | `() => void` |
+| `mtf.framework.showContextMenu` | `{ context }` | `void` |
+| `mtf.framework.closeContextMenu` | `undefined` | `void` |
+| `mtf.framework.destroy` | `undefined` | `void` |
+| `mtf.tracks.setTracks` | `{ tracks }` | `void` |
+| `mtf.tracks.getTracks` | `{ targetIds? } \| undefined` | `TrackRecord[]` |
+| `mtf.tracks.showTracks` | `{ targetIds }` | `void` |
+| `mtf.tracks.hideTracks` | `{ targetIds }` | `void` |
+| `mtf.tracks.removeTracks` | `{ targetIds }` | `void` |
+| `mtf.tracks.clearTracks` | `undefined` | `void` |
+
+创建 `SiteLayer` 后自动注册站点层方法：
+
+| action 字符串 | params | result |
+| --- | --- | --- |
+| `mtf.site.setData` | `{ sites }` | `void` |
+| `mtf.site.clear` | `undefined` | `void` |
+| `mtf.site.pickAt` | `{ position, thresholdPx? }` | `SiteData \| null` |
+| `mtf.site.destroy` | `undefined` | `void` |
+
+#### TypeScript 类型
+
+| 类型 | 说明 |
+| --- | --- |
+| `FrameworkEventBus` | 带框架事件/action 类型提示的 bus |
+| `FrameworkBusEventMap` | event name 到 payload 的映射 |
+| `FrameworkBusActionMap` | action name 到 params/result 的映射 |
+| `FrameworkEventName` / `FrameworkEventPayload` | 事件名和载荷辅助类型 |
+| `FrameworkBusActionName` / `FrameworkBusActionParams` / `FrameworkBusActionResult` | action 名、参数、结果辅助类型 |
+
+### 十、事件工具 `EventEmitter`
+
+`EventEmitter<EventMap>` 是一个轻量事件类，`MultiTargetScene`、`TrackManager`、`SiteLayer` 都继承它。
+
+| 方法 | 说明 |
+| --- | --- |
+| `on(event, handler)` | 注册监听，返回取消函数 |
+| `off(event, handler)` | 取消监听 |
+| `emit(event, payload)` | 触发事件，通常内部使用 |
+| `clear()` | 清空所有监听 |