Files
planet/docs/technical/en/earth-render-layer-order.md
T
rayd1o 45604a1ebb
ci / backend (push) Has been cancelled
ci / frontend (push) Has been cancelled
ci / delivery (push) Has been cancelled
release / images (push) Has been cancelled
release: bump version to 0.76.1
2026-10-01 01:25:24 +08:00

18 KiB
Raw Blame History

Earth Render Layer Order

The compute topic reuses the compute-center Interactable icons, depth behavior, and layer order. Country/year changes replace that layer's data and clear prior selection. Its HUD is screen UI excluded from Earth picking in main.js. Regional cards are tethered in screen space; rear anchors do not draw connectors through the globe. Facility details reuse the existing card and mobile details drawer. The visible HD surface uses a single-draw ShaderMaterial in earth-surface-material.js, retaining the R+0.48 mesh, depth policy and surface pick target. The existing controller still switches all four 8K maps, updates the sampler and disposes the previous texture only after success. Normals, view direction and astronomical sunlight share world coordinates. Land is matte; water has grazing-angle cool reflection without a white specular lobe. The existing geographic land/ocean texture owns the optical mask independently of border visibility, with a conservative chroma fallback until loaded and reflection suppression over ice. Original JPEGs are neither repainted nor downsampled. Color textures are tagged sRGB with mipmaps. The r128 surface shader decodes sRGB; r160 uses hardware texture decoding. Both combine light in linear space and encode once. A local filmic curve affects only the surface instead of enabling global ACES exposure on the sky and data layers. The terminator spans normal dot products [-0.12, 0.28]; night attenuation retains 0.12–0.32 linear illumination after tone mapping to avoid crushing source shadows twice. One R×1.025 BackSide/Additive shell replaces the three rim shells, with depthWrite=false and depthTest=true; inner scattering is part of the surface pass. Independently switchable clouds use matte day/night shading at renderOrder 1.1. The sky uses the existing starmap_deep_8k.jpg without a tint overlay.

This document records the current Earth renderer's layer order and the intent of each layer. When adjusting renderOrder, radius offsets, depth strategy, or pointer interaction, update this document accordingly.

Note: the layer control panel order and the registration / startup load order are two separate semantics.

Order type Current sequence Notes
Control panel order Cables → Satellites → Compute Centers → Vessels → BGP → Terrain → HD Texture → Cloud Layer → Border Lines → Grid Controlled by displayOrder, sorted by operational relevance; satellite trails moved to Settings and are no longer a layer-list item.
Registration / startup load order Grid → Border Lines / Land-Ocean Base → HD Texture → Cloud Layer → Cables → Compute Centers → Vessels → BGP → Satellites Controlled by registration order and startupPriority, sorted surface-to-sky; the startup queue reads persisted layer visibility first, skips normal layers explicitly saved as hidden, and HD Texture does not download the texture when disabled; Border Lines are the exception: the land-ocean base always preloads, while the persisted state only controls interactive border lines and hover; Trails and Terrain are dependency/optional display layers and do not participate in normal startup data loading.

Surface Layer Stack

