9.3 KiB
9.3 KiB
智能星球渲染图层顺序
本文记录当前 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 = 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 = 0.115 |
depthTest: true，禁用 raycast |
线层使用独立 line geometry 与 renderOrder 控制；地形 depthWrite: false，所以地形开启时仍可见。 |
| 2.29 | 国界 hover 光晕 | country-boundaries.js |
hover 半径加 glow 偏移 | depthTest: false，禁用 raycast |
用 additive 光晕增强交界边和地形开启时的 hover 可见性。 |
| 2.3 | 国界 hover 实线 | country-boundaries.js |
hoverAltitudeOffset = 0.115 |
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；参与 Interactable 同坐标避让 |
航行船只用三角点纹理，停泊/低速用圆点；普通态无 glow，交互态叠加同尺寸 glow；低于算力中心 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 = 0.48。 - 新增整球或近整球地表 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，平时将正面船只投影到屏幕坐标，用像素半径命中最近船只；点击后可加载轨迹线。 |