Files
planet/docs/technical/zh/earth-render-layer-order.md
T

17 KiB
Raw Blame History

智能星球渲染图层顺序

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

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

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

地表图层栈

算力专题沿用原算力中心 Interactable 图标、深度与层次顺序;国家/年份切换会替换该层数据并清除旧选中状态。专题 HUD 属于屏幕 UI,在 main.js 的指针排除列表中,不参与地球 picking;区域数据卡在屏幕空间由地理锚点牵引,背面不画穿球连线,设施详情复用原详情卡和移动端详情抽屉。高清地表由 earth-surface-material.js 的单次绘制 ShaderMaterial 负责,保持原有 R+0.48 网格、深度策略和地表拾取对象。四张 8K 底图仍由原控制器切换,成功后更新采样 uniform 并释放旧纹理,失败保留原图。法线、视线和真实太阳方向统一到世界坐标;土地哑光,海洋只有掠射角冷色反射,没有白色镜面高光。海洋区分优先复用现有海陆地理纹理,未加载时使用保守色差估计,冰雪抑制反射;关闭国界线不移除光学遮罩。原始 JPEG 不重绘、不降采样。 颜色纹理标记 sRGB 并启用 mipmaps。r128 在地表 Shader 中解码 sRGB,r160 由纹理硬件格式解码;二者在线性空间合成光照后只编码一次。局部 filmic 曲线只作用于地表,不打开全局 ACES 曝光,避免改变星空和业务图层。晨昏范围为法线点积 [-0.12, 0.28],夜面在线性色调映射后保留 0.12–0.32 光照,避免暗部被曲线再次压黑。大气收敛为 R×1.025 的一个 BackSide/Additive 壳,depthWrite=false、depthTest=true,内沿散射并入地表;云图独立开关,使用哑光昼夜材质并在 1.1 顺序绘制。星图使用已有 starmap_deep_8k.jpg,不加染色遮罩。

顺序 图层 来源 渲染 / 半径策略 深度 / 交互策略 备注
-1000 天体背景 mesh celestial.js 背景球 不参与地表拾取 位于所有智能星球内容之后。
0.5 智能星球遮挡球 earth.js 地球内侧不可见球 写入深度 遮挡地球背面的对象。
0 智能星球基座球 earth.js CONFIG.earthRadius 地表拾取兜底目标 深色基座,所有可选地图层关闭时仍可见。
0.2 国界暗色 tint country-boundaries.js tintAltitudeOffset = 0.32,与海陆填色共用网格及半径 depthTest=true、depthWrite=false,禁用 raycast 加载占位及高清材质关闭时使用;填色就绪后按 renderOrder 覆盖。
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 / 1.1 大气辉光 / 云图 earth.js 单层大气 R×1.025;云图 R+3 大气 BackSide、depthWrite=false、depthTest=true;保留云图开关 内沿光照并入高清地表,不新增全屏后处理。
1 海缆 / 登陆点 cables.js, cable-batches.js 海缆全量线段合并为一个 LineSegments;登陆点全量使用实例化 billboard;renderOrder = 1、海缆与登陆点统一使用高清地表 0.48 偏移和同源三角表面坐标 原始 Line / Sprite 仅作为逐项拾取和选择状态对象,材质不再单独绘制;登陆点仍按球体遮挡判断背面可见性,批量材质 depthTest: false 样式通过线缆样式纹理和登陆点实例属性同步;保留颜色、脉冲、尺寸、显隐与点击语义。
1.2 真实地形 earth.js, terrain.js TERRAIN_CONFIG.baseRadiusOffset 加地形位移 禁用 raycast 地形压过高清材质;高清材质关闭时临时隐藏,重新开启后恢复原状态。
2.05 经纬线 earth.js CONFIG.earthRadius + 0.14 禁用 raycast 低透明度显示在高清材质上。
0.97–0.99 国界线 country-boundaries.js lineAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48;claim 线不再额外抬高 depthTest: true,禁用 raycast 线层使用独立 line geometry 与 renderOrder 控制,但半径与高清材质壳完全一致,避免转动地球时与高清贴图出现视差。
0.98 国界 hover 光晕 country-boundaries.js 与地表锚点相同,无额外抬高 depthTest: true,透明绘制队列,禁用 raycast additive 光晕处于登陆点下方,背面由球体遮挡。
0.99 国界 hover 实线 country-boundaries.js hoverAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48 depthTest: true,透明绘制队列,禁用 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,参与同坐标避让 地表设施层,保持在卫星下方。登陆点已下沉到海缆层。
6 卫星点 satellites.js SGP4 高度压缩为 R+4..25;回退高度 R+8 屏幕空间卫星拾取 卫星点压过 footprint 和算力中心。
12+ 卫星锁定 ring、halo、预测轨道 satellites.js SATELLITE_CONFIG.overlayRenderOrder 及偏移;预测轨道使用同一真实高度开关,并固定锁定时刻的地球姿态来绘制 完整周期开放惯性轨道与方向流光;关闭真实高度时回到同层球面 卫星覆盖层路径 用于选中 / 锁定卫星强调。
98-100 太阳 / 月亮 halo 和 sprite celestial.js 固定 renderOrder 天体拾取禁用 前景天体 sprite。