Order Layer Source Render / Radius Strategy Depth / Interaction Strategy Notes
-1000 Celestial background mesh celestial.js Background sphere Not part of surface picking Behind all Earth content.
0.5 Earth occluder sphere earth.js Invisible inner sphere Writes depth buffer Occludes objects behind the Earth.
0 Earth base sphere earth.js CONFIG.earthRadius Surface picking fallback target Dark base; still visible when all optional map layers are off.
0.2 Country dark tint country-boundaries.js tintAltitudeOffset Raycast disabled Used when HD texture is off.
0.86 Land/ocean base fill country-boundaries.js landAltitudeOffset = 0.32; ocean #010609, land #080f1b Raycast disabled Base map remains usable even when country borders are off; radius is separated from the base sphere to avoid far-zoom z-fighting.
0.96 HD Earth texture earth.js textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48 Surface picking target when visible HD texture always overlays the land/ocean base fill; radius must stay above the land/ocean base and far enough from the base sphere.
1 / 1.1 Atmosphere / clouds earth.js One atmosphere shell at R×1.025; clouds at R+3 Atmosphere uses BackSide, depthWrite=false, depthTest=true; cloud toggle retained Inner scattering shares the surface pass; no fullscreen post-processing.
1 Submarine cables / landing points cables.js, cable-batches.js All cable segments share one LineSegments; all landing points use instanced billboards; render order remains 1; cables and landing-point anchors share the HD surface offset 0.48 and the same triangle-surface coordinates Original Line / Sprite objects retain per-item picking and selection state but no longer draw individually; landing-point sphere occlusion remains, with depthTest: false on the batch Style textures and instance attributes preserve color, pulse, size, visibility, and click behavior.
1.2 Real terrain earth.js, terrain.js TERRAIN_CONFIG.baseRadiusOffset plus terrain displacement Raycast disabled Terrain overlays HD texture; temporarily hidden when HD texture is off, restores to prior state when re-enabled.
2.05 Grid lines earth.js CONFIG.earthRadius + 0.14 Raycast disabled Low-opacity lines over HD texture.
0.97–0.99 Country borders country-boundaries.js lineAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48; claim lines have no extra lift Raycast disabled Line geometry still has its own renderOrder, but it shares the exact same radius as the HD texture shell to avoid parallax while the globe rotates.
0.98 Country border hover glow country-boundaries.js Same surface mapping, no extra lift depthTest: true, transparent render queue, raycast disabled Additive glow to reinforce border edge and terrain hover visibility.
0.99 Country border hover line country-boundaries.js hoverAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48 depthTest: true, transparent render queue, raycast disabled Neon red-orange hover line; aligned with the normal borders and HD texture shell to avoid ghosting or floating; China and Taiwan share the same highlight group.
3 Satellite footprint fill / Iridium coverage ring satellites.js, iridium-footprint-adapter.js GROUND_FOOTPRINT_RENDER_ORDER depth-tested; Iridium adapter fill / ring use the same renderOrder Footprint above land / texture / terrain and country borders, below compute centers and satellites.
3-4.5 BGP collectors, event rings, and event markers bgp.js, interactable.js Collector markers use BGP_COLLECTOR_RENDER_ORDER = 4.4; event markers use BGP_EVENT_RENDER_ORDER = 4.5; overlays remain in BGP-owned groups Screen-space Interactable picking; BGP collectors/events may use collision avoidance where appropriate BGP collectors share the surface-facility band with vessels; BGP events share the compute-center band.
4.3 AIS vessel track lines vessels.js VESSEL_RENDER_ORDER - 0.1; CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset Follows vessel selection, not independently picked Recent track for the selected vessel, below vessel markers.
4.4 AIS vessel markers vessels.js, interactable.js VESSEL_RENDER_ORDER; business radius CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset; normal markers are bucketed THREE.Points, hover / locked states are single-point overlays depthTest: true; main.js uses screen-space picking for front-facing markers; cluster: false and avoidance: false Moving vessels use triangular point textures, anchored / slow vessels use dots. Dense waterways may overlap and do not participate in dynamic screen clustering, avoiding Points rebuilds during rotation.
4.5 Compute centers compute-centers.js, interactable.js COMPUTE_CENTER_RENDER_ORDER Screen-space Interactable picking, with surface-icon collision handling Surface facilities, below satellites.
6 Satellite dots satellites.js SGP4 altitude compressed to R+4..25; fallback R+8 Screen-space satellite picking Satellite dots above footprints and compute centers.
12+ Satellite locked ring, halo, predicted orbit satellites.js SATELLITE_CONFIG.overlayRenderOrder and offsets; predicted orbit follows the same real-altitude toggle and fixes the lock-time globe pose to draw an open full-period inertial curve with forward-flow highlights; returns to same-sphere mode when real altitude is disabled Satellite overlay path Used for selected/locked satellite emphasis.
98-100 Sun / moon halo and sprite celestial.js Fixed renderOrder Celestial picking disabled Foreground celestial sprites.

