mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-20 18:22:25 +00:00
Merge remote-tracking branch 'origin/main' into denis/iss-live-telemetry
# Conflicts: # docs/CURRENT-STATE.md # scripts/package-boundaries.json # src/layers/satellites/interaction.js # src/layers/satellites/lifecycle.js # src/layers/satellites/tracking.js
This commit is contained in:
commit
fd3ca679ec
1125 files changed
+149994
-45970
No files matched your search
+118
-1
@@ -43,7 +43,11 @@ await app.destroy();
|
||||
```
|
||||
|
||||
The example's containers and three remaining constructors are supplied by the
|
||||
consumer. The viewer helper preserves the standalone viewer's render settings;
|
||||
caller. The standalone scene also returns `trimStaleCommands()`, which drops
|
||||
the draw commands the Cesium scene keeps after a turned-off layer stops drawing;
|
||||
the application tools call it one frame after each layer disable. A scene
|
||||
without it keeps those commands, and so the layer's memory, until they are
|
||||
overwritten. The viewer helper preserves the standalone viewer's render settings;
|
||||
it neither selects map sources nor reads keys. Supply a visible credit container
|
||||
and retain all attribution required by the chosen sources. Cesium is external to
|
||||
this export: the consuming build must provide the same instance used elsewhere
|
||||
@@ -81,6 +85,119 @@ constructed component objects; the component instances themselves remain mutable
|
||||
`ready` means all constructors have returned. Background feed activity and the
|
||||
standalone share-restoration result keep their existing separate contracts.
|
||||
|
||||
## Pointer input
|
||||
|
||||
`gods-eye-view/input` exports `inputFor(viewer)`, the scene's one input
|
||||
dispatcher. Every layer and tool takes its pointer input from it, and so can
|
||||
the caller: one pointer handler per viewer, and a click picked once and
|
||||
handed to every subscriber.
|
||||
|
||||
```js
|
||||
import { inputFor } from 'gods-eye-view/input';
|
||||
|
||||
const input = inputFor(viewer);
|
||||
const off = input.onClick((event) => {
|
||||
if (event.ownerId === 'flights') showFlight(event.id);
|
||||
});
|
||||
// Later:
|
||||
off();
|
||||
```
|
||||
|
||||
`onClick` runs while no tool holds the pointer (the draw tool, the imagery
|
||||
box), so a vertex placed on an aircraft is not also a click on it. Its event
|
||||
reads lazily; a subscriber that reads nothing costs no pick:
|
||||
|
||||
| Member | What it is |
|
||||
| -------------------- | ------------------------------------------------------------------------- |
|
||||
| `screenPosition` | Where the user clicked, in CSS pixels; for DOM and overlay hit-tests |
|
||||
| `position` | Where that lands in the pick buffer (corrected under sensor styles) |
|
||||
| `gesture` | `{ travelPx, durationMs }` of the press, to tell a click from a drag |
|
||||
| `topHit` | The renderer's `Hit` on top at `position`, or `null` for the map itself |
|
||||
| `drawHit` | `topHit` when it is an item of a draw set, else `null` |
|
||||
| `hit` | `topHit`, or on a coarse pointer the contact under a surface pick |
|
||||
| `id`, `ownerId` | The hit's pick id and the layer that registered it, or `null` |
|
||||
| `meta` | The hit's own metadata, when it carries any |
|
||||
| `surface` | Whether the hit is the map itself |
|
||||
| `drill(limit)` | The draw-set `Hit`s under the click, shared by every subscriber |
|
||||
| `windowHit(w, h)` | `{ id, drawHit, surface }` of a pick over a `w`×`h` window |
|
||||
| `ground()` | The world position under the click, or `null` over the sky |
|
||||
| `native` | The renderer adapter's own `{ pick, pickWindow(w, h), drill(limit) }` |
|
||||
| `pick`, `pickWindow` | `native.pick` and `native.pickWindow`, for code bound to the engine picks |
|
||||
|
||||
A hit is the renderer contract's `Hit` (`src/render/contract/query.d.ts`).
|
||||
Something drawn outside the renderer's draw port is a `Hit` with `set: ''`,
|
||||
named by the adapter. Positions are plain `{ x, y }` objects. The dispatcher
|
||||
takes its pointer events from the renderer's input port and its picks from
|
||||
its query port, so a viewer with no renderer bound needs the Cesium adapter's
|
||||
factories loaded (`gods-eye-view/render/cesium/unbound`), or `inputFor` throws.
|
||||
|
||||
`onPointer(type, fn, { lease })` subscribes to `down`, `move`, `up`, `click`
|
||||
or `dblclick`; with a lease it runs only while that lease is current. A tool
|
||||
takes its lease with `claimPointer(ownerId, { onLost })` from the same export
|
||||
(and gives it back with `releasePointer(lease)`), which also keeps every
|
||||
ambient subscriber off its clicks; `isPointerFree()` and `pointerOwner()`
|
||||
report who holds it. The newest claim takes over, as on the renderer's input
|
||||
port: the tool holding the pointer has its `onLost` called once and turns
|
||||
itself off, and its late release frees nothing. `suspendCamera(reason)` and `suppressStockClicks()` return their
|
||||
own release: camera input and the viewer's stock select and double-click-track
|
||||
come back when the last hold is released, so two holders cannot undo each
|
||||
other. The renderer's input port owns the camera controller's `enableInputs`: a direct
|
||||
write (Cesium's camera flights make one when they start and end) is kept, but
|
||||
reads true only while no hold is out. A caller-supplied `createScene` that creates its own viewer registers
|
||||
`defer(() => inputFor(viewer).destroy())` right after it; the standalone scene
|
||||
does this and returns the dispatcher as `scene.input`.
|
||||
|
||||
## Height queries
|
||||
|
||||
`gods-eye-view/queries/heights` exports `heightsOf(viewer)`, the one place
|
||||
height queries go. Layers, tools and the camera ask it instead of asking the
|
||||
renderer's query port (`sampleHeight`, `sampleHeightNow`, `clampToSurface`)
|
||||
or the scene themselves, so how the renderer answers heights can change
|
||||
without touching them. Pass the viewer the renderer is bound to, not its
|
||||
scene. A viewer with no renderer bound is answered by the Cesium adapter's
|
||||
fallback once the caller has loaded `gods-eye-view/render/cesium/unbound`;
|
||||
until then, every query answers `null`.
|
||||
|
||||
```js
|
||||
import { heightsOf } from 'gods-eye-view/queries/heights';
|
||||
|
||||
const heights = heightsOf(viewer);
|
||||
const ground = heights.now({ lon, lat }, { exclude: [ownSetId] });
|
||||
if (ground !== null) place(ground);
|
||||
```
|
||||
|
||||
| Member | What it answers |
|
||||
| ----------------------------- | ------------------------------------------------------------------------- |
|
||||
| `now(point, opts)` | Height in metres from what is loaded, or `null` |
|
||||
| `clampNow(position, opts)` | The ECEF `{ x, y, z }` moved onto the drawn surface, or `null` |
|
||||
| `batch(points, opts)` | A promise of heights once the most detailed tiles stream; `null` per miss |
|
||||
| `clampBatch(positions, opts)` | A promise of clamped `{ x, y, z }` copies; `null` per miss |
|
||||
| `supported()` | `{ surface, clamp }`: whether the drawn surface can be queried at all |
|
||||
|
||||
A point is `{ lon, lat }` in degrees or `{ longitude, latitude }` in radians.
|
||||
`against: 'surface'` (the default) reads what is drawn, 3D tiles and globe;
|
||||
`against: 'terrain'` reads the loaded terrain alone; `against: 'tiles'` the
|
||||
tiles without the globe. Both `surface` and `tiles` include draw sets drawn
|
||||
with `includeInHeightQueries`; `clampNow` and `clampBatch` always clamp to
|
||||
the surface. `exclude` lists draw set ids to see through, of those drawn with
|
||||
`includeInHeightQueries`; every other draw set is seen through already. Every
|
||||
miss is `null`, and every caller treats it as one; `batch` and `clampBatch`
|
||||
reject when the query itself fails. Without depth-texture support the Cesium
|
||||
renderer answers no `surface` or `tiles` height; `now` still answers
|
||||
`terrain` from the loaded tiles, while `batch` misses terrain too.
|
||||
|
||||
## Cesium internals
|
||||
|
||||
The app reaches private Cesium fields only through
|
||||
`src/render/cesium/internals.js`, one named helper per field (the main and
|
||||
offscreen pick views, a billboard's collection, a cluster's point collection,
|
||||
the widget's render-loop latch, the WebGL context and whether a camera flight
|
||||
is under way). `internals.test.mjs` fails when the installed Cesium stops
|
||||
declaring one of them, and when a private field is reached anywhere else.
|
||||
Imagery that rations its tile requests states the policy as a hook with
|
||||
`withTileRequestHook(provider, { requestImage, credit })` from
|
||||
`src/render/cesium/tileRequests.js`, which leaves the provider untouched.
|
||||
|
||||
## Standalone wiring
|
||||
|
||||
`src/main.js` reads the existing browser configuration and starts
|
||||
|
||||
+25
-1
@@ -33,12 +33,13 @@ export inventory. Use declared exports rather than reaching into internal files.
|
||||
| `src/layers/<family>/` | Source acquisition, records and Cesium resources with explicit controller/renderer owners |
|
||||
| `src/sources/` | Portable protocols and source contracts; request state belongs to each factory instance |
|
||||
| `src/services/` | Supplied application operations; scene construction owns caches and cancellation |
|
||||
| `src/render/` | The renderer contract, the stub renderer, the conformance suite and Cesium renderer pieces |
|
||||
| `src/voice/` | Portable action schemas/session, common controls, action execution and separate protocol adapters |
|
||||
| `server/providers/` | Node route factories, process-scoped provider caches and shutdown cleanup |
|
||||
| `server/standalone/` | Environment, local settings writes and server composition |
|
||||
|
||||
See [application construction](APPLICATION.md) and the
|
||||
[infrastructure contract](INFRASTRUCTURE-LAYERS.md) for construction interfaces.
|
||||
[infrastructure contract](INFRASTRUCTURE-LAYERS.md) for construction interfaces, and the [renderer contract](RENDERER-CONTRACT.md) for what a renderer provides.
|
||||
|
||||
## Import direction gates
|
||||
|
||||
@@ -470,6 +471,13 @@ release listeners; pending action feedback is limited to its current owner.
|
||||
rendering, HUD and share operations. `src/standalone/controls.js` provides the running
|
||||
application's instances. The shell
|
||||
imports no standalone bootstrap or concrete live layer implementation.
|
||||
The shell reaches the renderer through its ports alone, and loads no
|
||||
renderer: given a viewer with no renderer bound, load
|
||||
`./render/cesium/unbound` once first, which also provides the celestial
|
||||
ring's precise ICRF rotation (`src/sky/icrf.js`; until then the ring uses
|
||||
the TEME approximation). Whether Cockpit's aircraft is an entity of the
|
||||
viewer's own is the `viewerDrawsEntity` service's to say; the application
|
||||
scene supplies it.
|
||||
Panel layout, position/drag, notices, recording and deferred UI work have separate
|
||||
owners with synchronous cleanup. Existing scene, share and HUD engines retain
|
||||
their entry points. `ui/styles` loads the ordered stylesheet entry; component
|
||||
@@ -507,6 +515,15 @@ perform no network requests and discover no additional modules.
|
||||
standard sources and their setup/fallback policy. The standalone facade wires
|
||||
these to the application's render governor.
|
||||
|
||||
`maps/imagery`, `maps/terrain` and `maps/3d` are the Cesium renderer's
|
||||
(`src/render/cesium/`). `maps/controller` and `maps/defaults` are
|
||||
Cesium-free: they make their scene changes and build their providers
|
||||
through the map engine the renderer provides as it loads
|
||||
(`src/maps/engine.js`). The application's renderer provides it; with a
|
||||
viewer with no renderer bound, load `./render/cesium/unbound` once first, or pass the
|
||||
engine as the controller's and `createDefaultMapSources`' `engine` option.
|
||||
Without one, constructing a controller throws, naming that export.
|
||||
|
||||
A registry supplies `sources`, `defaultId`, `unknownId` and optional `recoveryId`.
|
||||
Each source has a user-facing `descriptor`, availability/reason, and either an
|
||||
`imagery({ signal })` factory or a supplied `tileset`/`createTileset({ signal })`.
|
||||
@@ -571,6 +588,13 @@ separate from standalone setup. Scene construction returns these operations; the
|
||||
catalog and controls use the same surface owner. Layers still own their individual
|
||||
ground-snap caches and model resources.
|
||||
|
||||
The entry is Cesium-free: ground snapping and mesh floor sampling ask the
|
||||
renderer's globe (`isSettled`), camera (`pose`) and query (heights) ports, and
|
||||
see through the caller's draw sets by id. A viewer with no renderer bound needs
|
||||
the Cesium adapter's factories loaded (`gods-eye-view/render/cesium/unbound`)
|
||||
first; until then the snap and the sampler answer nothing and location framing
|
||||
throws, naming that export.
|
||||
|
||||
Terrain cancellation rejects late replies before caching, clears floor queues and
|
||||
removes the map-stack listener. Annotation lookup caches are instance-owned and
|
||||
cleared on cancellation. Geometry selection and floor policies are unchanged.
|
||||
|
||||
+324
-113
@@ -12,16 +12,17 @@ north.
|
||||
|
||||
While anything moves (a layer in motion, the camera, a followed contact), the
|
||||
globe draws at the display's own refresh rate; there is no fixed 60 FPS cap.
|
||||
The idle render governor (`src/renderGovernor.js`) caps a parked scene at
|
||||
`IDLE_FRAME_RATE` (60) ticks a second, because Cesium still runs the clock,
|
||||
data sources and update listeners on every animation frame even when it skips
|
||||
the draw; the viewer starts at that cap until the governor is installed. The
|
||||
camera holds continuous render from `moveStart` to `moveEnd`, and samples its
|
||||
The Cesium frame port (`src/render/cesium/ports.js`, its `idleFps`) caps a
|
||||
parked scene at `IDLE_FRAME_RATE` (60, `src/renderGovernor.js`) ticks a
|
||||
second while no hold is out, because Cesium still runs the clock, data sources
|
||||
and update listeners on every animation frame even when it skips the draw; the
|
||||
viewer starts at that cap until the frame port takes over. Through the idle
|
||||
render governor, the camera port holds continuous render from `moveStart` to `moveEnd`, and samples its
|
||||
pose every 250 ms in between, so a camera drifting by rounding errors (no
|
||||
`moveEnd`) is released after half a second at rest and held again if it moves. The world clock holds continuous render while
|
||||
it plays away from the live edge (not while it steps or waits for data), so
|
||||
playback draws at the display's rate too. Waits that used to count frames (a followed contact's first
|
||||
position, a shared follow view, a trail's temporary copy) count drawn time
|
||||
position, a shared follow view) count drawn time
|
||||
through `src/time/frameWait.js`, at most 100 ms a frame, so they last the same
|
||||
at any refresh rate and a background tab does not use them up.
|
||||
|
||||
@@ -101,7 +102,7 @@ does nothing, wherever it starts. Rotation drags that start on the planet, and
|
||||
zoom, are unchanged. How much of the frame shows the planet's surface is
|
||||
measured by casting a 32×18 grid of view rays at the ellipsoid; while the scope
|
||||
mask is on (the default) only the rays inside its keyhole count, since the mask
|
||||
hides or dims the rest. Voice tilt and in-place turns of a free 3D camera above
|
||||
hides or dims the rest. Voice tilt and in-place turns of a free camera above
|
||||
1,000 km stop when about a tenth of the frame still shows the surface (or about
|
||||
as much as it showed when it started), never less than about 1% of the visible
|
||||
frame, and a view that already shows less only keeps or gains what it has. A
|
||||
@@ -132,7 +133,7 @@ Views with more surface than that, such as the oblique orbital Director shots,
|
||||
are left as they are, and so are tracked or locked cameras, a camera flight in
|
||||
progress, a Director scene while it plays (holds included), a pointer held
|
||||
down on the globe (a drag held still; with several fingers down, until the
|
||||
last is released) and the 2D and Columbus modes; a check a flight, scene or
|
||||
last is released); a check a flight, scene or
|
||||
held pointer defers runs once it ends. A release outside the window that the
|
||||
page never sees counts as given once the window loses focus, the page is
|
||||
hidden, the canvas loses the pointer's capture, or the pointer moves with no
|
||||
@@ -143,6 +144,11 @@ it is until the next move. A voice turn requested while the camera is tracked is
|
||||
judged by the pose voice's release of the follow camera will leave, before that
|
||||
release, so a refused turn keeps the tracking.
|
||||
|
||||
The app draws only the 3D globe: the renderer it draws through has no 2D or
|
||||
Columbus view. Voice tilt, in-place turns and the move-end recovery above are
|
||||
written for that globe alone and carry no check for the other scene modes,
|
||||
which in Cesium's 2D and Columbus views made them do nothing.
|
||||
|
||||
Analyst region queries resolve unique Natural Earth names offline without
|
||||
geocoding, so Gold Coast and Ivory Coast name the West African natural regions.
|
||||
Duplicate names require a geocoded containment anchor; when several entries for
|
||||
@@ -1019,9 +1025,10 @@ resources and subscriptions. The globe relief helper is enabled with Wind and
|
||||
released when Wind is disabled. It uses terrain vertex normals
|
||||
for view-directed shading, falling back to global globe-curvature shading when
|
||||
normals are unavailable; the fallback does not show local hillshade. Neither mode
|
||||
adds elevation data or represents sunlight. Relief declines to replace an
|
||||
existing globe material, restores the prior empty material only while still
|
||||
owning it, and leaves later owners intact.
|
||||
adds elevation data or represents sunlight. Relief is the globe port's
|
||||
`hillshade` surface shading: the renderer never replaces a globe material
|
||||
someone else holds (it waits until that one is gone), gives the globe back
|
||||
when Wind is disabled, and leaves later owners intact.
|
||||
Source acquisition retains deadlines, body budgets, disconnect cancellation,
|
||||
per-model/field singleflight caching and one-minute failure backoff. Application
|
||||
catalog construction owns each instance.
|
||||
@@ -1225,7 +1232,7 @@ Keyless terrain tiles retry when Re:Earth throttles them. The browser fetches
|
||||
`terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain` directly; no
|
||||
proxy in this repository sees those requests (`/api/terrain/heights` is the
|
||||
separate point-height endpoint), and the upstream edge answers zoom-out bursts
|
||||
with HTTP 429 under load. `src/maps/terrain.js` hands Cesium a `Resource`
|
||||
with HTTP 429 under load. `src/render/cesium/mapTerrain.js` hands Cesium a `Resource`
|
||||
whose retry policy (`src/maps/terrainRetry.js`) every derived tile fetch
|
||||
inherits: 429, 502, 503 and 504 replies retry up to three times, 750 ms
|
||||
doubling to a 15 s cap, with every retry waiting behind one shared cooldown
|
||||
@@ -1600,7 +1607,9 @@ unchanged.
|
||||
Polled layer refreshes and the HUD's camera readout pause while the page is
|
||||
hidden. An app embedded inline in a panel keeps both running, because the
|
||||
panel's host can report the page as hidden while it is on screen. This is the
|
||||
same rule the render loop follows (`keepPanelRendering` in `app/embed.js`).
|
||||
same rule the render loop follows (`keepPanelRendering` in
|
||||
`render/cesium/panelRendering.js`, which the Cesium plugin hands the
|
||||
application and the application scene hands the embed views).
|
||||
|
||||
Application scene setup owns request services, terrain/floor caches and annotation
|
||||
lookup state. Controls, layers and voice share those owners, and cancellation
|
||||
@@ -1760,15 +1769,19 @@ The view pass reruns while the camera moves, paced by its own cost. The camera
|
||||
picker lists the cameras in view, active camera first, and closes with the
|
||||
count of cameras outside the view.
|
||||
|
||||
Traffic owns its rendered-surface observer only while enabled, removes it on disable/destroy, and caches surface identity without allocating on unchanged frames.
|
||||
Traffic owns its rendered-surface observer only while enabled, removes it on disable/destroy, and rebuilds no cached heights on frames where the surface identity is unchanged. Its dots and heat-lines are two renderer draw sets, it animates on the frame port's preRender, and it follows the camera through the camera port at its own 5% threshold rather than the shared `percentageChanged` ledger. The surface identity is the globe port's `surfaceVersion()` and tile readiness its `isSettled('surface')`, so the layer no longer reaches Cesium. Heat-lines are always asked for draped: where the Cesium renderer cannot drape (no depth textures) its draw port draws them (and every other draped line) over the surface, in their colour where the surface hides them and hidden past the horizon, recolouring a line in place when only its colour changes, rather than the layer dropping them.
|
||||
|
||||
Traffic and bikeshare expose factories through `./layers/traffic` and
|
||||
`./layers/bikeshare`. Traffic separates road requests, ingestion, animation,
|
||||
flow matching, styling, viewport lifecycle and development timing. Each source
|
||||
owns its decoded flow cache; cancelled bodies cannot refill it. Bikeshare
|
||||
separates its city registry, station source, parsing, rendering, selection and
|
||||
proximity lifecycle. Existing standalone sources, live/simulated labels, road
|
||||
budgets, station availability and polling behavior are retained.
|
||||
proximity lifecycle; its station dots and selected-station highlight are two
|
||||
renderer draw sets and it no longer reaches Cesium, so a caller handing it a
|
||||
Cesium viewer, with no renderer bound, loads the
|
||||
`./render/cesium/unbound` export once first. Existing standalone sources,
|
||||
live/simulated labels, road budgets, station availability and polling behavior
|
||||
are retained.
|
||||
|
||||
Installations and proximity context now expose `./layers/installations` and
|
||||
`./layers/awareness` factories. Each owns its records, selection, presentation,
|
||||
@@ -1787,6 +1800,13 @@ a fresh winning record. Dense removal clears only its own provenance, and a
|
||||
fresh core rebuild or lifecycle reset replaces the corresponding ownership.
|
||||
Source adapters retain the existing CelesTrak and Launch Library
|
||||
endpoints; standalone entries provide scene services and the satellite dependency.
|
||||
The satellites layer draws through the renderer's draw port and no longer
|
||||
reaches Cesium: the dots are one point set moved in a single write a frame, the
|
||||
tracked satellite's dot a set of its own drawn where the follow camera framed
|
||||
it, and the orbit rings a line set dimmed behind the globe and turned with the
|
||||
Earth each second. A caller handing it a Cesium viewer, with no
|
||||
renderer bound, loads the `./render/cesium/unbound` export once first.
|
||||
|
||||
The ISS (NORAD 25544, by number, not name) is drawn as NASA's 3D model within
|
||||
1,500 km of the camera and as its dot beyond; the two split the distance range,
|
||||
so exactly one draws (the tracked dot too). The model is at its real 109 m span
|
||||
@@ -1818,6 +1838,10 @@ chosen position or a 40 s orbit, fold the arrays and radiators as a labelled
|
||||
demonstration, aim the dishes and pose Canadarm2 by joint. Automatic, a new
|
||||
selection, the Cockpit or turning the layer off hand every joint back.
|
||||
The mission factory separates paths, replay, camera, panel, overlays and placement.
|
||||
Its markers, lines, live rings and pad zone are renderer draw sets, and it
|
||||
follows a mission through the camera port, so a caller handing it a Cesium
|
||||
viewer, with no renderer bound, loads the
|
||||
`./render/cesium/unbound` export once first.
|
||||
Launch Library pad coordinates retain unknown values: missing fields use the
|
||||
reported location coordinates when available, and launches without a known pad
|
||||
position stay off the map. Genuine zero coordinates remain valid. Undisclosed
|
||||
@@ -1838,10 +1862,16 @@ and scene services. Disable and teardown cancel pending refreshes; malformed
|
||||
snapshots preserve the last good display. Refresh restoration keeps selection
|
||||
identity without announcing a new user selection. Source/label, LOD thresholds,
|
||||
card limits, fire identities, altitude placement and analyst records are retained.
|
||||
The layer draws its fire glows through the renderer's draw port and no longer
|
||||
reaches Cesium; a caller handing it a Cesium viewer, with no
|
||||
renderer bound, loads the `./render/cesium/unbound` export once first.
|
||||
|
||||
Earthquake rendering is exposed through `./layers/earthquakes`. The layer owns
|
||||
its entities and request lifecycle; the application supplies the overlay host
|
||||
and snapshot source. The standalone adapter keeps the existing USGS daily feed,
|
||||
its renderer draw set and request lifecycle and no longer reaches Cesium; the
|
||||
application supplies the overlay host and snapshot source. A caller handing
|
||||
it a Cesium viewer, with no renderer bound, loads the
|
||||
`./render/cesium/unbound` export once first. `depthColor` returns a renderer
|
||||
colour `[r, g, b, a]` and `depthAccent` its CSS. The standalone adapter keeps the existing USGS daily feed,
|
||||
M2.5+ filtering, static discs, magnitude labels and analyst records. Disabling or
|
||||
destroying the layer cancels pending work and ignores late results. While on,
|
||||
the layer registers its quakes of magnitude 6 and up
|
||||
@@ -1852,6 +1882,21 @@ feed's place, cut to 40 characters (`earthquakeMarkLabel` in
|
||||
`src/layers/earthquakes/model.js`: `M6.4 · 113 km SSE of Lata, Solomon
|
||||
Islands`, or `M6.4` with no place).
|
||||
|
||||
Air quality (`./layers/air-quality`) draws its station discs as one renderer
|
||||
draw set of ground-clamped fills and reads the view through the camera port; it
|
||||
no longer reaches Cesium, so a caller handing it a Cesium viewer,
|
||||
with no renderer bound, loads the `./render/cesium/unbound` export once
|
||||
first.
|
||||
|
||||
Cockpit (`./ui/cockpit`) flies the camera through the camera port on the frame
|
||||
port's `preUpdate`, with the shared geo maths, and no longer loads the Cesium
|
||||
camera factory: a caller handing it a Cesium viewer, with no
|
||||
renderer bound, loads the `./render/cesium/unbound` export once first, or its
|
||||
controller throws naming it. Whether the aircraft it flies still draws comes
|
||||
from its `trackedEntityDrawn` service (the shell asks the entity's record,
|
||||
and the application scene's `viewerDrawsEntity` for an entity of the viewer's
|
||||
own); without one, Cockpit takes the aircraft as drawn.
|
||||
|
||||
## Rendered-mesh floor readings — November 9, 2026
|
||||
|
||||
On the photoreal stack the shared floor (`cachedGroundFloor`) answers from
|
||||
@@ -1876,12 +1921,26 @@ directly under a deck or a roof overhang reads the structure above it, and a
|
||||
vehicle between readings takes the nearest one, so its floor steps where the
|
||||
nearest reading changes.
|
||||
|
||||
The sampler and the aircraft ground snap (`src/services/groundSnap.js`) reach
|
||||
the renderer only through its ports: the camera's `pose()` for the probe
|
||||
height gate, the globe's `isGlobeVisible()` (the sampler runs only with
|
||||
the globe hidden) and `isSettled('surface')` (sampler) and
|
||||
`isSettled('tiles')` with `isSettled('surface')` (snap) for whether the tiles
|
||||
have streamed, and the query
|
||||
port's heights, seeing through the caller's draw sets by id. Cockpit's ground
|
||||
probe names the tracked contact's icon and model sets, which the flights and
|
||||
military layers keep on its entity record (`groundSets`).
|
||||
|
||||
## Vessel components and sources
|
||||
|
||||
`src/data/aisLiveVessels.js` assembles `createVesselLayer` from the
|
||||
`./layers/vessels` package entry. The factory owns feed lifecycle, keyed records,
|
||||
rendering, selection, trails and cards in separate components. The standalone
|
||||
entry supplies its AISStream source, scene services and existing row limits.
|
||||
Its ship icons are one renderer icon draw set (held motion, course rotation,
|
||||
focus emphasis, horizon cull) and the entry no longer reaches Cesium, so a
|
||||
caller handing it a Cesium viewer, with no renderer bound,
|
||||
loads the `./render/cesium/unbound` export once first.
|
||||
|
||||
Incomplete observations retain missing keyed vessels for at most five minutes
|
||||
since their last accepted receipt, within the renderer's row budget (plus the
|
||||
@@ -1937,31 +1996,29 @@ A tracked civil or military aircraft's trail (`src/data/trailContinuity.js`) lif
|
||||
the pen, drawing nothing, between two points more than 48 minutes or over 1,500 kt
|
||||
apart (a parked aircraft within 0.1 nm keeps one line for up to three hours) and at a
|
||||
waypoint with no altitude; a ground waypoint is drawn on the ground. The head joins the
|
||||
aircraft only within 150 km. Each trail keeps up to 2,000 points, a full day of history
|
||||
at one fix per minute plus the live session; past that the oldest recorded points go
|
||||
first, and the oldest reports only once none are left. The renderer
|
||||
aircraft only within 150 km. Each trail keeps up to 2,000 reports, a full day of history
|
||||
at one fix per minute plus the live session; past that the oldest go first. The renderer
|
||||
(`src/data/trailRenderer.js`) freezes every chunk of 128 points except the newest into
|
||||
static geometry, so a long trail costs about as much per frame as a short one;
|
||||
`scripts/qa-trail-freeze.mjs` checks that a freeze never shows a blank frame.
|
||||
While an aircraft is tracked, its trail between reports is the path its icon was
|
||||
drawn along: the displayed position is recorded about once a second or every 150 m
|
||||
(`recordTrailPoint`). Recorded points are thinned by shape: one stays only where
|
||||
dropping it would move the line more than 30 m across the track or in height from any
|
||||
position it stood for, or leave a straight piece longer than 10 km, so straight flight
|
||||
adds a vertex every 10 km at most and a turn keeps its curve. A recorded point that
|
||||
would turn the line back sharper than 120° over a short step is dropped. Reports stay
|
||||
in the trail as anchors, in time order. Recorded points never join two reports that are
|
||||
not one flight under the 48-minute and 1,500 kt rules; the points between them go and
|
||||
nothing is recorded across such a pair. A report for a time the display has already
|
||||
passed replaces what was drawn after it, and nothing is recorded until the icon has
|
||||
eased onto it, so the line reads arc, report, corrected path. History from before tracking started, and the backfill, run report to report.
|
||||
A trail holds the aircraft's reports and nothing else, in time order: what the icon was
|
||||
drawn at between them is never kept, so a late report cannot leave a kink. Between two
|
||||
reports that are one flight and both carry a track, the icon is drawn along, and the
|
||||
trail drawn through, one curve (`src/data/fixCurve.js`): a biarc, two constant-rate
|
||||
turns sent to the renderer as contract `arc` segments, passing through both reports and
|
||||
leaving each along its reported track, so the icon sits on its trail with no offset.
|
||||
Pairs with no track, slower than 40 m/s, or with a track more than 75° off the line
|
||||
between them are joined straight. The trail samples the curve at least every degree of
|
||||
turn. History from before tracking started, and the backfill, run report to report the
|
||||
same way.
|
||||
The trail never runs past the icon or through its 3D model, and the head runs from the
|
||||
newest kept point outside the model to the icon (to the model's tail when the model is
|
||||
the visual). A contact with no new report coasts along its reported track for 5 minutes
|
||||
past its last real report, at no more than 1,500 kt and never below known ground, then stops;
|
||||
the visual). A contact with no new report coasts straight on along its reported track for 5 minutes
|
||||
past its last real report (no turn: a turn rate measured over earlier reports outlives
|
||||
the turn), at no more than 1,500 kt and never below known ground, then stops;
|
||||
one that
|
||||
went quiet on the ground, or within 150 m of a known ground floor, holds at its last
|
||||
report, records nothing and draws no head (with the ground unknown, a low barometric
|
||||
report and draws no head (with the ground unknown, a low barometric
|
||||
altitude alone does not hold it). The hold-or-coast choice is made once per report (`staleHoldsForFix`
|
||||
in `src/data/motionModel.js`), and the forward fix built when a repeated position carries
|
||||
new speed or course follows the same rules and is never a trail report. A live report
|
||||
@@ -2305,10 +2362,13 @@ hidden; tilted past the Earth's limb neither the sensor nor the swath
|
||||
reads. A swath is confirmed only on the operator's, an agency's (ESA's
|
||||
eoPortal included) or an academic page for its platform. From
|
||||
16×, with flat imagery on the globe (not Google 3D tiles) and the view at
|
||||
nadir, every 2 s the view asks the base imagery layer for the tiles it will
|
||||
need 5 to 20 s ahead along the ground track (`prefetchImageryAhead` in
|
||||
`src/ui/cockpitOrbitalView.js`), so the browser has them cached when the
|
||||
view arrives. The level is the one Cesium will draw there
|
||||
nadir, every 2 s the Cesium renderer asks the base imagery layer for the
|
||||
tiles the view will need 5 to 20 s ahead along the ground track, so the
|
||||
browser has them cached when the view arrives. The renderer works this from
|
||||
its own camera (`preloadImageryAhead` in
|
||||
`src/render/cesium/imageryLookAhead.js`): a vertical field of view as narrow
|
||||
as an orbital view's at 16× for the camera's height, a look straight down,
|
||||
and the camera's own motion over the ground, which gives the track. The level is the one Cesium will draw there
|
||||
(`imageryLevelForView` in `src/cockpitOrbital.js`, following Cesium's own
|
||||
choice: the terrain level whose error spans at most the globe's maximum
|
||||
screen-space error, then the imagery level whose texels are nearest that
|
||||
@@ -2318,7 +2378,7 @@ at the lowest priority, so a request is declined while the imagery server's
|
||||
slots are taken by the tiles on screen and is the first dropped when the
|
||||
scheduler is full (a declined or dropped tile is asked for again later, one that failed to load is not); it remembers the last 512 tiles asked for and does not ask
|
||||
for those again, starts over on another base map (cancelling the old map's
|
||||
pending requests), and cancels the requests still pending on exit. Across the track it samples the centre line, a third
|
||||
pending requests), and when the view widens (below 16× or on exit) cancels the requests still pending and forgets the tiles asked for. Across the track it samples the centre line, a third
|
||||
out and the frame's edges. While tilted off nadir the view looks away from
|
||||
the track, and with the world clock more than a minute from now (paused or
|
||||
played back) it will not pass where the look-ahead points, so nothing is
|
||||
@@ -2574,6 +2634,14 @@ owners. Tuner calculations have a pure entry, with existing layer exports
|
||||
preserved. Destruction removes listeners and state subscriptions before ending
|
||||
tuning; a delayed Enable result cannot reveal or refocus removed controls.
|
||||
|
||||
The stations, their clusters and the selected marker draw through the
|
||||
renderer's draw port, and the layer no longer reaches Cesium. Stations drawn
|
||||
too close together on screen stand behind one cluster dot, grouped as the
|
||||
default renderer's entity clustering grouped them (`geo/screenCluster.js`,
|
||||
42 px, three or more), reclustered as the camera moves and when the filter
|
||||
changes. A caller handing the layer a Cesium viewer, with no
|
||||
renderer bound, loads the `./render/cesium/unbound` export once first.
|
||||
|
||||
## Giroc / Webcam Romania CCTV source pack
|
||||
|
||||
`config/cctv_sources.romania.json` is an optional single-camera pack for Giroc,
|
||||
@@ -2722,7 +2790,7 @@ and a Denver coordinate underground. Search now resolves the application's
|
||||
ground-floor elevation (bounded wait, same ellipsoidal datum) before framing and
|
||||
warms the cell; after landing, `src/cameraGroundGuard.js` samples the rendered
|
||||
surface under the target and the camera once tiles stream in and lifts the eye
|
||||
to 120 m clearance, holding heading and pitch. Navigation ownership changes (Director, tracking, keyboard/UI controls and direct camera flights), layer/app teardown, and pointer/wheel gestures cancel the check and remove its listeners. `scripts/qa-context-arrivals.mjs` types Camp Mabry
|
||||
to 120 m clearance, holding heading and pitch. Navigation ownership changes (Director, tracking, keyboard/UI controls), any other caller moving the camera or starting a flight before a retry, layer/app teardown, and pointer/wheel gestures cancel the check and remove its listeners; the guard compares the pose it started on rather than wrapping camera methods. `scripts/qa-context-arrivals.mjs` types Camp Mabry
|
||||
and a Denver coordinate and requires at least 60 m clearance.
|
||||
|
||||
## Layer panel ownership
|
||||
@@ -2737,10 +2805,11 @@ provides its confirmed toggle, taxa presets and fixed-order, nonempty legend.
|
||||
|
||||
## Sky background
|
||||
|
||||
`src/sky/starrySky.js` fills Cesium's `Scene#skyBox` slot with 9,096 Yale
|
||||
`src/render/cesium/starrySky.js` fills Cesium's `Scene#skyBox` slot with 9,096 Yale
|
||||
Bright Star Catalogue stars and a soft ESO/S. Brunier Milky Way. Both layers
|
||||
rotate from ICRF/J2000 into the Earth-fixed frame at the scene clock, with
|
||||
a TEME fallback while Cesium's IAU 2006 tables load. Bundled assets and
|
||||
a TEME fallback while Cesium's IAU 2006 tables load. The precise rotation reaches
|
||||
Cesium-free code (the celestial ring) through `src/sky/icrf.js`. Bundled assets and
|
||||
their provenance are documented in `src/data/local_data/sky/README.md`.
|
||||
|
||||
Anime fades out the Milky Way with its style intensity to avoid cel-shaded
|
||||
@@ -2777,7 +2846,7 @@ during viewer construction, before any tile builds a draw command.
|
||||
|
||||
When the globe stops drawing, the scene chrome says so instead of leaving a
|
||||
black globe behind working controls. `installRenderFailureNotice()`
|
||||
(`src/ui/renderFailure.js`) listens for Cesium's `renderError` and the canvas'
|
||||
(`src/render/cesium/renderFailure.js`) listens for Cesium's `renderError` and the canvas'
|
||||
`webglcontextlost`, logs the error, and publishes a notice that
|
||||
`RenderFailure.vue` shows as an alert dialog with focus on its first action.
|
||||
The app's viewer uses `showRenderLoopErrors: false`, so Cesium's dead-end
|
||||
@@ -2831,11 +2900,14 @@ remain unchanged.
|
||||
|
||||
## Visual effects ownership
|
||||
|
||||
VisualEffects owns style-stage creation, crossfades, animation scheduling, bloom
|
||||
and sharpen. Display supplies actions and renders settings; effect execution has
|
||||
no DOM dependency. Existing presets and the 500 ms transition remain unchanged.
|
||||
Stopping the controller revokes animation before asynchronous UI teardown; final
|
||||
destruction removes its stages and restores the borrowed bloom configuration.
|
||||
VisualEffects keeps the records of the styles, their crossfades, bloom and
|
||||
sharpen, and drives them through the renderer's effects port: it defines each
|
||||
preset there as a style, and the renderer runs the passes and animates the
|
||||
animated ones. Display supplies actions and renders settings; effect execution
|
||||
has no DOM dependency. Existing presets and the 500 ms transition remain
|
||||
unchanged. Stopping the controller revokes animation before asynchronous UI
|
||||
teardown; final destruction removes its styles and turns bloom and sharpen off,
|
||||
and the renderer restores the scene's bloom configuration when it goes.
|
||||
Snow is no longer a visual preset. A share link that names it, in either the
|
||||
long or compact form, opens on Normal and drops the Snow shader parameters. A
|
||||
view passed to embed mode or `show_in_gods_eye_view`, and a saved scene shot,
|
||||
@@ -3711,9 +3783,14 @@ which embeds the MAP_KEY.
|
||||
windows reuse the active load. Disabling or returning Contacts to passive mode
|
||||
clears its anchor; passive refreshes cannot reclaim it. Background repaints
|
||||
refresh context records without publishing a new selection.
|
||||
Installation tiles decode only the `landuse` layer. Reloads keep the Cesium
|
||||
entities of sites whose geometry is unchanged, so outlines and fills do not
|
||||
blink. While Contacts has a subject, the layer loads a window around it
|
||||
Installation tiles decode only the `landuse` layer. The site dots, the
|
||||
selected site's dot (a set of its own, so selecting one redraws no other),
|
||||
their ground outlines and the selected site's fill are renderer draw sets;
|
||||
reloads keep the drawn items of sites whose geometry is unchanged, so
|
||||
outlines and fills do not blink. The layer no longer reaches
|
||||
Cesium; a caller handing it a Cesium viewer, with no
|
||||
renderer bound, loads the `./render/cesium/unbound` export once first.
|
||||
While Contacts has a subject, the layer loads a window around it
|
||||
instead of the camera view (100 km half-width at mid latitudes, shrinking so
|
||||
it fits 16 z9 tiles), moves it only after the subject travels 20 km, and
|
||||
ignores camera `moveEnd`; clearing the subject returns to the viewport. The
|
||||
@@ -3870,9 +3947,12 @@ which embeds the MAP_KEY.
|
||||
> so a turned-off layer's entities stayed reachable (Data Centers kept 116
|
||||
> MiB). `src/sceneCommandRelease.js`, installed in `src/app/tools.js`,
|
||||
> requests one frame through `governorRequestRender` after every layer
|
||||
> disable and then trims those arrays. It reads private Cesium fields;
|
||||
> `src/sceneCommandRelease.test.mjs` pins them and fails if Cesium renames
|
||||
> them or changes which passes it truncates.
|
||||
> disable and then has `src/render/cesium/sceneCommandRelease.js` (handed
|
||||
> handed over by the Cesium plugin through `src/app/scene.js`) trim those
|
||||
> arrays. It reads private Cesium
|
||||
> fields through `src/render/cesium/internals.js`;
|
||||
> `src/render/cesium/sceneCommandRelease.test.mjs` pins them and fails if
|
||||
> Cesium renames them or changes which passes it truncates.
|
||||
|
||||
> **2026-08-08 — performance waves 1+2:** the app idles via an explicit render
|
||||
> governor (`src/renderGovernor.js` — hold/release from every per-frame
|
||||
@@ -4280,7 +4360,7 @@ isCurrent })` gates BOTH halves of the map-stack switch, which is its only
|
||||
> tunnels. Every other layer
|
||||
> is untouched: aircraft, vessels and satellites draw their markers over the
|
||||
> scene on purpose and keep their labels over it. The test runs on the GPU
|
||||
> (`src/data/sceneOcclusionProbe.js`): one occlusion query per contact,
|
||||
> (`src/render/cesium/sceneOcclusionProbe.js`): one occlusion query per contact,
|
||||
> repeated every 100 to 200 ms, answered a frame or two later, with nothing
|
||||
> read back from the GPU and so no stall. A contact hides as soon as a
|
||||
> "hidden" answer arrives and returns 600 ms after its last one, which keeps
|
||||
@@ -4717,18 +4797,22 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with
|
||||
> it, and narrow screens retain Cesium's surface with an internal
|
||||
> scroller. The title, close control, links, and persistent Google/Cesium line
|
||||
> remain unchanged and visible.
|
||||
> - **Distant-aircraft recession:** both civilian and military billboard fleets
|
||||
> - **Distant-aircraft recession:** both civilian and military icon sets
|
||||
> retain their locked class/ground scale and `NearFarScalar`, then multiply a
|
||||
> limb-relative taper in the existing ~12 Hz tick. The taper is 1 below 0.5×
|
||||
> limb-relative taper. The sets say so themselves (`SetSpec.recede`, with
|
||||
> the tuning as its parameters, sent again when the tuning changes), and the
|
||||
> renderer works the taper out each frame from `render/recession`. The
|
||||
> taper is 1 below 0.5×
|
||||
> geometric limb distance and smoothsteps to 0.45 scale plus a 0.35 alpha-haze
|
||||
> factor at the limb. That treatment eases continuously back to identity from
|
||||
> 3,500–4,500 km camera height, avoiding a globe-view threshold pop. These
|
||||
> values, the start ratio, blend band, composed floor, and write epsilon remain
|
||||
> runtime tunings. No aircraft is count-culled or made fully transparent.
|
||||
> Focus emphasis and limb haze multiply at one deadband-gated write site, and
|
||||
> their product is clamped to 0.20 before freshness alpha is applied. Ambient
|
||||
> fleet models receive that same composed alpha; class/ground/cockpit repaints
|
||||
> preserve the current limb scale instead of dropping it for a tick.
|
||||
> Focus emphasis and limb haze multiply, and their product is clamped to
|
||||
> 0.20 before freshness alpha is applied. Ambient fleet models receive that
|
||||
> same composed alpha, worked out on each fleet tick from the camera then
|
||||
> and written again once it moves by more than 0.005; their set itself does
|
||||
> not recede. Under the IR boost they draw at full alpha.
|
||||
> - **Focus-aware contact de-emphasis:** civilian/military aircraft and
|
||||
> satellites publish the selected target's padded screen bounds and camera
|
||||
> distance from the same per-frame position cache already consumed by their
|
||||
@@ -4815,10 +4899,13 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with
|
||||
> untracking, so a stationary slow press on a plane still selects it. Escape
|
||||
> still releases tracking in place. The 200 px feel needs close-range field
|
||||
> verification; fleet model sizing remains unchanged.
|
||||
> - **Deterministic sprite stacking:** contact collections reassert the stable
|
||||
> bottom-to-top order CCTV, FIRMS, bikeshare, AIS, military, then civilian
|
||||
> flights after every relevant layer init/enable and immediately after FIRMS
|
||||
> lazily registers its detection sprites. Always-visible contact
|
||||
> - **Deterministic sprite stacking:** contact sets are made at draw orders
|
||||
> (`SetSpec.drawOrder`, from `spriteDrawOrder`) that stack them bottom to
|
||||
> top as CCTV, FIRMS, bikeshare, transit, directions, AIS, military, then
|
||||
> civilian flights on top, whichever layer was turned on first; picks
|
||||
> name the topmost first. The orders are negative, so every overlay at the
|
||||
> default order (selection highlights, route endpoints, the tracked plane)
|
||||
> still draws over all of them. Always-visible contact
|
||||
> depth settings are unchanged. Cesium OIT weighted blending may soften strict
|
||||
> alpha layering on some GPUs, so the ordering remains a real-browser check.
|
||||
> - **Deterministic card stacking:** CCTV, FIRMS, vessel, and tracked-target
|
||||
@@ -4975,8 +5062,14 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with
|
||||
> celestial ring, annotations SVG, missions frame tick, and traffic).
|
||||
> - **World-label accounting:** All intended label/card migrations use the
|
||||
> shared host. The former native `LabelGraphics` exception for cable reference
|
||||
> labels was retired on 2026-08-18; cable text may render over tile geometry,
|
||||
> so **zero native world-label creation sites remain**. The mission replay DOM vehicle, awareness
|
||||
> labels was retired on 2026-08-18; cable text may render over tile geometry.
|
||||
> The Directions A/B letters (`directions-markers` source) and data-pack media
|
||||
> labels (a pooled `data-pack-labels:<n>` source per pack resource, through
|
||||
> the pack handle's `label`) moved to the host on 2026-11-04, and
|
||||
> `src/noCesiumLabels.test.mjs` no longer keeps an allow-list, so **zero
|
||||
> native world-label creation sites remain**. A media pack shown without an
|
||||
> `overlayHost` fails to load rather than drawing a native label. The mission
|
||||
> replay DOM vehicle, awareness
|
||||
> compass, annotation SVG callouts, and host-owned detection isolation target
|
||||
> are explicit exceptions; the awareness ring and cockpit contact pips are
|
||||
> non-text out-of-scope surfaces. Annotation callout text, geometry, leaders,
|
||||
@@ -5024,7 +5117,7 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with
|
||||
> ambient-label host source. Its getter reads the point's own position, which
|
||||
> moves every frame, eliminating the former second ISS
|
||||
> propagation. Satellite tracking continues to publish exactly one protected
|
||||
> tracked-lane card through `gevLabelModel` and `_trackedDisplayCached`; the
|
||||
> tracked-lane card through its entity record's `labelModel` and `_trackedDisplayCached`; the
|
||||
> tracked entity is point-only. Tracking ISS suppresses the ambient entry and
|
||||
> untracking restores it, preventing duplicate ISS text. Disable, orbit-text
|
||||
> preference changes, catalog rebuild, and destroy clear/hide the source.
|
||||
@@ -5039,7 +5132,7 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with
|
||||
> - **Phase 5 tracked civil aircraft label:** A tracked flight's Cesium entity
|
||||
> is a billboard-only camera target with no native label. The flight source
|
||||
> retains callsign/registration fallback, flight-level/altitude, speed, stale
|
||||
> state, airline/type, and plausible-route formatting in `gevLabelModel`; the
|
||||
> state, airline/type, and plausible-route formatting in the entity record's `labelModel`; the
|
||||
> one protected tracked-lane host card renders that complete model. Its
|
||||
> position getter reads only `_trackedDisplayCached`, the same authoritative
|
||||
> Cartesian already consumed by the tracked visual and camera, and never
|
||||
@@ -5149,8 +5242,11 @@ down | auth-failed` (plus the unchanged `missing-key`/`unsupported`) with
|
||||
> - **Tracked-readout ownership:** `trackedReadout.js` is now a presentation-model
|
||||
> bridge only; it owns no canvas, projection, post-render listener, layout,
|
||||
> keyhole fade, or paint path. Civilian flights, military flights, satellites,
|
||||
> and mapped installations write explicit `gevLabelModel` objects and expose
|
||||
> `gevDisplayPosition` getters backed by their layer-owned frame/display cache.
|
||||
> and mapped installations write explicit `labelModel` objects and
|
||||
> `displayPosition` getters, backed by their layer-owned frame/display cache,
|
||||
> into the app's entity records (`src/data/entityRecords.js`), never onto the
|
||||
> Cesium entity. A layer's private per-entity state goes in its own store from
|
||||
> `createEntityStore()` (ALPR markers: `src/layers/alpr/markerState.js`).
|
||||
> Selected AIS vessels continue using the vessel source's protected selected
|
||||
> card, so they do not create a duplicate tracked readout. The host registers
|
||||
> the active readout in the protected tracked lane with a zero ambient quota;
|
||||
@@ -5561,8 +5657,8 @@ centre. Camera reads debounce for 600 ms with a monotonic 2.5 s minimum gap;
|
||||
nearby views share whole-degree cache keys, and a minute poll refreshes data.
|
||||
Counts and bands cover visited views over 30 minutes, including regions now off
|
||||
screen. Cells are H3 resolution-4 hexagons, gpsjam.org's grid, keyed by their H3
|
||||
index (`gnssCellKey`) and drawn from `cellToBoundary` (via `h3-js`) as one ground
|
||||
primitive of polygons, rebuilt only when a cell or band changes; a cell across the
|
||||
index (`gnssCellKey`) and drawn from `cellToBoundary` (via `h3-js`) as clamped
|
||||
polygons in one shapes set of the draw port, redrawn only when a cell or band changes; a cell across the
|
||||
antimeridian is drawn with its longitudes unwrapped around its centre. As on
|
||||
gpsjam.org there is no minimum aircraft count: every cell with an aircraft is
|
||||
shown, and the one-aircraft discount is the only small-sample guard.
|
||||
@@ -6052,13 +6148,14 @@ the same navigation authority as every other camera destination.
|
||||
given; re-arming for the other endpoint reuses that lease rather than asking
|
||||
for a second claim, and every release names the lease, so a superseded instance
|
||||
can never free the claim its replacement holds. The claim is held until
|
||||
the click that uses it has finished being dispatched — every layer binds its
|
||||
own handler to the same canvas and they all run inside one browser event, so a
|
||||
claim dropped the instant the endpoint is placed would hand the rest of that
|
||||
same click to the ambient handlers bound after this one. It is returned on the
|
||||
next tick after placement, and immediately on cancel, Escape, CLEAR, disable
|
||||
and destroy; if another tool already holds it nothing is armed and the row says
|
||||
so. Maneuver-dot selection is an ordinary ambient handler and yields while any
|
||||
the click that uses it has finished being dispatched: the input dispatcher
|
||||
checks the claim once per click, before any subscriber runs, but DOM canvas
|
||||
listeners (the evidence cards) still see the same browser event afterwards, so
|
||||
a claim dropped the instant the endpoint is placed would hand them that click.
|
||||
It is returned on the next tick after placement, and immediately on cancel, Escape, CLEAR, disable
|
||||
and destroy. The newest claim takes over: arming takes the pointer from a tool
|
||||
holding it, which is told and turns itself off, and a newer tool taking it
|
||||
disarms the layer as Escape would. Maneuver-dot selection is an ordinary ambient handler and yields while any
|
||||
tool holds the pointer. FLY runs through the UI shell's immediate-navigation
|
||||
facade — the same camera authority validated voice destinations use — and is
|
||||
handed the shared ground-floor read and corridor warm, so the dolly does not
|
||||
@@ -6253,11 +6350,27 @@ synchronizes visible playback before its next frame.
|
||||
Playback reserves numeric scratch before the first sample, including unknown
|
||||
heights, and reuses caller-owned sample and segment storage.
|
||||
|
||||
**Scene work.** Stationary and animated billboards use separate, adjacent
|
||||
collections above CCTV and Bikeshare. Traffic, Bikeshare and Transit share camera
|
||||
sensitivity claims; the original sensitivity returns after the last release.
|
||||
Visibility checks combine the camera frustum and ellipsoid occlusion at no more
|
||||
than 4 Hz; missing map bounds do not admit the globe's far side. Camera arrivals
|
||||
**Scene work.** Stationary and animated vehicles are two draw-port icon sets
|
||||
(`transit:<n>:still` and `transit:<n>:moving`), made at adjacent draw orders
|
||||
from the sprite order (`spriteDrawOrder`), above CCTV and Bikeshare. Each marker
|
||||
is a plain record (position, show, image, size, colour, rotation); a frame
|
||||
writes the changed ones to their set in one batched upsert, markers taken out
|
||||
in one task go in one removal, and a marker that starts or stops moving moves
|
||||
between the sets. The renderer moves and turns an icon without restyling it.
|
||||
Rotation is computed in screen space through the query port's projection
|
||||
(`perspectiveCourseRotation`), as before. Clicks read the draw-port hit. The
|
||||
layer no longer reaches Cesium, so a caller handing it a Cesium viewer,
|
||||
with no renderer bound, loads the `./render/cesium/unbound` export
|
||||
once first. Transit listens to the camera port at its own `changed` threshold
|
||||
(0.05); the port measures each listener separately, so no layer changes
|
||||
another's camera trigger.
|
||||
Visibility checks combine the camera port's frustum and the query port's
|
||||
ellipsoid occlusion at no more than 4 Hz; missing map bounds do not admit the
|
||||
globe's far side. Whether the globe is the bare ellipsoid is asked of the
|
||||
height service at the camera's subpoint each time the globe's surface
|
||||
changes; the answer comes asynchronously, the last one holds until then, and
|
||||
floors are read again when it flips.
|
||||
Camera arrivals
|
||||
rebuild an unprepared or cold marker corridor during that visibility sweep,
|
||||
adopt a loaded surface, and update both heightPending and surfaceReady diagnostics.
|
||||
A resolved display sample clears its pending-height gate without waiting for a poll. Frame work
|
||||
@@ -6288,7 +6401,8 @@ it does not establish Google 3D acceptance.
|
||||
The full run samples completed frames at 1920×1080 CSS pixels, records DPR, and
|
||||
measures moving fleets of 800 and 3,000 vehicles with 128 fixes each and DETECT
|
||||
on. Street/metro targets are respectively: transit frame CPU p95 ≤1/4 ms, frame
|
||||
interval p95 ≤20/25 ms, billboard uploads ≤256 KiB/1 MiB per frame, and retained
|
||||
interval p95 ≤20/25 ms, billboard uploads ≤256 KiB/1 MiB per frame (counted by
|
||||
`src/render/cesium/uploadProbe.js` for the two marker sets), and retained
|
||||
heap growth ≤24/48 MiB. The 3,000-vehicle CPU budget is 4 ms (recorded browser
|
||||
measurement 3.4 ms); the 800-vehicle budget stays at 1 ms (measured 0.9 ms).
|
||||
Transit-authored frame allocation is ≤8 KiB/frame at both fleets, attributed
|
||||
@@ -6926,7 +7040,7 @@ silently demoting every later lookup for the session.
|
||||
|
||||
- The internal Context coordinator is available in every visual style. Its dedicated right-side `CONTEXT` chooser exposes the neutral shell; the coordinator is not duplicated in Data Layers and does not enable a live-data dependency until a mode is selected.
|
||||
- The expanded `CONTEXT` view offers mutually exclusive `CONTACTS` and `SPACE MISSIONS` modes. Selecting `CONTACTS` enables the context-owned Flights, Military Flights, AIS Vessels, and Mapped Installations dependencies only when they are not already user-enabled; selecting `SPACE MISSIONS` enables the recent-launch layer and its Satellite dependency. `CONTACTS` cycles the nearest supported contact of whatever type is selected. Satellites are deliberately excluded from those Awareness cohorts and keep their own tracking UX. Selecting the active mode again returns to the neutral chooser and releases only mode-owned dependencies.
|
||||
- If a civilian or military aircraft is already tracked when `CONTACTS` becomes operational, that source-owned track is adopted as the Context subject before nearest-contact autofocus. Context rechecks the tracker after its dependencies settle, so a newer selection wins, while an explicit clear during activation prevents fallback from silently selecting a replacement. Cockpit entry remains unavailable until that Context transaction has settled, so its camera takeover cannot clear Cesium tracking before adoption. Adoption does not recreate tracking or transfer camera ownership; it initializes the normal 250 km ring, history, proximity results, and Cockpit Previous/Next state for the original aircraft.
|
||||
- If a civilian or military aircraft is already tracked when `CONTACTS` becomes operational, that source-owned track is adopted as the Context subject before nearest-contact autofocus. Context rechecks the tracker after its dependencies settle, so a newer selection wins, while an explicit clear during activation prevents fallback from silently selecting a replacement. Cockpit entry remains unavailable until that Context transaction has settled, so its camera takeover cannot clear Cesium tracking before adoption. Adoption does not recreate tracking or transfer camera ownership; it initializes the normal 250 km ring, history, proximity results, and Cockpit Previous/Next state for the original aircraft. With no tracked aircraft, an AIS vessel already selected (the vessel layer's `getSelectedInfo()`) becomes the subject, at activation and again when a deferred dependency settles, exactly as a vessel selected while `CONTACTS` is on; no nearest flight is picked and the camera is not moved.
|
||||
- `SEARCH NEARBY SITES` retains the bounded OSM results and makes one user-initiated, view-biased Google Maps Places text search for “military installation.” Google results are source-stamped, deduplicated against OSM by rounded location/name, and remain mapped context rather than operational claims. If Places is unavailable or the API is not enabled for the supplied key, OSM context remains available. A view across the antimeridian is searched around its own centre, with a radius from its real width.
|
||||
- The Context header holds only its title and collapse control. It no longer carries a Radio shortcut or a compact Radio player: Radio is the `RADIO` section inside the panel, with its own disclosure and the single `ENABLE` power control. Cockpit keeps its own compact Radio utility.
|
||||
- Context is set for reading in every theme: mode, standby and action labels are 10 px, and the panel draws no glow halo. Outside Cyber, the two modes form one segmented control, the standby guidance is plain left-aligned text rather than a dashed placeholder, and the panel's section titles share the side panels' dock-label colour. Cyber keeps its separately framed mode buttons, its red panel titles, and in layout-focus a framed, centred standby card over its radar art.
|
||||
@@ -6937,7 +7051,7 @@ silently demoting every later lookup for the session.
|
||||
- On activation it focuses the nearest currently observed aircraft across the civilian and military feeds, with military winning an exact distance tie; if none are available, it focuses an observed AIS vessel. The aircraft search is deliberately uncapped and one refresh-tick retry handles initially empty feeds. This is an attention-priority navigation shortcut, not a high-risk, affiliation, or threat classification.
|
||||
- A selected aircraft, AIS vessel, or mapped installation gets a 250 km **context window** with nearby cohort counts, nearest examples, source labels, and stale/unavailable reasons. It emits `NEARBY` or `UNKNOWN`; no detection, engagement, affiliation, or sensor-activity conclusion is calculated.
|
||||
- Contacts rows and the Cockpit Contact counts name each cohort's provider: the source of the last snapshot, marked `FALLBACK` or `STALE` as its layer row would be. A poll in flight keeps the mark, where the layer row shows `LOADING`. A flight snapshot from the adsb.lol regional fallback reads `adsb.lol · FALLBACK`, not `OpenSky`.
|
||||
- The window's edge is drawn on the globe as a 250 km range ring: a 4 px polyline with a 2 px Context-blue core inside a 1 px dark halo on each side, 2.5 km above the ellipsoid (`AWARENESS_RANGE_RING_STYLE` in `src/layers/awareness/policy.js`). The halo keeps it legible over bright desert and snow, dark ocean and forest, and under the FLIR, NVG and CRT styles, where the earlier 1 px ellipse outline disappeared. It is a polyline because WebGL draws ellipse outlines at 1 px whatever width is asked for, drawn as an unpickable primitive rather than an entity so a click or tap on its edge reaches the contact underneath (headless viewers without a primitive collection get a static entity instead); it is rebuilt when the subject moves. Three dim sonar pulses (3 px with a 1 px dark outline, same colours, at most 60% opacity) grow slowly from the subject at constant speed, one every 3 s and each taking 9 s, and arrive at the ring at about a third of that. Behind each pulse a radial gradient in the same blue fades inward over 35% of the radius. One unpickable 250 km disc draws both the pulse lines and the gradient, its shader reading the pulse radii and opacities each frame, so a click or tap near a pulse still reaches the contact underneath; the disc follows the subject by a model-matrix rotation and is rebuilt only after the subject moves 20 km, and not at all while the pulses rest. While the camera is below the disc's 2.5 km height, where it would sweep across the sky, the pulses rest: the disc is hidden and there is no ring flash, no echo and no frame request. Terrain or 3D tiles higher than 2.5 km (the Alps, Andes, Rockies) still cut through the disc and the ring when seen from above, as the ring alone already did; the height check uses the camera's height above the ellipsoid, not above the ground. While pulses run, the ring dims to 40% and flashes to full strength as each pulse reaches it, fading over 1.8 s. As a pulse front crosses a flight, military aircraft or AIS vessel, the detection overlay draws a second bracket around that contact's own bracket, in the pulse blue on the default detection style and in the style's own line colour under NVG, FLIR and CRT, which spreads outward as it fades over 1.4 s (`AWARENESS_RANGE_ECHO`, read through `src/awarenessEcho.js`; no layer's icon is restyled, and mapped installations have no detection bracket). Pulses are born 5 km out, so the subject itself and anything nearer never echo. Pulses run for 9 s (three ring flashes) after a selection or a camera move, fading in and out over 1.2 s, then rest: the ring stays on screen at full strength, the pulses, gradient and echoes are hidden, and nothing asks for frames, so a parked Contacts view is quiet again. Only a camera move within 1.5 s of the user handling the map (pointer, wheel or touch on the Cesium canvas, which covers a drag's inertia, and a drag or touch begun there keeps counting until its last finger or button lifts, even outside the canvas, unless the window loses focus or the page is hidden first; keys typed elsewhere do not count, nor does input while Cesium's camera controls are off, as in the cockpit view, and a gesture still pending when the cockpit or another owner takes the camera is dropped) wakes them; a moving subject and the app's own camera moves (a tracked aircraft, the cockpit view, an orbit, a fly-to) do not, since they move on every refresh. While they run they never hold continuous rendering: each drawn frame arms one render request 80 ms later (the Cyber sonar cadence, `CYBER_SONAR_RENDER_INTERVAL_MS`), so they repaint at about 12.5 fps and never beat the detection lane's 80 ms gate. Under `prefers-reduced-motion`, or in a scene without primitives or preRender and postRender hooks, there are no pulses or echoes and the ring stays on screen; changing the preference mid-session rebuilds the ring. The ring follows a moving subject once it has moved 250 m.
|
||||
- The window's edge is drawn on the globe as a 250 km range ring: a 4 px polyline whose outer 1 px, half a pixel on each side, is a dark halo around a 3 px Context-blue core, 2.5 km above the ellipsoid (`AWARENESS_RANGE_RING_STYLE` in `src/layers/awareness/policy.js`). The halo keeps it legible over bright desert and snow, dark ocean and forest, and under the FLIR, NVG and CRT styles, where the earlier 1 px ellipse outline disappeared. It is one outlined line in an unpickable draw-port line set (`src/layers/awareness/rangeRing.js`), so a click or tap on its edge reaches the contact underneath; the halo is the line's own outline, so the translucent core and halo never darken where they meet; it moves when the subject moves. Three dim sonar pulses (3 px with a dark edge half a pixel wide on each side, same colours, at most 60% opacity), each an outlined line in the same set, grow slowly from the subject at constant speed, one every 3 s and each taking 9 s, and arrive at the ring at about a third of that. Behind each pulse a radial gradient in the same blue fades inward over 35% of the radius: one unpickable flat ellipse 2.5 km up with 270 km semi-axes, filled with a 256-pixel canvas painted with the band (two canvases in turn, each under a new key). The ellipse stands until the subject has moved 20 km from where it was built, the canvas keeping the band concentric with the subject meanwhile, and not at all while the pulses rest. Fronts and band are fixed in the world, so they step every 80 ms however many frames are drawn and look the same whether the camera moves or not; crossing the 2.5 km rim height shows or hides them at once. While the camera is below the band's 2.5 km height, where it would sweep across the sky, the pulses rest: the band and fronts are hidden and there is no ring flash, no echo and no frame request. Terrain or 3D tiles higher than 2.5 km (the Alps, Andes, Rockies) still cut through the band and the ring when seen from above, as the ring alone already did; the height check uses the camera's height above the ellipsoid, not above the ground. While pulses run, the ring dims to 40% and flashes to full strength as each pulse reaches it, fading over 1.8 s. As a pulse front crosses a flight, military aircraft or AIS vessel, the detection overlay draws a second bracket around that contact's own bracket, in the pulse blue on the default detection style and in the style's own line colour under NVG, FLIR and CRT, which spreads outward as it fades over 1.4 s (`AWARENESS_RANGE_ECHO`, read through `src/awarenessEcho.js`; no layer's icon is restyled, and mapped installations have no detection bracket). Pulses are born 5 km out, so the subject itself and anything nearer never echo. Pulses run for 9 s (three ring flashes) after a selection or a camera move, fading in and out over 1.2 s, then rest: the ring stays on screen at full strength, the pulses, gradient and echoes are hidden, and nothing asks for frames, so a parked Contacts view is quiet again. Only a camera move within 1.5 s of the user handling the map (pointer, wheel or touch on the Cesium canvas, which covers a drag's inertia, and a drag or touch begun there keeps counting until its last finger or button lifts, even outside the canvas, unless the window loses focus or the page is hidden first; keys typed elsewhere do not count, nor does input while Cesium's camera controls are off, as in the cockpit view, and a gesture still pending when the cockpit or another owner takes the camera is dropped) wakes them; a moving subject and the app's own camera moves (a tracked aircraft, the cockpit view, an orbit, a fly-to) do not, since they move on every refresh. While they run they never hold continuous rendering: each drawn frame arms one step 80 ms later (the Cyber sonar cadence, `CYBER_SONAR_RENDER_INTERVAL_MS`) whose changes ask for the frame that draws them, so a parked view repaints at about 12.5 fps, one frame a step, and never beats the detection lane's 80 ms gate. Under `prefers-reduced-motion`, or on a renderer without frame hooks, there are no pulses or echoes and the ring stays on screen; changing the preference mid-session rebuilds the ring. The ring follows a moving subject once it has moved 250 m.
|
||||
- For a selected live aircraft or vessel, the context window refreshes from the existing tracker/feed position every 750 ms, so nearest distances and cohort counts follow the subject without introducing a duplicate poll loop.
|
||||
- Aircraft cohort membership uses every locally loaded, selectable contact inside the 250 km window, including a plane hidden only by horizon culling or because its 3D model owns the visual. Counts and navigation therefore do not change with the current camera angle or billboard/model handoff.
|
||||
- Nearby examples in the context panel are focus controls: they use their owning layer's existing selection/tracking path, then frame that contact. Static-installation distances use ellipsoidal surface distance so the count matches the ground-projected context disk.
|
||||
@@ -6953,8 +7067,8 @@ silently demoting every later lookup for the session.
|
||||
|
||||
### Motion & Symbology Correctness (June 10, 2026)
|
||||
|
||||
- **Flights (commercial + military)** render one poll interval behind real time (30s/15s) and interpolate between two known feed-stamped fixes (OpenSky `time_position`; adsb.lol `receipt − seen_pos`). The display latency is an intentional product decision — do not "fix" it away. The fleet dead-reckons at ~12Hz (1m² write gating); a contact already hidden behind the horizon whose last position still is re-reckons on a staggered one-in-13-ticks rotation (about once a second) instead, so the worldwide feed's ~13k contacts no longer cost a full pass when well under 1% are on screen. Anything that position puts in view, and any contact with a fleet model, takes the full pass immediately, and hidden-inclusive proximity queries read positions at most about a second old; aircraft get a 3-poll grace period (faded icon) before removal, except the tracked aircraft, which is kept until 10 minutes after its newest fix. When a position epoch pauses, both layers coast for five minutes on the last speed and heading (at most 1,500 kt), then stop dimmed as SIGNAL LOST; contacts on or near known ground hold instead. Source backoff marks each contact and the cockpit `STALE` and dims the tracked aircraft, as a missed update does; the cockpit then holds the exact layer position instead of continuing inertial flight. Repeated-position kinematic changes create a forward-only synthetic fix rather than mutating history, and grounded history is lifted only when no owned 3D model already controls its datum. A nominally successful worldwide OpenSky response whose own snapshot epoch is more than two minutes old prefers the existing 250-nm viewport-scoped adsb.lol fallback and labels the source/coverage accordingly when that upstream is available. If the fallback is also unavailable, the layer's freshness/error fields use the source epoch—never the cache receipt time—so the UI reports an old snapshot rather than “just now.”
|
||||
- **World-space headings at every angle** (`src/data/iconOrientation.js`): aircraft/vessel icon rotation uses the camera right/up basis per tick (alignedAxis always ZERO), which is exact at screen center and for orthographic/nadir views and remains stable through >180° tracked orbits. Perspective rays vary across the viewport, so off-center contacts at oblique pitch can diverge from an exact finite-difference window projection; a regression test pins that known regime, and field evidence decides whether to adopt exact projection with the basis method as fallback. Fleet rotations refresh on camera-pose change; tracked entities per frame. Billboards are horizon-culled via a shared EllipsoidalOccluder.
|
||||
- **Flights (commercial + military)** render behind real time and interpolate between two known feed-stamped fixes (OpenSky `time_position`; adsb.lol `receipt − seen_pos`). The delay (`src/data/displayDelay.js`) follows how late the feed is: the 90th percentile of the newest 256 lags (a report's receipt time less the same contact's previous report time) plus 5 s, never under the layer's floor (30 s civil, 15 s military) nor over five minutes, so the anonymous OpenSky feed, whose reports arrive about 90 s old every 30 s, draws about two minutes behind. Before 16 lags, first reports' ages plus a poll interval stand in. The delay moves toward that aim by at most 0.2 s per second up and 0.05 s per second down (an aim within 2 s leaves it be), and takes it at once only while nothing is drawn; deliveries following the world clock, or replacing the world at another time, leave it alone and draw with no delay. Every consumer (icons, the renderer's live motion clock, labels, HUD, detection, the tracked camera and trail) reads the one delay. When a newer report puts a moving contact elsewhere than it is drawn (it was coasting past its newest report), it eases onto the new path over at least 3 s, at most 30% faster than its speed and within 20 s, from where it would have been that frame; more than 5 km off, it jumps. The display latency is an intentional product decision — do not "fix" it away. The whole fleet dead-reckons at ~12Hz (1m² write gating); aircraft get a 3-poll grace period (faded icon) before removal, except the tracked aircraft, which is kept until 10 minutes after its newest fix. When a position epoch pauses, both layers coast for five minutes on the last speed and heading (at most 1,500 kt), then stop dimmed as SIGNAL LOST; contacts on or near known ground hold instead. Source backoff marks each contact and the cockpit `STALE` and dims the tracked aircraft, as a missed update does; the cockpit then holds the exact layer position instead of continuing inertial flight. Repeated-position kinematic changes create a forward-only synthetic fix rather than mutating history, and grounded history is lifted only when no owned 3D model already controls its datum. A nominally successful worldwide OpenSky response whose own snapshot epoch is more than two minutes old prefers the existing 250-nm viewport-scoped adsb.lol fallback and labels the source/coverage accordingly when that upstream is available. If the fallback is also unavailable, the layer's freshness/error fields use the source epoch—never the cache receipt time—so the UI reports an old snapshot rather than “just now.”
|
||||
- **World-space headings at every angle** (`src/data/screenRotation.js`; the scene-reading helpers in `src/render/cesium/iconOrientation.js`): aircraft/vessel icon rotation uses the camera right/up basis per tick (alignedAxis always ZERO), which is exact at screen center and for orthographic/nadir views and remains stable through >180° tracked orbits. Perspective rays vary across the viewport, so off-center contacts at oblique pitch can diverge from an exact finite-difference window projection; a regression test pins that known regime, and field evidence decides whether to adopt exact projection with the basis method as fallback. Fleet rotations refresh on camera-pose change; tracked entities per frame. Billboards are horizon-culled via a shared EllipsoidalOccluder.
|
||||
- **Military/OpenSky reconciliation** (`src/data/militaryRegistry.js`): known-military ICAOs render amber in the flights layer (60s self-poll of the cached mil endpoint when the military layer is off) and are suppressed there while the military layer renders them.
|
||||
- **Satellites**: core catalog from CelesTrak's stations, visual, GPS, GLONASS, Galileo, GEO, resource, weather, planet, SAR and science groups, tracking lands ~726km out via `viewFrom` (tracked entity owns a point graphic so the tracking camera engages), rings realign via primitive modelMatrix (no per-second rebuild flicker), optional `setParams({catalog:'dense'})` Starlink mode.
|
||||
- **Satellite classes** (`src/layers/satellites/classes.js`): every satellite is filed under one of six classes, each with its own point colour, legend swatch and toggle: STATIONS (warm white), IMAGING (cyan), TELECOM (violet; communications and navigation, so GPS, GLONASS, Galileo and BeiDou read as one family), STARLINK (dim slate), PROBES (muted blue-gray) and DEBRIS (receding brown-gray). That module is the single source of truth for class, label and colour, so the dot, the card and the legend swatch cannot disagree. Two deliberate palette rules: no class may sit in the 40–48° amber band, which is the app-wide known-military convention; and STARLINK stays far below PROBES in Rec.601 luminance so the dense shell stays separable when NVG/FLIR collapse the scene to one channel. The ISS keeps its long-standing red hero dot rather than the STATIONS colour — it carries a permanent name label and its card still reads `STATIONS · ISS`; it is a station whichever group ingested it, so a stations-feed outage cannot refile it. `src/data/satelliteClass.js` keeps the group-based labels beneath the classes: the constellation subtype and a group's own label for a satellite with no class.
|
||||
@@ -7606,8 +7720,8 @@ request viewbox and continues searching without that geographic preference.
|
||||
|
||||
- UTILITIES ▸ **Draw** turns the globe into a whiteboard drawn by hand. Pick a shape (icon buttons for Area, Line and Pin) and a colour swatch for the next shape, click the vertices on the real world, and finish. **Keyboard contract, live only while Draw is on and never while you are typing in another field:** Enter finishes the shape (as does a double-click, and the two cannot both submit it — the session is replaced before the annotate call is awaited); Backspace removes the last vertex; Esc cancels the shape in progress, and a second Esc — Esc on an empty session — leaves draw mode. **Clear** wipes the board (the shape in progress and every placed mark), so removing marks does not require the console or the microphone.
|
||||
- **Drawn shapes are listed under Draw like Import's files** (`src/ui/views/panels/DrawMarkList.vue`, rows worded by `presentDrawMarks` in `src/annotations/drawMarks.js`): one row per hand-drawn mark (`manual: true`; voice marks are not listed) with its colour swatch, its name, and show/hide, fly-to and remove. The draw tool publishes the rows with the rest of its controls and answers the row actions (`renameDrawMark`, `recolorDrawMark`, `toggleDrawMark`, `flyToDrawMark`, `removeDrawMark`) through the display store; it republishes on the engine's `onChange`, so a voice clear or an expiry updates the list. Rows are keyed and updated in place: a board change never takes a name being typed (the field keeps its draft while focused) or the button under a click. The name is saved on Enter or on leaving the field, once; Esc restores it, before anything else and with the row's colours open too. Both keep focus in the field, so neither drops it to the page or leaves Draw. The swatch opens the five colours right after it (shown at the end of the row), with the current colour focused; the arrows, Home and End try another, and a click or Esc closes them and returns focus to the swatch. Both colour groups (the next shape's and a row's) are one `DrawSwatches` radio group with a single tab stop, coloured from `DRAW_COLOR_CSS`; on touch screens each dot answers a 24 px target. An unnamed shape shows its kind, and an unnamed line its length; a renamed line keeps its length (`Ridge walk — 950 m`). **Hidden** keeps a mark on the board at alpha 0, and the world renderer takes every one of its entities out (`show = false`), so no material that keeps its own colour (the line's flowing stroke) still paints it; the screen renderer does not project a hidden callout, so it cannot push a visible label aside; `fly_route` skips a hidden route; and with every mark hidden the annotations render hold is released. **Fly to** is an immediate navigation (`runImmediateNavigation('drawing', …)`), like Import's: Cockpit refuses it and a running orbit, follow or track lets go first. A line is framed by its whole path, across the antimeridian too.
|
||||
- Runtime entry: `createApplicationTools` (`src/app/tools.js`, behind the `src/standalone/tools.js` shim) calls `initDrawTool({ viewer, annotations, navigation, publish, connect, markActions })` after `initAnnotations` and defers its `destroy()`, so disposing the shell returns every DOM listener, the Cesium handler, the preview data source, the borrowed click actions and the `window.__gevDrawTool` handle. Its controls are Vue views in the UTILITIES panel (`DrawControls.vue`, `DrawMarkList.vue`) that render what the tool publishes to the display store and call its actions. That handle (`setActive`, `setShape`, `addVertex(lon, lat)`, `finish`, `cancel`, `clearAll`, `marks`, `setColor`, `diagnostics`) is the no-mouse test seam.
|
||||
- **The pointer, for an application's own tool.** `createApplicationTools` also returns `pointer` (`data/inputOwnership.js`): `claim(owner)` takes the pointer as Draw does and returns its lease, or `null` while another tool holds it; `release(lease)` gives it back; `isFree()` lets the application's own click handlers yield, as the layers' do. An owner without a name in `pointerOwnerNames.js` is named by its id when another tool reports who holds the pointer.
|
||||
- Runtime entry: `createApplicationTools` (`src/app/tools.js`, behind the `src/standalone/tools.js` shim) calls `initDrawTool({ viewer, annotations, navigation, publish, connect, markActions })` after `initAnnotations` and defers its `destroy()`, so disposing the shell returns every DOM listener, the pointer subscriptions, the preview draw sets, the borrowed click actions and the `window.__gevDrawTool` handle. The live preview (a dashed rubber band, dashed behind the surface too through the line's `depthFail` style, and a dot per vertex) is two sets on the renderer's draw port, so the tool no longer reaches Cesium; the rubber band follows each move's `pickPosition`, the dispatcher's sensor-corrected pick-buffer point, as clicks do. Its controls are Vue views in the UTILITIES panel (`DrawControls.vue`, `DrawMarkList.vue`) that render what the tool publishes to the display store and call its actions. That handle (`setActive`, `setShape`, `addVertex(lon, lat)`, `finish`, `cancel`, `clearAll`, `marks`, `setColor`, `diagnostics`) is the no-mouse test seam.
|
||||
- **The pointer, for any other tool.** `createApplicationTools` also returns `pointer` (`data/inputOwnership.js`): `claim(owner, { onLost })` takes the pointer as Draw does, from any tool holding it, and returns its lease; `onLost` is called once when a newer claim takes it, and the tool turns itself off there; `release(lease)` gives it back; `isFree()` lets the application's own click handlers yield, as the layers' do.
|
||||
- **Row actions are an application's own.** `createApplicationTools({ drawMarkActions })` hands `initDrawTool` buttons for drawn areas' and lines' rows; the standalone shell passes none, so the open-source build shows no new button and makes no new request. Each action (`drawMarkActions` in `src/annotations/drawMarks.js`) is `{ id, icon, label(name), shapes: ['area', 'line'], accepts?(geometry, shape), run({ id, shape, name, title, geometry }) }`: the icon a Material Symbols name, the label worded by the application, `name` the person's own and `title` the row's (the name, else `Area` or `Line · 950 m`), the geometry `drawMarkGeometry`'s `[lon, lat]` `Polygon` (closed; a `MultiPolygon` for an area handle with several parts) or `LineString`, longitudes wrapped into [-180, 180]. A pin, and a shape that crosses the antimeridian or has a part that cannot be given whole, has no geometry and is offered nothing. Malformed actions and repeated ids are dropped once, at construction. What `run` returns or resolves to is a note under the row (`role=status`; past 200 characters it is cut at a word with an ellipsis); the row is busy (`aria-disabled`, no second press) until it settles, a rejection or a throw clears the note and is logged (so an action words its own refusals and resolves with them), and a shape's note goes with the shape, so a late answer never lands on a removed one.
|
||||
- Contract: a finished shape is submitted through the SAME `annotationEngine.annotate()` the voice agent uses, with geometry supplied and `manual: true` (`type: area` + `ring`, `type: route` + `path`, `type: pin` + coordinates). `resolveSpec` short-circuits manual specs (`resolveManualSpec`) so no geocoder, Places or Overpass call is made. A drawn area is a real (not synthesized) outline and drapes solid; a drawn line is a `route` with `mode: 'manual'`, labelled with its length and never a travel time; a pin is a point. Drawn marks therefore render with the whiteboard look, persist, appear in `.list()`, and clear with `clear_annotations` / `.clear()`. A drawn shape is never merged with another as a duplicate: every one is drawn on purpose, and every one is unnamed until its row names it, so two pins dropped close together are two pins.
|
||||
- **A vertex is a lon/lat, and the mark is DRAPED.** Clicks are picked through `pickWorldFromScreen` — one of two scene helpers the annotation resolver factory (`src/annotations/resolver.js`) exposes alongside `sampleGroundHeight`, so the app has ONE depth-aware pick cascade rather than a second written beside it — which returns the height the pick landed on as well as the coordinate, so the live preview hangs on the roof or hillside under the pointer instead of sinking to sea level. The world renderer draws areas and routes with `clampToGround`, so the height is dropped at finish in one place (`finishSpec`) rather than being carried downstream and discarded silently: what you get is the outline you drew, lying on the surface beneath it.
|
||||
@@ -7617,9 +7731,10 @@ request viewbox and continues searching without that geographic preference.
|
||||
- **Measurements and centres are computed on unwrapped longitudes** (`unwrapLongitudes` / `wrapLongitude` in `drawMode.js`, used by `ringAreaM2`, `ringCentroid` and the engine's manual-area anchor). A ~50,000 m² rectangle straddling the antimeridian reads its 0.002° width as 359.998° under raw arithmetic: it measured thousands of square kilometres and anchored on the Greenwich meridian, half a world from the shape. Path length was already safe — haversine is periodic in the longitude delta — and a test pins that so a "fix" cannot break it.
|
||||
- **Bounds.** One shape holds at most `MAX_VERTICES` = 512 points; two clicks within 0.5 m are one vertex (that is what makes a double-click finish without leaving a stray point); a vertex that is not a finite on-globe coordinate is refused. A shape that encloses nothing is refused rather than placed: three collinear points are not an area and a line under a metre long is not a line, and the hint says which.
|
||||
- Drawn-area measures round before choosing m², ha or km², so 9,999.6 m² displays as `1.0 ha`, not `10000 m²`, and 999,960 m² as `1.00 km²`, not `100.0 ha`.
|
||||
- Pointer ownership: while a session is open the tool holds the single pointer claim (`claimPointer('draw')`, `src/data/inputOwnership.js`) and **every** ambient scene selection handler — the shared tracking click gesture behind flights, military and CCTV, plus vessels, satellites, launches, fires, installations, bikeshare, radio, submarine cables, the bundled GeoJSON layers and the CCTV calibration gizmo — returns before picking. A vertex over an aircraft is a vertex, not a selection.
|
||||
- **The claim is a LEASE.** `claimPointer(owner)` returns an opaque token or `null`; `releasePointer(lease)` takes that token. A second claim fails even under the same owner name, because two live instances of one tool — an old one mid-teardown and its replacement — are two owners; releasing by name let the old instance free the claim its successor was holding, and every layer started selecting through the live session's vertices. A superseded lease now releases nothing.
|
||||
- **Cesium's own click actions are borrowed too.** The Viewer binds a selecting LEFT_CLICK and a tracking LEFT_DOUBLE_CLICK on its own handler, outside every layer and therefore outside the shared claim — guarding the layers alone still left a drawn vertex selecting the entity under it. Both are removed for the session and restored, as the same function objects, when it ends or the tool is destroyed.
|
||||
- Pointer ownership: while a session is open the tool holds the single pointer claim (`claimPointer('draw')`, `src/data/inputOwnership.js`), and the scene's input dispatcher (`src/input/dispatcher.js`) hands its clicks, moves and double clicks to the draw tool's leased subscriptions only: **every** ambient subscriber — flights, military, CCTV and its calibration gizmo, vessels, satellites, launches, fires, installations, bikeshare, radio, submarine cables, the bundled GeoJSON layers — is skipped for that event before anything is picked. A vertex over an aircraft is a vertex, not a selection.
|
||||
- The input dispatcher no longer reaches Cesium. It takes its pointer events from the renderer's input port (`findInput`, `src/render/rendererOf.js`) and its picks, drills and ground points from the query port, with positions as plain `{x, y}`. A click's hits are the contract's `Hit`; something drawn outside the draw port is a `Hit` with `set: ''` that the Cesium adapter names (`src/render/cesium/nativeClick.js`), which also hangs the engine's own picks on `event.native` (`pick`, `pickWindow`, `drill`, through the follow helper) for layers still bound to them. The adapter's pick reuses the query port's pass for the same pixel, window and frame, so an empty click still costs one pick pass; a sky click makes no depth pass unless a globe tile is on its ray. A touch tap's contact search drills Cesium's own picks, eight deep, so something drawn outside the draw port still stops it or is found by it.
|
||||
- **The claim is a LEASE, and the newest claim takes over.** `claimPointer(owner, { onLost })` returns an opaque token; `releasePointer(lease)` takes that token. A second claim, even under the same owner name, ends the lease out, and its holder's `onLost` is called once, after the new lease holds the pointer: Draw turns off as if toggled off (the half-drawn shape and preview go, the stock clicks come back), the imagery box cancels, and Directions disarms. Two live instances of one tool — an old one mid-teardown and its replacement — are two owners, so the replacement wins; releasing by name let the old instance free the claim its successor was holding, and every layer started selecting through the live session's vertices. A superseded lease releases nothing. This is the renderer contract's rule (`input.claimPointer`), and the two are one: each scene's input dispatcher bridges its renderer's input port (`bridgePointer`), so the port holds a lease while a tool holds the pointer (the port is not free), and a claim made on the port itself takes over from the tool like any newer claim. That lease takes no press itself: the dispatcher decides who hears each event when it arrives, as each layer's own handler used to (a click reaches ambient selection only if no tool holds the pointer then, and a tool's subscribers only while its lease is current), and Cesium's own select and double-click follow run unless the tool holds them off (`suppressStockClicks`: Draw and the imagery box do, Directions does not).
|
||||
- **Cesium's own click actions are suppressed too.** The Viewer binds a selecting LEFT_CLICK and a tracking LEFT_DOUBLE_CLICK on its own handler, outside every layer and therefore outside the shared claim — guarding the layers alone still left a drawn vertex selecting the entity under it. The tool takes the dispatcher's `suppressStockClicks()` hold for the session; both actions come back, as the same function objects, when the last hold is released (the imagery box takes the same hold).
|
||||
- **Enter belongs to whatever has the keyboard.** The finish key is taken only from the canvas and the page body. With a control focused — Clear, a shape button — Enter activates that control, as a keyboard user expects; it does not quietly finish the shape.
|
||||
- Pure half: `src/annotations/drawMode.js` (session, minimum vertices, double-click de-dup at 0.5 m, vertex ceiling, degenerate-geometry refusal, ring closing, dateline-safe length/area/centroid, hint text). Regression surface: `src/annotations/drawMode.test.mjs` and `src/data/inputOwnership.test.mjs` (pure), `src/annotations/drawToolBehaviour.test.mjs` (the tool driven against DOM and viewer doubles — leases, borrowed input actions, teardown, the Enter key, preview heights), `src/annotations/drawTool.test.mjs` (structural: where files live, which ids the markup carries, what the docs may claim), and the rendered harness `scripts/qa-draw-tool.mjs`.
|
||||
- The annotation tree is a declared ownership group: `./annotations` → `src/annotations/index.js` in `package.json`, with its module graph listed in `scripts/package-boundaries.json`, so an annotation module reaching outside that graph is a gate failure rather than a surprise in a layer's bundle. `drawMode.js`, `drawTool.js` and their tests are in `scripts/format-scope.json`.
|
||||
@@ -7644,14 +7759,14 @@ request viewbox and continues searching without that geographic preference.
|
||||
- Only a new head costs REST calls: one recursive tree and one commit. An optional `GITHUB_TOKEN` raises the REST limit.
|
||||
- After an upstream outage, a successful branch-head check clears the error and pushes a recovered catalog even when the commit is unchanged. Cached products stay in place; subsequent healthy unchanged checks stay silent.
|
||||
- The new catalog goes to `.gev-cache/ghostmaps/catalog.json` and to every open page over server-sent events (`/api/ghostmaps/events`, 25 s heartbeat, at most 64 subscribers). Default products are downloaded at once.
|
||||
- The layer reloads only products whose blob changed. The new edition's data source is added before the old one is removed. A product that leaves the catalog leaves the globe.
|
||||
- The layer reloads only products whose blob changed. The new edition's draw sets are added before the old ones are removed. A product that leaves the catalog leaves the globe.
|
||||
- The row reads `LIVE` while the stream is open. A five-minute catalog read is the backstop.
|
||||
- **Files.** `/api/ghostmaps/file/{product}` serves only catalog products. Files are downloaded by commit-pinned raw URLs, so a CDN cannot return an older edition. They are cached on disk by blob sha, and blobs no current product uses are pruned. A request whose `?v=` names the current blob is `immutable`. Repository paths never reach the page.
|
||||
- **Source ownership.** The application catalog receives `sources['s2-ghostmaps']` through the shared source contracts; an omitted or null source stays unavailable without opening a stream or fetching. The standalone source factory supplies the same-origin implementation and accepts replacements. Packed-image URLs are released on cancelled or failed product construction, and remain owned by a successfully loaded product until it is removed.
|
||||
- **Voice and locales.** S2 can be toggled through its registered id and aliases. The model already sees the S2 GhostMaps brand in the id, and compact alias-hint separators keep the complete voice prompt within its existing 52,000-character limit; accepted aliases are unchanged. The row and reports are translated in Spanish, Russian and Simplified Chinese.
|
||||
- **Rendering.** The page parses the KMZ with the import module's zip, KMZ and XML helpers into one `CustomDataSource` per product.
|
||||
- Points become ground-clamped billboards with the depth test off, so they never sink into terrain or 3D tiles. Because the Google 3D map hides the globe, nothing else would stop far-side pins drawing through the planet. Pins are therefore horizon-culled with Street Level's `createHorizonCull` before their first frame and again whenever the camera moves.
|
||||
- Lines and polygon outlines are ground-clamped polylines.
|
||||
- **Rendering.** The page parses the KMZ with the import module's zip, KMZ and XML helpers into renderer draw sets (icons, lines and shapes) per product edition. The layer no longer reaches Cesium, so a caller handing it a Cesium viewer, with no renderer bound, loads the `./render/cesium/unbound` export once first.
|
||||
- Points become ground-clamped icons with the depth test off, so they never sink into terrain or 3D tiles. Because the Google 3D map hides the globe, nothing else would stop far-side pins drawing through the planet. Pins are therefore horizon-culled with Street Level's `createHorizonCull` before their first frame and again whenever the camera moves.
|
||||
- Lines and polygon outlines are ground-clamped lines; polygon fills are ground-clamped shapes.
|
||||
- Styles, StyleMaps and inline styles are honoured. Icons come only from images packed in the same KMZ and at most 512 KB. Anything else uses a per-product round marker.
|
||||
- Network links, overlays, models and remote hrefs are never followed. Hidden placemarks are skipped. Bounds are 20,000 placemarks and 250,000 positions per product.
|
||||
- **Reports.** Clicking a marker opens a card with the product, folder, edition date and the placemark's report fields. `src/layers/ghostMaps/records.js` reads ArcGIS popup tables as text only: `<Null>` and internal fields are dropped and values are capped. Description markup is never inserted into the page. The first `http(s)` research link opens from the card. The card is `stateless`, so it comes and goes with the click, as CCTV cards do. It is also `horizonCull`ed, so it hides when its marker turns behind the planet. Picks are registered under `s2-ghostmaps`.
|
||||
@@ -7660,14 +7775,15 @@ request viewbox and continues searching without that geographic preference.
|
||||
### Import Your Own Files (October 2026)
|
||||
|
||||
- UTILITIES ▸ **Import** reads GeoJSON (`.geojson`/`.json`), KML, KMZ and GPX from the picker or a file drop anywhere in the app. Each file gets show/hide, Fly-to and Remove controls. GeoJSON and GPX use the row's color; KML/KMZ retain their styles and show a hatched swatch. The file bytes remain on the device for the page session. Rendered overlays can appear in map screenshots sent through voice or other existing screenshot tools.
|
||||
- **Ground and height.** GeoJSON XYZ coordinates become ground footprints. KML ground lines/rings are tessellated; static recorded tracks preserve their original vertices, segment gaps and explicit altitude modes. KML with absolute/relative altitude keeps that meaning. Ground pins resolve in batches of 256 against loaded terrain and, in the nearby camera footprint on photoreal maps, `clampToHeightMostDetailed`, then draw in one owned native BillboardCollection per file, with static positions and no per-frame point Entity visualizer or clamping callbacks. Point metadata remains in `dataSource.importedEntities` for framing/style inspection; non-point geometry stays in the normal source collection. Pin collections mount only after source admission, follow file show/hide, and are destroyed on removal. Settled camera/map-source changes and completed terrain loads refresh visible files through the same serial queue; distant points retain their latest available height. No detailed worldwide terrain sweep is started. Nearby mesh sampling can add requests/time; configured photoreal providers require separate validation. The depth test is disabled for ground pins, matching Draw's marker visibility policy.
|
||||
- **Ground and height.** GeoJSON XYZ coordinates become ground footprints. KML ground lines/rings are tessellated; static recorded tracks preserve their original vertices, segment gaps and explicit altitude modes. KML with absolute/relative altitude keeps that meaning. Ground pins resolve in batches of 256 through the height service: the loaded terrain's height (0 on the bare ellipsoid, whose coarse tiles can sag far below it) and, in the nearby camera footprint on photoreal maps, the mesh height (`clampBatch`). They then draw as static icons in the file's own draw sets (pins, lines and shapes), with no per-frame clamping callbacks. GeoJSON lines and polygon edges follow rhumb lines, split into steps of at most half a degree. Each file's sets mount only after admission, follow its show/hide, and are removed with it. Settled camera/map-source changes and completed terrain loads refresh visible files through the same serial queue; distant points retain their latest available height. No detailed worldwide terrain sweep is started. Nearby mesh sampling can add requests/time; configured photoreal providers require separate validation. The depth test is disabled for ground pins, matching Draw's marker visibility policy.
|
||||
- **Navigation.** Row Fly-to uses `runImmediateNavigation('file', …)`; Cockpit can refuse it and existing follow/track ownership is released first. Automatic Fly-to is stamped when a batch is submitted and reasserted before flying. Pointer/wheel gestures and newer navigation supersede it, including time spent in the queue. Framing uses every finite visible point/path/polygon-hole/wall vertex plus rotated overlay bounds, with viewport-aware range and a nadir view. The target uses available terrain/cached ground height and the ground guard on arrival. Empty footprints never fall back to deferred `viewer.flyTo`.
|
||||
- **Clock.** Imports expose no source clock and no entity availability. KML times/view metadata are removed before loading; recorded tracks become static lines. GPX segments remain separate and GPX times are ignored. The shared clock stays unchanged.
|
||||
- **Input handling.** Coordinates and GeoJSON geometry types are checked before Cesium allocation. Only short plain names reach GeoJSON property bags; file IDs, custom CRS and styling properties are removed. KML feature/geometry IDs are removed while Style/StyleMap references remain. Local style references are trimmed, incomplete style pairs removed, hidden-folder flags normalized to the import's show control, and unsupported prototype-named elements removed. UTF-16 BOMs and common KML namespace export defects are handled. Empty drawable content is refused. A loader failure or timeout does not hold the next file indefinitely; teardown aborts pending waits.
|
||||
- **References and images.** File-authored remote links/icons/styles, network links, models and screen/photo overlays are removed. Packed KMZ and embedded PNG/JPEG/GIF/WebP/BMP images remain local; decoded dimensions are checked before image decoding against a total 16-megapixel and 8,192-pixel-side budget per file. Blocked IconStyle images fall back to local pins; authored empty icons remain empty. Colored overlays without an Icon survive; overlays with a removed external image are dropped. Metadata, native labels and descriptions are removed, and generated pins share one lossless image URL per canvas.
|
||||
- **Clock.** Imports keep no clock and no time ranges: everything in a file draws at all times. KML times/view metadata are removed before loading; recorded tracks become static lines. GPX segments remain separate and GPX times are ignored. The shared clock stays unchanged.
|
||||
- **Input handling.** Coordinates and GeoJSON geometry types are checked before anything is drawn. Only short plain names reach GeoJSON property bags; file IDs, custom CRS and styling properties are removed. KML feature/geometry IDs are removed while Style/StyleMap references remain. Local style references are trimmed, incomplete style pairs removed, hidden-folder flags normalized to the import's show control, and unsupported prototype-named elements removed. UTF-16 BOMs and common KML namespace export defects are handled. Empty drawable content is refused. A loader failure or timeout does not hold the next file indefinitely; teardown aborts pending waits.
|
||||
- **References and images.** File-authored remote links/icons/styles, network links, models and screen/photo overlays are removed. Packed KMZ and embedded PNG/JPEG/GIF/WebP/BMP images remain local; decoded dimensions are checked before image decoding against a total 16-megapixel and 8,192-pixel-side budget per file. Blocked IconStyle images fall back to local pins; authored empty icons remain empty. Colored overlays without an Icon survive; overlays with a removed external image are dropped. Metadata, labels and descriptions are removed; only a short plain name reaches a drawn item. The default pins are shared SVG images.
|
||||
- **Bounds.** File size ≤50 MiB; inflated KMZ ≤120 MiB; ≤20,000 entities (including multipart children and Folder containers); ≤250,000 positions; ≤2,000 normalized style definitions and distinct image links; ≤12 files per session. Exact repeated styles share definitions without changing inheritance or inline overrides. Files of 20–30 MB fit the byte budget, subject to geometry/image limits. Refusals name a reason and batches continue; with multiple failures the hint shows the first reason.
|
||||
- **Lifecycle and keyboard.** `createApplicationTools` wires `initGeoFileImport` with viewer, navigation, ground services and map-source subscription. Destroy aborts pending work, unsubscribes, removes data sources, revokes blob URLs, removes document/canvas listeners and releases `window.__gevGeoImport`. List rebuilds retain keyboard focus; removing a row hands focus to the next row, else the previous row, else Import.
|
||||
- **Validation.** `node scripts/qa-geo-import.mjs` covers all four formats and real painted show/hide. Run `node scripts/qa-geo-import-regressions.mjs` against both dev and preview for XYZ/track heights, failure recovery, namespace/BOM support, portrait framing and panel drops. `node scripts/qa-geo-import-large.mjs [--file /absolute/path/sample.kml] [--expect-local-pins]` checks a 27.6 MB repeated-style file, native style/image equivalence, large-file painted output and frame times. It records the WebGL renderer; software-rendered runs do not establish GPU performance. Unit tests live beside the data/controller/framing modules.
|
||||
- **Code layout.** `src/data/geoFileImport.js` reads, bounds and sanitizes the files. `src/data/geoImportFeatures.js` turns the sanitized KML or GeoJSON into plain features (pins, lines, walls, polygons and ground overlays) with the styles Cesium's KML and GeoJSON loaders gave them: icon, scale, colour, heading and hot spot; line and polygon colours and widths; extruded or clamped geometry. `src/data/geoImportPins.js` draws those features through the renderer's draw port (`drawOf`), settles ground pins through the height service and frames the file for Fly-to. None of the three reaches Cesium, so the Cesium allow-list is empty. `src/data/geoImportShared.js` holds the error, limits, deadline and feature names they use.
|
||||
- **Lifecycle and keyboard.** `createApplicationTools` wires `initGeoFileImport` with viewer, navigation, ground services and map-source subscription. Destroy aborts pending work, unsubscribes, removes each file's draw sets, revokes blob URLs, removes document/canvas listeners and releases `window.__gevGeoImport`. List rebuilds retain keyboard focus; removing a row hands focus to the next row, else the previous row, else Import.
|
||||
- **Validation.** `node scripts/qa-geo-import.mjs` covers all four formats and real painted show/hide. Run `node scripts/qa-geo-import-regressions.mjs` against both dev and preview for XYZ/track heights, failure recovery, namespace/BOM support, portrait framing and panel drops. `node scripts/qa-geo-import-large.mjs [--file /absolute/path/sample.kml] [--expect-local-pins]` checks a 27.6 MB repeated-style file, that what the import draws matches Cesium's own `KmlDataSource` reading of the same file (positions, scale, heading, colours, widths, fills), large-file painted output and frame times. The QA scripts read what a file drew through `window.__gevGeoImport.drawn(id)`. It records the WebGL renderer; software-rendered runs do not establish GPU performance. Unit tests live beside the data/controller/framing modules.
|
||||
|
||||
### Recent Imagery (September 2026)
|
||||
|
||||
@@ -7682,7 +7798,7 @@ pins and share links already supply complete boxes.
|
||||
- DATA ▸ **Recent Imagery** (`recent-imagery`, `src/layers/recentImagery/`) lists the last 30 UTC days of imagery for a selected box and drapes the days you pick: HLS S30 (Sentinel-2) and L30 (Landsat 8/9) at 30 m, and the VIIRS NOAA-21 daily overview at 250 m. Keyless and browser-direct: NASA CMR for which days have HLS granules in the box (`catalog.js`, both collections concurrently, paged with `CMR-Search-After` up to 2,000 records each, `truncated` against CMR `hits`), GIBS WMTS for tiles, Worldview Snapshots for thumbnails and exports. Worldview's `Data-Present` header is the only availability signal: GIBS answers an empty tile with HTTP 200, and the JPEG overview would drape black, so a day confirmed empty never drapes.
|
||||
- **Box.** SELECT BOX (`src/ui/imageryBoxTool.js`) claims the pointer like Draw, borrows the stock click actions and freezes the camera only mid-drag; USE VIEW takes the camera rectangle; `boxFromPinAt` grows a 10 km box. Boxes must be ≤ 1,000 km a side, on one side of the dateline and inside the Web-Mercator limit (`validateBox`). A refusal (`boxError`, including the tool's own via `reportBoxRefusal`) stays at the top of the panel until a box succeeds; a view over the cap is refused with its size, never shrunk. An oversized box or view (`Box is … km wide · limit 1,000 km`, `View is … wide · …`) sets the hint to `Zoom in or draw a smaller box` and enables ZOOM IN: `zoomToFit()` flies top-down (1.2 s) to the refused box's centre, or the ground under the canvas centre for a view, at the height whose view is about 400 km wide for the canvas aspect and the camera's vertical FOV (`fitViewHeightM`, clamped 5–400 km), and returns that height.
|
||||
- **Modes, pins and the preview.** The mode is explicit: `image` (one pinned day, slot `a`), `basemap` (that day on the left of a swipe, the basemap on the right: slot `a` splits LEFT and there is no second layer) and `ab` (day `a` left, day `b` right). `setAssignment(slot, key | null)` / `toggleAssignment(slot, key)` pin and unpin; a day is in one slot at most (pinning it in the other slot moves it) and an empty day cannot be pinned. `setMode()` keeps both pins; `b` only drapes in `ab`. While the mode's first empty slot exists the focused day previews in it: a click at once, arrow keys after 250 ms of quiet (`FOCUS_DEBOUNCE_MS`, one timer, last day wins); an unprobed day is followed and previews when its probe says present, an empty or unknown day never drapes and the previous preview stays. A pin change drops the preview until focus moves again, and unpinning takes that layer off at once. `rankLatest` picks START HERE coverage first (a present HLS day whose footprints cover the box, or have none, beats a newer sliver), then newest with all granules ≤ 20% known cloud, then newest; slivers only as `partial`; else the newest non-empty VIIRS day; it is focused and previewed after each search when nothing is pinned. Escape clears the preview (`clearPreview()`), then cancels the box tool, then blurs — with SELECT BOX armed too, through the tool's `onEscape` interceptor wired in `createApplicationTools`. Pins, mode, box and split changes made in the panel are published with `adoptLayerParams`, never while a share link is being applied.
|
||||
- **Rendering.** `rendering.js` owns at most two GIBS layers on the host `src/maps/imageryHost.js` resolves: `viewer.imageryLayers` while the globe shows, the photoreal tileset's `imageryLayers` while it is hidden, or none (the panel says so). Layers are rebuilt on a new host, never re-parented. `MapSourceController.subscribe()` fires after every settled stack switch (silent switches and fallbacks included) and the layer rebinds on it. Tile requests pass a six-slot semaphore of our own (Cesium's global limits are untouched). Under `requestRenderMode` a deferred tile needs a later frame, but a deferral must never request one itself or a stalled tile keeps the scene rendering every frame: a request that finds the semaphore full asks for nothing (the settling request asks for one frame), and a tile Cesium itself deferred goes through one coalesced 250 ms retry. Thumbnails: three fetches at once, sixteen decoded images, least-recently-used where a `get` read is never a use; eviction keeps the probe result. The strip's visible window is probed around the focused card; the pinned and previewed days are probed wherever they sit, at the focused card's priority, so a pin restored or assigned off-screen still drapes.
|
||||
- **Rendering.** `rendering.js` owns at most two GIBS layers on the host `src/maps/imageryHost.js` resolves: the globe port's imagery while the globe shows, the shown photoreal tileset while it is hidden, or none (the panel says so). Layers are rebuilt on a new host, never re-parented. `MapSourceController.subscribe()` fires after every settled stack switch (silent switches and fallbacks included) and the layer rebinds on it. Tile requests pass a six-slot semaphore of our own (Cesium's global limits are untouched). Under `requestRenderMode` a deferred tile needs a later frame, but a deferral must never request one itself or a stalled tile keeps the scene rendering every frame: a request that finds the semaphore full asks for nothing (the settling request asks for one frame), and a tile Cesium itself deferred goes through one coalesced 250 ms retry. Thumbnails: three fetches at once, sixteen decoded images, least-recently-used where a `get` read is never a use; eviction keeps the probe result. The strip's visible window is probed around the focused card; the pinned and previewed days are probed wherever they sit, at the focused card's priority, so a pin restored or assigned off-screen still drapes.
|
||||
- **Esri surface and the swipe.** While any image is on the map (a preview included) the layer holds the map lease (`acquireImageryComparison`, owner `recent-imagery`, `esri-if-photoreal`): on Google 3D the map switches to Esri, because 30 m pixels over 3D buildings do not read, and Cesium's split only works on the globe. The lease is handed back, and Google 3D restored unless the operator changed maps meanwhile, when the last image leaves the map or the layer is disabled; the notice line says so while it holds. While a day is shown the imagery keeps Esri: a manual switch that lands on Google 3D is answered at once with a new lease under the same policy (`keepEsri`), the notice reads `Imagery stays on Esri · CLEAR to use Google 3D`, and the divider never suspends because of a map switch. It re-leases once per switch generation and only for a manual one (`MapSourceController#getSwitchOrigin()` is `manual` for an outside `setStack`, `automatic` for the controller's own fallback or recovery), never for the lease's own switch and never while releasing, so CLEAR and disable still return to Google 3D; a lease another owner holds stays refused. When Esri fails and the controller falls back to Google 3D on its own, the layer lets the lease go without restoring anything, both days drape on the tileset without a swipe and the guidance reads `Esri map unavailable · no swipe`; only the next manual switch to Google 3D takes Esri again, so a failing Esri map is never retried in a loop. Switching between globe stacks (Esri, OSM, Bing) only rebinds. On a tileset host both images drape without a swipe. The split control (`createImagerySplit`, labels A / B, or IMAGE / BASEMAP) exists only while a swipe is live, recentres on every new comparison (not while scrubbing the second day), except once for a split restored from a link. There is no keyboard shortcut (Space is the app's push-to-talk): SWAP (`#ri-swap`, in the controls row, its slot reserved and the button disabled while no swipe is live) trades the two sides, A to the right and B to the left, or the image to the right of the basemap, and a second click restores; the hint reads `Drag the divider · SWAP trades sides`. The swap is not in the share link, and every new comparison starts unswapped. One opacity applies to both drapes. Another owner holding the lease is reported and the images still drape.
|
||||
- **Panel.** `#recent-imagery-panel` is rail markup in the Context view (`src/ui/views/ContextView.vue`) beside `#weather-panel`, registered in `PanelLayoutController`, `PanelChrome` and the share panel state (`ui` token `i`), hidden while the layer is off and opened on first appearance unless a stored or shared collapse choice exists (`dataset.collapsedPreference`). `LayerPanel.attachRecentImagery(factory)` mounts the readout (`createRecentImageryPanel` in `src/ui/recentImagery.js`) into its `data-rail-scroller` body, as the weather readout is mounted. The body is a fixed stack in which no block changes height and no control moves in any state: `#ri-actions` (SELECT BOX · USE VIEW · CLEAR, rail-card actions), `#ri-notice` (one line: `#ri-notice-text` with the refusal, error, CLEAR notice or the Esri note, and `#ri-zoom-in` in a fixed slot at its right end, reserved unless an oversized box or view can be fitted), `#ri-strip` (day cards newest first: thumbnail, date, sensor, cloud, START HERE, PREVIEW, and a SHOW chip or A and B chips; ← → Home End move, S / A / B pin, Enter previews), `#ri-hint` (one line: the next step), `#ri-selection` (`#ri-mode` IMAGE · VS BASEMAP · A / B, then `#ri-slot-a` and `#ri-slot-b` with `#ri-unpin-a` / `#ri-unpin-b` kept in place when empty), `#ri-controls` (`#ri-opacity`, EXPORT / EXPORT A and EXPORT B) and `#ri-details`, a collapsed rail card holding the focused day's acquisition, coverage and granules, catalog notes, the empty-days toggle and the imagery credit. Absent controls are reserved (invisible), never removed. Every render preserves the body's `scrollTop`; opening DETAILS then scrolls its card into view once.
|
||||
- **Share links.** Layer options (token `1`): box edges as integers at degrees × 100000, pins `a` and `b` as compact days (`S20260918`), `m` mode (0 image, 1 basemap, 2 A / B), `p` split percent (share-link only: never stored locally) and `v` for the daily overview. Row chips: `MORE DETAIL · 30 m` (on) and `DAILY OVERVIEW · 250 m` (off).
|
||||
@@ -7691,7 +7807,7 @@ pins and share links already supply complete boxes.
|
||||
### 3D Aircraft + Tracking (June 2026)
|
||||
|
||||
- **The TRACKED contact's 2D↔3D handoff is DEFAULT behaviour (2026-08-19), driven by camera distance alone.** It does NOT consult the DISPLAY-rail `3D` toggle, which continues to own the FLEET (the un-instanced draw-call budget stays the operator's decision). Policy lives in `src/data/trackedModelRegime.js` and is shared by both layers: enter below `TRACKED_MODEL_ENTER_ALT_M` = 150,000 m and hand back to the billboard only above `TRACKED_MODEL_EXIT_ALT_M` = 172,500 m. **The swap distance was set by playtesting on 2026-08-20:** a first pass at 1,000,000 m switched too early; 2D reads correctly at ~600 km and the handoff belongs at ~150 km. **Consequence, recorded on purpose:** the tracked contact now enters 3D NEARER than the FLEET does (`MODEL_ALT_CEIL_M` = 800,000 m, unchanged), so with the DISPLAY-rail `3D` toggle on, 150–800 km draws surrounding contacts as models while the selected one is still a glyph. Nothing double-draws (the fleet pass skips the tracked icao) and aligning the two is a fleet-side decision, deliberately out of scope. **The two thresholds are asymmetric on purpose:** a single threshold makes a tracked orbit sitting ON the boundary strobe billboard↔model as the camera's altitude wobbles across it. Do not collapse them. The latch is scoped per selection, so a new target re-evaluates against the ENTER ceiling rather than inheriting the previous target's exit band. Exactly ONE model is involved; it loads on demand when the regime opens, is HIDDEN (not released) on regime exit so re-entry has no load gap, and is released by the existing teardown on deselect/re-track/destroy. Cockpit and TR-3B suppression are unchanged. **Two invariants around it:** (a) the hysteresis latch AND the load-failure latch are per-selection state cleared by `_resetTrackedSelectionState()` in the tracking lifecycle (deselect / re-track / cross-layer / init / destroy) — the predicate's icao-change guard is defence only, since it needs a drawn frame while nothing is selected and the render governor's idle mode does not promise one; (b) on-demand loading is bounded at 3 attempts per selection with a 1.5 s backoff and one console warning naming the asset — the driver runs every `scene.preUpdate`, so an unbounded catch means a missing GLB spins load→reject at frame rate. The billboard stays the visual throughout a failed load.
|
||||
- **Grounded 3D handoff is terrain-validity gated (2026-08-23).** A ready civilian or military glTF does not own the visual until `groundSnap` (`src/data/groundSnap.js`) can answer with a MEASURED photoreal-surface height. On success the layer writes `height + the model's measured belly offset` before revealing the model. Cache movement is measured on the WGS84 surface, not across altitude, so a stationary contact keeps its snap through poll-time vertical-datum changes. Model existence or GPU readiness alone never suppresses the billboard floor, and ordinary zoom/style/deselect transitions preserve a valid snap cache. **Two states, and the difference is the whole design.** COLD — nothing has ever resolved for this icao (tiles still streaming on first sight, sample failure, backoff after a first miss): there is no evidence of where the ground is, `heightFor` returns null, the model stays hidden and the depth-test-free 2D billboard remains opaque and floored. WARM — a snap resolved and then a >`MOVE_INVALIDATE_M` (50 m) taxi move stopped it answering directly: the measurement is DEMOTED to a bounded last-known rather than deleted, and it keeps answering while the resample is outstanding, so a taxiing aircraft does not pop 3D→2D→3D across a 2–30 s retry backoff. The bound is `HELD_SNAP_MAX_DRIFT_M` = 250 m from the spot the value was measured at, past which the hold is dropped rather than stretched and the contact is COLD again. It is spatial with no timer beside it (ground under a contact that has not moved does not change; what invalidates the value is the contact MOVING) and deliberately a quarter of the billboard chain's `HELD_FLOOR_MAX_DRIFT_KM` — that hold only ever RAISES a sprite, while a held snap IS the model's placement, so its error shows in both directions. A fresh sample releases the hold, and so does a ground flip (which already calls `forget`). **A loading model is HIDDEN, never zero-scaled:** admission sets `show = false` (Cesium's default is `true`, and an unplaced primitive would claim the visual at the identity matrix), and ownership is `ready && show` — Cesium 1.138's `Model.update` has no `show` guard, so hiding a primitive costs its load nothing.
|
||||
- **Grounded 3D handoff is terrain-validity gated (2026-08-23).** A ready civilian or military glTF does not own the visual until `groundSnap` (`src/data/groundSnap.js`) can answer with a MEASURED photoreal-surface height. On success the layer writes `height + the model's measured belly offset` before revealing the model. Cache movement is measured on the WGS84 surface, not across altitude, so a stationary contact keeps its snap through poll-time vertical-datum changes. Model existence or GPU readiness alone never suppresses the billboard floor, and ordinary zoom/style/deselect transitions preserve a valid snap cache. **Two states, and the difference is the whole design.** COLD — nothing has ever resolved for this icao (tiles still streaming on first sight, sample failure, backoff after a first miss): there is no evidence of where the ground is, `heightFor` returns null, the model stays hidden and the depth-test-free 2D billboard remains opaque and floored. Tiles still streaming is not a miss: no sample is taken, so it earns no retry backoff, and the first fleet tick after the tiles settle samples (2026-11-15); only a sample that finds no ground backs off (2 s, doubling to 30 s). WARM — a snap resolved and then a >`MOVE_INVALIDATE_M` (50 m) taxi move stopped it answering directly: the measurement is DEMOTED to a bounded last-known rather than deleted, and it keeps answering while the resample is outstanding, so a taxiing aircraft does not pop 3D→2D→3D across a 2–30 s retry backoff. The bound is `HELD_SNAP_MAX_DRIFT_M` = 250 m from the spot the value was measured at, past which the hold is dropped rather than stretched and the contact is COLD again. It is spatial with no timer beside it (ground under a contact that has not moved does not change; what invalidates the value is the contact MOVING) and deliberately a quarter of the billboard chain's `HELD_FLOOR_MAX_DRIFT_KM` — that hold only ever RAISES a sprite, while a held snap IS the model's placement, so its error shows in both directions. A fresh sample releases the hold, and so does a ground flip (which already calls `forget`). **A loading model is HIDDEN, never zero-scaled:** admission sets `show = false` (Cesium's default is `true`, and an unplaced primitive would claim the visual at the identity matrix), and ownership is `ready && show` — Cesium 1.138's `Model.update` has no `show` guard, so hiding a primitive costs its load nothing.
|
||||
- **Ground-snap clock rollback recovery.** If the wall clock moves before the
|
||||
sampling-window start, ground snap opens a new window while retaining the
|
||||
normal four-samples-per-250-ms budget. Retry timestamps more than the maximum
|
||||
@@ -7711,7 +7827,7 @@ pins and share links already supply complete boxes.
|
||||
- Fleet model eligibility is distance-based with on-screen priority and hard caps (`MODEL_MAX`, `MODEL_MAX_ALL`) to avoid draw-call explosions. Each model owns its own `modelMatrix`; shared scratch matrices are forbidden because they caused stacking/flicker.
|
||||
- Tracked aircraft use standalone model primitives driven from the already-settled dead-reckoned display position, while the tracked Cesium entity remains billboard-backed so `viewer.trackedEntity` always has a ready bounding sphere.
|
||||
- Flights and military layers mirror the same tracking invariants: no warm-up freeze/jump, altitude-scaled framing, trail head glued to the displayed plane, no pull-out when switching targets, and no cross-layer orphan when switching between commercial and military tracks.
|
||||
- Regression surface: `npm run test:track` drives the real app headless with synthetic aircraft feeds and asserts the tracking invariants without depending on live OpenSky/adsb data. Arrival-rotation checks observe the settle frame and then the first reveal frame, each within a 500 ms wall-clock budget that sits inside the one-second idle fallback, rather than assuming the 80 ms fleet cadence fits inside four rendered frames; an incorrect first orientation fails immediately. Only an inconclusive timeout is retried (once); a timeout keeps every angle it measured (the settle frame before a reveal timeout, and the late frame itself, which is read before the deadline check), so a measured wrong angle fails without retry. `src/data/trackedModelRegime.test.mjs` pins the tracked contact's threshold math, the enter/exit asymmetry, and the default-on / cockpit / TR-3B / deselect wiring in both layers.
|
||||
- Regression surface: `npm run test:track` drives the real app headless with synthetic aircraft feeds and asserts the tracking invariants without depending on live OpenSky/adsb data. The harness reads what the app draws through its own seams: what the camera follows through `src/data/followed.js`, icons from the draw port's icon sets as the renderer holds them, and models by their `{set, id}` pick ids. Arrival-rotation checks read the drawn rows' course (the icon sets turn each icon along it on the GPU every frame, so there is no CPU rotation pass to repair a stale nose) and observe the settle frame and then the first reveal frame, each within a 500 ms wall-clock budget; an incorrect first orientation fails immediately. Only an inconclusive timeout is retried (once); a timeout keeps every angle it measured (the settle frame before a reveal timeout, and the late frame itself, which is read before the deadline check), so a measured wrong angle fails without retry. `src/data/trackedModelRegime.test.mjs` pins the tracked contact's threshold math, the enter/exit asymmetry, and the default-on / cockpit / TR-3B / deselect wiring in both layers.
|
||||
|
||||
### TR-3B conversion Easter egg (August 2026)
|
||||
|
||||
@@ -8000,6 +8116,76 @@ easier to meet (detection is now on more often), but does not create it.
|
||||
above and the DISPLAY-rail entry below (was `OFF`).
|
||||
- Style shader starting params: CRT/NVG/FLIR pixelation `1.2` (just above the native `1.0` floor); thermal/FLIR ships an optional Ironbow "Predator" palette (`palette` uniform, default `0` = accurate grayscale).
|
||||
|
||||
## Renderer contract
|
||||
|
||||
`src/render/contract/` types the renderer contract, version `0`: nine ports
|
||||
(frame, globe, draw, camera, query, input, effects, credits and quality),
|
||||
plus the renderer itself. `PORTS` lists every member at run time, and
|
||||
`contract.test.mjs` keeps that list and the types in step.
|
||||
`src/render/stub/` is a renderer that draws nothing, with the default
|
||||
camera's exact maths. `src/render/conformance/` is the suite: logic checks
|
||||
in Node, plus camera traces recorded from Cesium's own `Camera` into
|
||||
`goldens/camera.json`. It also holds the reference scenes, whose views are
|
||||
checked against `goldens/visual/` on the `/dev/conformance/` page.
|
||||
`npm run qa:conformance` runs the logic checks on the Cesium renderer in
|
||||
headless Chromium, in CI too. After `destroy()` the Cesium renderer's
|
||||
handles do nothing, and `renderOnce` and `capture` reject. See
|
||||
[RENDERER-CONTRACT.md](RENDERER-CONTRACT.md).
|
||||
|
||||
### The application and its renderer
|
||||
|
||||
The application starts on whichever `RendererPlugin` it is given
|
||||
(`createStandaloneApplication({ renderer })`), and on Cesium when none is.
|
||||
`src/app/scene.js` loads the Cesium adapter (`src/render/cesium/application.js`)
|
||||
only then, with `import()`; the standalone page starts that load as it
|
||||
starts, beside its own setup. Outside `src/render/` no code reaches a
|
||||
renderer's own objects: the record of files that still did,
|
||||
`src/render/viewerAccessAllowList.json`, is empty.
|
||||
|
||||
- What every layer and tool is handed is the scene object
|
||||
(`createSceneHost`), bound to the renderer: its container, and whether it
|
||||
is destroyed. Everything else goes through the renderer's ports.
|
||||
- What a renderer's own plugin adds beside the contract (stale draw-command
|
||||
trims, inline panel drawing, the zoom-out guard, its own map engine, the
|
||||
detection overlay's occlusion probe, what QA scripts read) it hands through `src/render/applicationHooks.js`; the
|
||||
application uses each where given and does without where not.
|
||||
Renderer-only startup (Cesium's free-look limit, credit keyboard access)
|
||||
runs in that plugin's `create`.
|
||||
- The map stacks switch through the plugin's map engine, else the globe
|
||||
port (`src/maps/globeEngine.js`): Esri and OSM as `xyz` imagery, Cesium
|
||||
ion imagery as `world` imagery, terrain as `world` terrain, or the
|
||||
ellipsoid where no keyless terrain is offered, and photoreal as the port's
|
||||
photoreal base. A photoreal base that fails to come back leaves the globe
|
||||
shown.
|
||||
- The renderer follows its container's size (`Renderer.resize`, from a
|
||||
`ResizeObserver`).
|
||||
- The credits: the Cesium renderer's plugin says it shows them in a display
|
||||
of its own (`ownCreditDisplay`; `#cesium-credits`), which it keeps. On the
|
||||
stub, the application shows what the credits port lists in its own line
|
||||
at the bottom left (`#gev-credits`, `src/ui/creditsView.js`): the inline
|
||||
credits on the line, the rest (the layers' data credits among them) in
|
||||
the "Data attribution" list it opens, a keyboard button with Escape to
|
||||
close.
|
||||
|
||||
`npm run qa:stub-boot` boots the whole application on the stub with only
|
||||
the contract's required members (`dev/stub-app/main.js`, served in place of
|
||||
`src/main.js` on the application's own page), headless. It fails if
|
||||
the credits line is not shown or its list is empty, if Cesium's code is
|
||||
requested (the one stylesheet `vite-plugin-cesium` links
|
||||
into every page is reported), on any page or console error, or if a data
|
||||
layer (flights, military aircraft, transit, traffic, CCTV, AIS vessels,
|
||||
weather radar and satellite, wind, satellites, FIRMS, wildlife, shipwrecks,
|
||||
news) fails to turn on or off. A
|
||||
feed's failed response (no key, no network) is reported, not failed;
|
||||
`--strict` also fails a layer that drew nothing, and `--all-capabilities`
|
||||
gives the stub every capability. CI runs it in the browser job.
|
||||
|
||||
`src/geo/` (export `./geo`) is the Cesium-free maths: WGS84, ECEF and
|
||||
geodetic conversions, surface normals and east-north-up frames, as plain
|
||||
`{x, y, z}` objects. It follows Cesium's formulas step for step, and
|
||||
`geo.test.mjs` checks it against Cesium. The stub renderer's maths is built
|
||||
on it.
|
||||
|
||||
## Operational Notes
|
||||
|
||||
- **Earthquake discs are STATIC geometry.** Every quake is a `CLAMP_TO_GROUND`
|
||||
@@ -8256,8 +8442,9 @@ easier to meet (detection is now on more often), but does not create it.
|
||||
Every failed read cancels its body and aborts its owned request, including
|
||||
declared and streaming byte-cap failures.
|
||||
- Development captures opened with `?trafficDebug=1` mint an interaction anchor
|
||||
from the exact `camera.changed` event that arms each debounced load, then emit
|
||||
scheduling-correlated User Timing entries for production `response.json`, road
|
||||
from the exact camera-port `changed` event that arms each debounced load,
|
||||
then emit scheduling-correlated User Timing entries for production
|
||||
`response.json`, road
|
||||
parse, dot construction, heat-line rebuild, and next-post-render
|
||||
boundaries. Every trace is paired with the exact camera-change that scheduled
|
||||
its load; mismatches are counted drops. Cesium's `moveEnd` remains a diagnostic
|
||||
@@ -8592,6 +8779,25 @@ request HTTPS tiles even on HTTP localhost, with the existing Content Security
|
||||
Policy unchanged. Ion attribution and Bing's per-tile credits are preserved;
|
||||
other ion imagery assets continue through the SDK's standard ion factory.
|
||||
|
||||
The imagery, terrain and 3D factories are the Cesium renderer's
|
||||
(`src/render/cesium/mapImagery.js`, `mapTerrain.js`, `google3d.js`; the
|
||||
package exports `./maps/imagery`, `./maps/terrain` and `./maps/3d` point
|
||||
there). The catalog, the default registry and the controller are
|
||||
Cesium-free: they reach those factories, and the scene operations a
|
||||
switch makes (imagery layers, terrain, the globe's visibility, tilesets),
|
||||
through the scene's map engine (`mapEngineFor` in `src/maps/engine.js`). The
|
||||
Cesium plugin hands the application its own engine with each renderer it makes
|
||||
(`src/render/cesium/mapEngine.js`, through `src/render/applicationHooks.js`),
|
||||
and the application scene loads the photoreal base through it too. A renderer
|
||||
whose plugin hands none switches through its globe port
|
||||
(`src/maps/globeEngine.js`): Esri and OSM as `xyz` imagery, ion's world
|
||||
imagery as `world` imagery, photoreal as the port's photoreal base (turned off
|
||||
while hidden, on again when shown), and world terrain, or without a key
|
||||
Re:Earth's keyless terrain as `quantizedMesh` terrain at its URL
|
||||
(`src/maps/keylessTerrain.js`), as the Cesium engine draws it; a renderer
|
||||
without the `terrain` capability keeps the ellipsoid. A viewer with no renderer bound gets the Cesium engine, with the
|
||||
other unbound ports, from the package's `./render/cesium/unbound` export.
|
||||
|
||||
The controller accepts other source registries without adding provider branches.
|
||||
Each instance caches source construction, ignores superseded scene changes and
|
||||
releases imagery layers/listeners on replacement. Destroy invalidates pending
|
||||
@@ -8659,7 +8865,12 @@ product's next frame until that frame loads (for at most eight seconds), so
|
||||
every frame shows. Hidden documents, reduced motion and unavailable imagery
|
||||
hosts suspend products. Re-enabling or
|
||||
restoring a host joins the retained history target. The wind row explicitly says
|
||||
“Forecast · does not follow history” while the observed clock is in history mode.
|
||||
“Forecast · does not follow history” while the observed clock is in history mode,
|
||||
unless a host follows the world clock for `wind` (`weatherClock.follows('wind')`):
|
||||
its source then follows the timeline and the row says nothing of it. In history
|
||||
mode, frame ages and the “Source observations delayed” status are measured from
|
||||
the timeline time rather than the wall clock, and the timeline readout shows the
|
||||
time alone; live, they count from now as before.
|
||||
The Weather panel's frame time shows the newest frame and its age while live
|
||||
(each product's newest, suspended products included), and the timeline time
|
||||
alone at a past time.
|
||||
|
||||
@@ -95,6 +95,11 @@ registry of source functions. Each receives `{ path, signal, maxBytes }` and
|
||||
returns `{ bytes: Uint8Array, mimeType }`. Custom transports must honor the
|
||||
signal, bound reads and return the real MIME type. They remain application code,
|
||||
not scene document fields. Without registrations, referenced sources fail closed.
|
||||
A standalone `SceneDirector` also passes `dataPacks.overlayHost`, the
|
||||
world-overlay host that draws pack world text such as a media pack's label (an
|
||||
object with `setEntries(sourceId, entries)` and `clearSource(sourceId)`);
|
||||
without it a media pack fails to load. `createApplicationTools` passes the
|
||||
application's shared host.
|
||||
|
||||
The portable session receives format adapters separately. Each adapter receives
|
||||
`{ pack, asset, anchors, signal }` and returns a resource with an idempotent
|
||||
|
||||
@@ -31,8 +31,9 @@ const layers = createInfrastructureLayers({
|
||||
| `overlayHost.clearSource` | `(sourceId)`; remove that source's overlay entries |
|
||||
| `registerEntityContext` | `(entity, metadata)`; register selectable feature metadata, including the owning layer and data source |
|
||||
| `selectEntityContext` | `(entity)`; select that registered feature |
|
||||
| `clearSelectedEntityContextForLayer` | `(layerId)`; clear selection only if owned by this layer |
|
||||
| `removeEntityContextsForLayer` | `(layerId)`; remove records owned by the layer on destruction or failed setup |
|
||||
| `clearSelectedEntityContextForLayer` | `(layerId, { evicted })`; clear selection only if owned by this layer; `evicted` when its feature left the data |
|
||||
| `removeEntityContextsForLayer` | `(layerId, { retainIds })`; remove records owned by the layer on destruction or failed setup, or those a new feature set no longer has |
|
||||
| `getSelectedEntityContext` | optional; `()` the selected record, so `replaceFeatures` keeps a selection the new set still has |
|
||||
| `governorRequestRender` | `(reason)`; request a frame through the existing render scheduler |
|
||||
|
||||
Each returned layer supports `init(viewer)`, `enable(viewer)`, `disable(viewer)`,
|
||||
@@ -45,18 +46,43 @@ Callbacks must be ready before enable and remain usable through destruction.
|
||||
|
||||
Disable retains the loaded dataset for reuse and clears selection and listeners.
|
||||
Concurrent enables share one load. Destroy is permanent, aborts pending fetches,
|
||||
discards late results, and clears the owned data source, context records, overlays,
|
||||
discards late results, and clears the owned draw sets, context records, overlays,
|
||||
input handler and listeners. The layer never creates an application context store,
|
||||
overlay host, viewer, or render scheduler. The consumer must resolve one compatible
|
||||
Cesium installation shared with its viewer; it must not bundle separate copies.
|
||||
|
||||
The layers draw, size their stems and fly the camera through the renderer's
|
||||
ports. A viewer the application has bound a renderer to needs nothing more; a
|
||||
Cesium viewer with no renderer bound loads
|
||||
`gods-eye-view/render/cesium/unbound` once first; until then the layer reports
|
||||
an error naming it, as it does for a dataset it cannot load.
|
||||
A selected feature is the context record its draw item carries as `meta`; the
|
||||
layer no longer sets the viewer's `selectedEntity`.
|
||||
Features keep their own simplestyle `fill`, `fill-opacity`, `stroke`,
|
||||
`stroke-opacity`, `stroke-width`, `marker-color` and `marker-size`, given as
|
||||
hex, `rgb()` or `hsl()` colours or by the CSS colour names the default renderer
|
||||
knows (it has no `rebeccapurple`, and spells `lavenderblush` `lavendar_blush`);
|
||||
a `marker-symbol` is stamped on the pin as the default renderer stamped it: a
|
||||
one-character string as bold upper-case text, any other value as the Maki icon
|
||||
of that id from the renderer's assets, the plain pin when the icon cannot be
|
||||
loaded. The assets are found as the renderer finds them from a page script: the
|
||||
`CESIUM_BASE_URL` global, else the folder `Cesium.js` is loaded from; a
|
||||
page bundling Cesium as modules sets `CESIUM_BASE_URL` for icon pins. Polygons with heights are drawn at them, outlined; points with
|
||||
heights stand their pin on the stem's tip. Edges follow rhumb lines.
|
||||
|
||||
`gods-eye-view/infrastructure/geojson` exports the lower-level
|
||||
`createLocalGeoJsonLayer(options, services)` and existing infrastructure overlay
|
||||
helpers. `gods-eye-view/infrastructure/lod` exports the existing LOD policy helpers.
|
||||
helpers. Its options also take `loadFeatures({ signal })`, a loader resolving to
|
||||
GeoJSON features in place of `url`, and `featureColor(properties)`, a CSS colour
|
||||
per feature for its fill, stem, dot, pin and label accent. The layer it returns
|
||||
also has `dropCachedFeatures()`, so the next `enable` loads again, and
|
||||
`replaceFeatures(viewer, features)`, which draws a new feature set in place of
|
||||
the current one: the current one stays drawn until the new one is built, and
|
||||
stays if that fails (the call then rejects). `gods-eye-view/infrastructure/lod` exports the existing LOD policy helpers.
|
||||
Consumers use the package exports, which do not import standalone application
|
||||
globals.
|
||||
|
||||
Dataset files and source/license notices remain under `src/data/local_data/`.
|
||||
Their input counts are 4,352 datacenter features and 704 dam features. Cesium may
|
||||
expand multipart geometries into multiple entities; entity and stem counts are
|
||||
different measurements. This change does not refresh or relicense the datasets.
|
||||
Their input counts are 4,352 datacenter features and 704 dam features. A multipart
|
||||
geometry draws as several parts, each with its own stem; part and stem counts are
|
||||
different measurements from feature counts. This change does not refresh or relicense the datasets.
|
||||
+2
-1
@@ -34,7 +34,8 @@ hardware-rendered overlay scenes.
|
||||
|
||||
These frame rates were measured when the globe was capped at 60 FPS. It now
|
||||
draws at the display's refresh rate while anything moves and ticks at most 60
|
||||
times a second when parked (`src/renderGovernor.js`).
|
||||
times a second when parked (the Cesium frame port's idle rate,
|
||||
`IDLE_FRAME_RATE` in `src/renderGovernor.js`).
|
||||
|
||||
The initial-settle measurement is the more useful launch reference because it
|
||||
includes the first visual and data settling window. All three samples reached
|
||||
|
||||
@@ -0,0 +1,746 @@
|
||||
# Renderer contract
|
||||
|
||||
The renderer contract is what the application asks of a 3D renderer. The
|
||||
Cesium renderer draws the application through it, and the stub renderer
|
||||
stands in for it in tests. The contract is version `0`. Today the application
|
||||
still drives Cesium directly; later work moves the layers onto the contract
|
||||
one family at a time.
|
||||
|
||||
The package exports these modules:
|
||||
|
||||
| Export | What it is |
|
||||
| ------------------------------------ | -------------------------------------------------------------------------------------- |
|
||||
| `gods-eye-view/render/contract` | The types, one `.d.ts` per port, plus the run-time member list and shape check |
|
||||
| `gods-eye-view/render/stub` | A renderer that draws nothing, for tests |
|
||||
| `gods-eye-view/render/camera/events` | The camera port's events: `changed` per listener, `moveStart`/`moveEnd`, command hooks |
|
||||
| `gods-eye-view/render/conformance` | The conformance suite, reference scenes and visual comparison |
|
||||
|
||||
The pieces that do not depend on Cesium are exported too, each with its
|
||||
own `.d.ts`:
|
||||
|
||||
- `gods-eye-view/render/input/router`: the input port's leases and routing;
|
||||
- `gods-eye-view/render/stub/camera`, `.../stub/viewRectangle` and
|
||||
`.../stub/harness`: the stub's camera, its view rectangle and its
|
||||
conformance harness;
|
||||
- `gods-eye-view/render/motion`: where a moving icon is drawn at a time;
|
||||
- `gods-eye-view/render/vectorBase`: the vector base painter;
|
||||
- `gods-eye-view/render/iconSegment`: icon motion segments;
|
||||
- `gods-eye-view/render/recession`: how a set that recedes shrinks and
|
||||
fades its items toward the limb;
|
||||
- `gods-eye-view/render/windStreamlines`: the wind field's streamlines;
|
||||
- `gods-eye-view/geo/screenCluster`: screen-space clustering.
|
||||
|
||||
`src/render/neutralExports.test.mjs` checks that each is declared, that its
|
||||
names match what it exports, that it type-checks under strict TypeScript and
|
||||
that it imports no Cesium.
|
||||
|
||||
A camera controller takes the camera events from `render/camera/events`
|
||||
and the geodesy it needs (`geodesicAt`, `horizonFrom` and the rest) from
|
||||
`gods-eye-view/geo`, so it measures and fires exactly as the stub does. `CameraControllerFactory`
|
||||
(`camera.d.ts`) types such a controller: what it is given (`NativeCamera`)
|
||||
and what it gives back (the camera port and its two frame steps).
|
||||
|
||||
## Ports
|
||||
|
||||
A renderer is created by a `RendererPlugin` (`{ id, create(options) }`). It
|
||||
exposes nine ports, each typed in its own file in `src/render/contract/`:
|
||||
|
||||
| Port | File | Covers |
|
||||
| --------- | -------------- | ----------------------------------------------------------------------- |
|
||||
| `frame` | `frame.d.ts` | The render-on-demand loop, frame phases, continuous holds, scene time |
|
||||
| `globe` | `globe.d.ts` | Base (photoreal, terrain, vector, imagery), imagery layers, split, sky |
|
||||
| `draw` | `draw.d.ts` | Draw sets: icons, points, lines, shapes, models, quads, meshes, fields |
|
||||
| `camera` | `camera.d.ts` | Pose, views, flights, `lookAt`, follow, user controls, events, matrices |
|
||||
| `query` | `query.d.ts` | Picks, projection, rays, heights |
|
||||
| `input` | `input.d.ts` | Pointer events with their pick made, leases, stock behaviours |
|
||||
| `effects` | `effects.d.ts` | Screen styles, bloom, sharpen, screen modulation |
|
||||
| `credits` | `credits.d.ts` | Data credits owed |
|
||||
| `quality` | `quality.d.ts` | Quality knobs, device facts, frame signals |
|
||||
|
||||
Version `0` is still being shaped, and not only by additions. Members
|
||||
were removed or replaced (among them `camera.move`, `look`,
|
||||
`rotateAround` and `zoom`, now step views placed with `setView`;
|
||||
`query.sampleHeightNowMany`; `input.ctrlWheelZoom`, now the `ctrlWheel`
|
||||
zoom input), `depthFailColor` and `depthFailDash` became one `depthFail`
|
||||
style, and quality settings became detail only. The Cesium port and the
|
||||
stub follow those changes.
|
||||
|
||||
Some members and options were added to version `0` later. Each is
|
||||
optional:
|
||||
|
||||
- `globe.isGlobeVisible()` (capability `globeVisibility`) reads back whether
|
||||
the globe surface is shown, for code that holds only the scene.
|
||||
- `camera.followFrame()` (capability `followFrame`) reads the frame the eye
|
||||
is placed in, as a column-major 4×4 matrix to ECEF: a follow's own frame
|
||||
(east-north-up, or the orbit frame `autodetect` chose), a `lookAt`
|
||||
target's east-north-up frame, or the identity. `setView` keeps that frame
|
||||
while it places a world pose. A share link's follow offset is
|
||||
re-expressed in it, satellites included.
|
||||
- `globe.surfaceVersion()` (capability `surfaceIdentity`) is a number that
|
||||
changes whenever what surface heights answer against changes (base,
|
||||
terrain or photoreal route swapped, the globe shown or hidden) and never
|
||||
otherwise (not on camera moves or tile loads), so the application can key cached
|
||||
heights by it. `isSettled('surface')` says whether that surface has
|
||||
loaded what is in view; a renderer without it answers `surface` as `base`.
|
||||
- `SurfaceShading` is `hillshade`: view-lit shading of the drawn terrain's
|
||||
own relief (the ellipsoid's curvature where terrain has no normals) that
|
||||
only darkens, at most `strength` opacity. The Cesium port draws it as a
|
||||
globe material it takes only while no one else holds the globe's
|
||||
material.
|
||||
- Fields: `windStreamlines` takes `alpha` (changed without a rebuild) and
|
||||
`paused`; `rasterShell` replaces `detailWindow` with
|
||||
`detail: {image, rectangle}`, a sharper image drawn in place of the base
|
||||
one, and says how shells stack, blend and update. `FieldHandle.on('drawn')`
|
||||
says once per spec or `update` that it is drawn, never while hidden. These
|
||||
change `fields` itself rather than add to it, so the renderer follows
|
||||
them where it lists `fields`. The Cesium adapter lists `fields` and
|
||||
draws `rasterShell` and `windStreamlines`. It reads the grid's samples as
|
||||
points, the first column at `rectangle.west` and the first row at
|
||||
`rectangle.north`, rows running south. Over the whole globe its paths
|
||||
wrap east and west; over part of it they seed inside the rectangle,
|
||||
equal-area, and stop at its edges.
|
||||
- `ModulationSector` gains `radius` and `floor` and says what it modulates:
|
||||
icons, points and models dimmed toward `floor` outside the band, the map,
|
||||
lines and shapes as they are, picks unchanged. Its pass is named
|
||||
`screenModulation`. This changes `screenModulation` itself; only the stub
|
||||
lists it, and the Cesium adapter does not draw it yet.
|
||||
- `camera.on('changed', cb, { threshold })` measures each listener by its
|
||||
own threshold under the capability `cameraChangeThreshold`; a renderer
|
||||
without it fires every `changed` listener at 0.5.
|
||||
- A line item's `depthFail` style, solid or dashed, draws the parts behind
|
||||
the surface (the Draw tool's rubber band is dashed there too); without one
|
||||
they are hidden.
|
||||
- A solid line's `outline.widthPx` is the outline's whole width, half on
|
||||
each side, inside the line's own width: an 8 px line with a 4 px outline
|
||||
is 2 px of outline, 4 px of colour and 2 px of outline, as Cesium draws
|
||||
it. The check `draw.lines.outline` pins it.
|
||||
- A shape's `lit` chooses shading by the renderer's fixed light (true) or a
|
||||
flat colour (false); omitted, extruded shapes are lit and the rest flat,
|
||||
as before. The Cesium port lights unclamped shapes only
|
||||
(clamped ones drape unlit). The `shapes-lit` scene draws both.
|
||||
- `SetSpec.recede` (`RecedeSpec`, for icon and model sets) makes a set's
|
||||
items shrink and fade toward the globe's limb, replacing the icon item's
|
||||
own `recede` flag. Its parameters (each optional: where receding starts
|
||||
as a share of the limb's distance, the scale and haze reached at the
|
||||
limb, the least focus × haze draws with, and the eye heights over which
|
||||
it all eases off for a view of the whole globe) and the maths are
|
||||
`render/recession`'s, so the renderer draws exactly those factors: an icon
|
||||
draws at its scale times the scale factor, and an icon or model at its
|
||||
alpha times `max(combinedAlphaFloor, focus × haze)`. `ModelItem.focus`
|
||||
dims a model as `IconItem.focus` dims an icon. It changes live
|
||||
(`setOptions`). The Cesium port draws a receding icon set on the GPU,
|
||||
the factors worked out in its shader, and fades a receding model set's
|
||||
models each frame before the scene draws, writing a model's colour again
|
||||
once its focus and haze move by more than 0.005. The check
|
||||
`draw.sets.recede` makes and changes both kinds, and
|
||||
`draw.sets.recede.models` reads a receding model's pixels: at focus 0.25
|
||||
it draws faded, and a `combinedAlphaFloor` of 1, set live, brings it back.
|
||||
- `SetSpec.drawOrder` stacks sets drawn over depth: a higher one draws over
|
||||
a lower one and is picked first; equal ones keep the order they were
|
||||
made in. The Cesium port stacks opaque icons and points by it;
|
||||
translucent ones blend order-independently there.
|
||||
- A rectangle shape's `rotation` (radians counter-clockwise) turns it about
|
||||
its centre in longitude and latitude, as a KML ground overlay turns, and
|
||||
its image fill turns with it. The Cesium port drapes image fills too, each
|
||||
on a ground primitive of its own.
|
||||
- `camera.controls.keepEarthFramed` (capability `keepEarthFramed`) stops
|
||||
the user's outward zooms at a whole-Earth view (about 40,000 km, or
|
||||
higher where a camera command left the eye) and, from high up, turns the
|
||||
view down toward the globe so the whole Earth stays in frame; camera
|
||||
commands are not held to it and end its turn. The Cesium port eases the
|
||||
view until the Earth's limb is 8° below its centre line above 300 km
|
||||
(`zoomOutGuard.js`). The application turns it on where a renderer has it.
|
||||
- `query.occlusionTest()` (capability `occlusionTest`) tests many points
|
||||
against the depth of the frames drawn without waiting for the GPU; the
|
||||
detection overlay leaves out the street vehicles it finds hidden. The
|
||||
Cesium port builds its test with `gods-eye-view/render/occlusion`
|
||||
(`createDepthOcclusionTest`, given a `DepthSource`: depth packed into
|
||||
RGBA8 or a depth texture, standard or logarithmic, with the view it was
|
||||
drawn from).
|
||||
- `RendererPlugin.applicationHooks(renderer)` hands the application what
|
||||
lies beside the contract (`ApplicationHooks`); see
|
||||
[The application and its renderer](#the-application-and-its-renderer).
|
||||
- `frame.renderNow()` throws when the frame fails to draw. With
|
||||
`{ifDue: true}` it runs one tick of the loop now, as the loop's own would
|
||||
(camera flight, input, clock), and draws only a frame that is due.
|
||||
|
||||
The Cesium port lists `gpuTiming` where its context has
|
||||
`EXT_disjoint_timer_query_webgl2`: while anyone listens to frame signals,
|
||||
each drawn frame is timed on the GPU from `preRender` to `postRender`, and a
|
||||
signal carries `gpuMs` of the newest frame whose timing has come back (a
|
||||
frame or more late; a disjoint timing is dropped). Without the extension it
|
||||
answers `gpuTiming: 'none'` and lists no capability. The check
|
||||
`quality.signals.gpuTiming` pins both.
|
||||
|
||||
The Cesium port lists `modelAtmosphere`: Cesium scatters drawn models
|
||||
through the atmosphere in the same stage as its distance fog, so models take
|
||||
it while `globe.sky`'s `fog` is on.
|
||||
|
||||
`weather` adds `globe.weather`: clouds, fog, haze, rain and snow drawn
|
||||
around the view, each a strength from 0 to 1, with the wind they drift on.
|
||||
`src/render/weather.js` (exported as `./render/weather`) keeps and clamps
|
||||
them (`mergeWeather`), and `./weather/effects`
|
||||
turns a weather observation into strengths (`deriveWeatherEffectProfile`).
|
||||
The application sets none, and the Cesium port does not list it. The strengths say what
|
||||
is observed (`clouds` is the fraction of the sky covered), not how it is
|
||||
drawn: the renderer draws clouds, fog and haze its own way, with clouds
|
||||
placed by scene time and the wind, and shading the ground under them where
|
||||
the sun lights it. The checks `globe.weather`, `globe.weather.drawn` and
|
||||
`globe.weather.sceneTime` (pixel checks) pin it.
|
||||
|
||||
How the sky, atmosphere, haze, lighting and the frame's tone mapping and
|
||||
exposure look is the renderer's own: `globe.sky` switches parts on and
|
||||
off, and no check compares colours. With
|
||||
`atmosphere`, `fog` and `lighting` off and clear weather a renderer applies
|
||||
none of its look, so the checks that read an exact colour (`bareSky` in
|
||||
`checks/ports.js`) set that sky first. The
|
||||
reference images under `src/render/conformance/goldens/visual/` are the
|
||||
Cesium renderer's own, for checking it against itself.
|
||||
|
||||
The Cesium port lists `followAutodetect`: an `autodetect` follow is
|
||||
Cesium's own AUTODETECT tracking frame, east-north-up on a still or slow
|
||||
target and an orbit frame (x along the inertial motion, z up) on a fast
|
||||
one. The stub's is a frame along the ground track, so an autodetect
|
||||
`viewFrom` reads differently on each; the check `camera.follow.autodetect`
|
||||
pins what both share (the range kept, north-up when still, the frame on the
|
||||
target standing up).
|
||||
|
||||
A follow target's `transitionS` makes the first framing a move instead of a
|
||||
jump: from its first frame the eye is in the target's frame, and over
|
||||
`transitionS` seconds of wall time it goes from where it stood to
|
||||
`viewFrom`, by the one rule in `src/render/camera/followTransition.js`
|
||||
(its offset and its view each turned and eased with smoothstep, the view
|
||||
ending on the target with no roll). The Cesium port, the stub and a camera
|
||||
controller import that rule rather than restating it. The tracked aircraft
|
||||
and followed trains use it with a `viewFrom` taken from the camera
|
||||
at the click: the eye's own view direction at its own range from the target,
|
||||
so neither changes and only the eye's place moves, sliding the target to the
|
||||
centre. The check `camera.follow.transition` pins it.
|
||||
|
||||
The Cesium port draws clamped shapes of every kind. A clamped outline is a
|
||||
draped line (a ground polyline a ring, under the shape's pick id; an outlined
|
||||
clamped shape is rebuilt on any change; a pulsing one pulses through its line's
|
||||
material, as an image fill pulses through its image material's colour). What
|
||||
a ground primitive cannot drape stands on the surface unclamped, the surface
|
||||
read when the set is built: an extruded shape from the lowest surface height
|
||||
under it up to its `extrudeHeight`, a wall with its foot on the surface under
|
||||
each position and its heights above it, and an image fill where the scene
|
||||
cannot drape materials (no depth textures). The check `draw.shapes.clamped`
|
||||
draws each.
|
||||
|
||||
The Cesium port takes every kind of `ImageRef` wherever an image is drawn
|
||||
(icons on billboards and on the GPU, line patterns, shape fills, quads and
|
||||
raster shells): a URL, SVG, a blob (by an object URL made once per blob,
|
||||
revoked once the blob itself has been collected; a material drawing a blob,
|
||||
a quad's among them, holds it while it lives, since a material loads its image
|
||||
on its first draw, even after the atlas slot it came from has a new one; a
|
||||
quad given another source lets the old blob go with its old material, once the
|
||||
frame has drawn), a
|
||||
keyed canvas, and an atlas slot as the image it holds (an icon waits for an
|
||||
unregistered slot; anything else refuses it). The check `draw.icons.images`
|
||||
draws each kind on still icons and in a set that recedes.
|
||||
|
||||
Icon sets with `cluster` (`ClusterSpec`) cluster the same way on every
|
||||
renderer: `clusterScreenPoints` (`src/geo/screenCluster.js`) over the shown
|
||||
icons in front of the eye and above the horizon, in the set's order, boxed at
|
||||
their drawn size, the last pass's clusters kept. A cluster draws one icon at
|
||||
the mean of its members' positions in place of its members (`icon(count)`,
|
||||
else a default badge with the count, at the seed's size). A pick on it
|
||||
answers one hit a member, seed first, each with the member's own `set`, `id`
|
||||
and `meta` and the cluster's position, so `pick` gives the seed and
|
||||
`drillPick` every member. Clusters are made again in the frames drawn after
|
||||
the camera moves or the set changes, never on a timer. The Cesium port draws
|
||||
a set's cluster icons in a billboard collection of their own and hides the
|
||||
members' billboards. A set on the GPU (`columns`, a set that recedes, or moving,
|
||||
proxy-picked or level-of-detail icons) clusters its rows where their segments
|
||||
(and ground) put them at the frame's motion-clock time, hiding the members'
|
||||
rows; while rows still move it clusters again every frame. The checks
|
||||
`draw.icons.cluster` and `draw.motion.cluster` (members coming to rest on
|
||||
their segments) draw a cluster, pick it, and part it by moving in.
|
||||
|
||||
Icon sets on the Cesium GPU path draw what its billboards draw: pixel offsets, `bottom` and `top` anchors, screen and axis
|
||||
rotations (turned as Cesium's billboards turn), `fadeByDistance`,
|
||||
`displayRange`, and `clampGround` / `relativeGround` heights. Each row reads
|
||||
these from a float texture by instance, so the 16 vertex attributes hold;
|
||||
WebGL 1 has no such fetch and refuses them. A clamped row stands on the
|
||||
ground taken between the heights under its segment's two ends, sampled after
|
||||
a frame draws, 256 ends a frame across the port's sets: loaded terrain first,
|
||||
then (but for `clampTo: 'terrain'`) the drawn surface, eight a frame. They are
|
||||
sampled again when the globe's tiles finish loading and, clamped to more than
|
||||
terrain, every 5 s. The check `draw.motion.look` draws each on a moving icon.
|
||||
|
||||
A set's `blend` holds for every kind of set: omitted, opaque parts draw
|
||||
opaque with depth writes and translucent ones blend without; `opaque` draws
|
||||
every item opaque, its alpha ignored, with depth writes; `translucent` blends
|
||||
every item without depth writes, even at alpha 1; `additive` adds each item's
|
||||
colour times its alpha, without depth writes and still depth-tested. It
|
||||
changes live (`setOptions`, from the next frame; models do not load again).
|
||||
The Cesium port builds billboards and points in Cesium's blend options, and
|
||||
turns every set's draw commands to its blend each frame before the scene
|
||||
sorts them (`src/render/cesium/setBlend.js`): additive ones draw after every
|
||||
opaque command and before the translucent pass, which blends
|
||||
order-independently and would undo the addition; ground commands keep their
|
||||
pass and stencil and only blend differently. The checks `draw.sets.blend`
|
||||
(points, icons, lines, shapes) and `draw.models.blend` read the pixels.
|
||||
|
||||
A model item may bring its glTF bytes (`gltf`): the renderer builds it from
|
||||
them and never fetches its `url`, which stays the model's identity, so a
|
||||
model set loaded up front (the procedural fleet models, GLBs compressed with
|
||||
`EXT_meshopt_compression` and `KHR_mesh_quantization`) is never fetched
|
||||
mid-session. `axisScale` stretches a model along its own glTF axes on top of
|
||||
`scale` (a hull drawn at its reported beam), `maskColor` paints a colour
|
||||
where the model's `_TINT` vertex attribute marks it (a vehicle in its route's
|
||||
colour), and `clip: 'belowOrigin'` draws only what is above the horizontal
|
||||
plane through its position (a hull above its waterline). Each changes live.
|
||||
The Cesium port passes the bytes as the model's `gltf` with its url as the
|
||||
base path, scales its model matrix along the axes Cesium's glTF axis
|
||||
correction turns them to, paints the mask in a custom shader per colour
|
||||
(unlit under `unlit` shading, left out under `thermal`), and clips with a
|
||||
clipping plane through the model's origin. The checks `draw.models.bytes`
|
||||
and `draw.models.fleet` cover them.
|
||||
|
||||
The Cesium port draws timed imagery (`imageryFrames`): a layer given a timed
|
||||
source hides its own imagery and draws each frame its clock shows as a Cesium
|
||||
imagery layer just above it (in `blend` mode the later frame over the earlier
|
||||
at its share of the way, as a layer's `alpha` blends), with the next
|
||||
`prefetch` frames (1 by default) loading unseen at alpha 0. A video source is
|
||||
seen every 250 ms of each segment (at most 1,200 times a segment), each tile
|
||||
the video its URL names for it (or one video over the layer's rectangle for a
|
||||
`single-image` layer), seeked to the time's share of its length. A layer
|
||||
keeps its 48 most recently seen tile videos; a tile waiting on one it lets
|
||||
go, or on a seek that takes over 10 s (60 s for the seek past its end that
|
||||
learns the length of a video that does not state it), fails rather than
|
||||
waiting. A video whose seek did not end is let go, so the next tile loads a
|
||||
fresh one; one that failed to load (or to say how long it is) fails its tiles
|
||||
at once for 3 minutes, then loads again. `frameReady`
|
||||
names the nearest frame's time once every globe tile drawn shows that
|
||||
frame's own imagery (`src/render/cesium/imageryFrames.js`). The checks
|
||||
`globe.imagery.frames` and `globe.imagery.video` cover both.
|
||||
|
||||
Every Cesium draw set takes `setColumns` (`columns`): icon sets on the GPU,
|
||||
any other as the rows the columns make over the items it holds, each row the
|
||||
item of that id with the columns' fields over it, replacing every item as
|
||||
`set` does (`columnRows` in `src/render/cesium/draw.js`, as the stub does).
|
||||
`renderer.shape` holds on Cesium.
|
||||
|
||||
The Cesium port also draws `pattern` line styles (the image repeated
|
||||
`repeat` times along the line, in the translucent pass; draped too), lines in the
|
||||
`inertial` frame (turned each frame by the set's motion clock, a depth-fail
|
||||
style included; never batched; a draped one is draped where the sky is,
|
||||
turned into the fixed frame, and draped again each second of its clock),
|
||||
segment colours and shows
|
||||
on lines of every mode and style (a draped solid line as ground instances,
|
||||
any other as a primitive a segment with a material of its own, recoloured
|
||||
and shown in place; an arrow's head on its last segment, a pattern keeping
|
||||
its image; the check `draw.lines.segmentStyles`), and image fills on clamped ellipses, cut finely so a
|
||||
round image (the launch pad zone's rim) runs round. A clamped colour fill
|
||||
whose geometry alone changes (an annotation's target ring, resized as the
|
||||
camera climbs) is drawn alone where it now is, in the same frame. A hidden
|
||||
line that cannot settle into a static batch leaves its polyline collection
|
||||
until it shows again, since the collection draws every line it holds.
|
||||
|
||||
The renderer itself (`renderer.d.ts`) adds capture, pixel reads, settling,
|
||||
resize, context loss and `destroy`. `common.d.ts` holds the shared shapes
|
||||
(ECEF positions, colours, listener semantics) and the capability list.
|
||||
|
||||
The rules that hold everywhere:
|
||||
|
||||
- **The application keeps its own records.** It never reads a renderer to learn its own
|
||||
state, only what the renderer measures: picks, depth, heights and
|
||||
readiness.
|
||||
- **Capabilities.** An optional member (`?`) exists only with the capability
|
||||
its documentation names first. A required member that names a capability
|
||||
always exists, and without the capability it answers null or empty.
|
||||
Quality support is listed by `quality.knobs()`, not by capabilities.
|
||||
- **Picks see the scene before effects.** A style that moves pixels does not
|
||||
move what is picked, so the application maps a pointer through its own
|
||||
style first
|
||||
(`src/input/sensorPick.js`). A bounded `drillPick` (`limit`) also bounds
|
||||
its work: it looks through at most `max(limit, 16)` things under the
|
||||
pointer.
|
||||
- **Heights are physical.** All heights are metres above the ellipsoid,
|
||||
unexaggerated. Only drawing follows exaggerated terrain.
|
||||
- **Listeners** run in subscription order. A listener removed during
|
||||
delivery does not run; one added during delivery runs from the next event.
|
||||
A listener that throws is reported to the renderer's `error` event, or to
|
||||
the platform's `reportError` when nothing listens for errors. The other
|
||||
listeners, and the frame, still run.
|
||||
- **The frame order is fixed:** camera flight → input → camera `changed` →
|
||||
follow → `preUpdate` → move detection → `preRender` → render →
|
||||
`postRender`, the default renderer's own. A camera move made by follow or
|
||||
in `preUpdate` is reported by `changed` on the next frame.
|
||||
- **Destroy ends everything.** After `destroy()`, every handle does
|
||||
nothing: a set's or field's methods neither draw nor throw, and a set or
|
||||
field asked for afterwards is such a handle. The same holds for one handle
|
||||
after its own `dispose()`. `frame.renderOnce()` and `capture()` reject
|
||||
with a "renderer destroyed" error, and a `renderOnce` still waiting at
|
||||
destroy rejects rather than hang.
|
||||
- **Results are read-only.** `camera.matrices()` and `followFrame()` may
|
||||
hand the same arrays again while they hold, and hand new ones once they
|
||||
change, so one kept from an earlier frame stays as it was.
|
||||
- **Reading the frame.** `capture()` and `readPixels()` read the last
|
||||
presented frame; neither draws one of its own when the frame is kept.
|
||||
Whether to keep the drawing buffer is the renderer's own business, not a
|
||||
creation option. The creation options a renderer takes are `msaa`, `sky`
|
||||
and `time`, set before the first frame, and `clock`, which its frame
|
||||
ticks, the camera's `moveEnd` wait, its input and its flights read, and
|
||||
its inertia where the renderer times that itself: on Cesium, inertia
|
||||
keeps Cesium's own timing.
|
||||
- **Leases:** a tool takes the pointer with `claimPointer`. With `grab`, it
|
||||
takes only the presses it grabs on `down`; the rest, and wheel and pinch,
|
||||
stay with the camera and everyone else. The newest claim takes over: it
|
||||
ends the previous lease, whose `onLost` is called once, after the new lease
|
||||
holds the pointer, so that tool turns itself off. A lease its holder
|
||||
releases is never told, and an ended lease's release frees nothing.
|
||||
The application's own tools (Draw, the imagery box, Directions) claim through
|
||||
`src/data/inputOwnership.js`, which the input dispatcher bridges onto the
|
||||
port, so a claim on either takes over from the other. The bridge's lease
|
||||
grabs no press: the dispatcher decides who hears each event when it
|
||||
arrives, and the renderer's stock select and double-click follow run
|
||||
unless a tool holds them off.
|
||||
|
||||
`src/render/contract/index.js` lists every member of every port in `PORTS`,
|
||||
along with `CAPABILITIES`, `FRAME_STEPS` and `QUALITY_KEYS`.
|
||||
`checkRendererShape(renderer)` names each required member that is missing,
|
||||
and each capability member present without its capability.
|
||||
`contract.test.mjs` type-checks the contract under strict TypeScript, and
|
||||
fails when `PORTS` and the types disagree on a single member.
|
||||
|
||||
### The vector base painter
|
||||
|
||||
`vectorBase` (`BaseSpec.vector = { styleUrl }`) draws a MapLibre style
|
||||
document's vector tiles as the globe's base. They are painted in shared,
|
||||
Cesium-free code, `src/render/vectorBase/`, which the renderer draws as
|
||||
imagery:
|
||||
|
||||
- `loadVectorStyle(styleUrl, fetch)` fetches the style and the TileJSON its
|
||||
vector sources name (a source's `url`; inline `tiles` are used as given,
|
||||
resolved against the style), compiles every layer, and returns the
|
||||
sources (tile templates, `minzoom`, `maxzoom`, `xyz` or `tms`), the layers
|
||||
it draws, the background, the sources' attributions, and `skipped`: each
|
||||
layer it does not draw, with why.
|
||||
- `paintVectorTile(style, z, x, y, { size, fetch, signal, canvas })` paints
|
||||
one Web Mercator tile on a canvas at style zoom `z + log2(size / 512)` (at
|
||||
least 0). A source past its `maxzoom` is drawn from its deepest tile,
|
||||
overzoomed; below its `minzoom` it draws nothing. Decoded source tiles
|
||||
(gzipped ones inflated) are kept per style, the last 128.
|
||||
|
||||
What it draws of the style specification:
|
||||
|
||||
- Layers: `background` (`background-color`, `background-opacity`); `fill`
|
||||
(`fill-color`, `fill-opacity`, `fill-outline-color`); `line`
|
||||
(`line-color`, `line-width`, `line-opacity`, `line-dasharray`,
|
||||
`line-cap`, `line-join`, and `line-gap-width` drawn as one line the full
|
||||
cased width); `circle` (`circle-radius`, `circle-color`,
|
||||
`circle-opacity`, `circle-stroke-width`, `circle-stroke-color`,
|
||||
`circle-stroke-opacity`); `symbol` text only (`text-field` as an
|
||||
expression or with `{name}` tokens, `text-size`, `text-font` as the
|
||||
system's sans-serif or serif in bold or italic as its name says,
|
||||
`text-color`, `text-opacity`, `text-halo-color`, `text-halo-width`,
|
||||
`text-transform`, `text-anchor`, `text-offset`, `text-max-width`).
|
||||
Layer `minzoom`, `maxzoom`, `filter` and `visibility` hold.
|
||||
- Labels are painted into the tiles: top layer first (within a layer, its
|
||||
features in their order in the tile), each clear of those placed before
|
||||
it and wholly inside its tile (one across a tile edge is
|
||||
left out). A point labels at itself, a line halfway along it (level, not
|
||||
along the line), a polygon at its outer ring's bounding-box centre.
|
||||
- Filters in both syntaxes (legacy, with `$type` and `$id`, and
|
||||
expressions). Legacy `{stops, base, property, type}` functions
|
||||
(exponential, interval, categorical, identity; not zoom-and-property);
|
||||
one without a `type` is exponential on a property that interpolates (a
|
||||
number or colour) and interval on any other (`line-cap`, `line-join`,
|
||||
`text-font`, `text-transform`, `text-anchor`, ...), as the specification
|
||||
says. `has`, `get` and legacy filters see a feature's own properties only.
|
||||
- Expressions: `literal`, `get`, `has`, `id`, `geometry-type`, `zoom`,
|
||||
`properties`, `!`, `all`, `any`, `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`,
|
||||
`case`, `match`, `coalesce`, `step`, `interpolate` (`linear` and
|
||||
`exponential`; `-hcl` and `-lab` blend in RGB), `to-string`,
|
||||
`to-number`, `to-boolean`, `to-color`, `number`, `string`, `boolean`,
|
||||
`rgb`, `rgba`, `concat`, `format` (its text), `upcase`, `downcase`,
|
||||
`length`, `at`, and arithmetic (`+ - * / % ^`, `min`, `max`, `abs`,
|
||||
`floor`, `ceil`, `round`, `sqrt`, `ln`, `log10`, `log2`).
|
||||
- Skipped whole: `fill-extrusion`, `raster`, `hillshade`, `heatmap` and
|
||||
`sky` layers; layers on raster sources; layers setting a pattern
|
||||
(`fill-pattern`, `line-pattern`, `background-pattern`), `line-offset`,
|
||||
`line-gradient` or a translation; layers whose values use an expression
|
||||
not listed (or are malformed). As MapLibre does, a paint or layout value
|
||||
that cannot be evaluated for a feature (a type that does not fit, a
|
||||
`step` or `interpolate` over what is not a number) or is not of the
|
||||
property's kind (null; not a finite number, a string included, where a
|
||||
number is needed; not a colour `parseColor` reads, which takes the CSS
|
||||
colour names; not one of the property's keywords) is the property's
|
||||
default; a legacy function's miss is its `default`, else the property's.
|
||||
A feature whose filter cannot be evaluated is left out. Nothing
|
||||
unsupported throws.
|
||||
- Ignored: icons (`icon-image`, sprites: a symbol layer draws its text
|
||||
alone), text along lines (drawn level), `glyphs` (system fonts), and any
|
||||
other paint or layout property not listed above.
|
||||
|
||||
The Cesium port loads the style before the base changes (a style that fails
|
||||
leaves the base as it was; a later `setBase`, or disposal, aborts the load and
|
||||
the overtaken call changes nothing, resolving with `imagery: []` and
|
||||
`settled: false`; `settled` is whether, when the call resolves, its base is
|
||||
still the one drawn and has settled, so an earlier call that resolves while a
|
||||
later call's style is still loading, or after that style fails, is settled,
|
||||
and one that resolves after a later call changed the base is not), draws it as Web Mercator imagery under the
|
||||
base's other imagery (`src/render/cesium/vectorBase.js`, 256 px tiles to
|
||||
level 20, transparent where the style paints no opaque background; a tile
|
||||
whose request is cancelled, its layer removed, is not painted), and credits each source's attribution as plain text. The stub
|
||||
loads the style and paints nothing. The check `globe.base.vector` serves a
|
||||
style and a tile from data URLs and reads the drawn fill.
|
||||
|
||||
### What a renderer does, by role
|
||||
|
||||
A renderer is more than a drawing surface: it is a whole globe engine. The
|
||||
application keeps the data (providers, records, layers and their
|
||||
behaviour). The renderer owns everything from a source spec or a draw set
|
||||
down to the pixels. The ports follow the API's shape; `ROLES` in
|
||||
`src/render/contract/index.js` names what the engine behind them does, and
|
||||
puts every member of `PORTS` in exactly one role. It changes no member.
|
||||
|
||||
| Role | What it does | Members |
|
||||
| --------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `surface` | Streams, decodes and builds the globe from map sources: imagery, terrain, photoreal 3D tiles, draped layers | `globe`, `imageryLayer`, `credits` |
|
||||
| `scene` | Draws the application's data as keyed, retained sets | `draw`, `drawSet` |
|
||||
| `view` | Places and moves the camera, hands pointer input to the application | `camera`, `flight`, `input`, `lease` |
|
||||
| `queries` | Picks, surface positions and heights, rays, projection, occlusion | `query` |
|
||||
| `look` | Sky and atmosphere, surface shading, per-layer lighting, styles and screen effects | `effects`, `globe.sky`, `globe.weather`, `globe.setSurfaceShading`, `imageryLayer.lit` |
|
||||
| `host` | Canvas and life cycle, the frame loop and scene time, quality, capture, settling | `renderer`, `frame`, `quality` |
|
||||
|
||||
An entry is a port or a `port.member` prefix; the most specific one wins, so
|
||||
`roleOf('globe', 'sky.set')` is `'look'` while `roleOf('globe', 'setBase')`
|
||||
is `'surface'`. `contract.test.mjs` fails when a member has no role, when
|
||||
two roles claim the same entry, or when an entry names no member.
|
||||
|
||||
## Moving code onto the contract
|
||||
|
||||
Two ratchet tests keep code that has moved onto the contract from drifting
|
||||
back to Cesium. Both lists only ever shrink.
|
||||
|
||||
- `src/render/cesiumAllowList.json` lists the files outside the Cesium
|
||||
adapter (`src/render/cesium/`) that may still import or be handed Cesium
|
||||
(`src/render/noCesiumOutsideRender.test.mjs`). A file leaves the list
|
||||
when it no longer drives Cesium at all; nothing is added. The list is
|
||||
empty: no file outside the adapter reaches Cesium. Two files name
|
||||
the adapter by design and are not on it: the application scene
|
||||
(`src/app/scene.js`), the composition root that picks the default renderer
|
||||
when it is given none, may import `src/render/cesium/application.js` (only
|
||||
then, so a page on the stub never loads Cesium) and nothing else of
|
||||
the adapter; the conformance page (`dev/conformance/main.js`) may import the
|
||||
adapter's harness and scene renderer. The test names both
|
||||
(`ADAPTER_ENTRIES`), and that list is never grown.
|
||||
- `src/render/viewerAccessAllowList.json` counts, per file off that list,
|
||||
the Cesium-shaped accesses through the viewer it still makes (none: the
|
||||
list is empty, so no file may make one)
|
||||
(`src/render/viewerAccess.test.mjs`): the viewer's `entities`,
|
||||
`dataSources`, `scene`, `camera`, `clock`, `imageryLayers`,
|
||||
`terrainProvider`, `trackedEntity` and `canvas`, and the scene's
|
||||
`primitives`, `pick`, `drillPick`, `pickPosition`, `globe`, `preRender`,
|
||||
`postRender`, `preUpdate`, `postUpdate`, `canvas`, `requestRender` and
|
||||
`camera`, written plainly, with `?.`, in brackets or destructured.
|
||||
`viewer.container` is a DOM element and does not count; reach the canvas
|
||||
through `canvasOf(viewer)`. Comments and tests do not count.
|
||||
`src/testSupport/viewerAccess.mjs` is the matcher.
|
||||
A file may not make more accesses than recorded (a file not listed may
|
||||
make none), and a count higher than the file now needs fails too. So a
|
||||
file that leaves the Cesium list must port its viewer accesses in the
|
||||
same change: it cannot be added to the count. After
|
||||
porting accesses away, run `node scripts/viewer-access-baseline.mjs` (or
|
||||
`--check` to see what it would change): it lowers counts and drops
|
||||
entries, and never adds or raises one.
|
||||
|
||||
## The application and its renderer
|
||||
|
||||
The application runs on a renderer with only the contract's required
|
||||
members (the stub proves it below); nothing outside `src/render/<renderer>/` asks which renderer it runs
|
||||
on (no `renderer.id`, no engine type, no engine object's presence).
|
||||
|
||||
- **The scene object.** `createApplicationScene` (`src/app/scene.js`) takes a
|
||||
`RendererPlugin`, or a promise of one (default: Cesium, imported only then;
|
||||
`loadDefaultRenderer` starts that import as the standalone page starts),
|
||||
creates the renderer in the page's container, and hands every layer and
|
||||
tool the application's own scene object (`createSceneHost` in
|
||||
`src/render/rendererOf.js`): the container and `isDestroyed()`, bound to
|
||||
the renderer. Code reaches the renderer's
|
||||
ports through it (`findCamera`, `drawOf`, `canvasOf`...).
|
||||
- **What only the Cesium renderer needs at startup** is done in its
|
||||
plugin's `create`: the free-look height limit and keyboard access to its
|
||||
credits' expand link (`src/render/cesium/appRenderer.js`).
|
||||
- **What a plugin may hand the application beside the contract** is its
|
||||
`applicationHooks(renderer)` (`ApplicationHooks`,
|
||||
`src/render/contract/renderer.d.ts`), asked once as the scene creates the
|
||||
renderer and recorded for the application (`src/render/applicationHooks.js`):
|
||||
a map engine of its own, stale command trimming, whether an entity is its
|
||||
own, whether it shows its credits in a display of its own
|
||||
(`ownCreditDisplay`; otherwise the application's own line,
|
||||
`src/ui/creditsView.js`, shows the credits port's list), and what QA
|
||||
scripts read from `window.__godsEyeView` (Cesium's viewer there, for the
|
||||
scripts that drive it). Each is optional, none is a contract member, and
|
||||
a renderer without them runs the application without that behaviour.
|
||||
- **What the renderer should do is in the ports**, each through the
|
||||
application's own code: outward zooms stop at a whole-Earth view that
|
||||
stays framed (`camera.controls.keepEarthFramed`, which the scene turns
|
||||
on; Cesium's is `src/render/cesium/zoomOutGuard.js`); the detection
|
||||
overlay leaves out street vehicles something stands in front of through
|
||||
`query.occlusionTest()` under the `occlusionTest` capability (the GPU
|
||||
probe is `src/render/occlusion/depthProbe.js`, which Cesium's
|
||||
`src/render/cesium/sceneOcclusionProbe.js` feeds; without it every such
|
||||
vehicle's bracket shows); and an inline panel whose host stops animation
|
||||
frames keeps running through `resize` and `frame.renderNow({ifDue: true})`
|
||||
(`src/app/panelRendering.js`), so flights, input and the clock go on as
|
||||
in the renderer's own loop, stopping at a frame that throws.
|
||||
- **The map stacks** switch through the renderer's own map engine when its
|
||||
plugin hands one, else through its globe port (`src/maps/globeEngine.js`);
|
||||
see `docs/CURRENT-STATE.md` § Map source factories and coordination.
|
||||
- **The proof.** `npm run qa:stub-boot` (`scripts/qa-stub-boot.mjs`) serves
|
||||
the application's page with `dev/stub-app/main.js` as its entry: the whole
|
||||
application on the stub with no capability at all. It fails when the page
|
||||
requests any Cesium module or asset, when the credits line is not shown
|
||||
with its data credits, on a page or console error, or when a
|
||||
data layer (flights, military aircraft, transit, traffic, CCTV, vessels,
|
||||
weather, wind, satellites, FIRMS, wildlife, shipwrecks, news) fails to
|
||||
turn on or off; `--strict` also fails
|
||||
a layer that draws nothing on the stub (it needs the live feeds).
|
||||
`src/app/scene.test.mjs` runs the scene itself on the stub in Node.
|
||||
|
||||
## The stub renderer
|
||||
|
||||
`createStubRenderer({ capabilities, viewport, time, container })` implements
|
||||
every port in memory and draws nothing. Given a `container` (in a page), its
|
||||
canvas is a real canvas filling it, which `resize()` follows; otherwise a
|
||||
stand-in that takes event listeners. `createStubRendererPlugin(options,
|
||||
onCreate)` is the stub as a `RendererPlugin`. It has:
|
||||
|
||||
- the default camera's exact maths: views, `lookAt`, flights with their
|
||||
height arc and easing, `changed` thresholds and follows;
|
||||
- picks against what was drawn, or a scripted table;
|
||||
- scripted heights;
|
||||
- a virtual clock that nothing advances on its own;
|
||||
- models that load at once, but for urls under `stub-fail:`
|
||||
(`STUB_FAILING_MODEL_SCHEME`), which fire `loadFailed` instead of `ready`
|
||||
(they are still picked where they are).
|
||||
|
||||
`renderer.testing` drives it with `tick()`, `advance(ms)`, `pointer(type, x, y)`,
|
||||
`scriptPicks`, `setHeights` and `cacheHeight`, and records its calls.
|
||||
`testing.drawnPosition({ set, id }, aheadMs)` is where it draws an item now
|
||||
(or `aheadMs` from now), so a
|
||||
camera controller over the stub can follow drawn items there.
|
||||
A listener that throws with nothing subscribed to `error` goes to
|
||||
`reportError`; Node has none, so the stub rethrows it on a microtask and
|
||||
`node:test` fails the running test. A test that expects a throw subscribes
|
||||
to `error`.
|
||||
The stub passes the whole conformance suite (`src/render/stub/stub.test.mjs`).
|
||||
|
||||
## Conformance suite
|
||||
|
||||
`runConformance(harness)` runs every check against the Cesium renderer or
|
||||
the stub through the contract alone and reports each one as passed, failed or skipped. It runs in
|
||||
Node and in a browser page. A harness tells the suite how to drive the
|
||||
renderer under test:
|
||||
|
||||
- `create({ viewport, capabilities })`;
|
||||
- `frame(r)`: one frame, 1/60 s on a virtual clock;
|
||||
- `now(r)` and `toEcef(p)`;
|
||||
- `tolerance` and `flightPaths`.
|
||||
|
||||
Optional members widen what is checked: `pointer` for synthetic input,
|
||||
`cameraInput` (the camera answers that input: the drag and wheel traces
|
||||
run), `scriptHeights`, `resizeContainer` (sizes the element the renderer
|
||||
fills, for the `resize` check, which skips without it), `assets.model`, and
|
||||
`assets.missingModel` (a model url that fails to load, for the `loadFailed`
|
||||
check). `pixels: false` says
|
||||
the renderer draws nothing but models into its pixels, as the stub: the
|
||||
checks that read drawn icons, lines and fields then skip. Without it they
|
||||
run, and the renderer fails them if it draws nothing there.
|
||||
|
||||
There are two layers of checks.
|
||||
|
||||
**Logic checks** run in CI. They cover:
|
||||
|
||||
- the shape check;
|
||||
- listener semantics and the frame loop;
|
||||
- draw-set bookkeeping, picks and the `meta` round-trip;
|
||||
- projection, rays and heights;
|
||||
- leases and click picks;
|
||||
- imagery order, sky, styles, credits and quality knobs;
|
||||
- the camera traces.
|
||||
|
||||
**Camera traces.** `cameraScripts.js` lists camera scripts in the contract's
|
||||
terms. `scripts/record-camera-goldens.mjs` runs them on Cesium's own
|
||||
`Camera`, headless, on a virtual clock, and writes
|
||||
`src/render/conformance/goldens/camera.json`. A renderer under test must
|
||||
match each recorded pose:
|
||||
|
||||
- within 1 mm in position, 1e-9 in unit vectors and angles, and 1e-3 px on
|
||||
screen;
|
||||
- with every flight ending within one frame of the recording.
|
||||
|
||||
Some scripts move the camera by user input: left, middle, Shift and Ctrl
|
||||
drags, and wheels in pixel and line mode. The recorder runs those on
|
||||
Cesium's own `ScreenSpaceCameraController`, fed the DOM events the script
|
||||
describes, with `Date` on the virtual clock too (its coasting reads it). A
|
||||
renderer under test gets them through its harness's `pointer`, a wheel as
|
||||
the input port's lines. Only a harness with `cameraInput` runs them: the
|
||||
stub's camera takes no gestures, so it skips them; a camera controller
|
||||
over the stub would run them. `cameraPort.test.mjs` runs them on Cesium's
|
||||
controls under the Cesium camera port, each wheel sent back as lines.
|
||||
|
||||
A wheel's `delta` is lines as Cesium counts them: a pixel-mode wheel at
|
||||
40 px a line and a page at 3 lines (`src/render/input/wheel.js`). Turning
|
||||
lines back into pixels at 40 px a line gives Cesium's own wheel in every
|
||||
mode, so a controller that does that zooms as Cesium does in Chrome (pixel
|
||||
mode) and Firefox (line mode) alike.
|
||||
|
||||
`src/render/cesium/cameraGoldens.test.mjs` fails when the installed Cesium
|
||||
no longer records the committed traces. After a Cesium upgrade or a script
|
||||
change, run `node scripts/record-camera-goldens.mjs` and review the diff.
|
||||
|
||||
**Visual checks** run in the browser. The reference scenes
|
||||
(`src/render/conformance/scenes.js`) are built from contract calls only:
|
||||
|
||||
- one scene per primitive family;
|
||||
- a city scene;
|
||||
- a calibration path from orbit down to the street.
|
||||
|
||||
The scenes load nothing from the network.
|
||||
|
||||
`npm run dev`, then open `/dev/conformance/`. The page can:
|
||||
|
||||
- **Run logic suite (stub)** runs the logic checks in the browser.
|
||||
- **Record references** draws every scene the chosen renderer supports.
|
||||
It saves each view to `src/render/conformance/goldens/visual/`, through a
|
||||
dev-server-only endpoint.
|
||||
- **Check scenes** draws the scenes again and compares each capture with its
|
||||
reference. Pixels are compared as pixelmatch compares them: by YIQ
|
||||
difference (threshold 0.1), with antialiasing in either image excused. A
|
||||
capture matches when at most 250 pixels are unexcused and at most 2 are
|
||||
solid (a differing pixel whose four neighbours differ too). Between them
|
||||
the two catch a dropped 4 px point, a dropped 2 px line and a 1 px shift
|
||||
of the view, and pass any MSAA setting. A change nowhere 3 px thick (a
|
||||
thin line gone, an item moved a pixel or two) that covers at most 250 px
|
||||
passes. `visual.js` has the measurements.
|
||||
The page shows the capture, the reference and the difference side by side.
|
||||
|
||||
`window.conformance.runScenes()` and `runLogic()` do the same from a script.
|
||||
|
||||
`npm run qa:conformance` runs the logic checks on the Cesium renderer in
|
||||
headless Chromium (software WebGL, no GPU needed). It starts its own Vite
|
||||
server unless given `--url`; `--only id,id` runs just those checks and
|
||||
`--json path` writes the report. It fails on any failed check and on any
|
||||
skip it does not expect (`query.heights`, which needs scripted heights, is
|
||||
the one it expects). CI runs it in the `street-level-browser` job.
|
||||
Browser checks use the chrome-devtools MCP against a page in its own window.
|
||||
|
||||
The Cesium scene renderer (`src/render/cesium/sceneRenderer.js`) draws
|
||||
every scene (icons, points, lines, shapes, models, quads, meshes, fields
|
||||
and the city), and the references were recorded with it, on a GPU: a
|
||||
software rasterizer such as SwiftShader draws the glow line differently.
|
||||
It has only the members the scenes need.
|
||||
|
||||
Some behaviour is only drawn, so the logic checks cannot see it: course
|
||||
easing (`courseGlide`), and a hidden row keeping its eased
|
||||
course. The stub keeps no drawn course. These wait for scenes that capture
|
||||
an icon mid-turn. Height queries that count a set
|
||||
(`includeInHeightQueries`) are not checked either: the stub's heights are
|
||||
scripted, so it does not model them. Nor are video frames (a check needs a
|
||||
video) or `fetchTile` (the stub fetches nothing).
|
||||
Reference in new issue
Block a user