docs: add render diagrams and complete config examples
This commit is contained in:
Richard Zink committed
1 parent
b9a77fbaa4
commit
d5fb1f12c4
3 files changed
+246
-139
No files matched your search
@@ -8,8 +8,8 @@ dropped into an iframe or kiosk browser and left running.
|
||||
|
||||
- **WebGL flight scene** (`vendor/clouds3d.js`): a 3D terrain mesh built from
|
||||
real elevation data (Copernicus DEM), a raymarched volumetric cloud deck,
|
||||
and a figure-eight flight path around the configured location with a
|
||||
vertical bob inside the 15-35 km flight band.
|
||||
optional round-world curvature, and a figure-eight flight path around the
|
||||
configured location with a vertical bob inside the 15-35 km flight band.
|
||||
- **One physical light model** shared by sky, clouds, contrails, aircraft and
|
||||
ground: direct beam through a Kasten-Young air mass with Rayleigh, ozone and
|
||||
aerosol extinction, diffuse skylight, moonlight, a starlight floor and aerial
|
||||
@@ -20,11 +20,12 @@ dropped into an iframe or kiosk browser and left running.
|
||||
- **Theme-tinted lighting**: each theme may pull the physical colours toward
|
||||
its own palette and set its own day/night exposure, without replacing the
|
||||
physics (`window.THEMES[...].lighting`).
|
||||
- **Shadows**: moving cloud shadows sampled from the same cloud field the sky
|
||||
renders, plus terrain self-shadowing over the DEM height field.
|
||||
- **Shadows**: moving cloud shadows sampled from the same wind-advected cloud
|
||||
field the sky renders, plus terrain self-shadowing over the DEM height field.
|
||||
- **Realistic night sky**: ~8700 stars from the Yale Bright Star Catalogue
|
||||
(points sized by magnitude, coloured by temperature), rotated at the sidereal
|
||||
rate for the site's latitude, a Milky Way band and a moon disc with a real
|
||||
rate for the site's latitude, a Milky Way band, approximate Keplerian planet
|
||||
points for Mercury..Pluto with planet colours, and a moon disc with a real
|
||||
lunar surface map: the terminator comes from the sun direction, so crescent,
|
||||
gibbous and full fall out of the geometry (sun and moon discs are drawn
|
||||
enlarged - `CONFIG.sun`/`CONFIG.moon` - while the lighting stays physical).
|
||||
@@ -37,7 +38,8 @@ dropped into an iframe or kiosk browser and left running.
|
||||
nodes (bigger towns get more and brighter dots). Both fade in light by light
|
||||
across twilight instead of switching as one block.
|
||||
- **Live weather** (Open-Meteo): current conditions plus a 4-day forecast
|
||||
widget; the weather code selects the cloud coverage and the colour mood.
|
||||
widget; the weather code selects the cloud coverage and the colour mood, and
|
||||
wind speed/direction advect the cloud field.
|
||||
- **Fully cached, offline-capable**: basemap tiles, the elevation grid, Overpass
|
||||
road/place cells, the merged road chains and the decoded settlement list live
|
||||
permanently in IndexedDB; the star catalogue is inlined. Once warm, the scene
|
||||
@@ -106,6 +108,138 @@ cache, which is the gentlest option for the upstreams. If a source is
|
||||
unreachable, the scene degrades instead of failing: an "OFFLINE"-labelled
|
||||
ground grid in place of basemap tiles.
|
||||
|
||||
## Render flow diagrams
|
||||
|
||||
The scene is a sequence of full-screen and geometry passes sharing one light
|
||||
state. The diagrams below describe the current pipeline.
|
||||
|
||||
### Frame pipeline
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[background.html] --> B[CONFIG + THEMES]
|
||||
A --> C[Open-Meteo weather]
|
||||
A --> D[SunCalc clock: sun, moon, sidereal time]
|
||||
A --> E[IndexedDB cache: tiles, DEM, Overpass]
|
||||
B --> F[clouds3dRender]
|
||||
C --> F
|
||||
D --> F
|
||||
E --> F
|
||||
|
||||
F --> G[Sky pass: gradient, stars, Milky Way, sun, moon]
|
||||
G --> H[Star catalogue points]
|
||||
H --> I[Planet points]
|
||||
G --> J[Terrain distance pass]
|
||||
J --> K[Terrain mesh pass]
|
||||
K --> L[City lights]
|
||||
L --> M[Car lights]
|
||||
M --> N[Optional atmosphere model]
|
||||
N --> O[Front haze]
|
||||
O --> P[Cloud raymarch]
|
||||
P --> Q[Aircraft]
|
||||
Q --> R[Contrails]
|
||||
```
|
||||
|
||||
### Weather and cloud calculation
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Open-Meteo current/hourly] --> B[weather_code]
|
||||
A --> C[wind_speed_10m]
|
||||
A --> D[wind_direction_10m]
|
||||
B --> E[weather theme]
|
||||
B --> F[cloud coverage density]
|
||||
C --> G[wind speed in world units/s]
|
||||
D --> H[advection vector toward opposite bearing]
|
||||
F --> I[cloudDensity fBm]
|
||||
G --> I
|
||||
H --> I
|
||||
I --> J[raymarch cloud deck]
|
||||
J --> K[cloud colour and alpha]
|
||||
K --> L[sky/cloud pixels]
|
||||
K --> M[terrain cloud shadows]
|
||||
```
|
||||
|
||||
### Cloud shadows on terrain
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Sky as Sky/Cloud pass
|
||||
participant Cloud as cloudDensity()
|
||||
participant Wind as wind vector
|
||||
participant Terrain as Terrain shader
|
||||
participant Sun as Sun direction
|
||||
|
||||
Wind->>Cloud: offset cloud field over time
|
||||
Terrain->>Cloud: sample from ground point toward sun
|
||||
Cloud-->>Terrain: optical depth through cloud deck
|
||||
Terrain->>Terrain: darken direct sunlight by cloud optical depth
|
||||
Terrain->>Terrain: reduce skylight by cloudShadowAmbient
|
||||
Terrain-->>Screen: shaded ground patch under moving cloud
|
||||
```
|
||||
|
||||
### Terrain self-shadowing
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant T as Terrain fragment
|
||||
participant H as DEM height field
|
||||
participant Sun as Sun direction
|
||||
|
||||
T->>H: march from surface point toward sun
|
||||
H-->>T: terrain height samples
|
||||
T->>T: compare surface height with sampled terrain height
|
||||
T->>T: shadow = 0 if blocked, 1 if lit
|
||||
T-->>Screen: ridge/valley shading with terrainShadowFloor
|
||||
```
|
||||
|
||||
### Aircraft and contrails
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[OSM aerodromes] --> B[airport graph]
|
||||
B --> C[destination selection]
|
||||
C --> D[Bezier route: climb, cruise, descent]
|
||||
D --> E[aircraft mesh + night strobes]
|
||||
D --> F[eligible for contrail]
|
||||
F --> G[contrail ribbon geometry]
|
||||
G --> H[world-space fBm shader]
|
||||
H --> I[contrail pixels]
|
||||
E --> I
|
||||
```
|
||||
|
||||
### Roads, car lights and city lights
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Overpass road cells] --> B[road chains]
|
||||
B --> C[road slots]
|
||||
C --> D[traffic side lookup]
|
||||
D --> E[vehicle points]
|
||||
E --> F[distance fade + night ramp]
|
||||
F --> G[car light pixels]
|
||||
|
||||
H[Overpass place nodes] --> I[settlement list]
|
||||
I --> J[rank/population weighting]
|
||||
J --> K[city light clusters]
|
||||
K --> L[city light pixels]
|
||||
```
|
||||
|
||||
### Planets and stars
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[scene date] --> B[Keplerian planet positions]
|
||||
B --> C[geocentric ecliptic vector]
|
||||
C --> D[RA/Dec]
|
||||
D --> E[local sky direction]
|
||||
E --> F[planet points]
|
||||
|
||||
G[Yale star catalogue] --> H[RA/Dec]
|
||||
H --> I[sidereal rotation]
|
||||
I --> J[star points]
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
`config.js` is the reference: every key is documented in place, and unused
|
||||
@@ -125,13 +259,15 @@ Groups:
|
||||
| `ground.style` | `'satellite'` (ESRI World_Imagery) or `'streets'` (ESRI World_Street_Map) |
|
||||
| `orbit` | figure-eight path, `radiusKm`, direction, reorientation, `altBob` |
|
||||
| `fog.distanceKm` | distance haze (0/false = off) |
|
||||
| `clouds` | deck height (`top`/`bottom` in world units) and `density` per weather level |
|
||||
| `clouds` | deck height (`top`/`bottom` in world units), `density` per weather level, and `wind` motion from Open-Meteo |
|
||||
| `flights` | aircraft count, altitudes, speeds, destination weights, contrails, night strobes |
|
||||
| `terrain` | DEM mesh, `exaggeration`, `edgeFadeTiles`, `carLights`, `cityLights`, `wireframe` |
|
||||
| `terrain` | DEM mesh, `exaggeration`, edge fade/skirt, `outerDem`, `carLights`, `cityLights`, `wireframe` |
|
||||
| `carLights` | road width, light sizes, lane separation, traffic range/fade, `trafficSide`, spacing, speed, density, brightness |
|
||||
| `lights` | twilight switching window of every artificial light (`offDeg`, `onDeg`, `softDeg`) |
|
||||
| `atmosphere` | turbidity, moon/star gains, night floor, albedo/sky/air gains, haze residual, cloud albedo and cloud haze, cloud shadows, terrain shadows |
|
||||
| `atmosphere` | turbidity, moon/star gains, night floor, albedo/sky/air gains, haze blocks, cloud albedo/haze, cloud shadows, terrain shadows |
|
||||
| `stars` | star colour `tint` and `brightness` |
|
||||
| `planets` | planet points: `enabled`, `brightness`, `sizeScale`, `showPluto` |
|
||||
| `curvature` | round-world curvature: `enabled`, `earthRadiusKm`, `exaggeration` |
|
||||
| `sun` | `angularRadius` (disc size only, 12x physical by default) |
|
||||
| `moon` | disc size (`angularRadius`, 12x physical by default), `texture`, `lightGain`, `earthshine`, `limbDarkening`, `brightness`, `halo`, `flipU`/`flipV` |
|
||||
| `camera` | `aim` (`'off'` or `'moon'`), `aimEase`, `aimBob` |
|
||||
@@ -140,7 +276,7 @@ Groups:
|
||||
### World scale
|
||||
|
||||
1 world unit = one zoom-11 tile ≈ 12.9 km at 48.6°N. World axes are
|
||||
`+X = west`, `+Y = up`, `+Z = north`; the camera flies the 15-35 km band
|
||||
`+X = east`, `+Y = up`, `+Z = north`; the camera flies the 15-35 km band
|
||||
(`y ≈ 1.16-2.70`). Cloud deck heights, fog distance and orbit radius are all
|
||||
expressed in these units or in km where noted.
|
||||
|
||||
|
||||
Reference in new issue
Block a user