全量绘制与更新约束

  • 合批只改变 GPU 提交方式,不减少卫星、线段或登陆点数量,也不按相机半球裁剪数据。海缆每对相邻顶点都保留,拾取仍返回原始业务对象。
  • 卫星普通态为单批硬边圆盘 Points,无背景点批次;可选呼吸仍由顶点着色器计算,默认关闭。分类过滤与 hover / locked 的点隐藏保持统一。
  • satellite-position-worker.js 使用与主线程相同的 Three.js / SGP4 版本,通过 satellite-propagation.js 共享轨道、显示高度和 fallback 计算;全量位置及初始轨迹以可转移数组交给主线程。主线程维持一个在途计算,不堆积过期帧;重载、清空和高度模式变更会终止旧 Worker。
  • Worker 启动失败或超过 SATELLITE_CONFIG.workerStartupTimeoutMs 时退回共享的同步计算,避免图层无限等待。计数、数据接口、原有更新周期和轨迹长度不变。
  • 验证时同时检查全量 draw range、逐项拾取、锁定覆盖层、轨迹、背面遮挡、开关及清空后的资源释放;比较帧耗时必须使用相同数据、相同视角和分辨率。

开关联动

开关 行为
高清材质 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,平时将正面船只投影到屏幕坐标,用像素半径命中最近船只;点击后可加载轨迹线。

国界贴地与登陆点顺序

earth-surface.js 在几何构建阶段按高清 SphereGeometry 的 UV 三角形计算贴地点,供普通国界、海岸、主张线、高亮和登陆点共用。长线段按地表网格间距细分,避免把理想球面顶点之间的长弦当作地表。高亮始终进入透明队列并启用深度测试:地表贴图 0.96 → 国界/高亮 0.97–0.99 → 登陆点 1。只调整地表附着与遮挡,不改变地理数据或经纬度归属;构建后缓存,不在转动时重新投影几何。

启动加载与绘制顺序

运行时优先完成选中的完整高清地表,再启动相互独立的数据图层请求;国界构建不再阻塞地表首帧。该启动优化不改变各图层的 renderOrder、深度策略、几何精度或贴图分辨率。数据刷新不清除当前地表,纹理仅在替换成功或场景销毁时释放。

国界加载态菱形格回归防护

v0.58.0 曾将海陆填色抬至 R+0.32、高清贴图抬至 R+0.48,但遗留的占位 tint 仍为 R+0.04、64×32 网格。它与 128×128 主球的弦面交叉,会在海陆/高清纹理未就绪时形成纬圈菱形格;加载后只被上层盖住,并非问题消失。实测旧几何在采样处切入主球约 0.153。

基座、占位 tint、海陆填色和高清地表统一由 createEarthSurfaceGeometry() 使用相同 UV 三角网格。tint 和 land 共用 R+0.32;两者不写深度,靠原 renderOrder 完成填色替换,高清贴图仍为 R+0.48。遮挡球、地形、云图、国界拾取及政治显示策略不变。不能仅靠改 renderOrder、关闭深度测试或隐藏加载球掩盖几何穿插。

earth-surface.test.js 用实际创建的加载态 tint 做径向相交检查,并在 50% / 100% / 500% 下验证至少两个 24-bit 深度单位的前后余量。浏览器验收需覆盖延迟贴图、国界开关、远近距旋转和填色/高清就绪后的状态。

地表标记对齐与侧面显隐

海缆和登陆点现在统一使用 R+0.48 及 earthSurfacePoint 三角表面投影,并保持 renderOrder=1。登陆点关联光晕进入原实例批次的 emphasis 属性,不增加独立 Sprite 或 draw call。侧面的完整圆角徽标采用 GPU 锚点射线/球体遮挡:锚点可见则整个 billboard 绘制,锚点被地球挡住则整块裁除。CPU 拾取使用同样的射线判断,避免点到背面图标。该路径只作用于 icon.badge 层(含算力、观测站;船舶独立使用航向箭头)。选中 BGP 事件的静态覆盖光晕使用事件图标相同的 R+0.48 锚点、前景顺序和整块前后显隐;BGP 发散圆环仍保留原有独立动画语义。

聚合投影层 .map-clusters 的 z-index 为 8,低于 HUD;以真实地表锚点做整标遮挡。普通点仍使用原 Three.js 图层,过渡中的成员只在投影层显示一次,避免双图标。Spiderfy 引线有透明加宽命中区域,悬停联动高亮引线与子点,点击返回同一业务对象;滚轮在图标与引线上继续缩放地球。

跨图层同坐标/极近坐标标记在同一投影层内紧凑堆叠,不以屏幕碰撞合并不同地点;选中项使用投影子点 z-index: 1000,普通未聚合图标的锁定覆盖层使用共享的前景 renderOrder >= 100,因此跨图层重叠时仍由焦点对象在最上层;取消后恢复稳定 ID 顺序。聚合徽标在展开过渡期间保持低于选中子点。icon_presentation_screen 仅供详情引线跟随显示偏移,真实锚点仍由原 marker 持有;隐藏状态变化立即重建对应 GPU 批次。

区域新闻卡片与算力卡片共用 #earth-region-callouts 空间布局根节点(z-index 48),各自数据与阅读状态独立。新闻卡片按大区代表锚点引线,内容轮播不改变锚点;同一布局控制器排除自身所有卡片后测量 HUD 障碍,并统一处理卡片尺寸变化。手机新闻卡片进入抽屉,不绘制地图连线。