# 智能星球可交互图标聚类策略

智能星球的可交互图标由 `createInteractableLayer` 统一管理。图标仍然使用 Three.js `Points` 渲染，拾取、hover、locked、tooltip 和巡航焦点继续依赖 marker 的 `userData`；聚类策略只决定“哪些 marker 被合成一个 cluster dot”。

## 策略

`cluster.strategy` 支持三种模式：

- `stable-spherical`：稳定球面聚类。按地球局部 3D 坐标聚合，并用 zoom band 缓存拓扑；旋转和同档缩放只更新投影和尺寸，不重算谁和谁聚在一起。适合 BGP、超算/GPU 中心和 Earth interactable 这类半静态图层。
- `dynamic-screen`：动态屏幕聚类。保留原来的屏幕空间聚类逻辑，每帧按可见投影关系判断。适合船舶等高频实时图层，也可作为稳定策略的回退。
- `none`：不聚类。所有 marker 独立显示，适合低数量或需要精确展示的图层。

`cluster: false` 等价于 `strategy: "none"`。未显式声明 `strategy` 时，保持兼容行为：开启聚类的旧图层继续走 `dynamic-screen`。

## Stable Spherical

`stable-spherical` 的核心是把聚类身份从屏幕距离迁到球面距离：

- 每个 marker 使用 `icon_base_position` 作为真实地理锚点。
- 默认 zoom 超过 `2.5` 时强制关闭聚类，所有 marker 展开为原图标。
- 当前 zoom 只映射到离散 band；同一 band 内旋转地球或细微缩放不会重算拓扑。
- 跨 band、数据变更、图层显隐变化时才重新计算 cluster。
- cluster 质心由成员 3D 坐标平均后 normalize 回球壳半径，因此 cluster dot 刚性贴在地理质心投影上。
- cluster dot 不参与 2D 避让，避免被屏幕排斥推离真实地理位置。
- band 切换带有少量 hysteresis，避免缩放停在临界点时在两个 band 之间来回跳。
- 新生成的 marker / cluster dot 会执行短 scale + opacity ease；这只是渲染过渡，不改变 marker 的真实经纬度、拾取对象或 locked 状态。

稳定策略使用球面 bucket/hash 邻域查询，禁止用全量双循环。这样大多数帧只承担投影与材质尺寸更新，聚类成本只在 band 或数据版本变化时支付。

## 配置示例

```js
const computeCenterIconLayer = createInteractableLayer({
  id: "computeCenters",
  // ...
  avoidance: SURFACE_AVOIDANCE_PROFILES.city,
  cluster: {
    strategy: "stable-spherical",
    minCount: 2,
    maxMarkersPerDot: 14,
    transitionMs: 220,
    bandHysteresis: 0.08,
    disableAboveZoom: 2.5,
    bands: [
      { key: "far", maxZoom: 1.7, distance: 15 },
      { key: "mid", maxZoom: 2.6, distance: 8 },
      { key: "near", maxZoom: 3.5, distance: 4 },
      { key: "detail", maxZoom: Infinity, distance: 0 },
    ],
  },
});
```

实时层可以保留动态策略：

```js
const vesselIconLayer = createInteractableLayer({
  id: "vessels",
  // ...
  cluster: {
    strategy: "dynamic-screen",
    enabled: true,
    maxMarkersPerDot: 10,
  },
});
```

## 调参原则

- `distance` 是球面 3D 距离阈值，单位与 `CONFIG.earthRadius` 一致。值越大，越容易聚合。
- 最远 band 用较大的 `distance` 降低视觉密度；最近 band 通常设为 `0`，让图标完全解散。
- `bandHysteresis` 控制 band 边界滞回。值太小容易临界闪烁，值太大会让切换略显迟钝。
- `transitionMs` 控制聚散过渡时间。建议保持在 160-260ms，过长会让实时层显得拖泥带水。
- `disableAboveZoom` 控制精细查看阈值。默认 `2.5`，超过后不再生成 cluster；设为 `false` 可关闭这个硬阈值。
- 高实时性图层优先用 `dynamic-screen`，避免数据频繁变更时触发稳定策略的拓扑重算。
- 若某图层出现异常，可临时切回 `dynamic-screen` 或 `cluster: false`。

## 验收重点

- 同一 zoom band 内旋转地球，cluster 不应闪烁或重新聚散。
- cluster dot 应跟随地球表面质心，不被避让逻辑推开。
- 放大到 detail band 后，应恢复该图层原本的图标纹理和点击行为。
- zoom 超过 250% 后不应再显示 cluster dot。
- vessel 等实时层更新后，图标和 cluster 应立即反映最新数据。