cesium-ground-fog-mechanisms.md 3.4 KB
Research: Cesium ground-level view-distance fog mechanisms
Ticket: 04 — Cesium 地面视距雾的机制与限制 Date: 2026-09-18 Scope: decision facts only. No production cockpit code was modified; no build/dev/serve was run (repo rule).
Bottom line
The built-in scene.fog cannot act as a stable view-distance limit at county scale. The engine ships no built-in fog/haze post-process stage. A hand-rolled PostProcessStage depth fog is the only controllable option. The repo's Three.js useThreeGeospatial pipeline is dormant in the cockpit.
1. Built-in fog is on, but structurally unsuitable
services/cesiumEngine.js VIEWER_OPTIONS are widget-chrome flags only, so Scene.fog sits at Cesium defaults: enabled = true, density = 6e-4, heightScalar = 1e-3, heightFalloff = 0.59, maxHeight = 8e5, visualDensityScalar = 0.15.
Fog.update recomputes density per frame from camera height:
density = this.density * heightScalar * (h / maxHeight)^-heightFalloff
density *= 1 - |dot(camera.direction, up)|
Two structural problems:
- Nadir kills it:
1 - |dot(dir, up)|→ 0 when looking straight down, exactly the cockpit's dominant view (home pitch −55° gives a ×0.181 factor). - Radius drifts with height: density is an inverse function of camera altitude, so the same setting cannot hold a stable visibility radius across zoom levels.
Derived 50%-fog distances (4-arg czm_fog, visualDensityScalar = 0.15, nadir): 200 m → ~20 km; 500 m → ~34 km; 1 km → ~51 km; 3 km → ~97 km; 10 km → ~197 km. The cockpit home view (≈9.8 km altitude) sees ~1.3% fog at 50 km — invisible.
2. No built-in fog post-process stage
PostProcessStageLibrary.create*Stage ships 17 factories (blur, depthOfField, edgeDetection, silhouette, bloom, ambientOcclusion, FXAA, 4 tonemapping, autoExposure, blackAndWhite, brightness, nightVision, depthView, lensFlare). None is fog/haze.
But PostProcessStage shaders receive colorTexture and depthTexture uniforms by default, and Context.depthTexture exists at runtime (verified in Build/CesiumUnminified/Cesium.js; it is absent from the bundled Cesium.d.ts). A custom depth-fog stage is feasible: one depth-attached scene target + one full-screen pass + a line of GLSL (czm_readDepth/czm_unpackDepth). Requires WEBGL_depth_texture (fine on WebGL2).
3. showGroundAtmosphere is the wrong scale
Globe.showGroundAtmosphere defaults true (WGS84) but is distance-fenced by lightingFadeIn/FadeOutDistance — high-altitude aerial perspective, tens to hundreds of km. Not a ground-level limit.
4. The Three.js pipeline is dormant
src/plugins/useThreeGeospatial/lib/clouds documents haze / hazeDensityScale = 3e-5 / hazeExponent = 1e-3 and implements CloudsEffect/AerialPerspectiveEffect. But src/modules has zero references to it; it mounts only as a standalone <TresCanvas> page under /plugins/useThreeGeospatial/<page>, not as a layer over the Cesium canvas.
5. Repo has no per-frame camera/height listeners
No camera.changed / preRender / postRender / percentageChanged usage in src/modules/cockpit. The only host-side requestAnimationFrame loop is the intro globe spin (ticket 30). Camera.percentageChanged defaults to 0.5 (coarse); a height-driven fade must lower it or poll scene.preRender.