Full-set rendering and updates

  • Batching changes GPU submission, not the number of satellites, cable segments, or landing points. It does not filter data by the visible hemisphere. Every adjacent cable vertex pair remains present, and picking still returns the original business object.
  • Normal satellites use one hard-disc Points batch without a backdrop batch. Optional breathing remains in the vertex shader, defaulting off; category filters and hover/locked masking share the same visibility state.
  • satellite-position-worker.js uses the same Three.js / SGP4 versions as the main thread. satellite-propagation.js owns shared orbit, display-altitude, and fallback calculations. Full positions and initial trail samples use transferable arrays; only one calculation is in flight. Reload, clear, and altitude-mode changes terminate the previous Worker.
  • Worker startup failure or SATELLITE_CONFIG.workerStartupTimeoutMs expiry falls back to the shared synchronous calculation. Counts, APIs, the existing update interval, and trail length are unchanged.
  • Verify full draw ranges, per-item picking, locked overlays, trails, rear-side occlusion, visibility toggles, and resource release after clearing. Frame-time comparisons require identical data, view, and resolution.

Toggle Behavior

Toggle Behavior
HD texture off Hides HD texture, enables country tint / base surface, disables terrain and day/night toggle interaction, and remembers terrain and day/night previous states.
HD texture on Restores HD texture and the remembered terrain / day/night states.
Terrain on Displayed above HD texture, but below country border hover, footprints, satellites, and other emphasis layers.
Cloud layer Only controls cloud mesh visibility.
Border Lines off Hides only interactive border lines and hover, clearing hover state; the land/ocean base fill remains as the Earth base map.
Real Satellite Altitude off Satellite dots, trails, and predicted orbits use the legacy same-sphere height; satellites with missing TLE data or failed propagation also use this fallback height.

Depth Spacing Rules

The Earth surface is not a single mesh. It is a stack of near-concentric shells: base sphere, land/ocean base, HD texture, terrain, clouds, atmosphere, and the occluder. Radius offsets that look harmless at close zoom can collapse into the same depth-buffer pixels at zoomed-out views such as 50%, causing z-fighting that appears as black blocks, snow, or flicker.

Maintenance rules:

  • Do not reach first for hiding layers at far zoom. Check neighboring shell altitudeOffset, renderOrder, depthTest, and depthWrite first.
  • Whole-globe overlays such as the land/ocean base and HD texture must keep explicit separation from CONFIG.earthRadius; the current stable values are landAltitudeOffset = 0.32 and textureOverlayAltitudeOffset = EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET = 0.48.
  • Country borders, coastlines, claim lines, and country hover lines must use EARTH_SURFACE_TEXTURE_ALTITUDE_OFFSET, exactly matching the HD texture shell. Do not give border lines an independent lower or higher offset, because globe rotation will make the lines appear to drift relative to the surface texture.
  • Any new whole-globe or near-whole-globe surface overlay must be screenshot-verified at 50% zoom and at common close zooms, with no black blocks, snow, flicker, or obvious floating.
  • If these radii change, update this document and the intent around the constants in frontend/public/earth/js/constants.js.

Interaction Rules

Interaction Current Rule
Earth coordinate hover When HD texture is visible, uses the HD texture overlay as the surface picking target; otherwise uses the Earth base sphere.
Country border hover Converts surface pick coordinates to lat/lon, then uses GeoJSON point-in-polygon; the border hover line itself does not receive raycasts.
Country border hover visual On hover, dims normal border lines and draws depth-tested glow and solid lines below landing points.
China / Taiwan hover CHN and TWN are grouped in the same hover highlight group; the tooltip still shows the actually-hit feature.
Terrain Acts as a visual layer only; terrain.raycast is disabled.
Satellites Uses screen-space satellite picking to prevent footprints or surface layers from blocking satellite clicks.

