# 智能星球渲染图层顺序

本文记录当前 Earth 渲染器的图层顺序和每层意图。后续调整
`renderOrder`、半径偏移、深度策略或指针交互时，需要同步更新这里。

注意：图层控制面板顺序和注册 / 启动加载顺序是两套语义。

| 顺序类型 | 当前顺序 | 说明 |
| --- | --- | --- |
| 控制面板顺序 | 海缆 → 卫星 → 算力中心 → 船只 → BGP → 地形 → 高清材质 → 大气云图 → 国界线 → 经纬线 | 由 `displayOrder` 控制，按操作关注度排列；卫星轨迹已迁到设置面板，不再作为图层列表项。 |
| 注册 / 启动加载顺序 | 经纬线 → 国界线 / 海陆基座 → 高清材质 → 大气云图 → 海缆 → 算力中心 → 船只 → BGP → 卫星 | 由注册顺序和 `startupPriority` 控制，按地表到天空排列；启动队列会先读取保存的图层可见状态，明确关闭的普通图层不预加载，高清材质关闭时不下载贴图；国界线图层例外，海陆基座始终预加载，保存状态只控制可交互国界线和 hover；轨迹和地形是依赖/可选显示层，不参与常规启动数据加载。 |

## 地表图层栈

| 顺序 | 图层 | 来源 | 渲染 / 半径策略 | 深度 / 交互策略 | 备注 |
| --- | --- | --- | --- | --- | --- |
| -1000 | 天体背景 mesh | `celestial.js` | 背景球 | 不参与地表拾取 | 位于所有智能星球内容之后。 |
| -1 | 智能星球遮挡球 | `earth.js` | 地球内侧不可见球 | 写入深度 | 遮挡地球背面的对象。 |
| 0 | 智能星球基座球 | `earth.js` | `CONFIG.earthRadius` | 地表拾取兜底目标 | 深色基座，所有可选地图层关闭时仍可见。 |
| 0.2 | 国界暗色 tint | `country-boundaries.js` | `tintAltitudeOffset` | 禁用 raycast | 高清材质关闭时使用。 |
| 0.86 | 海陆基座填充 | `country-boundaries.js` | `landAltitudeOffset = 0.32`; 海洋 `#010609`，陆地 `#080f1b` | 禁用 raycast | 即使国界线关闭，基座地图仍保持可用；半径与基座球拉开以避免远距 z-fighting。 |
| 0.96 | 高清 Earth 材质 | `earth.js` | `textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48` | 可见时作为地表拾取目标 | 高清材质始终压过海陆基座填充；半径必须高于海陆基座并与基座球保持足够间距。 |
| 1 | 大气辉光和云图 | `earth.js` | 大气 / 云层球 | 不走普通对象选择路径 | 云图由“大气云图”图层开关控制。 |
| 1 | 海缆 / 登陆点 | `cables.js` | 海缆线和登陆点都使用 `renderOrder = 1`；半径偏移都为 `0.2`；登陆点是专用 `THREE.Sprite` 黄色扁平球 | 海缆走海缆拾取路径；登陆点 `depthTest: false` 保持球体完整，并用相机到球心的球体遮挡判断避免背面穿透 | 登陆点和海缆同层贴地，避免地表设施层的凌空感。 |
| 1.2 | 真实地形 | `earth.js`, `terrain.js` | `TERRAIN_CONFIG.baseRadiusOffset` 加地形位移 | 禁用 raycast | 地形压过高清材质；高清材质关闭时临时隐藏，重新开启后恢复原状态。 |
| 2.05 | 经纬线 | `earth.js` | `CONFIG.earthRadius + 0.14` | 禁用 raycast | 低透明度显示在高清材质上。 |
| 2.2 | 国界线 | `country-boundaries.js` | `lineAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48`；claim 线不再额外抬高 | `depthTest: true`，禁用 raycast | 线层使用独立 line geometry 与 `renderOrder` 控制，但半径与高清材质壳完全一致，避免转动地球时与高清贴图出现视差。 |
| 2.29 | 国界 hover 光晕 | `country-boundaries.js` | hover 半径加 glow 偏移 | `depthTest: false`，禁用 raycast | 用 additive 光晕增强交界边和地形开启时的 hover 可见性。 |
| 2.3 | 国界 hover 实线 | `country-boundaries.js` | `hoverAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48` | `depthTest: false`，禁用 raycast | 霓虹红橘 hover 线；与普通国界线和高清材质同源半径对齐，避免重影和漂浮感；中国和中国（台湾）共享高亮组。 |
| 3 | 卫星 footprint 填充 / Iridium coverage ring | `satellites.js`, `iridium-footprint-adapter.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested；Iridium adapter 的 fill / ring 也使用同一 renderOrder | Footprint 在 land / texture / terrain 和国界线之上，但在算力中心和卫星之下。 |
| 3-4.5 | BGP 观测站、事件扩散圈和事件 marker | `bgp.js`, `interactable.js` | BGP 观测站和事件 marker 均使用 `Interactable` 批量 `THREE.Points`；事件 marker 使用 `BGP_EVENT_RENDER_ORDER = 4.5`；观测站主图标使用 `BGP_COLLECTOR_RENDER_ORDER = 4.4` 和 `BGP_CONFIG.collectorAltitudeOffset = 0.2`；事件 overlay 进入 `bgp-event-overlay-layer`；观测站 halo 和覆盖扇形进入 `bgp-collector-radar-layer` | BGP 事件和观测站都通过 `Interactable` 屏幕空间 picking，并参与同坐标避让 | BGP 观测站主图标与船只同层；BGP 事件与算力中心同层；向外扩散圈、观测站雷达/覆盖动画继续由 BGP 业务逻辑驱动。 |
| 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`；`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐，不单独参与拾取 | 选中船只后显示最近轨迹，低于船只 marker。 |
| 4.4 | AIS 船只 marker | `vessels.js`, `interactable.js` | `VESSEL_RENDER_ORDER`；业务高度为 `CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`；普通 marker 为分桶 `THREE.Points`，hover / locked 为单点 `THREE.Points` overlay | `depthTest: true`；`main.js` 使用屏幕空间 picking，只取正面 marker；`cluster: false` 且 `avoidance: false` | 航行船只用三角点纹理，停泊/低速用圆点；密集海域允许重叠，不参与动态屏幕聚类，避免旋转时重建 Points；低于算力中心 `4.5`。 |
| 4.5 | 算力中心 | `compute-centers.js`, `interactable.js` | 使用 `COMPUTE_CENTER_RENDER_ORDER` 并由 `Interactable` 绘制 | 通过 `Interactable` 屏幕空间 picking，参与同坐标避让 | 地表设施层，保持在卫星下方。登陆点已下沉到海缆层。 |
| 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder；默认按 TLE/SGP4 真实高度压缩到 `CONFIG.earthRadius + 4..25`，关闭真实高度或传播失败时回退到 `fallbackAltitudeOffset = 8` | 屏幕空间卫星拾取 | 位于卫星点下方。 |
| 6 | 卫星点 | `satellites.js` | 与卫星背景点使用同一压缩高度 / fallback 高度 | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
| 12+ | 卫星锁定 ring、halo、预测轨道 | `satellites.js` | `SATELLITE_CONFIG.overlayRenderOrder` 及偏移；预测轨道使用同一真实高度开关，并固定锁定时刻的地球姿态来绘制闭合惯性轨道；关闭真实高度时回到同层球面 | 卫星覆盖层路径 | 用于选中 / 锁定卫星强调。 |
| 98-100 | 太阳 / 月亮 halo 和 sprite | `celestial.js` | 固定 renderOrder | 天体拾取禁用 | 前景天体 sprite。 |

## 开关联动

| 开关 | 行为 |
| --- | --- |
| 高清材质 off | 隐藏高清材质，启用国界 tint / 基座表面，禁用地形和昼夜开关交互，并记住地形和昼夜之前状态。 |
| 高清材质 on | 恢复高清材质，并恢复记住的地形 / 昼夜状态。 |
| 地形 on | 显示在高清材质之上，但低于国界 hover、footprint、卫星等强调层。 |
| 大气云图 | 只控制云图 mesh 显隐。 |
| 国界线 off | 只隐藏可交互国界线和 hover，高亮状态会清除；海陆基座填充仍作为 Earth 底图保留。 |
| 真实卫星高度 off | 卫星点、轨迹和预测轨道都使用旧版同层球面；缺失 TLE 或传播失败的卫星也使用同一 fallback 高度。 |

## 深度间距规则

Earth 的地表不是单一 mesh，而是多层近似同心球：基座球、海陆基座、高清材质、地形、云层、大气和遮挡球。近距看起来只差几个小数的半径偏移，在 50% 这类远距视图下会被深度缓冲压到同一批像素，导致 z-fighting，表现为黑块、雪花或闪烁。

维护规则：

- 不要用“远距隐藏图层”作为第一反应；先检查相邻 shell 的 `altitudeOffset`、`renderOrder`、`depthTest` 和 `depthWrite`。
- 海陆基座和高清材质这类整球 overlay 必须与 `CONFIG.earthRadius` 保持明确间距；当前稳定值为 `landAltitudeOffset = 0.32`、`textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48`。
- 国界线、coastline、claim 线和国界 hover 线必须使用 `EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET`，与高清材质壳完全同半径；不要再用低于或高于高清材质的独立线层 offset，否则转动地球时会产生相对地表的视差漂浮感。
- 新增整球或近整球地表 overlay 时，必须在 50% 缩放和常用近距视图各截一次图，确认没有黑块、雪花、闪烁，也没有明显漂浮感。
- 如果必须调整这些半径，需同步更新本文和 `frontend/public/earth/js/constants.js` 的注释/常量意图。

## 交互规则

| 交互 | 当前规则 |
| --- | --- |
| 智能星球坐标 hover | 高清材质可见时使用高清材质 overlay 作为地表拾取目标，否则使用智能星球基座球。 |
| 国界 hover | 先把地表拾取坐标转成经纬度，再用 GeoJSON 点面判断；国界 hover 线本身不接收 raycast。 |
| 国界 hover 视觉 | hover 时压暗普通国界线，并绘制无深度测试的光晕和实线。 |
| 中国 / 台湾 hover | `CHN` 和 `TWN` 被归到同一个 hover 高亮组；tooltip 仍显示鼠标实际命中的 feature。 |
| 地形 | 只作为视觉层参与，`terrain.raycast` 已禁用。 |
| 卫星 | 使用屏幕空间卫星拾取，避免 footprint 或地表层挡住卫星点击。 |
| 船只 | 不使用对象级 sprite raycast。`main.js` 会在拖动 / 惯性期间跳过 hover picking，平时将正面船只投影到屏幕坐标，用像素半径命中最近船只；点击后可加载轨迹线。 |