planet/docs/technical/zh/earth-interactable-clustering.md

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

智能星球的可交互图标由 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 或数据版本变化时支付。

配置示例

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 },
    ],
  },
});

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

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 应立即反映最新数据。