Merge main into german/i18n-plurals-context
The catalogs conflicted only on neighbouring lines: no key changed on both sides, so they are merged key by key in main's order. Main removed the rail timeline, the other user of plain "Latest", so that entry is pruned and the News test no longer checks the timeline's wording.
No files matched your search
@@ -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
|
||||
@@ -187,7 +304,28 @@ instances. Configure sources with `application/sources` before registration or
|
||||
state restoration, and release them after the consumers stop. The catalog
|
||||
constructor (`application/layers`) also requires `wind`, `weather` and
|
||||
`cyclones` sources with `getSnapshot` for the Weather layers, and owns the
|
||||
observed-history clock those layers share for the catalog's lifetime.
|
||||
observed-history clock those layers share for the catalog's lifetime. That
|
||||
clock, the catalog's `weatherClock`, follows the world clock (`gods-eye-view/time`)
|
||||
and has no time controls of its own: move time with the world clock's `seek`,
|
||||
`play`, `pause` and `goLive` (`weatherClock.world` is the one it follows).
|
||||
|
||||
A layer gives the world clock's timeline the time it can show with
|
||||
`worldClock.register({ id, coverage })` (`gods-eye-view/time`), which returns
|
||||
the unregister; call `worldClock.coverageChanged()` when that time changes.
|
||||
`coverage()` returns null while the layer has none, or
|
||||
`{ start, end, marks? }` in epoch ms. `marks` are the moments worth going to,
|
||||
drawn as ticks the timeline's arrow keys step to and a tap on or within 6 px of
|
||||
snaps to. Each mark is a number, or `{ time, label?, id?, kind? }`: `label` is
|
||||
short text (cut to 60 characters, ending in `…`) shown when the pointer is on
|
||||
the tick and told with the time while the handle is on the mark, `id` the layer's own key for the event and `kind`
|
||||
what sort of event it is (`'launch'`, `'earthquake'`). The two forms may be
|
||||
mixed; a mark without a finite time, and a `label`, `id` or `kind` that is not
|
||||
a non-empty string, are ignored. `worldClock.coverage()` returns the union of
|
||||
the registered layers, `{ start, end, marks, markDetails }`, or null: `marks`
|
||||
is every mark's time once, in order, as numbers, and `markDetails` the marks in
|
||||
time order, each a frozen `{ time, label?, id?, kind? }` holding only the
|
||||
fields given, with marks given alike by several layers once and a bare time
|
||||
left out where a mark with more to say shares it.
|
||||
A `weather` source may also supply decoded frames: an optional
|
||||
`getFrameImage({ product, time, size, bbox, signal })` returns a whole-extent or
|
||||
detail image and an optional `getFrameTile({ product, time, z, x, y, size,
|
||||
@@ -195,6 +333,12 @@ signal })` returns one tile or null for a transparent tile, each as an
|
||||
`ImageBitmap`, `ImageData`, canvas or `VideoFrame` of exactly the requested
|
||||
size, which the layer draws once and closes. Without them the layers read the
|
||||
image and tile routes (`WeatherFrameFeed` in `src/layers/weather/source.js`).
|
||||
It may also name its source with an optional `sourceName(kind)`, `kind` being
|
||||
`'radar'`, `'lightning'` or `'satellite'`: the layer's row shows that name until
|
||||
a manifest names its own, and NOAA nowCOAST when the source names none. The
|
||||
name is read once, when the layer is built, and held to the same rule as a
|
||||
manifest's `display.source`. The map credit still comes from each manifest's
|
||||
`display.credit`, so a source that is not nowCOAST sets that too.
|
||||
|
||||
`application/services` accepts boundary, terrain, regional-context, weather and
|
||||
summary services; its weather service supplies cockpit local conditions, not the
|
||||
@@ -230,3 +374,125 @@ starts and switches the language with the `./i18n` entry (`startPageLocale`,
|
||||
`localePicker: false` to `createApplicationControls` instead of editing the
|
||||
markup. Node tests that import application modules register the component
|
||||
loader with `node --import=<core package>/build/register-vue`.
|
||||
|
||||
### Cockpit subjects
|
||||
|
||||
Core's Cockpit rides a tracked aircraft, the tracked satellite and the
|
||||
selected AIS vessel. An application adds kinds of its own with
|
||||
`services.cockpitSubjects` on `createApplicationControls`: a list of
|
||||
providers, checked once when the controls are built
|
||||
(`src/cockpitSubjectProviders.js`). A malformed provider, or one with a member
|
||||
that throws when read (a getter), is left out with a warning and the rest are
|
||||
kept. A provider's subject takes entry when it was selected after every
|
||||
built-in subject present (a tracked aircraft or satellite, a selected vessel),
|
||||
whose own fixed order is unchanged, and needs the provider's `layerId` on; the
|
||||
provider then holds its subject, hands the camera a frame and the generic HUD
|
||||
a view model on every update, and releases it on exit. Provider methods are
|
||||
synchronous and are called on the provider, so a class instance's methods keep
|
||||
their `this`; one that throws or returns a promise is treated as having
|
||||
failed. What a method returns may carry getters: one that throws when read
|
||||
makes a candidate none, a frame malformed (the view ends) and a HUD view keep
|
||||
the last; a worded member (labels, entry face, look) that throws keeps its
|
||||
last good words.
|
||||
|
||||
```js
|
||||
import { getLocale, onLocaleChange } from 'gods-eye-view/i18n';
|
||||
import { pointAtS } from 'gods-eye-view/layers/rail/paths';
|
||||
|
||||
const words = {
|
||||
en: { view: 'Ride view', exit: 'Exit ride view', exitText: 'EXIT RIDE' },
|
||||
de: {
|
||||
view: 'Fahrtansicht',
|
||||
exit: 'Fahrtansicht verlassen',
|
||||
exitText: 'VERLASSEN',
|
||||
},
|
||||
};
|
||||
|
||||
/** Ride the Rail layer's selected train; `rail` is its layer instance. */
|
||||
const ride = {
|
||||
kind: 'example-ride',
|
||||
layerId: 'rail',
|
||||
entryFace: { icon: 'train', label: 'RIDE' },
|
||||
// A function is read again when the page's language changes.
|
||||
labels: () => words[getLocale()] ?? words.en,
|
||||
candidate() {
|
||||
const train = rail.getSelectedTrain();
|
||||
return (
|
||||
train && {
|
||||
id: train.key,
|
||||
name: train.label,
|
||||
selectedAt: train.selectedAtMs,
|
||||
}
|
||||
);
|
||||
},
|
||||
// Only a train bound to its line can be ridden: read() needs its path.
|
||||
isEntryAllowed: () => Boolean(rail.getSelectedTrain()?.path),
|
||||
hold: (id) => rail.setCockpitSubject(id),
|
||||
read(nowMs, ctx) {
|
||||
const train = rail.getCockpitSubject();
|
||||
if (!train?.path) return null; // ends the view
|
||||
const point = pointAtS(train.path.line, train.path.s);
|
||||
return {
|
||||
id: train.key,
|
||||
latitude: point.lat,
|
||||
longitude: point.lon,
|
||||
heightM: train.position.railHeightM, // null stands it on the shared floor
|
||||
name: train.label,
|
||||
headingDeg:
|
||||
train.path.direction < 0 ? point.bearingDeg + 180 : point.bearingDeg,
|
||||
speedMps: train.motion.reportedSpeedMps ?? train.motion.derivedSpeedMps,
|
||||
// The layer already moves the train smoothly: sit on it.
|
||||
anchor: 'exact',
|
||||
eye: { upM: 3.5 },
|
||||
};
|
||||
},
|
||||
hud: (frame) => ({ title: frame.name }),
|
||||
release(id, { restore }) {
|
||||
rail.setCockpitSubject(null);
|
||||
if (restore) rail.focusTrain(id);
|
||||
},
|
||||
};
|
||||
|
||||
createApplicationControls({ /* ... */ services: { cockpitSubjects: [ride] } });
|
||||
```
|
||||
|
||||
The `./i18n` entry gives `getLocale()` and `onLocaleChange()`:
|
||||
Core translates only its own strings, so a provider words its labels, entry
|
||||
face and HUD for the page's language (labels may be functions, as above; the
|
||||
HUD is read again on a change). `gods-eye-view/layers/rail/paths` is the
|
||||
Rail layer's pure path module (`createRailPath`, `pointAtS`, `projectOnPath`)
|
||||
for a provider placing a train along its line. The frame, HUD view and
|
||||
candidate fields are documented in `src/cockpitSubjectProviders.js`; the Rail
|
||||
and Transit read APIs in `src/layers/rail/cockpitSubject.js` and
|
||||
`src/layers/transit/cockpitSubject.js`. A snapshot read again while nothing in
|
||||
it changed is the one read before, so `read` may take one on every update; a
|
||||
train's `path.line` is a frozen copy of its line, for `pointAtS` and
|
||||
`projectOnPath`. The `layers/rail/paths` export and the
|
||||
Rail and Transit read APIs (`getSelectedTrain`, `getSelectedVehicle`,
|
||||
`getCockpitSubject` and the snapshots they return, `path.line` among them)
|
||||
are experimental and may change without notice.
|
||||
|
||||
A candidate's `selectedAt` is a token that changes each time the user selects
|
||||
the subject, even the same one again, so entry counts it as selected then; a
|
||||
new `id` under the same token is the same selection (a train's selection
|
||||
moving to another feed's copy of it). The Rail and Transit snapshots give one,
|
||||
`selectedAtMs`: when the user last selected the train or vehicle by a click or
|
||||
`focusTrain`/`focusVehicle`. It is null after a deselection and for one
|
||||
selected only by a hold, since a hold is not the user's selection.
|
||||
|
||||
A frame with `heightM: null` stands on the shared floor, or where it last
|
||||
stood while that floor is cold. If no height has been known since entry, the
|
||||
view waits, showing ACQUIRING SURFACE, for at most five seconds
|
||||
(`COCKPIT_GROUND_WAIT_TIMEOUT_MS`), then ends and releases the subject.
|
||||
|
||||
`hold(id)` returns `true` once it holds the subject, or `false` to refuse
|
||||
entry; any other answer, `undefined` included, refuses entry too, with one
|
||||
warning. A refused hold, and one that throws or returns a promise, is followed
|
||||
by `release(id, { restore: false })`, again once a returned promise settles,
|
||||
so `release` must be harmless for a subject it does not hold and when called
|
||||
more than once.
|
||||
|
||||
Leaving the view does not track again an aircraft that was tracked before
|
||||
entry, as with the bridge and orbital views: when the user leaves by the exit
|
||||
control, the map goes back to the ridden subject through
|
||||
`release(id, { restore: true })`.
|
||||
@@ -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
|
||||
|
||||
@@ -293,9 +294,9 @@ the user's later collapse choice, including body remounts. Mark the body
|
||||
`max-height` and puts the scroll offset back afterwards. Panel bodies only
|
||||
scroll on an open-card change, with one write, never on a refresh.
|
||||
|
||||
Compose `createRailCards({ container, document, onParams, onOpen })` and
|
||||
`createRailTimeline({ container, document, onCommit, onPreview, onStep,
|
||||
onLatest, onPlay })`. Cards reconcile `{ id, title, badge, open, compact,
|
||||
Compose `createRailCards({ container, document, onParams, onOpen })`. Rails
|
||||
have no time controls of their own; the world timeline moves time. Cards
|
||||
reconcile `{ id, title, badge, open, compact,
|
||||
compactStatus, blocks }` in place. Their full-width native button headers expose
|
||||
`aria-expanded` and `aria-controls`; articles expose `data-open`. The feature
|
||||
adapter owns accordion state. Generic cards do not select data or enable layers.
|
||||
@@ -330,10 +331,9 @@ consumers. They expose `summary.settings`, `summary.actions` and optional
|
||||
subscriptions still refresh the cards. Cards own configuration and readings.
|
||||
|
||||
Weather orders cyclones, wind, then a bordered Observed history group containing
|
||||
the timeline and active radar, satellite and lightning cards. The group heading
|
||||
and scope name its active products. The timeline stays visible whenever any
|
||||
observed product is enabled; fewer than two ticks disables transport. Pass
|
||||
`heading: false` to the timeline when the containing group owns the heading.
|
||||
the frame time and active radar, satellite and lightning cards. The group
|
||||
heading and scope name its active products. The frame time shows whenever any
|
||||
observed product is enabled and has a frame; the world timeline moves time.
|
||||
Exactly one active card is open. Header clicks and newly enabled ids choose it
|
||||
(the last new entry wins a batch); refreshes and clock ticks retain it. First
|
||||
appearance uses cyclones with storms, otherwise the first card. Disabling the
|
||||
@@ -341,7 +341,7 @@ open layer falls back to the first remaining card. A WeakMap per document keeps
|
||||
explicit choices through body remounts without adding share state. Card opening,
|
||||
storm selection and layer enabling remain independent.
|
||||
|
||||
Optional card/badge/slider class names provide feature styling. Card titles use
|
||||
Optional card/badge class names provide feature styling. Card titles use
|
||||
`.data-name` typography; meta/time/badges use `.data-toggle-meta` typography;
|
||||
setting/result labels use `.panel-title`; chips retain `.data-toggle-chip`.
|
||||
Reserve one status line, even without a legend. Use app tokens. Wind's footer
|
||||
@@ -471,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
|
||||
@@ -508,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 })`.
|
||||
@@ -572,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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -83,6 +83,21 @@ menu.onChoose = (code) => switchLocale(code); // switched in place and stored (i
|
||||
|
||||
`switchLocale` does what a choice in the globe picker does, and returns `'unchanged'` for the active language. `onLocaleChange` tells the application's own menu to mark the new language.
|
||||
|
||||
The same entry exports the translator Core's text goes through (`t`, `tn`, `msg`, `translateKnown`, `formatNumber`, `formatDate`, `formatRelativeTime`), so the application's own text follows the same language. To show its own wording for one of Core's messages, it overrides it by the catalog key, in English and in any locale it words:
|
||||
|
||||
```js
|
||||
import { setMessageOverrides } from '<core package>/i18n';
|
||||
|
||||
setMessageOverrides({
|
||||
en: { 'Download scene JSON': 'Download scene file' },
|
||||
de: { 'Download scene JSON': 'Szenendatei herunterladen' },
|
||||
});
|
||||
```
|
||||
|
||||
Keys are the catalogs' (`context|text` for a context, the English plural for `tn`). A `t` entry is text; a `tn` entry is `{one, other, …}` forms, chosen by the plural rules of the locale they are worded in; an entry of the other kind is ignored. An overridden message shows the application's text in the active locale, else its English: an English-only override replaces Core's translations of that message too, so word every locale that should keep its own. Each call replaces the earlier overrides and `{}` removes them.
|
||||
|
||||
Call it before views render. `onLocaleChange` listeners word their text again at once, but a view already drawn keeps its text until it next renders. Import it from the `./i18n` entry only: a second copy of the module (a path alias into Core's sources) keeps its own overrides and language.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Pass literals.** `t('Close')`, not `t(label)` (unless `label` holds a `msg()` value) and never a template literal with `${…}`.
|
||||
|
||||
@@ -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.
|
||||
@@ -32,6 +32,11 @@ hardware-rendered overlay scenes.
|
||||
| 3 | 558.527 ms | 1,809.592 ms | 438.8 ms | 60 / 60 FPS | 105.1 MiB |
|
||||
| Median | 604.849 ms | 1,855.836 ms | 439.5 ms | 60 / 60 FPS | 105.1 MiB |
|
||||
|
||||
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 (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
|
||||
the display ceiling during both motion and rest.
|
||||
|
||||
@@ -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).
|
||||
@@ -148,6 +148,7 @@ probability of about 255 in 256 (many of them already fail as base64url).
|
||||
| 27 | `styleParams` | LEN | style | packed `(token, value × 100)` pairs |
|
||||
| 28 | `worldTime` | epoch | none (live) | zigzag seconds since 2026-01-01T00:00:00Z |
|
||||
| 29 | `library` | LEN | none | Data Library ledger tokens, two base-36 characters each, concatenated |
|
||||
| 30 | `scopeOpacityPct` | uint | 100 | 0–100, how strongly the scope mask shows |
|
||||
|
||||
Field 1 absent means `thing` when field 13 is present and `place` otherwise,
|
||||
so v1 never writes it; a later view kind writes its code.
|
||||
@@ -170,6 +171,10 @@ tokens in `src/library/ledger.json` (the long form's `lib=ab.cd`). A share
|
||||
without it switches no library entry on; the recipient's added entries stay
|
||||
in their panel, off. Tokens this build does not know are skipped.
|
||||
|
||||
Field 30 is how strongly the scope mask shows, from the Visual panel's
|
||||
Opacity slider (the long form's `sco`). It is written only below 100, so a
|
||||
link made before it, which opens at full opacity, keeps its code.
|
||||
|
||||
Flag bits (field 9): 0 `bloom`, 1 `sharpen`, 2 `hudVisible`, 3
|
||||
`celestialRing` (each defaulting by style), 4 `scopeEnabled` (default on).
|
||||
|
||||
|
||||
@@ -153,9 +153,9 @@ a feature supplying only its accent.
|
||||
`t()`, which follows the locale as the view renders; the views carry no
|
||||
`data-i18n*` markers, which `npm run i18n` rejects in a template. Shared builders become components first and
|
||||
keep their imperative entry points until their owners are components:
|
||||
the rail cards, card blocks and timeline (`src/ui/rail/`) render through
|
||||
Vue's synchronous `render()` behind `createRailCards()`,
|
||||
`createRailCardBlocks()` and `createRailTimeline()`. Order: Scenes (done: `SceneOptions` and
|
||||
the rail cards and card blocks (`src/ui/rail/`) render through
|
||||
Vue's synchronous `render()` behind `createRailCards()` and
|
||||
`createRailCardBlocks()`. Order: Scenes (done: `SceneOptions` and
|
||||
`SceneShotList` over the `gev-scenes` store; the panel's buttons, status
|
||||
line, progress bar and the runtime chip render the panel SceneControls
|
||||
presents there, and the buttons and file chooser call its actions), Weather (done: the owner
|
||||
|
||||
|
Before Width: | Height: | Size: 981 KiB |
|
Before Width: | Height: | Size: 5.6 MiB |
|
Before Width: | Height: | Size: 5.8 MiB |
|
Before Width: | Height: | Size: 3.0 MiB |
|
Before Width: | Height: | Size: 4.8 MiB |
|
Before Width: | Height: | Size: 5.3 MiB |
|
Before Width: | Height: | Size: 6.0 MiB |
|
Before Width: | Height: | Size: 4.8 MiB |
|
Before Width: | Height: | Size: 889 KiB |
|
Before Width: | Height: | Size: 1.8 MiB |
|
Before Width: | Height: | Size: 3.7 MiB |
|
Before Width: | Height: | Size: 2.2 MiB |
|
Before Width: | Height: | Size: 3.0 MiB |
|
Before Width: | Height: | Size: 2.6 MiB |
@@ -1,39 +1,36 @@
|
||||
# README media provenance
|
||||
|
||||
## Capture GIFs
|
||||
## Site clips
|
||||
|
||||
Bilawal Sidhu created and owns the following 17 GIFs and has authorized their inclusion and redistribution as part of this public repository and its project documentation. Any appearance by Bilawal Sidhu in these captures is included with his permission.
|
||||
The following animated images in `site/` are the clips shown on [godseyeview.ai](https://godseyeview.ai), converted to animated WebP for the README. Bilawal Sidhu and Halfpixel, Inc. created them and have authorized their inclusion and redistribution as part of this public repository and its project documentation.
|
||||
|
||||
- `hero-open-source-reveal.gif`
|
||||
- `06-cockpit-ar.gif`
|
||||
- `start-here/airport-ground-traffic-google-3d.gif`
|
||||
- `03-austin-cctv.gif`
|
||||
- `14-iss-over-ukraine.gif`
|
||||
- `01-style-sweep.gif`
|
||||
- `12-switch-aircraft-cockpit.gif`
|
||||
- `start-here/military-cockpit-dense-google-3d.gif`
|
||||
- `01-voice-annotate-zilker.gif`
|
||||
- `04-airport-distance.gif`
|
||||
- `15-global-radio-layer.gif`
|
||||
- `08-falcon9-replay.gif`
|
||||
- `09-undersea-cables.gif`
|
||||
- `07-helicopter-loops.gif`
|
||||
- `10-walking-route-flythrough.gif`
|
||||
- `08-boneyard.gif`
|
||||
- `05-traffic-to-cctv.gif`
|
||||
- `site/hero.webp`
|
||||
- `site/voice.webp`
|
||||
- `site/flights.webp`
|
||||
- `site/satellites.webp`
|
||||
- `site/cameras.webp`
|
||||
- `site/cockpit.webp`
|
||||
- `site/weather.webp`
|
||||
- `site/imagery.webp`
|
||||
- `site/transit.webp`
|
||||
- `site/sdr.webp`
|
||||
- `site/radio.webp`
|
||||
- `site/mcp.webp`
|
||||
- `site/director.webp`
|
||||
|
||||
Copyright © Bilawal Sidhu. These files are not covered by the project's MIT License. Permission is limited to their inclusion and redistribution with this repository and its project documentation. No permission is granted for standalone reuse or modification. Commercial reuse outside this repository requires separate permission. No share-alike license applies.
|
||||
Copyright © Bilawal Sidhu and Halfpixel, Inc. These files are not covered by the project's MIT License. Permission is limited to their inclusion and redistribution with this repository and its project documentation. No permission is granted for standalone reuse or modification. Commercial reuse outside this repository requires separate permission. No share-alike license applies.
|
||||
|
||||
The GIFs are promotional captures of God's Eye View. They include Google Photorealistic 3D Tiles and public or third-party data layers with in-frame attribution. Bilawal Sidhu's ownership and permission cover the captures and his likeness; they do not replace the terms of Google Maps Platform or any displayed data provider. Keep the visible attribution intact.
|
||||
The clips are promotional captures and renders of God's Eye View. Some include Google Photorealistic 3D Tiles and public or third-party data layers with in-frame attribution. The permission above covers the clips; it does not replace the terms of Google Maps Platform or any displayed data provider. Keep the visible attribution intact.
|
||||
|
||||
The launch-era capture GIFs that this page listed before were removed from the README and from the repository in November 2026. They remain in the Git history under the terms stated for them at the time.
|
||||
|
||||
## Public README PNGs
|
||||
|
||||
Bilawal Sidhu published the following PNGs in the existing public `bilawalsidhu/gods-eye-view` repository and authorized their continued inclusion and redistribution with this repository and its project documentation:
|
||||
Bilawal Sidhu published the following PNG in the existing public `bilawalsidhu/gods-eye-view` repository and authorized their continued inclusion and redistribution with this repository and its project documentation:
|
||||
|
||||
- `youtube-popular-videos.png`
|
||||
- `open-source-survey.png`
|
||||
|
||||
Source: [`assets/youtube-popular-videos.png`](https://github.com/bilawalsidhu/gods-eye-view/blob/7afb3beefb2dd39110ed117c8f06825e9ca2ada4/assets/youtube-popular-videos.png) and [`assets/open-source-survey.png`](https://github.com/bilawalsidhu/gods-eye-view/blob/7afb3beefb2dd39110ed117c8f06825e9ca2ada4/assets/open-source-survey.png) in public repository commit [`7afb3beefb2dd39110ed117c8f06825e9ca2ada4`](https://github.com/bilawalsidhu/gods-eye-view/commit/7afb3beefb2dd39110ed117c8f06825e9ca2ada4). The localized files preserve the source bytes unchanged.
|
||||
Source: [`assets/open-source-survey.png`](https://github.com/bilawalsidhu/gods-eye-view/blob/7afb3beefb2dd39110ed117c8f06825e9ca2ada4/assets/open-source-survey.png) in public repository commit [`7afb3beefb2dd39110ed117c8f06825e9ca2ada4`](https://github.com/bilawalsidhu/gods-eye-view/commit/7afb3beefb2dd39110ed117c8f06825e9ca2ada4). The localized files preserve the source bytes unchanged.
|
||||
|
||||
These files are not covered by the project's MIT License. No permission is granted for standalone reuse or modification. Commercial reuse outside this repository requires separate permission. No share-alike license applies.
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 6.2 MiB |
|
After Width: | Height: | Size: 467 KiB |
|
After Width: | Height: | Size: 447 KiB |
|
After Width: | Height: | Size: 538 KiB |
|
After Width: | Height: | Size: 664 KiB |
|
After Width: | Height: | Size: 1.8 MiB |
|
After Width: | Height: | Size: 314 KiB |
|
After Width: | Height: | Size: 405 KiB |
|
After Width: | Height: | Size: 453 KiB |
|
After Width: | Height: | Size: 304 KiB |
|
After Width: | Height: | Size: 299 KiB |
|
After Width: | Height: | Size: 788 KiB |
|
After Width: | Height: | Size: 370 KiB |
|
After Width: | Height: | Size: 690 KiB |
|
Before Width: | Height: | Size: 1.2 MiB |
|
Before Width: | Height: | Size: 8.2 MiB |
|
Before Width: | Height: | Size: 958 KiB |