Surface attachment and landing point order

earth-surface.js projects geographic vertices onto the high-resolution SphereGeometry UV triangles at geometry construction time. Boundaries, coastlines, claim lines, hover outlines and landing points share this surface mapping. Long edges are subdivided using the surface grid spacing. Landing-point anchors now use the texture shell offset of 0.48; cable line offsets remain 0.2. The draw order is texture 0.96, boundaries/highlights 0.97–0.99, then landing points 1. Hover outlines always use the transparent queue with depth testing, so they do not draw through the globe or over landing markers. Geography is unchanged, and cached geometry is not rebuilt during rotation.

Startup loading versus drawing order

The selected full-resolution surface loads before independent data requests; boundary construction no longer blocks its first frame. This does not change renderOrder, depth behavior, geometry precision or image resolution. Data refresh retains the surface, with texture disposal limited to successful replacement or scene teardown.

Loading-state boundary diamond regression

v0.58.0 moved land fill to R+0.32 and HD imagery to R+0.48, but left the tint placeholder at R+0.04 with a 64×32 mesh. Its chords intersected the 128×128 base, producing latitude-ring diamonds until loaded imagery covered them. The old geometry penetrated the base by approximately 0.153 at tested samples.

Base, tint, land fill and HD surface now use createEarthSurfaceGeometry() and one UV triangulation. Tint and land share R+0.32; neither writes depth, so their existing renderOrder lets loaded fill replace the tint. HD remains R+0.48. Occluder, terrain, clouds, picking and geographic display policy are unchanged. Do not mask intersecting geometry by changing renderOrder alone, disabling depth tests or hiding the loading globe.

earth-surface.test.js ray-tests the actual loading tint and verifies at least two 24-bit depth steps of separation at 50%, 100% and 500%. Browser checks cover delayed textures, boundary toggles, rotation/zoom, and land/HD completion.

Surface marker alignment and limb visibility

Cables and landing points share R+0.48, the earthSurfacePoint triangle projection and renderOrder=1. Related landing halos use an emphasis attribute in the existing batch, adding no Sprite or draw call. Rounded badges use GPU anchor ray/sphere occlusion: draw the entire billboard when its anchor is visible, otherwise clip it entirely. CPU picking uses the same test to reject rear anchors. Only icon.badge layers (including compute and collectors; vessels independently use heading arrows) use this path. The selected BGP event's static overlay halo uses the event icon's R+0.48 anchor, foreground order and whole-anchor front/rear visibility; the existing animated BGP event ring remains a separate effect with its original behavior.

The .map-clusters projection layer uses z-index 8 below HUD and whole-marker occlusion from real surface anchors. Ordinary points retain their Three.js layers; transitioning members render only once in the projection layer. Spider legs use widened transparent hit areas; hover highlights the matching line and child, and both clicks resolve the same business object. Wheel input over projected markers and legs continues to zoom the globe.

Co-located markers share a compact projection stack across categories; screen collisions never merge different locations. A selected child uses projection z-index: 1000, while the locked overlay for an unclustered marker uses the shared foreground renderOrder >= 100, so focus stays on top across layers; clearing focus restores stable ID order. The aggregate badge stays below a selected child during its opening tween. icon_presentation_screen lets detail connectors follow display offsets while markers retain their real anchors. Ownership changes immediately rebuild the corresponding GPU batch.

Regional news and compute cards share the #earth-region-callouts spatial root (z-index 48), with independent data and reading state. News connectors use representative regional anchors, unchanged by story rotation. One controller excludes all owned cards when measuring HUD obstacles and tracks size changes by element. Mobile news cards live in the drawer without map connectors.