From 09ea182f86f435e28c2492e3d5e9849a5d78e024 Mon Sep 17 00:00:00 2001
From: Protonmatter <102541048+Protonmatter@users.noreply.github.com>
Date: Wed, 23 Sep 2026 23:56:25 +0000
Subject: [PATCH 1/2] Add optional Enhanced Earth oceans, clouds and shadows
---
README.md | 10 ++
apps/web/index.html | 4 +
apps/web/js/atmosphereColumnField.js | 10 +-
apps/web/js/atmosphereColumnManifest.js | 4 +-
apps/web/js/earthOceanMask.js | 6 +
apps/web/js/enhancedEarth.js | 68 +++++++
apps/web/js/orrery.js | 72 +++++++-
apps/web/js/orreryShaders.js | 35 +++-
apps/web/js/planetAppearance.js | 12 +-
docs/IMPLEMENTATION_PLAN.md | 13 +-
docs/REQUIREMENTS.md | 1 +
docs/SPEC.md | 13 ++
docs/STATUS.md | 10 +-
docs/requirements.json | 23 +++
docs/rfcs/0008-enhanced-earth.md | 107 +++++++++++
docs/validation/enhanced-earth/README.md | 92 ++++++++++
docs/validation/enhanced-earth/comparison.jpg | Bin 0 -> 238889 bytes
docs/validation/enhanced-earth/gl-probe.json | 29 +++
tests/python/test_earth_ocean_mask.py | 24 +++
tests/python/test_release_artifact.py | 1 +
tests/web/enhancedEarth.test.mjs | 166 ++++++++++++++++++
tests/web/helpers/orreryHarness.mjs | 1 +
tests/web/illustrativeHaze.test.mjs | 2 +-
tools/build_web.py | 2 +-
tools/enhanced_earth_probe.mjs | 14 ++
tools/prepare_earth_ocean_mask.py | 116 ++++++++++++
tools/render_enhanced_earth_probe.py | 126 +++++++++++++
27 files changed, 944 insertions(+), 17 deletions(-)
create mode 100644 apps/web/js/earthOceanMask.js
create mode 100644 apps/web/js/enhancedEarth.js
create mode 100644 docs/rfcs/0008-enhanced-earth.md
create mode 100644 docs/validation/enhanced-earth/README.md
create mode 100644 docs/validation/enhanced-earth/comparison.jpg
create mode 100644 docs/validation/enhanced-earth/gl-probe.json
create mode 100644 tests/python/test_earth_ocean_mask.py
create mode 100644 tests/web/enhancedEarth.test.mjs
create mode 100644 tools/enhanced_earth_probe.mjs
create mode 100644 tools/prepare_earth_ocean_mask.py
create mode 100644 tools/render_enhanced_earth_probe.py
diff --git a/README.md b/README.md
index fd37277d..2a549de9 100644
--- a/README.md
+++ b/README.md
@@ -113,3 +113,13 @@ Sol is not for navigation, occultation prediction, mission safety or operational
space-weather warnings. `space_weather_operational` remains false. Project code is
MIT OR Apache-2.0; third-party data attribution and outstanding coefficient notice
correspondence are documented separately and are not resolved by that project license.
+
+### Optional Enhanced Earth
+
+Solar System → View controls → Earth layers → **Enhanced Earth** adds darker
+offshore oceans and an elevated historical NASA cloud layer with Sun-directed
+shadows. Clouds drift independently during Play time and freeze when paused.
+The option is off by default; cloud height, motion and lighting are illustrative.
+MODIS swaths and the scientific sea-ice palette suspend the enhancement.
+See [RFC 0008](docs/rfcs/0008-enhanced-earth.md) and the
+[validation record](docs/validation/enhanced-earth/README.md).
diff --git a/apps/web/index.html b/apps/web/index.html
index 5f757864..bd797410 100644
--- a/apps/web/index.html
+++ b/apps/web/index.html
@@ -25,6 +25,8 @@
+
+
@@ -455,6 +457,8 @@
Tools
Earth layers
+
+
Deeper oceans and raised clouds with Sun-aligned shadows. Clouds drift independently during Play time. Color, nominal 8 km cloud height and motion are illustrative; the NASA imagery keeps its historical date. Uses the Blue Marble cloud layer; suspended for MODIS swaths and the sea-ice analysis palette.
diff --git a/apps/web/js/atmosphereColumnField.js b/apps/web/js/atmosphereColumnField.js
index f957c67a..7925e9fa 100644
--- a/apps/web/js/atmosphereColumnField.js
+++ b/apps/web/js/atmosphereColumnField.js
@@ -213,16 +213,16 @@ vec3 atmosphereCombinedTail(float impact,float x){
// Rationalize altitude before lookup: subtracting a rounded body-sized radius
// quantizes a short interval's height increment and corrupts its column mass.
float radius=length(vec2(impact,x)),height=((impact-u_atmosphereRadiusKm)*(impact+u_atmosphereRadiusKm)+x*x)/(radius+u_atmosphereRadiusKm);
- vec3 packed;
+ vec3 columnValues;
if(height<0.0){
float ground=sqrt(max(0.0,u_atmosphereRadiusKm*u_atmosphereRadiusKm-impact*impact));
float below=max(0.0,ground-x);
- packed=atmosphereOutwardPacked(0.0,ground/u_atmosphereRadiusKm)+vec3(below,below,below*atmosphereOzoneDensity(0.0));
- }else packed=atmosphereOutwardPacked(height,x/max(radius,1e-9));
+ columnValues=atmosphereOutwardPacked(0.0,ground/u_atmosphereRadiusKm)+vec3(below,below,below*atmosphereOzoneDensity(0.0));
+ }else columnValues=atmosphereOutwardPacked(height,x/max(radius,1e-9));
// A uniform scale, not a literal zero, keeps the admitted sampler from being
// constant-folded out of the generator. The runtime value stays 0.
- packed.xy+=texelFetch(u_atmosphereColumnField,ivec2(0),0).rg*u_atmosphereColumnKeep;
- return packed;
+ columnValues.xy+=texelFetch(u_atmosphereColumnField,ivec2(0),0).rg*u_atmosphereColumnKeep;
+ return columnValues;
}
vec2 atmosphereOutwardColumns(float height,float mu){return atmosphereOutwardPacked(height,mu).rg;}
float atmosphereOzoneOutward(float height,float mu){return atmosphereOutwardPacked(height,mu).b;}
diff --git a/apps/web/js/atmosphereColumnManifest.js b/apps/web/js/atmosphereColumnManifest.js
index 12d8bcce..ee7e6dde 100644
--- a/apps/web/js/atmosphereColumnManifest.js
+++ b/apps/web/js/atmosphereColumnManifest.js
@@ -13,7 +13,7 @@ export const ATMOSPHERE_COLUMN_FIELDS=Object.freeze({
"profile_encoding": "atmosphere-profile-binary32-v1",
"profile_sha256": "e15e53579417f828a4f02b401d2c9ddebd78c6f956f5177d1def336ac7d7bed8",
"generator_source_sha256": "6c7c90d4a4b72fc4d9c38bdb191889780e2f3a2cf44375cfe00f87c82c2fb48c",
- "field_source_sha256": "26f9171d8db660af0bbe46b7631ec89b86895e143a181aaa13c2d6afce2115f1",
+ "field_source_sha256": "7da48dcd0061e244de4365de8e8ba1acbce7d27a79a42cbebcda6784ae05ed44",
"solver_source_sha256": "282d74036c31b418ca8e1e43f9fdb4f975cf3ec03e3217da801d54ec945aa635",
"profile_source_sha256": "b8ad270b14c4ef16affc7c31bd7fb5111895bc9cc6332cbe7c8c171d4582b965"
},
@@ -30,7 +30,7 @@ export const ATMOSPHERE_COLUMN_FIELDS=Object.freeze({
"profile_encoding": "atmosphere-profile-binary32-v1",
"profile_sha256": "28e25e74130b1a426f07004ebdc66ca6c8f1094433f305302dab4c7338b15d7e",
"generator_source_sha256": "6c7c90d4a4b72fc4d9c38bdb191889780e2f3a2cf44375cfe00f87c82c2fb48c",
- "field_source_sha256": "26f9171d8db660af0bbe46b7631ec89b86895e143a181aaa13c2d6afce2115f1",
+ "field_source_sha256": "7da48dcd0061e244de4365de8e8ba1acbce7d27a79a42cbebcda6784ae05ed44",
"solver_source_sha256": "282d74036c31b418ca8e1e43f9fdb4f975cf3ec03e3217da801d54ec945aa635",
"profile_source_sha256": "b8ad270b14c4ef16affc7c31bd7fb5111895bc9cc6332cbe7c8c171d4582b965"
}
diff --git a/apps/web/js/earthOceanMask.js b/apps/web/js/earthOceanMask.js
new file mode 100644
index 00000000..bc7d25fb
--- /dev/null
+++ b/apps/web/js/earthOceanMask.js
@@ -0,0 +1,6 @@
+// GENERATED by tools/prepare_earth_ocean_mask.py. Public-domain Natural Earth.
+// Conservative offshore display mask, not a qualified coastline or reflectance map.
+export const OCEAN_MASK_WIDTH=512,OCEAN_MASK_HEIGHT=256;
+export const OCEAN_MASK_SOURCES={"ne_110m_land.geojson":"9e0729ee253ca7d7a5c4ae9395fb1902264c5377c52e224d13dd85010e2835d9","ne_110m_glaciated_areas.geojson":"e61e3f45e22f087f861ac2fda6258fc15c849a216d74c27ccf0164eeafbd950a"};
+export const OCEAN_MASK_SHA256='0644b40d075dc4da2ed10928a6dbc40f2924ceaff9a300948b2f2c8781ca2bdf';
+export const OCEAN_MASK_RUNS=[0,3782,24,422,38,17,41,408,104,404,120,150,5,234,123,42,11,28,9,55,13,231,123,31,25,25,9,55,15,216,7,6,123,30,26,25,9,55,20,211,136,30,26,25,9,55,23,197,8,3,131,35,26,25,9,55,23,186,19,3,128,38,26,90,24,182,152,38,22,50,13,34,30,173,152,40,20,44,19,27,38,29,15,128,67,5,80,43,8,1,8,41,22,22,43,29,23,117,70,6,79,44,6,50,23,22,43,29,23,117,71,7,75,101,24,14,58,2,10,10,23,116,72,22,60,99,20,3,13,4,72,8,23,115,76,21,57,99,16,8,89,9,22,40,5,70,81,17,55,100,13,9,123,36,8,21,15,34,84,15,54,60,13,27,11,10,136,24,8,18,32,12,95,13,52,55,19,27,11,10,136,11,7,6,8,16,142,12,52,53,27,21,11,1,177,12,146,13,51,50,35,16,191,10,149,10,51,48,40,2,7,1,196,8,150,9,49,49,42,1,210,2,125,2,26,7,45,9,6,36,381,2,26,7,42,1,17,34,383,1,27,7,35,8,18,32,384,1,27,7,33,10,18,31,413,8,30,12,18,29,414,9,26,16,18,26,250,2,12,1,149,14,21,21,16,24,251,6,9,2,148,14,20,23,14,24,252,10,5,2,111,1,36,15,19,26,6,29,252,15,113,6,31,16,16,63,251,16,110,9,32,16,14,64,248,19,109,18,25,16,13,64,244,23,110,17,26,19,9,49,7,8,241,26,31,2,78,16,27,20,6,50,9,6,240,35,20,11,77,11,27,76,9,7,228,46,17,16,77,9,29,74,9,7,20,2,175,16,15,44,19,22,77,3,30,73,10,10,16,2,174,17,15,44,19,23,113,65,15,9,190,19,15,44,12,31,112,63,18,8,192,17,15,44,10,33,114,61,19,2,201,13,13,46,6,37,114,61,222,13,13,89,114,61,222,13,12,90,114,61,222,14,10,92,113,61,223,13,9,93,5,1,107,61,223,13,7,101,110,64,217,13,6,102,111,63,217,121,111,63,217,123,95,1,13,65,215,124,108,65,214,127,106,65,214,127,96,2,8,67,212,127,96,4,6,68,214,124,96,68,224,124,94,70,224,124,91,73,58,2,151,1,12,124,89,75,210,2,12,124,82,82,208,4,12,124,82,82,21,4,178,9,9,127,82,82,21,4,177,10,7,129,77,87,19,6,6,1,169,10,8,129,76,88,18,7,176,9,9,130,75,88,17,4,180,6,12,130,74,89,41,1,159,6,12,131,72,90,40,3,158,1,16,133,70,91,39,4,7,2,139,2,24,134,70,91,33,1,5,5,6,2,139,2,24,135,69,92,32,22,134,4,24,136,68,91,37,6,6,10,130,4,24,136,67,92,39,2,10,8,131,3,22,141,62,93,41,1,149,7,14,147,59,94,191,7,10,151,57,96,192,7,6,155,55,96,193,7,6,155,55,95,194,7,5,157,55,92,196,169,42,1,12,91,197,170,33,2,5,6,8,90,197,171,31,15,8,89,198,171,30,16,8,89,198,172,29,17,11,84,199,175,26,17,11,83,200,175,26,15,13,83,200,175,25,15,14,82,113,6,82,110,5,62,23,9,21,81,113,7,81,110,7,61,23,5,25,80,113,8,80,110,8,60,5,1,18,4,27,78,113,9,71,2,5,111,8,67,17,4,34,71,113,9,67,122,8,67,30,8,19,69,112,11,29,3,31,127,6,67,30,9,18,69,111,16,25,3,31,9,7,112,5,67,30,9,18,70,109,18,23,5,30,9,7,112,5,68,29,9,18,69,110,18,21,8,28,10,7,186,32,5,18,69,109,19,20,10,27,10,7,189,31,3,7,2,5,73,108,20,19,11,25,12,7,190,30,90,107,21,17,13,25,12,7,193,27,90,103,25,17,13,25,12,9,194,24,90,102,27,13,17,24,12,10,199,18,12,5,73,100,29,13,21,20,12,11,199,17,10,9,71,101,29,12,21,20,13,11,201,13,8,14,69,101,29,12,21,20,13,11,204,11,7,24,59,101,29,12,22,19,10,14,205,41,59,101,30,12,21,19,9,15,206,41,59,100,30,12,21,19,9,16,206,42,59,98,31,12,20,18,10,16,206,43,58,97,32,12,20,7,2,7,12,16,208,42,59,95,33,11,20,15,11,7,1,10,209,45,55,95,33,11,20,14,11,6,3,10,212,45,52,94,35,10,16,15,13,9,1,10,213,45,52,93,38,7,16,15,11,11,1,10,218,41,53,90,40,6,16,15,11,11,3,8,218,42,53,21,1,67,62,15,10,12,4,6,217,44,54,17,4,66,63,16,6,15,227,45,55,6,14,64,64,16,4,17,8,5,213,46,80,58,66,15,3,32,211,47,80,58,67,14,3,32,211,49,78,57,69,13,3,32,210,53,75,55,72,12,3,40,202,55,73,54,74,12,2,46,196,58,70,52,76,13,1,48,194,63,65,52,77,37,1,27,190,65,63,51,79,12,1,23,1,30,186,67,62,50,80,12,2,22,1,31,5,6,174,70,60,48,82,11,2,22,1,32,1,9,174,70,61,46,84,12,2,20,1,45,171,70,62,45,85,22,2,9,10,37,170,71,61,44,87,18,5,9,12,35,171,70,62,43,88,20,2,9,12,40,166,70,62,43,90,34,7,28,1,11,167,69,63,42,90,34,12,20,5,13,165,68,63,43,91,32,12,22,8,8,165,67,65,43,95,27,12,22,8,8,166,66,65,43,104,18,5,5,6,18,9,7,166,65,66,43,108,12,4,13,3,6,1,9,9,7,167,64,65,44,7,6,96,10,4,14,2,7,3,7,183,63,66,44,7,6,110,14,2,7,194,61,66,45,6,7,104,20,2,9,192,60,67,45,5,9,102,21,2,10,26,5,161,58,68,45,3,11,101,22,2,10,26,5,16,2,143,58,68,45,1,13,100,24,1,10,26,6,11,6,144,57,68,45,1,13,98,38,25,6,11,6,145,56,68,45,1,13,98,38,25,6,9,8,146,55,68,44,2,13,97,39,26,5,9,8,148,52,69,43,3,12,97,41,25,5,9,6,152,50,69,41,5,11,95,46,37,6,153,49,69,40,6,11,92,50,18,5,13,6,154,48,69,39,6,12,90,52,18,6,172,48,70,37,7,12,89,54,17,8,170,47,71,37,7,11,89,56,16,8,170,46,73,36,7,11,89,57,15,8,170,46,73,36,7,11,88,59,15,7,170,45,75,35,7,10,89,60,15,6,169,45,76,35,7,10,89,61,189,41,80,34,8,10,89,61,189,39,83,33,8,9,90,61,189,37,85,31,11,8,90,61,189,36,86,30,110,61,188,37,86,30,110,61,188,37,87,29,111,60,188,37,87,28,112,60,188,37,88,27,113,59,188,36,90,25,114,59,188,35,91,24,116,58,188,34,93,22,117,58,188,33,95,21,117,58,187,33,96,19,119,22,2,33,25,5,158,32,97,18,120,18,9,30,25,6,156,33,97,16,122,16,12,28,26,6,156,32,98,9,129,10,18,27,27,8,153,31,239,7,23,24,27,8,153,28,274,21,28,12,149,28,276,19,29,11,149,28,276,18,31,10,149,27,277,18,31,10,149,26,281,13,30,13,149,21,290,9,29,13,149,22,290,9,28,13,150,21,291,9,27,13,151,20,292,9,25,14,152,20,292,9,23,14,154,20,293,7,23,14,154,19,295,6,24,13,155,18,326,12,156,18,326,11,157,18,326,10,157,19,187,5,134,9,158,19,187,6,300,19,187,6,300,18,188,6,300,16,5,9,176,6,301,15,5,9,176,6,301,14,6,9,483,15,5,9,483,17,3,9,484,17,495,17,496,16,498,14,501,11,4101,6,502,10,499,13,498,14,224,5,41,5,220,17,151,12,40,5,14,10,4,10,18,12,218,14,151,18,34,18,1,72,204,11,150,34,16,97,204,11,133,5,7,43,9,105,193,16,133,56,8,115,184,17,109,8,11,60,2,126,179,18,91,96,1,131,171,23,68,261,121,12,26,24,66,264,118,14,6,5,15,24,64,266,84,6,1,5,22,30,2,33,59,270,84,6,1,17,10,65,59,270,68,46,4,65,58,271,57,126,54,274,58,126,46,281,55,129,41,284,45,138,41,285,41,143,19,11,8,292,39,137,24,13,7,292,39,131,14,5,9,15,7,292,39,133,5,13,4,19,7,292,39,151,4,19,5,294,40,8,1,141,4,314,53,142,1,317,52,466,23,8,15,471,9,23,12,5085];
diff --git a/apps/web/js/enhancedEarth.js b/apps/web/js/enhancedEarth.js
new file mode 100644
index 00000000..7b594159
--- /dev/null
+++ b/apps/web/js/enhancedEarth.js
@@ -0,0 +1,68 @@
+// Illustrative presentation only. Source images, epochs and ephemerides are immutable.
+import {OCEAN_MASK_WIDTH,OCEAN_MASK_HEIGHT,OCEAN_MASK_RUNS} from './earthOceanMask.js';
+import {rotationDisplayStepSeconds} from './orreryTime.js';
+
+export const EARTH_CLOUD_HEIGHT_KM=8;
+export const ENHANCED_EARTH_UNIFORMS=['u_earthEnhanced','u_earthCloudShadow','u_cloudPhase','u_cloudScale','u_oceanMask'];
+
+export function enhancedEarthSelected(state){
+ return state.earthEnhanced===true&&state.useTextures!==false&&state.earthCloudSource!=='daily'&&state.earthIce!==true&&!state.galaxy;
+}
+
+export function advanceEarthCloudPhase(phase,realSeconds,simulatedSeconds,rotationHours,enabled){
+ if(!enabled||!Number.isFinite(realSeconds)||realSeconds<=0)return phase;
+ const seconds=rotationDisplayStepSeconds(realSeconds,simulatedSeconds,rotationHours);
+ if(seconds===0)return phase;
+ const drift=seconds/(Math.abs(rotationHours)*3600)*.03;
+ if(!Number.isFinite(drift))return phase;
+ const step=Math.sign(drift)*Math.min(Math.abs(drift),.002*realSeconds);
+ return ((phase+step)%1+1)%1;
+}
+
+export function oceanMaskPixels(){
+ const pixels=new Uint8Array(OCEAN_MASK_WIDTH*OCEAN_MASK_HEIGHT);
+ let offset=0,value=0;
+ for(const run of OCEAN_MASK_RUNS){pixels.fill(value,offset,offset+run);offset+=run;value=255-value;}
+ return pixels;
+}
+
+export function uploadOceanMask(gl){
+ const texture=gl.createTexture();
+ if(!texture)throw new Error('Ocean mask allocation failed');
+ try{
+ gl.activeTexture(gl.TEXTURE0+11);gl.bindTexture(gl.TEXTURE_2D,texture);
+ gl.texImage2D(gl.TEXTURE_2D,0,gl.R8,OCEAN_MASK_WIDTH,OCEAN_MASK_HEIGHT,0,gl.RED,gl.UNSIGNED_BYTE,oceanMaskPixels());
+ gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_MIN_FILTER,gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_MAG_FILTER,gl.LINEAR);
+ gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_WRAP_S,gl.REPEAT);
+ gl.texParameteri(gl.TEXTURE_2D,gl.TEXTURE_WRAP_T,gl.CLAMP_TO_EDGE);
+ if(gl.getError()!==gl.NO_ERROR)throw new Error('Ocean mask upload failed');
+ return texture;
+ }catch(error){gl.deleteTexture(texture);throw error;}
+ finally{gl.activeTexture(gl.TEXTURE0);}
+}
+
+// Input p is on the unit sphere before oblate scaling. Return a point on the
+// homothetic cloud ellipsoid in those same unflattened coordinates. The rational
+// root avoids subtractive cancellation for a thin shell and an overhead Sun.
+export const EARTH_CLOUD_GEOMETRY_GLSL=`
+vec3 earthCloudHit(vec3 p,vec3 light,float oblate,float shell){
+ vec3 d=vec3(light.xy,light.z/oblate);
+ float a=dot(d,d),b=dot(p,d),c=dot(p,p)-shell*shell;
+ float root=sqrt(max(0.0,b*b-a*c));
+ float t=b>=0.0 ? -c/max(root+b,1e-12) : (root-b)/max(a,1e-12);
+ return p+d*t;
+}
+`;
+
+// The mask excludes coarse land/ice/coastal margins. Dark-blue gating additionally
+// protects bright ice, land-like colors and islands omitted by the coarse vectors.
+export const EARTH_OCEAN_GLSL=`
+vec3 enhancedOceanColor(vec3 c,float ocean){
+ float blue=max(0.0,c.z-max(c.x,c.y));
+ float bright=max(c.x,max(c.y,c.z));
+ float weight=ocean*min(1.0,blue/.03)*min(1.0,max(0.0,(.25-bright)/.1));
+ float luminance=dot(c,vec3(.2126,.7152,.0722));
+ return c*(1.0-weight)+(c*.8+vec3(luminance)*.2)*.55*weight;
+}
+`;
diff --git a/apps/web/js/orrery.js b/apps/web/js/orrery.js
index a6756a61..62cafed7 100644
--- a/apps/web/js/orrery.js
+++ b/apps/web/js/orrery.js
@@ -17,6 +17,7 @@
import { store } from "./store.js?v=dcca6290db";
import { createShaderPrograms } from "./shaderPrograms.js";
import { linearFilterReference } from './materialColor.js';
+import {EARTH_CLOUD_HEIGHT_KM,ENHANCED_EARTH_UNIFORMS,enhancedEarthSelected,advanceEarthCloudPhase,uploadOceanMask} from './enhancedEarth.js';
import { createHdrPresentation } from './hdrPresentation.js';
import { srgbToLinear } from './surfaceMapping.js';
import { appearanceReference, appearanceReferences, appearanceUniforms, appearanceFallbackColor, earthLayerDescription, earthCloudRole, surfaceReferenceShown } from "./planetAppearance.js";
@@ -160,6 +161,7 @@ const state = (store.orrery = {
galSpeed: 2, // galaxy-view rate (millions of years per real second), decoupled from the planetary rate
showOrbits: true, showSky: true, showConst: false, showLabels: true, showSunEq: false, useTextures: true, galaxy: false,
earthNight: true, earthWeather: true, earthIce: false, earthCloudSource: 'composite', venusRadar: false,
+ earthEnhanced:false, earthCloudPhase:0, earthMaskStatus:'deferred',
appearanceStatus: {},
terrainEnabled:true, opticsEnabled:true, terrainStatus:{}, terrainRendered:{}, opticsStatus:{}, scatteringStatus:{}, scatteringFrame:null,
programStatus:{base:'deferred',physical:'deferred'},programDiagnostics:{},
@@ -194,6 +196,7 @@ const DRAW_LIST = ["Sun", ...PLANET_ORDER, "Moon"];
// live in orreryMath.js; GLSL sources in orreryShaders.js — both imported above.)
// ---------------------------------------------------------------- WebGL2 renderer
+let earthOceanMask=null;
let gl, P = {}, sphere, quadBuf, cel, celBufs = {}, particles = null;
let shaderPrograms=null,programContextGeneration=0;
let hdrPresentation=null,hdrFailure=null,contextGeneration=0,sceneSerial=0,linearFrame=false,graphicsLifecycle=0;
@@ -864,7 +867,7 @@ function finishGL(){
P.glowU = uloc(P.glow, ["u_vp", "u_center", "u_right", "u_up", "u_size", "u_color", "u_pow"]);
Object.assign(P.sphereU,uloc(P.sphere,[...ATMOSPHERE_UNIFORMS,...INCIDENT_FIELD_UNIFORMS,'u_atmosphereColumnField','u_atmosphereOzoneField','u_bodyRadiusKm','u_terrainHeight','u_terrainShadowEnabled','u_terrainShape','u_terrainPoles']));
P.solarU=uloc(P.solar,['u_mvp','u_camObj','u_pass','u_extent','u_atlas','u_quiet','u_frameMix','u_phase','u_displayGain','u_coronaGlow','u_cmeProgress','u_cmeAxis','u_sourceBasis0','u_sourceBasis1','u_projection0','u_projection1','u_observerRadii','u_loopNormal[0]','u_loopTangent[0]','u_loopGain[0]']);
- Object.assign(P.sphereU,uloc(P.sphere,['u_textureLinear']));
+ Object.assign(P.sphereU,uloc(P.sphere,['u_textureLinear',...ENHANCED_EARTH_UNIFORMS]));
for(const name of ['sphere','line','ring','pt','glow','solar'])
Object.assign(P[`${name}U`],uloc(P[name],['u_linearOutput']));
@@ -1933,6 +1936,55 @@ function updateEarthLayerStatus() {
if (caption) caption.textContent = `${ice?.label || 'Sea ice unavailable'} · ${ice?.observation_label || 'Date unavailable'}. Transparent areas have no displayed data.`;
}
+function prepareEarthEnhancement(body,referenceReady) {
+ const selected=body==='Earth'&&referenceReady&&enhancedEarthSelected(state);
+ if(selected&&!earthOceanMask&&state.earthMaskStatus!=='unavailable'){
+ try{earthOceanMask=uploadOceanMask(gl);state.earthMaskStatus='ready';}
+ catch(error){state.earthMaskStatus='unavailable';console.warn('Enhanced Earth:',error.message);}
+ updateEarthLayerStatus();
+ }
+ const asset=appearanceReference('Earth','cloud-composite');
+ const clouds=selected&&state.earthWeather&&referenceTextures[asset.id]?.ready ? referenceTextures[asset.id] : null;
+ return {selected,clouds,phase:state.earthCloudPhase,scale:1+EARTH_CLOUD_HEIGHT_KM/BODY.Earth.radiusKm};
+}
+
+function bindEarthEnhancement(enhancement,locations) {
+ gl.uniform1i(locations.u_earthEnhanced,enhancement.selected&&earthOceanMask?1:0);
+ gl.uniform1i(locations.u_earthCloudShadow,enhancement.clouds?1:0);
+ gl.uniform1f(locations.u_cloudPhase,enhancement.phase);
+ gl.uniform1f(locations.u_cloudScale,enhancement.scale);
+ gl.activeTexture(gl.TEXTURE0+11);gl.bindTexture(gl.TEXTURE_2D,earthOceanMask||whiteTex);
+ gl.uniform1i(locations.u_oceanMask,11);gl.activeTexture(gl.TEXTURE0);
+ // Keep its sampler bound for the shadow, but remove the flattened cloud blend.
+ if(enhancement.clouds)gl.uniform1i(locations.u_earthWeather,0);
+}
+
+function drawEarthClouds(enhancement,pos,rot,rEq,rPol,vp,eye,light,normals,reference) {
+ const u=P.sphereU,model=mul(translate(pos),mul(rot,scaleM([rEq*enhancement.scale,rEq*enhancement.scale,rPol*enhancement.scale])));
+ gl.useProgram(P.sphere);setAtmosphereUniforms(gl,u,null);
+ gl.uniform1i(u.u_linearOutput,linearFrame?1:0);
+ gl.uniformMatrix4fv(u.u_mvp,false,new Float32Array(mul(vp,model)));
+ gl.uniformMatrix4fv(u.u_model,false,new Float32Array(model));
+ gl.uniformMatrix3fv(u.u_nmat,false,new Float32Array(normals));
+ gl.uniform3fv(u.u_cam,new Float32Array(eye));gl.uniform3fv(u.u_light,new Float32Array(light));
+ gl.uniform1f(u.u_oblate,BODY.Earth.polarKm/BODY.Earth.radiusKm);
+ gl.uniform1i(u.u_mode,3);gl.uniform1i(u.u_style,-1);
+ gl.uniform1i(u.u_earthNight,0);gl.uniform1i(u.u_earthIce,0);gl.uniform1i(u.u_earthWeather,0);
+ gl.uniform1i(u.u_earthEnhanced,0);gl.uniform1i(u.u_earthCloudShadow,0);
+ gl.uniform1f(u.u_cloudPhase,enhancement.phase);gl.uniform1f(u.u_cloudScale,enhancement.scale);
+ const uniforms=appearanceUniforms(reference);
+ gl.uniform4fv(u.u_map,new Float32Array(uniforms.map));
+ gl.uniform4fv(u.u_mapLat,new Float32Array(uniforms.lat));
+ gl.uniform4fv(u.u_mapWindow,new Float32Array(uniforms.window));
+ gl.activeTexture(gl.TEXTURE0+3);gl.bindTexture(gl.TEXTURE_2D,enhancement.clouds.tex);gl.uniform1i(u.u_weatherTex,3);
+ gl.activeTexture(gl.TEXTURE0);
+ setHazeUniforms(gl,u,getAtmosphereProfile('Earth'));
+ bindBodyMesh();gl.enable(gl.CULL_FACE);gl.cullFace(gl.BACK);gl.depthMask(false);
+ gl.blendFunc(gl.SRC_ALPHA,gl.ONE_MINUS_SRC_ALPHA);
+ gl.drawElements(gl.TRIANGLES,sphere.count,gl.UNSIGNED_SHORT,0);
+ gl.depthMask(true);gl.disable(gl.CULL_FACE);
+}
+
function bindEarthTextures(enabled,locations=P.sphereU) {
for (const [role, active, flag, sampler, unit] of /** @type {[string,boolean,string,string,number][]} */ ([
['night-lights', state.earthNight, 'u_earthNight', 'u_nightTex', 2],
@@ -2067,6 +2119,8 @@ function drawBody(b, vp, eye) {
gl.uniform1i(sphereUniforms.u_mapNoData, uniforms.nodata);
}
bindEarthTextures(!!referenceTex && b.name === 'Earth',sphereUniforms);
+ const earthEnhancement=prepareEarthEnhancement(b.name,!!referenceTex);
+ bindEarthEnhancement(earthEnhancement,sphereUniforms);
gl.uniform3fv(sphereUniforms.u_sunA, new Float32Array(sunTexd ? sunDiskBasis() : [1, 0, 0]));
// Ring-shadow inputs: the light direction expressed in the BODY frame (Rᵀ·light — rot's
// upper 3×3 is orthonormal, column-major), the annulus radii in equatorial-radius units, the
@@ -2097,6 +2151,8 @@ function drawBody(b, vp, eye) {
gl.drawElements(gl.TRIANGLES,mesh.count,mesh.indexType||gl.UNSIGNED_SHORT,0);
gl.disable(gl.CULL_FACE);
+ if(earthEnhancement.clouds)queueTransparent(pos,eye,()=>drawEarthClouds(earthEnhancement,pos,rot,rEq,rPol,vp,eye,light,normals,reference));
+
// atmosphere limb halo (additive shell, slightly larger, no depth write)
if (atmoStr > 0 && b.name !== "Sun" && b.name !== "Earth" && !profile) {
// A restrained illustrative optical limb, not an atmospheric-height measurement.
@@ -2291,6 +2347,7 @@ function drawMoons(parentName, parentPos, parentDisplayAU, vp, eye, drawn) {
gl.uniform1i(P.sphereU.u_mapNoData, uniforms.nodata);
}
bindEarthTextures(false); // auxiliary layers must never leak from Earth onto moons
+ bindEarthEnhancement({selected:false,clouds:null,phase:0,scale:1},P.sphereU);
gl.uniform1f(P.sphereU.u_oblate, 1);
gl.uniform2fv(P.sphereU.u_ringRad, new Float32Array([0, 0])); // no ring shadow on moons — clear the parent's state
// Nor a moon shadow ON a moon: mutual Galilean events are real but they need each moon's
@@ -2676,6 +2733,10 @@ function tick(now) {
finishPositionUpdate();
stepParticles(dt);
updateRotationDisplay(dt);
+ const cloudAsset=appearanceReference('Earth','cloud-composite');
+ const drift=enhancedEarthSelected(state)&&state.earthWeather&&!prefersReducedMotion()
+ &&referenceVisible.get('Earth')>=2&&referenceTextures[cloudAsset.id]?.ready;
+ state.earthCloudPhase=advanceEarthCloudPhase(state.earthCloudPhase,dt,state.simStepSeconds,BODY.Earth.rotationHours,drift);
}
}
}
@@ -3347,8 +3408,12 @@ async function showFallback(msg) {
if(solarDetail?.status('reference')==='unavailable')solarDetail.retry('reference');
syncSolarPlaybackControls();paint();
});
- for (const [id, key] of [['orreryEarthNight', 'earthNight'], ['orreryEarthWeather', 'earthWeather'], ['orreryEarthIce', 'earthIce']]) {
- bind(id, 'change', e => { state[key] = inputTarget(e).checked; updateEarthLayerStatus(); paint(); updateOrreryAccuracy(); });
+ for (const [id, key] of [['orreryEarthEnhanced', 'earthEnhanced'], ['orreryEarthNight', 'earthNight'], ['orreryEarthWeather', 'earthWeather'], ['orreryEarthIce', 'earthIce']]) {
+ bind(id, 'change', e => {
+ state[key] = inputTarget(e).checked;
+ if(key==='earthEnhanced'&&state[key]&&state.earthMaskStatus==='unavailable')state.earthMaskStatus='deferred';
+ updateEarthLayerStatus(); paint(); updateOrreryAccuracy();
+ });
}
bind('orreryVenusRadar', 'change', e => { state.venusRadar = inputTarget(e).checked; updatePhysicalAppearance(); paint(); updateOrreryAccuracy(); });
bind('orreryEarthCloudSource', 'change', e => {
@@ -3427,6 +3492,7 @@ async function showFallback(msg) {
scatteringTargets?.dispose();scatteringTargets=null;scatteringFrame=null;state.scatteringFrame=null;state.scatteringStatus={};
hdrPresentation?.dispose();hdrPresentation=null;linearFrame=false;state.hdrFrame=null;
state.hdrStatus={state:'deferred',reason:'Graphics context lost.'};
+ if(earthOceanMask)gl.deleteTexture(earthOceanMask);earthOceanMask=null;state.earthMaskStatus='deferred';
gl = null; P = {};
textures = {}; sunTex = { ready: false, tex: null }; ringTex = { ready: false, tex: null };
cancelPendingReferenceTextures();
diff --git a/apps/web/js/orreryShaders.js b/apps/web/js/orreryShaders.js
index f42c1cd7..d66ded19 100644
--- a/apps/web/js/orreryShaders.js
+++ b/apps/web/js/orreryShaders.js
@@ -8,6 +8,8 @@ import { INCIDENT_FIELD_GLSL } from './atmosphereIncident.js';
import { TERRAIN_SHADOW_GLSL } from './terrainShadowShaders.js';
import { DISPLAY_COMPOSITION_GLSL } from './materialColor.js';
import { RING_TRANSPORT_GLSL } from './ringTransportShaders.js';
+import {EARTH_CLOUD_GEOMETRY_GLSL,EARTH_OCEAN_GLSL} from './enhancedEarth.js';
+export {EARTH_CLOUD_GEOMETRY_GLSL,EARTH_OCEAN_GLSL};
const NOISE = `
float h31(vec3 p){ p=fract(p*0.3183099+0.1); p*=17.0; return fract(p.x*p.y*p.z*(p.x+p.y+p.z)); }
@@ -75,6 +77,9 @@ uniform vec4 u_map; uniform vec4 u_mapLat; uniform vec4 u_mapWindow; uniform int
uniform int u_earthNight; uniform int u_earthWeather; uniform int u_earthIce;
uniform sampler2D u_nightTex; uniform sampler2D u_weatherTex; uniform sampler2D u_iceTex;
uniform int u_textureLinear;
+uniform int u_earthEnhanced,u_earthCloudShadow;
+uniform float u_cloudPhase,u_cloudScale;
+uniform sampler2D u_oceanMask;
uniform vec3 u_hazeRayleighTau; uniform vec3 u_hazeAerosol;
// Illustrative atmospheric haze for the distant, non-physical path. See
// atmosphereOptics.js for the profile columns and the cited closed forms.
@@ -170,6 +175,8 @@ ${ATMOSPHERE_GLSL}
${TERRAIN_SHADOW_GLSL}
${RING_TRANSPORT_GLSL}
${NOISE}
+${EARTH_CLOUD_GEOMETRY_GLSL}
+${EARTH_OCEAN_GLSL}
// Every registered layer of a body shares one source grid. main computes this
// once per fragment (u, v, source latitude) and passes it to each lookup, so the
// same atan pair is not re-evaluated for every layer and coverage test.
@@ -201,6 +208,11 @@ float referenceCoverage(vec3 grid,vec4 sampleColor){
if(u_mapNoData==1&&max(sampleColor.r,max(sampleColor.g,sampleColor.b))<0.00392157) return 0.0;
return u_mapNoData==2 ? sampleColor.a : 1.0;
}
+vec4 earthCloudSample(vec3 p){
+ vec2 uv=referenceGrid(p).xy;
+ uv.x=fract(uv.x-u_cloudPhase);
+ return referenceSample(u_weatherTex,p,uv);
+}
float spotGroup(vec3 p,vec4 s){
if(s.w<=0.0) return 0.0;
float ang=acos(clamp(dot(normalize(p),normalize(s.xyz)),-1.0,1.0));
@@ -247,6 +259,17 @@ void main(){
// bright full-circumference ring that made every planet look like an annular eclipse.
float day=smoothstep(-0.32,0.22,dot(N,normalize(u_light)));
o=vec4(displayOutput(u_atmo*pow(1.0-clamp(dot(N,V),0.0,1.0),2.2)*u_atmoStr*1.4*(0.04+0.96*day)), 1.0); return; }
+ if(u_mode==3){
+ // A separate, raised transparent shell. This branch is removed from the
+ // physical ground specialization; cloud haze remains explicitly illustrative.
+ vec4 clouds=earthCloudSample(p);
+ if(clouds.a<=0.001) discard;
+ float lambert=max(dot(N,normalize(u_light)),0.0);
+ vec3 color=decodeSRGB(coveredRGB(clouds))*(.001+.999*lambert);
+ vec3 path=hazeOverSurface(color,N,V,normalize(u_light),1.0);
+ color+=path;
+ o=vec4(u_linearOutput==1?color:encodeSRGB(color),clouds.a);return;
+ }
if(u_mode==1){
if(u_style<0){
float limb=pow(clamp(dot(N,V),0.0,1.0),0.45);
@@ -314,6 +337,7 @@ void main(){
vec4 mapped=referenceSample(u_tex,p,referenceGridValue.xy);
vec3 sourceRGB=u_mapNoData==2 ? coveredRGB(mapped) : mapped.rgb;
col=mix(decodeSRGB(u_base),u_textureLinear==1 ? sourceRGB : decodeSRGB(sourceRGB),referenceCoverage(referenceGridValue,mapped));
+ if(u_earthEnhanced==1) col=enhancedOceanColor(col,referenceSample(u_oceanMask,p,referenceGridValue.xy).r);
// Earth auxiliaries share the documented WGS84 pixel-area grid, 180W..180E.
// Weather is the provider's dated clouds-and-surface image, never inferred clouds.
if(u_earthWeather==1){
@@ -493,6 +517,13 @@ void main(){
}
}
sunVis*=terrainSunVisibility(surfaceBodyKm,incidentBody);
+ float hazeSunVis=sunVis;
+ if(reference&&u_earthCloudShadow==1&&dot(N,normalize(u_light))>0.0){
+ // Same ellipsoid and phase as the visible clouds. Trace straight geometric
+ // sunlight, not a fixed UV offset; alpha is a display opacity, not optical depth.
+ vec3 hit=earthCloudHit(p,normalize(u_lightObj),u_oblate,u_cloudScale);
+ sunVis*=1.0-.35*earthCloudSample(normalize(hit)).a;
+ }
// The shadow removes DIRECT sunlight only. The 0.05 floor is the light a planet's own
// atmosphere scatters into it, which is why Io's shadow reads as very dark grey rather than
// as a hole in the planet.
@@ -543,7 +574,7 @@ void main(){
// shared encode below handles it; a procedural display recipe is decoded and
// re-encoded so its own downstream handling stays exactly as it was.
vec3 surface=reference ? col : decodeSRGB(col);
- vec3 path=hazeOverSurface(surface,N,V,normalize(u_light),sunVis);
+ vec3 path=hazeOverSurface(surface,N,V,normalize(u_light),hazeSunVis);
col=reference ? surface+path : encodeSRGB(surface+path);
displayLimb=vec3(0);
}
@@ -618,7 +649,7 @@ export function physicalEnabledSource(source) {
' // Direct reflected sunlight sees the incident atmospheric column. The\n // single-scattering mode has no invented diffuse-ambient weather term.\n col*=lambert*sunVis*(refracted ? v_incidentTransmission : atmosphereSunTransmission(surfaceBodyKm))\n *u_atmosphereSolarScale*u_atmosphereExposure;'],
[' if(u_atmosphereEnabled==1) col=atmosphereSurfaceColor(',' col=atmosphereSurfaceColor('],
[' if(u_atmosphereEnabled==0)return vec3(0);\n',''],
- [' if(u_atmosphereEnabled==0&&dot(u_hazeRayleighTau,vec3(1))>0.0){\n // Path radiance is linear light. A registered map is still linear here and the\n // shared encode below handles it; a procedural display recipe is decoded and\n // re-encoded so its own downstream handling stays exactly as it was.\n vec3 surface=reference ? col : decodeSRGB(col);\n vec3 path=hazeOverSurface(surface,N,V,normalize(u_light),sunVis);\n col=reference ? surface+path : encodeSRGB(surface+path);\n displayLimb=vec3(0);\n }\n',''],
+ [' if(u_atmosphereEnabled==0&&dot(u_hazeRayleighTau,vec3(1))>0.0){\n // Path radiance is linear light. A registered map is still linear here and the\n // shared encode below handles it; a procedural display recipe is decoded and\n // re-encoded so its own downstream handling stays exactly as it was.\n vec3 surface=reference ? col : decodeSRGB(col);\n vec3 path=hazeOverSurface(surface,N,V,normalize(u_light),hazeSunVis);\n col=reference ? surface+path : encodeSRGB(surface+path);\n displayLimb=vec3(0);\n }\n',''],
];
for(const [from,to] of rewrites){
if(source.split(from).length!==2)throw new Error('Physical enabled-flag boundary changed');
diff --git a/apps/web/js/planetAppearance.js b/apps/web/js/planetAppearance.js
index c80022d7..bd26f462 100644
--- a/apps/web/js/planetAppearance.js
+++ b/apps/web/js/planetAppearance.js
@@ -73,7 +73,7 @@ export function appearanceSummary(body, state = {}) {
export function earthLayerDescription(state = {}, compact = false) {
const roles = /** @type {[string, boolean][]} */ ([['night-lights', state.earthNight !== false], [earthCloudRole(state), state.earthWeather !== false], ['sea-ice', state.earthIce === true]]);
- return roles.filter(([, enabled]) => enabled).map(([role]) => {
+ const layers=roles.filter(([, enabled]) => enabled).map(([role]) => {
const asset = appearanceReference('Earth', role);
if (!asset) return `${role}: unavailable`;
const status = state.appearanceStatus?.[asset.id];
@@ -82,4 +82,14 @@ export function earthLayerDescription(state = {}, compact = false) {
return `${label} · ${asset.observation_label}${status === 'ready' ? '' : status === 'unavailable' ? ' · unavailable'
: status === 'deferred' || !status ? ' · loads when Earth is in view at a useful scale' : status === 'queued' ? ' · queued' : ' · loading'}${limits}`;
}).join(' · ');
+ return [layers,enhancedEarthDescription(state)].filter(Boolean).join(' · ');
+}
+
+export function enhancedEarthDescription(state){
+ if(!state.earthEnhanced)return '';
+ if(state.earthCloudSource==='daily')return 'Enhanced Earth suspended for MODIS swaths containing the ground.';
+ if(state.earthIce===true)return 'Enhanced Earth suspended to preserve the scientific sea-ice palette.';
+ if(state.useTextures===false)return 'Enhanced Earth suspended while source textures are off.';
+ const ocean=state.earthMaskStatus==='unavailable'?'Ocean grading unavailable. ':'Darker offshore oceans. ';
+ return `Enhanced Earth · illustrative: ${ocean}Cloud height (nominal 8 km), shadows and drift are display choices, not measured weather. Cloud lighting uses approximate haze. Drift follows Play time; reduced motion holds it.`;
}
diff --git a/docs/IMPLEMENTATION_PLAN.md b/docs/IMPLEMENTATION_PLAN.md
index 7ebf3355..9fdb4e97 100644
--- a/docs/IMPLEMENTATION_PLAN.md
+++ b/docs/IMPLEMENTATION_PLAN.md
@@ -1,7 +1,7 @@
# Implementation plan
Status: active
-Updated: 2026-09-11
+Updated: 2026-09-23
This plan describes delivery work, while `STATUS.md` describes implemented product behavior
and `ROADMAP.md` records longer-horizon product direction.
@@ -47,6 +47,17 @@ Exit criteria:
## Next product increments
+### Enhanced Earth review candidate
+
+The user approved the bounded optional mode in [RFC 0008](rfcs/0008-enhanced-earth.md).
+Implementation includes guarded ocean grading, a nominal 8 km cloud shell,
+Sun-directed shadows, independent rotation-gated drift, lifecycle recovery and
+release-fingerprint coverage for the new rendering modules. The default remains off.
+See [validation evidence](validation/enhanced-earth/README.md) for the comparison and
+exact scope. Next gates are draft review, CI Rust/WASM/browser and coverage checks,
+then native/mobile appearance and performance. Local source completion does not
+authorize merge or production promotion.
+
### Operational evidence
- Calibrate physical magnetic units and publish the method.
diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md
index 5e04306e..9886b696 100644
--- a/docs/REQUIREMENTS.md
+++ b/docs/REQUIREMENTS.md
@@ -31,6 +31,7 @@ unrecognized status, and incomplete workflow enforcement.
| `SOL-VIS-005` | Numeric terrain datum, finite geometry, physical extents and source identity |
| `SOL-VIS-006` | Dimensioned optical transfer with distinct reflection, scattering and emission |
| `SOL-VIS-007` | Source band, frame, coverage and finite dynamic appearance playback |
+| `SOL-VIS-009` | Opt-in Enhanced Earth with disclosed ocean grading, raised clouds, aligned shadows and gated drift |
| `SOL-CI-001` | SHA-pinned actions, least privilege, and deployment of the tested SHA |
| `SOL-DOC-001` | Documentation, plans, instructions, and traceability updated with code |
| `SOL-SUPPLY-001` | Locked dependencies and automated ecosystem update review |
diff --git a/docs/SPEC.md b/docs/SPEC.md
index 630bd24a..883c1675 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -32,6 +32,19 @@ reuse the existing view transform without moving physical bodies.
Scientific and source claims remain anchored to public methods and data: NOAA/SWPC products, Helioviewer quicklook imagery and metadata, IERS Earth-orientation data, JPL Horizons/DE441 validation, published analytic ephemerides, and NASA/IAU constants. Sol does not claim proprietary JPL, NOAA, or commercial forecasting algorithms.
+[RFC 0008](rfcs/0008-enhanced-earth.md) adds an optional Enhanced Earth presentation,
+off by default. It retains NASA maps and their epochs, grades dark offshore ocean
+pixels, raises the historical cloud layer by a nominal 8 km, and samples that same
+shell/phase for Sun-directed display shadows. Independent drift advances only with
+visible Earth during Play time; pause, hidden/inactive views and reduced motion
+hold its phase. MODIS ground-containing swaths and the scientific sea-ice palette
+suspend enhancement. Cloud height, drift, opacity-based shadows and cloud haze
+are illustrative; they are not measured weather or volumetric optical transfer.
+The ground keeps its existing reference atmosphere. Source-qualified defaults,
+other bodies, engine snapshots and observation dates remain unchanged. See the
+[validation record](validation/enhanced-earth/README.md) for local evidence and
+outstanding browser/device qualification.
+
Planetary appearance follows [RFC 0004](rfcs/0004-registered-planetary-appearance.md).
Registered, dated mission display maps are separate from calibrated or complete
observations. Earth layers distinguish land/ice, annual night lights, dated satellite
diff --git a/docs/STATUS.md b/docs/STATUS.md
index 8f92ffb0..c442d083 100644
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -1,6 +1,6 @@
# Sol status
-Updated: 2026-09-13. Scope: inspected local implementation, not production activation.
+Updated: 2026-09-23. Scope: inspected local implementation, not production activation.
## Implementation versus qualification
@@ -37,6 +37,14 @@ while a scoped, tested implementation can be submitted for code review.
## User-visible behavior implemented locally
+The optional Enhanced Earth candidate (SOL-VIS-009 / Accepted RFC 0008) preserves
+the default view and adds darker ocean colors, raised historical clouds, shared-phase
+Sun-directed ground shadows and drift during Play time. Scientific sea-ice and MODIS
+views suspend it. [Candidate validation](validation/enhanced-earth/README.md) records
+renderer lifecycle checks, deterministic mask generation and an actual offscreen
+production-shader comparison. Native browser/mobile and release qualification remain
+open; this candidate does not change the deployed site.
+
Sun, My Sky and Solar System expose selected non-canvas facts, native object controls,
visible mode/source/epoch/limitations and bounded lists. The timeline distinguishes
idealized cycle frames from observed data and treats missing frames as gaps.
diff --git a/docs/requirements.json b/docs/requirements.json
index da7e9cda..4fd1eb6b 100644
--- a/docs/requirements.json
+++ b/docs/requirements.json
@@ -496,6 +496,29 @@
"ci_gates": [
"CI / Web, provider, and browser validation"
]
+ },
+ {
+ "id": "SOL-VIS-009",
+ "status": "implemented",
+ "statement": "Enhanced Earth MUST be opt-in, preserve original NASA sources and engine state, keep cloud geometry and Sun-directed shadows phase-aligned, freeze drift outside visible animation, and suspend visual edits for ground-containing swaths or scientific sea-ice palettes. Height, motion, ocean grading and cloud lighting MUST remain disclosed as illustrative.",
+ "source": "docs/rfcs/0008-enhanced-earth.md#requirements",
+ "implementation": [
+ "apps/web/js/enhancedEarth.js",
+ "apps/web/js/earthOceanMask.js",
+ "apps/web/js/orrery.js",
+ "apps/web/js/orreryShaders.js",
+ "apps/web/js/planetAppearance.js",
+ "apps/web/index.html",
+ "tools/prepare_earth_ocean_mask.py"
+ ],
+ "verification": [
+ "tests/web/enhancedEarth.test.mjs",
+ "tests/python/test_earth_ocean_mask.py",
+ "tools/render_enhanced_earth_probe.py"
+ ],
+ "ci_gates": [
+ "CI / Web, provider, and browser validation"
+ ]
}
]
}
diff --git a/docs/rfcs/0008-enhanced-earth.md b/docs/rfcs/0008-enhanced-earth.md
new file mode 100644
index 00000000..e82d9bf0
--- /dev/null
+++ b/docs/rfcs/0008-enhanced-earth.md
@@ -0,0 +1,107 @@
+# RFC 0008: Optional Enhanced Earth presentation
+
+- Status: Accepted
+- Authors: Codex for Protonmatter
+- Created: 2026-09-23
+- Target: Enhanced Earth review candidate
+- Requirements: `SOL-VIS-009`
+
+## Summary
+
+Add an opt-in Enhanced Earth checkbox: deeper oceans, a raised historical cloud
+layer, Sun-directed offset shadows and independent drift during Play time.
+The owner approved this design in conversation on 2026-09-23. Acceptance authorizes
+implementation; it does not qualify native graphics, merge or deployment.
+
+## Context
+
+Earth already uses NASA surface, cloud, night-light and sea-ice maps. Clouds are
+currently composited on the ground. This change retains those immutable sources
+and their dates. It does not import the lab's artistic Earth or simulate weather.
+
+## Requirements
+
+`SOL-VIS-009`: Enhanced Earth MUST be opt-in and disclosed as illustrative. It
+MUST preserve source-qualified defaults, engine state and non-Earth materials.
+Cloud geometry, shadows and drift MUST share a single map phase. Pausing time,
+hidden/inactive views and reduced motion MUST stop drift. Camera redraws MUST NOT
+advance phase. MODIS clouds-and-ground swaths MUST NOT be lifted or drifted.
+Unavailable cloud imagery MUST NOT create opaque fallback clouds or shadows.
+
+## Design
+
+Use the existing surface and cloud resources. Grade only dark blue pixels inside
+a conservative offshore mask derived offline from the committed Natural Earth
+land/ice polygons. Protect bright ice; suspend enhancement for the sea-ice palette.
+The mask is display support, not a qualified coastline or ocean reflectance map.
+
+Raise the cloud ellipsoid homothetically by a nominal 8 km at the equator
+(slightly less at the poles). Reuse the sphere mesh and base program in a
+transparent cloud pass, back-face culled, depth-tested and without depth writes.
+The base program's existing haze approximation lights the cloud shell; this is
+not dense-cloud or volumetric optical transfer. The ground retains its existing
+reference atmosphere. Cloud shadows trace straight sunlight rays from the oblate
+ground to this same shell and sample the same phase, attenuating direct sunlight
+only. No fixed screen-space or longitude offset is used.
+
+Drift adds 3% of the visible Earth rotation, capped at 0.002 turns per real second,
+using a bounded phase advanced once per successful animation tick. The clock is
+illustrative and never alters observation dates, positions or Earth orientation.
+Daily MODIS or scientific sea-ice palette selection suspends the enhancement; toggling back resumes its phase.
+
+## UX and accessibility
+
+Earth layers contains a native unchecked Enhanced Earth checkbox, a concise help
+paragraph and status describing active, suspended, loading or unavailable layers.
+It is independent of the other planets' appearance mode. Keyboard/touch behavior
+uses existing controls; reduced motion suppresses independent cloud drift.
+
+## Security and privacy
+
+No new runtime dependencies, external requests, user data or schemas. Existing
+bounded/cancellable reference loaders own NASA imagery. One 512x256 R8 mask is
+uploaded lazily, retained per context and disposed on context loss. Upload failure
+leaves oceans ungraded with visible status. The generated mask pins input hashes.
+
+## Alternatives
+
+A fixed UV shadow offset contradicts a moving Sun. Full volumetric clouds need
+different data and performance qualification. Replacing scientific defaults would
+hide display edits; a separate toggle permits direct comparison and rollback.
+
+## Risks
+
+Cloud height, opacity-to-shadow strength and drift are artistic choices, not
+retrieved meteorology. Coarse vectors omit small islands; blue/brightness guards
+and an offshore margin restrict grading, but the mask is not survey accuracy.
+Cloud scattering uses illustrative haze; it is not the ground's qualified optical
+transfer. Physical-height depth is subtle at globe scale. Native GPU/mobile visual
+and performance qualification remain required; CPU draw tests cannot establish it.
+
+## Acceptance criteria
+
+1. Default/off, non-Earth, no textures and MODIS paths retain their original draws.
+2. Ready composite clouds appear once on the shell; missing/off clouds cast no shadow.
+3. Executed shader geometry hits the correct raised oblate shell toward the Sun;
+ tangent/polar/night cases are finite, and opposite light directions reverse offsets.
+4. Draw tests prove shared cloud/shadow phase, elevation, depth/culling/blending,
+ no night-light leakage, and pause/camera/context continuity.
+5. Ocean math preserves masked land, neutral/bright ice and non-blue pixels;
+ deterministic mask regeneration and known land/ocean/polar samples pass.
+
+## Validation
+
+Run focused shader/helper and full-renderer lifecycle tests, all Node tests,
+mask regeneration, Python tests, type/static/doc/SDLC/UX gates and the web build.
+Required CI retains native WebGL2, browser visual, coverage, WASM and release gates.
+
+## Rollout and rollback
+
+Submit a separate draft PR based on the existing default branch. Default is off.
+Merge/deploy only after normal review and required gates. Uncheck Enhanced Earth
+for immediate comparison/rollback; revert the feature commit for full removal.
+
+## Documentation
+
+Update SPEC, requirements catalogue/traceability, README, status and validation
+evidence with the actual local results and remaining qualification limits.
diff --git a/docs/validation/enhanced-earth/README.md b/docs/validation/enhanced-earth/README.md
new file mode 100644
index 00000000..7d59c11f
--- /dev/null
+++ b/docs/validation/enhanced-earth/README.md
@@ -0,0 +1,92 @@
+# Enhanced Earth validation record
+
+Date: 2026-09-23. Scope: local review candidate for RFC 0008 / SOL-VIS-009.
+This record does not claim merge, deployment or native-device qualification.
+
+## Behavior
+
+Earth layers → Enhanced Earth is off by default. It reuses NASA surface/cloud
+maps, protects coarse land/ice with a conservative offshore mask, and darkens
+only dark blue water colors in linear light. A homothetic cloud shell is nominally
+8 km above the equator. Ground shadows intersect that shell toward the Sun and
+use the same drifting UV phase. The cloud pass uses illustrative haze, while the
+ground retains reference optical transfer. No source image, observation epoch,
+ephemeris or other body's appearance is modified.
+
+Cloud drift follows 3% of displayed Earth rotation, capped at 0.002 turns per real
+second. Pause, hidden/inactive scenes and reduced motion freeze the phase; camera
+movement never advances it. MODIS ground-containing swaths and the scientific
+sea-ice palette suspend enhancement. Missing/off clouds have no shell or shadow.
+Failed mask upload leaves the cloud view usable and reports ocean grading as
+unavailable; switching Enhanced Earth off/on retries once.
+
+## Automated evidence
+
+- `tests/web/enhancedEarth.test.mjs` executes production renderer lifecycle and
+ shader geometry/color helpers. Cases cover defaults, scientific-state identity,
+ shell elevation, shared phase, transparent draw state, non-Earth reset, missing
+ maps, swath/sea-ice suspension, drift and rate caps, pause/reduced motion, active
+ hidden/inactive suspension, context loss and explicit upload retry.
+- `tests/python/test_earth_ocean_mask.py` verifies exact offline regeneration and
+ rejects changed source data. The generator is standard-library-only; its
+ Natural Earth source hashes and the decoded pixel hash are committed.
+- `tools/render_enhanced_earth_probe.py` compiles and links the actual base and
+ physical shaders on Linux EGL/Mesa. It renders a controlled base-haze comparison
+ with original NASA maps. Metamorphic checks require visible changes when
+ enhancement, drift or shadows change. A black-ground test verifies that cloud
+ shadows do not attenuate atmospheric path radiance.
+
+The probe initially exposed the existing GLSL local name `packed`, rejected as
+a reserved token by Mesa. Renaming that local to `columnValues` changes no
+formula. `node tools/prepare_atmosphere_columns.mjs` regenerated the pinned
+manifest from the actual source; both 2 MiB numerical field files reproduced
+byte-for-byte. No source-identity check was bypassed or weakened.
+
+Final candidate checks on 2026-09-23:
+
+| Command | Observed result |
+| --- | --- |
+| `npm test` | 1,323 tests passed; no failures or skips. |
+| `PYTHONPATH=tools python -m unittest discover -s tests/python -p 'test_*.py' -v` | 390 tests ran; 5 errors from missing `cargo`/`rustc`, 3 skips, no assertion failures. |
+| `python tools/typecheck_web.py` | 114 files clean. |
+| `python tools/validate_web_static.py` | Passed. |
+| `python tools/validate_sdlc.py` | 24 requirements and workflow/traceability checks passed. |
+| `python tools/validate_docs.py` | 140 Markdown files passed. |
+| `python tools/validate_ux_contract.py` | Structure checks passed. |
+| `python tools/prepare_earth_ocean_mask.py --check` | Exact reproduction passed. |
+| `python tools/render_enhanced_earth_probe.py` | Both production programs compiled/linked; image, drift, shadow and haze-isolation assertions passed. |
+| `git diff --check` | Passed. |
+
+The five Python errors are three native snapshot subcases, the native hybrid-time
+case, and local Rust toolchain evidence capture. An earlier broad rerun ended
+without a summary; the complete confirmation run above finished in 46.666 seconds.
+Release-artifact and ocean-mask cases passed in that full run. The new module
+classification regression was also observed failing before the classifier update
+and passing afterward. The release builder requires source/run metadata and valid
+WASM inputs; no qualified release build was produced without the Rust/WASM toolchain.
+Independent review found two minor issues (haze shadowing and an insufficiently
+active suspension test); both were fixed and confirmed in focused follow-up review.
+
+## Reproduction
+
+```sh
+python tools/prepare_earth_ocean_mask.py --check
+node --experimental-vm-modules --test tests/web/enhancedEarth.test.mjs
+PYTHONPATH=tools python -m unittest tests.python.test_earth_ocean_mask -v
+python tools/render_enhanced_earth_probe.py
+```
+
+The optional EGL probe requires Linux libEGL, Node, NumPy, Pillow and DejaVu Sans.
+It is a diagnostic, not the repository's browser/native graphics gate. The
+[comparison](comparison.jpg) holds maps, camera and Sun direction constant.
+[Probe metadata](gl-probe.json) records renderer, shader/source hashes and changed
+pixel counts. Those counts prove an effect, not its perceptual quality or accuracy.
+
+## Remaining qualification
+
+Native WebGL2/ANGLE, Safari/iOS/mobile appearance, physical-path visual quality,
+whole-web/Rust coverage and frame-time measurements require the normal CI/device
+gates. CPU lifecycle tests and Mesa images do not substitute for those gates.
+The cloud layer has no measured heights, evolving meteorology, multiple
+scattering or volumetric structure. The offshore mask is deliberately coarse and
+omits small islands; it is not qualified for glint, coastlines or ocean analysis.
diff --git a/docs/validation/enhanced-earth/comparison.jpg b/docs/validation/enhanced-earth/comparison.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..28d0a77dcad71d28b5b1a3b67a88be6b3d889618
GIT binary patch
literal 238889
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