Merge remote-tracking branch 'origin/main' into feat/alpr-model-specs

This commit is contained in:
German Khokhlov committed 2026-11-19 18:24:38 +04:00
commit 4eacbe67c7
2602 files changed
+251040 -57704

No files matched your search

+153 -4
View File
@@ -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
@@ -167,7 +284,10 @@ rejects delayed responses; a new start requests a fresh secret. Secret expiry
limits connection creation and does not describe the connected session lifetime.
`createStandaloneApplication({ voice })` passes these construction options to
the controls. An incompatible protocol needs a separate controller adapter;
the controls. An app can supply `voice.openStories({ isCurrent })` for what the
`open_stories` action does, spoken or typed; it answers true when it opened,
`'already-open'`, or false. Without it the action opens the Stories page.
An incompatible protocol needs a separate controller adapter;
changing an endpoint alone does not translate protocol messages. No alternate
model is bundled by this extraction. The Node Realtime provider accepts
`realtime: { endpoint, models: { standard, mini }, resolveApiKey, fetchImpl }`;
@@ -187,7 +307,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 +336,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
@@ -249,7 +396,9 @@ 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.
last good words. An entry face's `icon` is a Material Symbols name whose glyph
the application's page must load (GEV's own `index.html` loads a subset, its
`icon_names`); a glyph the page does not load renders as its name.
```js
import { getLocale, onLocaleChange } from 'gods-eye-view/i18n';
+35 -12
View File
@@ -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
@@ -149,7 +150,8 @@ Google credentials are resolved on each request; the default uses the existing
server-key precedence, and callers may supply `resolveApiKey`.
`gods-eye-view/sources/places` exports portable response projections for Google
place results and OSRM route results/profile aliases. These functions own no
place results and OSRM route results/profile aliases, and the turn-by-turn
steps (`normalizeOsrmSteps`) Core's `/api/route` serves with `steps=1`. These functions own no
credentials, requests, caches, environment loading, or rendering. Callers retain
input validation and upstream-response acceptance. The boundary check builds
this entry independently and rejects Node imports.
@@ -293,9 +295,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 +332,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 +342,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 +472,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 +516,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 +589,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.
@@ -757,8 +781,7 @@ palettes use `--gev-field-background`, `--gev-field-border-color`,
`--gev-field-color` and `--gev-field-disabled-opacity`. Radio retains its own
compact density and arrow space. CCTV owns calibration editor width in
`cctv.css`; the shared inline density does not impose a feature-specific width.
Cyber supplies a shared-field palette explicitly and keeps its legacy native
field rules separate, so Radio's palette remains an intentional exception.
Radio's palette remains an intentional exception.
### Read-only status badges
+1617 -334
View File
File diff suppressed because it is too large. Load diff
+47
View File
@@ -167,6 +167,53 @@ code. It reaches only the manifest's host, refuses redirects, caps bodies,
caches per `cacheSeconds` and never returns upstream error text. The browser
names an entry id, never a URL, so the proxy cannot be pointed anywhere else.
## Serving the library from another server
The proxy is also a fetch handler, `createLibraryHandler` from
`gods-eye-view/sources/library` (`src/library/proxy.js`): a `Request` in, a
`Response` out, for a server other than the dev server (a Worker, say). Its
options decide what the server offers:
- `listed(entry)` false hides an entry: `/catalog` marks it `listed: false`,
Browse leaves it out entirely, and no route serves it.
- `proxied(entry)` true routes a `browser-direct` entry through the handler:
`/catalog` marks it `fetch: "proxied"` and the browser asks the server for
its tiles and data. A view-bounded entry then asks `/data/<id>?bbox=…` for
the camera's box snapped out to a power-of-two grid (`libraryViewBox`), so
nearby views share one answer; any other box is refused.
- `keep: false` keeps nothing in the process's memory, for a server with a
shared cache in front. Answers carry `Cache-Control: public,
max-age=<cacheSeconds>` (`private` for a keyed entry).
- `partitionCache` is the map of decoded GeoParquet partitions (at most four
are kept); pass one map per process to cap them there.
- `fetchIndex(entry)` reads a partitioned entry's index, for example the
handler's own `/index/<id>` through a shared cache. A `/data` request never
builds an index itself: without a complete or partial one it answers 503
`index_unavailable`.
- `subrequestLimit` caps the upstream requests one request may make (a host's
per-request limit); a request that would need more answers 503
`subrequest_limit` instead.
Every resource has one spelling: tile paths are `/tile/<id>/<z>/<x>/<y>` with
integers without leading zeros, `x` and `y` below `2^z` and `z` within the
entry's zoom range; a path with an empty segment or a trailing slash is
refused; a view box is accepted only in `libraryViewBox`'s exact spelling. A
shared cache keyed on the path (and a `/data` request's `bbox`) therefore
holds each answer once.
Same-site gates and rate limits stay with the server that mounts it. An
application can also fetch the library's tiles and proxied datasets itself,
to keep them in its own cache: `createApplicationTools({ library: { fetchTile,
fetchData } })`. `fetchTile` is the imagery spec's tile fetch, told which
entry asks; `fetchData` answers a proxied dataset URL.
`library: { requireCatalog: true }` makes the server's `/catalog` an
allowlist: the library offers only what it names, and while it does not
answer (an error status, a timeout, a page that is not the catalog) it offers
nothing at all, rather than every entry the browser could fetch itself. It is
asked again after 30 seconds, then at doubling intervals up to ten minutes,
and the viewer's saved entries come back once it answers.
## Operator switches
| Variable | Effect |
+5
View File
@@ -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
+17 -2
View File
@@ -17,7 +17,9 @@ file sharing, along with the remaining extensions.
The runner imports no renderer, UI, storage, recipe or dataset. An adapter supplies
these phases, in order: `selectShot`, `applyVisual`, `applyLayers`, `travel`,
`settle`, `hold`, `completeShot`. Each receives `{ scene, shot, index, total,
token }`. It also supplies `releaseScene(scene, token?)` and optionally `complete()`.
token, resume }`, where `resume` is the queue item's own (null unless the queue
starts partway into its first shot). It also supplies `releaseScene(scene, token?)`
and optionally `complete()`.
Callbacks may return promises. Each playback invocation requires its own adapter
state and token; the caller owns camera arbitration and concurrent-run refusal.
@@ -32,7 +34,20 @@ acquire no resources. This low-level API expects normalized scene objects;
untrusted file validation belongs at the import boundary.
`src/scenes/playbackAdapter.js` connects this runner to the existing
`SceneDirector`. The latter still owns editor state, saved-project import/export,
`SceneDirector`. `startScene(sceneId, { fromProgress })` starts a run at a
point of the scene's clock: the queue begins with the shot that point falls in,
carrying that point's seek state as `resume`. Inside the shot's flight the camera
goes on from there along the rest of the path a seek samples, over the rest of the
flight; inside its hold, the layers take that moment's state as a seek gives them
and then play on from it: a reveal goes on from where the seek put it, and a
clip the moment falls in starts again from its beginning (a clip cannot be
joined partway), while one the moment is past stays finished. A clip started
again plays the hold out as from its start: until its media gate opens (a
trimmed clip, with its fade), or for the shot's whole hold (a clip without
one). Otherwise only the rest of the hold is waited out. The scene clock
carries on from the same point; while a restarted clip plays past where the
shot would have ended, the timeline waits at the shot's end until the clip
and the rest of the hold finish. `SceneDirector` still owns editor state, saved-project import/export,
camera ownership and asynchronous load/seek arbitration. Pure seek calculations
live in `src/director/timeline.js`; `src/director/clock.js` owns the run/load/shot
tickers, hold deadlines, snapshots and clock subscriptions. Stop settles pending
+19 -1
View File
@@ -83,11 +83,27 @@ 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 `${…}`.
- **Use placeholders, not concatenation.** `t('Flying to {place}…', { place })`, not `t('Flying to') + ' ' + place`. Word order differs between languages.
- **Use `tn()` for counts**, not `count === 1 ? … : …`. Russian has three forms.
- **Give a fallback phrase its own message.** When code has no name to pass and falls back to a phrase ("the view centre", "this spot"), write `t('{source} at the view centre', { source })`, not `t('{source} at {place}', { place: t('the view centre') })`: after a preposition, other languages put the phrase in a case a separately translated phrase does not have.
- **Use `tn()` for counts**, not `count === 1 ? … : …`. Russian has three forms for whole numbers and a fourth for fractions. That includes a number the English writes with a symbol or abbreviation, so both English forms read the same (`tn(hours, 'Last {hours} h', 'Last {hours} h', { hours: formatNumber(hours) })`): other languages inflect the words around it («Última 1 h», «Últimas 24 h»). Fractions take their own form (ru «0,75 МОР. МИЛИ»).
- **Translate the label, not the value.** Layer ids, enums, share-link parameters, API fields, voice tool schemas and feed data (callsigns, vessel and place names) stay as they are; translate only the text shown for them.
- **No `t()` at module top level.** Keep the English in `msg()` and call `t()` when rendering.
- **Numbers and dates** go through `formatNumber`, `formatDate`, `formatRelativeTime` and `formatUtcDayMonth` from `src/i18n/index.js`, which follow the active language.
@@ -104,6 +120,8 @@ npm run i18n -- --prune # drop entries whose English no longer exists
Changing the English changes the key: the old translation goes unused and the new text shows as missing. Add the translation to every `src/i18n/locales/<code>.json` (or ask a translator), prune, and run `npm test`; it fails until every language is complete.
Do not translate `zh-Hant`: it is generated. After `zh-CN`, run `npm run i18n -- --zh-hant` (see [zh-Hant.md](./translations/zh-Hant.md)).
To see a language, open the app with `?lang=ru`, or use the language picker (the globe button in the bottom-right corner).
An empty translation is reported, and so is one left as the English, plural forms included. When English is right on purpose (a code such as CRT, a product name), list it under the language in `src/i18n/same-as-english.json`.
+33 -7
View File
@@ -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.
+5
View File
@@ -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 render governor'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.
+805
View File
@@ -0,0 +1,805 @@
# 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;
- `gods-eye-view/fleet`: fleet contacts as the Flights and Vessels layers
draw them: the fleet model set and its loader, which model and size an
aircraft or a vessel takes, the distances a contact's icon hands over to
its model at, how a model is lit, tinted and posed, and the vessel hull
sprites.
`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.
- `ModelItem.parts` (capability `modelParts`, `ModelPartState`) poses a
model's moving parts. It applies to a model whose mesh carries a `_PART`
vertex attribute (each vertex's part index) and whose root node's glTF
`extras.parts` is its part table: each part's name, kind (`body`, `spin`,
`hinge`, `slide`, `deploy`, `separable`, `marker`), pivot, axis, limits,
rest and parent. `spin` turns parts at degrees a second, advanced by the
renderer on its own clock (a change of rate goes on from the angle
reached); `deploy` sets parts between stowed (0) and deployed (1);
`poses` moves, turns, hides or highlights a part by name, in the model's
glTF frame (forward −X, up +Y, right −Z). It changes live without loading
the model again. A model without a part table ignores it, and a renderer
without the capability, or that cannot pose parts, draws the model
whole, at rest, as its file draws it: the application runs fully without
it. The maths is `gods-eye-view/render/modelParts` (`partMatrices`:
deploy, then spin, then the pose, then the parent's), so a renderer that
poses parts draws exactly those; with `axisScale` the parts turn rigidly
in the stretched model. The Cesium port lists it and poses parts where
its context is WebGL 2 with floating-point textures, drawing models whole
elsewhere. A posed model gets a custom shader that moves each vertex by
its part's matrix, read from a small texture written in place when the
parts change and each frame a part of a model in view spins (a model out
of view or under 4 pixels across is not turned and asks for no frame),
composed with `maskColor`, `unlit` and `thermal`. A moved part's material
normal (its normal map and back-face flip kept) turns by the inverse
transpose of its matrix, exact under `axisScale`; a hidden part draws
nothing and a highlighted one is mixed toward its colour. A model at rest
keeps the shader it had, and part shaders go with the draw port. Cesium
culls and picks a model by its bounds as its file draws it, so a part
moved outside them (a large `offsetM`) draws only while those bounds are
in view, and is not picked there. The check `draw.models.parts` poses,
hides, moves, clamps and spins the parts of a model built in code
(`render/conformance/partsModel.js`): a move right lands a quarter turn
clockwise of a move forward, a mesh node turned, scaled and moved changes
nothing, a move stretches with `axisScale`, and a slide and a hinge stop
at their limits. The live layers drive it from each vehicle's record
(`src/data/modelPartDrivers.js`).
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.
`draw.models.paint` reads a lit model's vertex paint (`COLOR_0`) at a fixed
sun: its colour by day, still its colour (not black) with the sun below the
horizon, and its paint kept under a tint mixed in.
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.
It also draws `decoded` sources (`imageryDecoded`): tiles the application
makes itself and hands over as finished images. Their slots are times: the
source's `slotAt` names the slot a time shows and `prefetch` the slots held
ahead, of which the first `prefetch` (the option, 1 by default) load unseen.
Each slot is a Cesium imagery layer in the layer's tiling whose tiles are the
images the source's `tile` answers, asked as `shown` or `prefetch`; a
deferred tile is asked again on a later frame, a missing one draws its
parent's, and a slot let go aborts the tiles it still waits on and closes an
image that arrives after. A time with no slot draws nothing and announces
nothing; `frameReady` names the slot shown once it is drawn. The check
`globe.imagery.decoded` covers it.
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), and its own engine (`engine`, whose `kind` names
it: Cesium's is `{kind: 'cesium', viewer}`) for an application that draws
with that engine directly beside the contract, only with engines whose
kind it knows, adding, updating and removing what it draws. 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).
+18 -8
View File
@@ -1,13 +1,14 @@
# Scene document format
Authoring exports a UTF-8 JSON project. Version 5 adds [data packs](DIRECTOR-DATA-PACKS.md)
and is the write format. Versions 1, 2, 3, 4 and unversioned legacy files migrate on
import without converting their existing shots into authored moves. Unknown versions or unsupported fields are rejected with
a field path before the current project, selection or saved bytes change.
Authoring exports a UTF-8 JSON project. Version 7 records Stories metadata.
Versions 1 through 6 and unversioned legacy files migrate on import, including
version 6 projects written by early Stories builds. Existing shots keep their
camera behavior. Unknown versions or unsupported fields are rejected with a
field path before the current project, selection or saved bytes change.
```json
{
"version": 5,
"version": 7,
"scenes": [{
"id": "my-scene",
"title": "My scene",
@@ -33,6 +34,9 @@ Each scene requires a `shots` array; optional fields are `id`, `title`,
`releaseLayerIds`, `appliedShotPacks` and version-4 `anchors`. A pack marker has `id`, optional numeric
`version` and `shotBindings` (original shot title to saved shot ID). These markers
retain the editor's existing pack-update and rename behavior.
From version 6 (written by early Stories builds), scenes may include `stories`
(true when saved to Stories), `storyThumb` (a JPEG or PNG data URL of at most
300,000 characters) and `storyTags` (up to five supported topic keys).
Shots accept `id`, `title`, `durationSec`, `holdSec`, `camera`, `visual`, `layers`,
`sourcePackId`, `sourcePackVersion` and version-4 `move`. Scene IDs are unique within the project;
@@ -50,8 +54,14 @@ fallback for zero; holds may be zero.
Visual fields are `style`, `mapStack`, `styleParams`, `bloom`, `sharpen`, `hud`, and
`detection`, and `scope`. Bloom has `enabled`, `intensity`, `version`; sharpen has `enabled`,
`intensity`; HUD has `visible`, `variant`; detection has `mode`, `density`,
`intensity`; HUD has `visible`, `variant` and an optional `sonar`; detection has `mode`, `density`,
`allocation`, `fadePct` and `outsideOpacityPct`. Scope has `enabled`, `featherPct`.
HUD `sonar: true` is Sonar on beside a layout that cannot say it (Minimal); it
is written only then, so Tactical with Sonar stays the variant `cyber` and a
shot without Sonar has no `sonar`. A shot without it opens with Sonar on only
when its variant is `cyber`. A build from before `sonar` refuses a project
that has it, as it refuses any field it does not know; every other project
still opens there.
The latter settings were written by Update Shot but previously lost during
normalization; they now survive import and capture.
Version-1/2 bloom without an explicit scale version uses the original inverted
@@ -75,8 +85,8 @@ UTF-8 size before JSON decoding; the file importer also checks file size before
reading it. Migration/defaults live separately in `src/scenes/project.js`.
Limits are 5 MiB, 256 scenes, 10,000 total shots, 10,000 entries per collection,
24 levels of nesting, 200,000 visited values, 65,536 characters per JSON string,
256 characters per field/ID, and 4,096 characters per title. Numeric values must
24 levels of nesting, 200,000 visited values, 65,536 characters per JSON string
(300,000 for a Stories thumbnail), 256 characters per field/ID, and 4,096 characters per title. Numeric values must
be finite. Camera limits are latitude ±90, longitude ±180, altitude −12,000 to
1 billion meters, heading/roll ±360 and pitch ±90; durations/holds are at most
86,400 seconds. Post-processing values are bounded and normalized to the existing
+12 -2
View File
@@ -134,7 +134,7 @@ probability of about 255 in 256 (many of them already fail as base64url).
| 13 | thing | LEN | none | sub-message, see thing views |
| 14 | `style` | enum | `normal` | normal, retro, surveillance, thermal, anime, noir, snow (retired) |
| 15 | `mapStack` | enum | `photoreal` | photoreal, bing-aerial, bing-labels, esri-imagery, osm |
| 16 | `hudVariant` | enum | style | tactical, operator (retired), minimal, cyber |
| 16 | `hudVariant` | enum | style | tactical, operator (retired), minimal, cyber (Tactical + Sonar) |
| 17 | `bloomIntensity` | uint | style | |
| 18 | `bloomVersion` | uint | 2 | |
| 19 | `sharpenIntensity` | uint | style | |
@@ -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,8 +171,16 @@ 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).
`celestialRing` (each defaulting by style), 4 `scopeEnabled` (default on), 5
`hudSonar` (default off). `hudSonar` is Sonar on beside a HUD layout whose code
cannot say so, Minimal (the long form's `hs=1`); Tactical with Sonar stays the
`cyber` layout code alone. A link made before the bit has it off, and opens
with Sonar on only when it names `cyber`, as before.
### Style defaults
@@ -277,6 +286,7 @@ reserved: a decoder ignores that entry, as for collapsed 0.
| 8 | `global-context-panel` | `g` | collapsed |
| 9 | `pp-toggles` | `p` | collapsed |
| 10 | `param-slider-panel` | `m` | expanded |
| 11 | `space-missions-panel` | `n` | collapsed |
### Style parameters (field 27)
+2
View File
@@ -36,6 +36,8 @@ npm run i18n -- --prune # drop entries the code no longer uses
Changing English text changes its key: the old translation becomes unused and the new text shows as missing. Translate it and prune.
Do not translate `zh-Hant`: it is generated. Translate `zh-CN`, then run `npm run i18n -- --zh-hant` (see [zh-Hant.md](./translations/zh-Hant.md)).
## Fixing a translation
Edit `src/i18n/locales/<code>.json` and run `npm run i18n`. To see your change, open the app with `?lang=<code>`.
+185 -23
View File
@@ -37,14 +37,40 @@ one-panel rule too. Share links continue to record which panels are open.
## Component kit
`src/ui/kit/` holds the generic components: `UiRail`, `UiTooltip`, `UiIcon`,
`UiButton`, `UiPanel`, `UiSegmented`, `UiSlider`, `UiChip`, `UiSelect`,
`UiBadge` and `UiEmpty` so far, with more joining as the controls they serve
are converted. One component
`UiButton`, `UiCloseButton`, `UiPanel`, `UiSegmented`, `UiSlider`, `UiChip`,
`UiSelect`, `UiSearchField`, `UiCheckbox`, `UiDialog`, `UiBadge` and `UiEmpty` so far, with more
joining as the controls they serve are converted. One component
serves every use of a control, with props for the differences (`UiPanel`'s
`sideways`, `glow`, `scroll`), rather than a copy per panel. The components
are styled by the existing stylesheet and custom properties; a kit class such as
`ui-button--icon` carries no Core style yet, and a converted control keeps
its own classes beside it. They contain no application state.
are styled by the existing stylesheet and custom properties, and they contain
no application state. The kit's own classes wear Core's standard looks, each
sharing one selector list with the Core skin it comes from, so the rules are
never copied:
| Kit class | Look | Rules |
| --- | --- | --- |
| `UiButton` `variant="ghost"` (default) | none: the caller's classes style it | — |
| `UiButton` `variant="action"` | the action surface (`gev-action-button`); `tone="danger"` hovers red, `size="compact"` is the shot-row footprint (on this variant only) | `src/ui/styles/action-button.css` |
| `UiButton` `variant="primary"` | the action surface with a group's main-action accent | `src/ui/styles/action-button.css` |
| `UiButton` `variant="icon"` | the 22px square glyph button of a panel's collapse toggle | `src/ui/styles/controls.css` |
| `UiCloseButton` | a close, dismiss or clear button: a bare glyph (× with `glyph="times"`, the Material `close` symbol with `glyph="icon"`) with no padding, border or background of its own and a pointer; the site's feature class sets size, colour, hover and any surface, and `bare` leaves the look off for a skin that sets its own padding and border | `src/ui/styles/close-button.css` |
| `UiSearchField` | a search field: the Material `search` glyph and a search input in a flex row, the input bare (no border or background, free to shrink); the site's feature classes set the frame's size, surface and focus ring and the input's type and outline, and the browser's own cancel button is left to each skin | `src/ui/styles/search-field.css` |
| `UiCheckbox` | a checkbox: a label wrapping a native box and its words in a centred flex row; the box keeps each site's size, margin and accent colour, and the site's feature class sets the row's gap, direction and colour | `src/ui/styles/checkbox.css` |
| `UiDialog` | none: a native modal `<dialog>`; the site's feature class or inline style draws it | — |
| `UiChip` | the read-only chip (a pill of uppercase mono text); `selected` takes the accent | `src/ui/styles/chip.css` |
| `UiEmpty` | the one-line empty state (dim mono text), its hint on a line below | `src/ui/styles/empty-state.css` |
| `UiBadge` | the read-only badge (`gev-status-badge`) | `src/ui/styles/status-badge.css` |
| `UiSegmented` | the segmented control (`gev-segmented`, `gev-segment`) | `src/ui/styles/segmented-control.css` |
A pressed action, primary or icon button looks as a hovered regular one does
(a compact action's quieter hover is for an unpressed button), and a disabled
one dims and ignores hover and press. `tone` is `accent` or `danger`, and
`size` styles the action variant only. Each look's resting rule selects one
kit class; the button, chip and empty-state skins load before the feature
stylesheets that restyle them, so a feature class still wins. The badge and
segmented skins are the stylesheets their Core classes always used. A
converted control keeps its own classes beside the kit's.
`src/ui/kit/kitStyles.test.mjs` pins these rules.
`UiPanel` takes a `title`, slots and `v-model:collapsed`, but its
`collapsed` drives only the button and `ui-panel--collapsed`: the root's
`collapsed` class, which hides the body, is drawn at once by `v-panel-state`
@@ -57,12 +83,70 @@ segmented group in Core is a `UiSegmented`; the old `segmentedControl.js`
adapter is gone.
`UiButton` adds `pressedClass`, Core's class on a pressed toggle (most use
`active`); its pressed classes toggle through `classList`, so a class other
code adds (a voice highlight) survives a press. Every pressed toggle in the
views is a `UiButton` except Bhote Koshi's cinematic button and the
tilt-map button, whose owners still write their state into the DOM. Core's
code adds (a voice highlight) survives a press. Not every pressed toggle in
the views is one yet: the context view and a few panel buttons still
hand-write theirs, and
Bhote Koshi's cinematic button and the tilt-map button have owners that
write their state into the DOM. Core's
pressable chips and pills (rail card chips, map sources, cities and places)
are `UiButton`s too; `UiChip` is a non-interactive label chip, used by
the voice card.
The welcome card's buttons (SKIP, the three start tiles, BROWSE STORIES,
BACK and the main NEXT / ENTER GOD MODE action) are ghost `UiButton`s:
the start tiles are pressed toggles, and all but SKIP keep `aria-disabled`
rather than `disabled`, so they stay focusable while the card is busy. Its
tile, tip, Stories and arrow glyphs are `UiIcon`s with `:size="null"`, so
first-run.css still sizes them (`src/ui/kit/welcomeControls.test.mjs` pins
it). God mode's preview globe and callouts stay inline SVG drawings, and
its outbound links stay links.
Every button in the Stories views (the Stories entry and its popup and
toast, Explore, the Story screen, its header, rail, timeline and context
panel) is a ghost `UiButton`. Explore's topic chips and map pins, the
Story screen's Context button and the timeline's Expand map are pressed
toggles, with no pressed class since their skins read `aria-pressed`;
Explore's story cards are `role="button"` elements and keep their own
`aria-pressed`. Their glyphs are inline SVG drawn for Stories, which no
Material symbol the page loads draws the same, so they stay SVG; the two
search fields keep their own markup, since `UiSearchField`'s Material
magnifier would replace their SVG one, and their clear buttons, which draw
an SVG cross, are ghost `UiButton`s rather than `UiCloseButton`s
(`src/ui/kit/storiesControls.test.mjs` pins it).
The Omnibar's mic (a pressed toggle with `active`) and its suggestion
strip's chips (options, so `aria-current` rather than `pressed`) are
ghost `UiButton`s, and its search, row and chip glyphs are `UiIcon`s with
`:size="null"`, so its own rules still size them
(`src/ui/kit/omnibarControls.test.mjs` pins it). The mic's and the chat
row's glyphs stay inline SVG, since no Material symbol the page loads
draws them, and its field is its own combobox rather than a
`UiSearchField`.
The Visual panel's buttons (its presets and map sources, HUD, Sonar,
Detection, 3D, Clean UI, Celestial, Bloom, Sharpen and Reset to default) are
ghost `UiButton`s. HUD, Sonar, 3D, Celestial, Bloom and Sharpen are
pressed toggles with `active` as their pressed class; Detection sets its own
`active` and `panoptic` classes, and Clean UI is not a pressed toggle (its
owner marks it `active`). The panel's Scope, Celestial,
sky, application-row and Reset glyphs are `UiIcon`s with `:size="null"`, so
the panel's rules still size them (`src/ui/kit/visualControls.test.mjs` pins
it). The toggles' other glyphs (◎ ▣ ✈ □ ✨ 🔍) and the presets' style glyphs
are text characters, not Material symbols, and stay plain spans.
The entity card's buttons are ghost `UiButton`s: its four preview buttons
(Photos, Route, 3D, Cockpit view) are pressed toggles with `active`, Follow
is one with `entity-card__action--on`, and the cockpit entry, Fly to and
Ask GEV are plain buttons; so are the camera preview's bigger-view and More
info buttons and the nearby lists' rows (`SpotConditions`, which the
context view shows too). Their glyphs are `UiIcon`s with `:size="null"`,
so entity-card.css and spot-conditions.css still size them
(`src/ui/kit/entityCardControls.test.mjs` pins it). Ask GEV's chat bubble
stays inline SVG, since no Material symbol the page loads draws it.
The Layer Finder's buttons (Search, Filter, the filter menu's Status and
Category options and the bar's two clear chips) are ghost `UiButton`s.
Search and the options are pressed toggles; the options' pressed class is
`active`, while Search keeps its own `active` binding, which also stays on
while a query is typed. The Filter button opens a disclosure and carries
`aria-expanded`, not `aria-pressed`. Every glyph its own template draws is
a `UiIcon` with `:size="null"`, so `layer-finder.css` still sizes them
(`src/ui/kit/layerFinderControls.test.mjs` pins it); the search field's
magnifier is `UiSearchField`'s own span.
`UiSelect` renders the bare native select (Core's labels sit outside it or
come as an `aria-label`) with `v-model`, `options` and `disabled`;
options that carry their own attributes come through the slot, a caller's
@@ -74,9 +158,66 @@ gain) takes `hold`. Every select in the views is a `UiSelect`.
density variants and colours stay caller classes, and it renders the CCTV
source and calibration badges and the rail card badges. `UiEmpty` takes
a `title` and `hint`, but Core's empty states are one line, so the title
is the text itself rather than a bold heading; the Scene shot list, mission
roster and imagery strip use it. The locale picker's and the mission tables'
is the text itself rather than a bold heading; the News feed, Scene shot
list, mission roster and imagery strip use it. The locale picker's and the mission tables'
empty rows stay a paragraph and table cells.
`UiCloseButton` is a `UiButton` with a fixed glyph, a required `label` and
no tip unless the site passes a `title`; attributes and classes pass through,
so each site keeps its id, feature class and look. Every close, dismiss and
clear button in the views that draws a cross is one
(`src/ui/kit/closeButtons.test.mjs` pins it) except Story Explore's two
search clears, whose SVG cross is neither of its glyphs; the Story context
sheet's Close is a text button, a plain `UiButton`. Street Level's and the
space mission's keep `bare`, since their skins set their own padding and
border, and so does the credits list's. The
Quebec CCTV overlay's close is one too, and so is the Omnibar guide's,
which keeps its feature class and tip.
`UiSearchField` takes `v-model`, a required `label` (the input's
accessible name), `placeholder` and `tag` (`div`, given `role="search"` by
the site, or `label`); attributes and classes go to the frame, and
`inputId`, `inputClass`, `autocomplete` and `spellcheck` to the input. With
`clearLabel` it shows a `UiCloseButton` (`clearClass`, its label as its tip)
while text is typed, which empties the field and focuses the input again.
Escape stops at the input and is emitted with its event, so a site that also
keeps the browser from clearing the field prevents it there; `focus()`
focuses the input. The Context search and the Layer Finder's are
`UiSearchField`s; the locale picker's combobox, the Omnibar's location
field and the Data Library's labelled search are other controls. Its kit rules hold the declarations both search
skins had in common, moved rather than copied, and load before them.
`UiCheckbox` is a `<label>` wrapping a native `<input type="checkbox">` and
its default slot; `trailing` puts the box after the words, as the Visual
panel's rows have it. It takes `v-model` (the change emits the checked state)
and emits `change` with its event; without a `modelValue` the box is the
browser's own, as the welcome card's "Don't show this again" is, whose
owner puts a refused save back itself. `restore` puts the box back to
`modelValue` once a change has rendered without the owner taking it, so the
voice panel's quick commands and Voice Preview show the applied value after
a refused change. Attributes and classes go to the label; `inputId` and
`inputAttrs` (such as `aria-describedby` or a data hook) to the box. The
Visual panel's Scope, sky and application toggles, the voice and chat
preferences, the Data Library's filter and the welcome card's box are
`UiCheckbox`es, and so are Story Explore's filter options, whose label
keeps its `fopt` class (`src/ui/kit/checkboxes.test.mjs` pins it). Its kit
rule holds the centred row the checkbox-only labels drew, moved rather than
copied.
`UiDialog` is a native `<dialog>` its owner opens and closes with `open`:
true opens it with `showModal()` (on mount, for one mounted open), false
closes it, and unmounting closes it. Each change is applied once the content
has rendered and then emitted as `opened` or `closed`, so the Data Library
focuses its search field on open and returns focus to Browse on close.
Escape's `cancel` is prevented and emitted as `dismiss`, so the owner
decides; `backdropDismiss` makes a click on the dialog itself, outside its
content, a `dismiss` too. When the browser closes the dialog on its own
while `open` is still true (an Escape the page may not cancel),
`browserClose` tells the owner; closing on unmount reports nothing. A DOM
without `showModal()` leaves it closed rather than failing. Attributes,
classes, styles and listeners go to the dialog, and `element` is exposed.
The Data Library and the scene sharing dialogs are `UiDialog`s
(`src/ui/kit/dialogs.test.mjs` pins it); the panels drawn as
`role="dialog"` (key setup, the welcome launcher, the CCTV popup, Story
Explore's filter, the credits) and the render failure's `alertdialog` are
other controls. The two dialogs share no declarations, so it has no kit
rules.
`UiSlider` keeps the native range input rather than drawing a
`role="slider"` track, so Core's keyboard, form behaviour and styling stay;
it takes `v-model`, `min`, `max`, `step` and `disabled`, emits a
@@ -92,14 +233,19 @@ a functional component would not render again.
Controls share one skin, so every panel reads the same. Every scrolling
surface carries the kit's `.ui-scroll`, which draws the thin
themed scrollbar from `--scroll-thumb` and `--scroll-track`; the Cyber theme
sets those two tokens, and Cockpit's HUD windows keep their accent tint. A
themed scrollbar from `--scroll-thumb` and `--scroll-track`, and Cockpit's HUD windows keep their accent tint. A
surface without it would draw the platform's light scrollbar, because the
page declares no dark `color-scheme`. Selects and number fields are
`.gev-field`, which draws its own chevron in place of the platform's arrow
and keeps native spinners dark; ranges are `.gev-quantitative-slider`, with
a feature supplying only its accent.
`t()` is not reactive. Words a view passes to a kit component as a prop
(`UiCloseButton`'s `label`) follow a locale change on the view's next
render, but words in a kit component's slot do not: the compiled slot does
not render the child again. A view whose words must follow the locale at
once passes the locale itself as a prop or key, as the credits line does.
## Phases
1. **Foundation.** Vue, Pinia and the Vite Vue plugin join the browser build
@@ -153,9 +299,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
@@ -167,8 +313,13 @@ a feature supplying only its accent.
the whole panel from the `gev-cctv` store, including the camera picker,
the inline pose editor, the frame preview, source badge and typed
summary; `CctvControls` keeps its listeners, the frame requests and the
live video surface), Layers (done: `LayerPanel` presents each row and
renders `LayerRows` synchronously; keyed chips and list items keep focus
live video surface; `QuebecCctvOverlay` teleports the Québec 511 player
and its map preview to the end of the body, rendered synchronously by
`createQuebecCctvOverlay()` from the view it computes, as the rail cards
are; the owner keeps every decision and the parts the template never
binds: each video's source, playback and refresh timer, the window's drag
and the marker's per-frame visibility and place), Layers (done:
`LayerPanel` presents each row and renders `LayerRows` synchronously; keyed chips and list items keep focus
through the refresh their own click triggers, and clicks re-read the live
descriptor before acting), Display (in progress: `DisplayPanel` renders
the HUD, Sonar, Scope, Celestial, detection, bloom, sharpen and the
@@ -213,7 +364,11 @@ a feature supplying only its accent.
`gev-location` store, and the search field keeps its listeners; beside
the voice control, the dock teleports each voice pointer reticle to the
body where its `PointerReticle` presents it in the `gev-pointer-reticle`
store), the phone shell (`PhoneTabBar` renders the tabs and open sheet the shell
store; `startGuide()` renders the Omnibar's guided walk, `OmnibarGuide`,
synchronously from the view it computes for each step, teleported to the
end of the body, and keeps every decision and word, focus and its return,
Escape, the entrance replay, and the callout's and spotlight rings' place
each frame), the phone shell (`PhoneTabBar` renders the tabs and open sheet the shell
publishes to the `gev-display` store, teleporting the tab bar and sheet
backdrop to the end of the page from the first publish until the shell
is destroyed; the shell takes their clicks from the document), the
@@ -291,7 +446,14 @@ a feature supplying only its accent.
choices, DISMISS and "Don't show this again" call the launcher's
controls; a refused save hands the tick back to the view to revert. The
launcher still reads the rendered card for its hit test, keyboard trap,
focus and overflow measurement), then
focus and overflow measurement), the attribution line (for a renderer
without its own credit display, `mountCreditsView()` renders
`CreditsView` synchronously, as the weather readout is, and the view
teleports the line and its "Data attribution" list to the end of the
body, where the page's rules select them; the owner keeps the credits
shown, the list's open state and its focus, and words the view again
when the locale changes; the list's close button is a bare
`UiCloseButton`), then
Cockpit (in progress: `CockpitBriefing` renders the briefing card's
pages, cycle toggle, regional news and local conditions, and
`CockpitContext` the Contact card's scope, navigation, counts, nearest
@@ -338,8 +500,8 @@ a feature supplying only its accent.
records surface by surface; [Building UI](../CONTRIBUTING.md#building-ui)
now requires the pattern for new UI. The page-level markup tests read
`renderApplicationHtml()`, the real views rendered on the server, and new
tests mount components; three tests still read a `.vue` file's source
(`cyberTheme`, `panelStorageDocs`, `geoFileImport`). The views translate with `t()`
tests mount components; two tests still read a `.vue` file's source
(`panelStorageDocs`, `geoFileImport`). The views translate with `t()`
while rendering, and vue-i18n holds the locale they read; the attribute
translation pass is left for static page markup (the loading screen and a
host's own markup). An explicit API for hosts to register panels and rail items is
@@ -361,7 +523,7 @@ a feature supplying only its accent.
- Panels lifted out of a view keep its verbatim markup in
`src/ui/views/panels/`, which Prettier leaves alone like the views.
- Visual parity: before/after screenshots of every panel at desktop and phone
widths, in the default and Cyber themes, with the rail as the only expected
widths, in the default theme, with the rail as the only expected
difference.
- Browser QA: the selector-based `scripts/qa-*.mjs` suites keep passing.
- `npm run format:check`, `npm run check:boundaries`, `npm run i18n` and
Binary file not shown.

Before

Width:  |  Height:  |  Size: 981 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.6 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.8 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.0 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.8 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.3 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.0 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.8 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 889 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.8 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.7 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.2 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.0 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.6 MiB

+21 -24
View File
@@ -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.
Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 467 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 447 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 538 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 664 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.8 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 314 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 405 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 453 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 304 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 299 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 788 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 370 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 690 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.2 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 8.2 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 958 KiB

+9 -11
View File
@@ -1,9 +1,8 @@
# Panel surface contract
`src/ui/styles/panel-surfaces.css` supplies an opt-in visual surface for new
panels. It uses the application's default color, font, border and radius tokens;
Cyber supplies its existing red/slate palette, monospace typography and shaped
frame. This is CSS shared by the existing panel system, not a panel registry or
panels. It uses the application's default color, font, border and radius tokens.
This is CSS shared by the existing panel system, not a panel registry or
a controller. A panel ID does not need a new theme selector.
## Markup
@@ -57,13 +56,12 @@ fit when those contents should instead scroll.
| Mount | Shared contract | Owner responsibilities |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Direct child of `#left-panel-stack` | An owner with a direct `[data-panel-surface]` child receives relative positioning and allocated height; inner surface/body skin | Add the wrapper shown above, use the existing layout/disclosure owners, and retain left-rail focus/auto-collapse rules. |
| Direct child of `#right-context-rail` | The same hooks with right-rail allocation and intrinsic measurement | Keep `data-rail-scroller` on the body so measurement preserves its scroll position. Respect Cyber's one-expanded-panel policy. |
| Direct child of `#right-context-rail` | The same hooks with right-rail allocation and intrinsic measurement | Keep `data-rail-scroller` on the body so measurement preserves its scroll position. |
| Surface inside `#command-dock` | Surface, controls, popup decoration and inherited dock concealment | Supply geometry, stacking, disclosure, pin behavior if wanted, safe viewport bounds and dismissal. This CSS does not extend the existing Location/Visual Presets tray stack manager to arbitrary panels. |
| `dialog[data-panel-surface]` | The same surface/body skin; a closed dialog remains hidden | Set width/max-height, use `showModal()` or `show()` and `close()`, and own labels, initial/return focus and dismissal. Do not put `panel-collapsible` on a dialog. |
For rails, `--panel-expanded-width` and `--panel-collapsed-width` customize
the desired widths within the rail; otherwise Cyber uses its existing left,
right and collapsed panel widths. `--left-panel-allocated-height` and
the desired widths within the rail. `--left-panel-allocated-height` and
`--right-panel-allocated-height` belong
to the existing layout owner, not to individual panels. The surface must be
the wrapper's first non-glow child because left-rail intrinsic measurement
@@ -121,9 +119,9 @@ dismiss open popups/dialogs and restore focus before removing a dynamic panel.
## Decoration, popups and visibility
The shared surface reserves `::before` for its non-interactive background. The
Cyber frame clips this pseudo-element only; the surface stays unclipped with
visible overflow. This follows the existing Display and Global Context pattern.
The shared surface reserves `::before` for its non-interactive background; the
surface stays unclipped with visible overflow. This follows the existing
Display and Global Context pattern.
Putting the shape on an interactive ancestor clips all descendant popups even
if their `z-index` is high. A scrolling body also clips descendants by design,
so outward popups must be siblings of the body, or use an explicitly owned
@@ -148,8 +146,8 @@ visible.
## Check an addition
Use the real application with the default and Cyber themes. Check open,
collapsed, hidden, disabled/error, theme round trips, clean UI/recording and
Use the real application with the Tactical and Minimal HUD layouts. Check open,
collapsed, hidden, disabled/error, layout round trips, clean UI/recording and
the intended Cockpit behavior. Exercise keyboard focus, Escape, pointer input,
the last scrolling item, resize without reload and any pin/unpin controls.
For an outward popup, test visible pixels and pointer hit-testing outside the
+1
View File
@@ -66,6 +66,7 @@ Every form must keep `{count}`. For one and two, Arabic names the quantity with
| call sign | رمز النداء |
| vessel, ship | سفينة |
| satellite | قمر صناعي |
| CONFIRMED (sightings chip; a landing) | مؤكَّدة / مؤكَّد |
| launch (rocket) / space mission | إطلاق / مهمة فضائية |
| contact (tracked object) | هدف |
| installation, site / mapped | منشأة، موقع / مرسوم |
+1
View File
@@ -53,6 +53,7 @@ Keep the verb in agreement: «{count} Station meldet» / «{count} Stationen mel
| aircraft / flight / military flights | Luftfahrzeug (HUD and short labels: Flugzeug) / Flug / Militärflüge |
| vessel, ship | Schiff |
| satellite / shell (Starlink) / DENSE | Satellit / Schale / DICHT |
| CURRENTLY OVER (orbit, before a place name) | ÜBERFLUG |
| launch (rocket) / launch site / space mission | Start / Startplatz / Raummission |
| ascent / replay / payload / stage / downrange | Aufstieg / Replay, Wiedergabe / Nutzlast / Stufe / Downrange |
| contact / tracking | Kontakt / Verfolgung |
+2 -1
View File
@@ -45,6 +45,8 @@ The `many` form is the `other` text with «de» after the number: «{count} de c
| aircraft, plane / flight / military flights | aeronave / vuelo / vuelos militares |
| vessel, ship | buque |
| satellite / shell (Starlink) / DENSE | satélite / capa / DENSO |
| FOCUS (the held object; the button) | ENFOQUE / ENFOCAR |
| CONFIRMED (sightings chip; a landing) | CONFIRMADOS / CONFIRMADA |
| launch (rocket) / launch site / space mission | lanzamiento / lugar de lanzamiento / misión espacial |
| ascent / replay / payload / stage | ascenso / repetición / carga útil / etapa |
| contact / tracking | contacto / rastreo |
@@ -63,7 +65,6 @@ The `many` form is the `other` text with «de» after the number: «{count} de c
| detection overlay | superposición de detección |
| pin (Draw tool) | marcador |
| Bloom / Glow (visual effect) | resplandor |
| Cyber (HUD layout, effect) | Ciber |
| heading, course / altitude / ground speed | rumbo / altitud / velocidad respecto al suelo (short: VEL. SUELO) |
| HDG / BRG / CRS / FOV / DEST / SPD / RANGE | HDG / BRG / CRS / FOV / DEST / SPD / RANGE (unchanged) |
| PREV / NEXT | ANT. / SIG. |
+2 -1
View File
@@ -49,6 +49,8 @@ The `many` form is the `other` text with « de » (« d' » before a vowel) afte
| aircraft / flight / military flights | aéronef (avion in short copy) / vol / vols militaires |
| vessel, ship / tanker (AIS type) | navire / navire-citerne |
| satellite / shell (Starlink) / DENSE | satellite / couche de la constellation / DENSE |
| FOCUS (the held object; the button) | CENTRÉ / CENTRER |
| CONFIRMED (sightings chip; a landing) | CONFIRMÉES / CONFIRMÉE |
| launch / launch site / space mission | lancement / site de lancement / mission spatiale |
| ascent / replay / payload / stage / downrange | ascension / rejeu / charge utile / étage / distance au sol (DIST. SOL) |
| contact / tracking / track (HUD) | contact / suivi / piste |
@@ -80,7 +82,6 @@ The `many` form is the `other` text with « de » (« d' » before a vowel) afte
| Recent Imagery / box | imagerie récente / zone |
| Daily overview / overview (Recent Imagery VIIRS product) | vue quotidienne (one name for the product, not « vue d'ensemble ») |
| pin (Draw tool) / pin (Recent Imagery) | épingle / épingler |
| Cyber (HUD layout, effect) | Cyber |
| heading / course (ground track) / altitude / ground speed | cap / route / altitude / vitesse sol |
| HDG / BRG / CRS / FOV / DEST / SPD / ALT | unchanged |
| RANGE / PITCH / HGT (CCTV calibration chips) | PORTÉE / INCL. / HAUT. |
+2
View File
@@ -41,6 +41,8 @@ With {count} shown as a digit, `two` and `other` share the plural noun (2 מצל
| aircraft / flight / military flight | מטוס (כלי טיס in class lists) / טיסה / טיסה צבאית |
| vessel / ship / ships | אונייה / אוניות |
| satellite | לוויין |
| FOCUS (the held object; the button) | מוקד / התמקד |
| CONFIRMED (sightings chip; a landing) | מאושרות / מאושר |
| launch (rocket) / space mission | שיגור / משימת חלל |
| contact / tracking | מגע / עקיבה |
| installation / site | מתקן / אתר |
+4 -1
View File
@@ -52,6 +52,9 @@ The `many` form is the `other` text with «di» after the number when a noun fol
| aircraft, plane / flight / military flights | aereo / volo / voli militari |
| vessel, ship | nave |
| satellite / shell (Starlink) / DENSE | satellite / shell / DENSO |
| FOCUS (the held object; the button) | PUNTAMENTO / FOCUS |
| CONFIRMED (sightings chip; a landing) | CONFERMATI / CONFERMATA |
| CURRENTLY OVER (orbit, before a place name) | SORVOLO |
| SPARSE / BALANCED / DENSE (detection modes) | RADO / BILANCIATO / DENSO (agree with «overlay») |
| broadband (Starlink shell) | a banda larga |
| VISUAL (CelesTrak group) | VISIBILI |
@@ -79,7 +82,7 @@ The `many` form is the `other` text with «di» after the number when a noun fol
| briefing / panel / dock | briefing / pannello / dock |
| cockpit | cockpit |
| preset / visual preset | preset / preset visivo |
| Tactical / Minimal / Cyber | Tattico / Minimale / Cyber |
| Tactical / Minimal | Tattico / Minimale |
| Scope (circular viewport mask) / keyhole | scope / foro |
| feather / fade | sfumatura / dissolvenza |
| detection overlay | overlay di rilevamento |
+1 -1
View File
@@ -61,7 +61,7 @@ Translation source: abiyeenzo (#913).
| scene / shot | シーン / ショット |
| briefing / panel / dock | ブリーフィング / パネル / ドック |
| preset / visual preset | プリセット / ビジュアルプリセット |
| Tactical / Minimal / Cyber | タクティカル / ミニマル / サイバー |
| Tactical / Minimal | タクティカル / ミニマル |
| Scope (circular viewport mask) / keyhole | スコープ / キーホール |
| Clean UI | クリーンUI |
| cockpit | コックピット |
+4 -2
View File
@@ -57,6 +57,9 @@ The `many` form is the `other` text with «de» after the number: «{count} de c
| aircraft, plane / flight / military flights | aeronave, avião / voo / voos militares |
| vessel, ship / TANKER (AIS class) | embarcação / NAVIO-TANQUE |
| satellite / shell (Starlink) / DENSE | satélite / camada orbital / DENSO |
| FOCUS (the held object; the button) | FOCO / FOCAR |
| CONFIRMED (sightings chip; a landing) | CONFIRMADOS / CONFIRMADA |
| CURRENTLY OVER (orbit, before a place name) | SOBREVOO |
| SPARSE / BALANCED / DENSE (detection modes) | ESPARSO / EQUILIBRADO / DENSO (o modo) |
| launch (rocket) / launch site / space mission | lançamento / local de lançamento / missão espacial |
| KM DOWNRANGE / EST. DOWNRANGE | KM DO LOCAL DE LANÇAMENTO / EST. PELA DIST. DO LANÇAMENTO |
@@ -88,8 +91,7 @@ The `many` form is the `other` text with «de» after the number: «{count} de c
| feather / fade | suavização / esmaecimento |
| detection overlay | sobreposição de detecção |
| pin (Draw tool) / box (Recent Imagery) | marcador / área |
| Cyber (HUD layout, effect) | Ciber |
| heading / course / altitude / ground speed | rumo / curso / altitude / velocidade solo (VELOC. SOLO) |
| heading / course / altitude / ground speed | rumo / curso (a ship's course: rumo) / altitude / velocidade solo (VELOC. SOLO) |
| map heading / bearing (compass, north up) | orientação (do mapa) |
| HDG / BRG / CRS / FOV / DEST / SPD / RANGE | HDG / BRG / CRS / FOV / DEST / SPD / RANGE (unchanged) |
| V/S (vertical speed code) | V/S (unchanged) |
+1 -1
View File
@@ -8,7 +8,7 @@ Catalog: `src/i18n/locales/ru.json`. General rules: [TRANSLATORS.md](../TRANSLAT
- Sentence case, not Title Case: "Live Flights" → «Рейсы в реальном времени».
- Quotes inside Russian text are «ёлочки». Write ё where it belongs: её, ещё, всё.
- In short labels, a standard abbreviation with a period beats a wrapped line: НЕОПРЕД., СЛЕД.
- Units: км, м, км/ч, м/с, уз (knots), фт (feet), ч, мин, с; in UPPERCASE text КМ, М, КМ/С, УЗ, ФТ. MW is МВт in any case. `°` and `%` stay.
- Units: км, м, км/ч, м/с, уз (knots), фт (feet), ч, мин, с; in UPPERCASE text КМ, М, КМ/С, УЗ, ФТ. MW is МВт in any case. `°` and `%` stay. Nautical miles on the bridge radar are «мор. миля», a noun that follows the count: «3 МОР. МИЛИ», «12 МОР. МИЛЬ», «0,75 МОР. МИЛИ».
## Plurals
+1
View File
@@ -53,6 +53,7 @@ Abbreviated units and codes do not change: «{count} MEDD.».
| aircraft / flight / military flights | luftfartyg (short labels: flygplan) / flygning / militärflyg |
| vessel, ship | fartyg |
| satellite / shell (Starlink) | satellit / skal |
| CONFIRMED (sightings chip; a landing) | BEKRÄFTADE / BEKRÄFTAD |
| launch (rocket) / launch site / space mission | uppskjutning / uppskjutningsplats / rymduppdrag |
| contact / tracking | kontakt / följning |
| installation / site | anläggning / plats |
+2 -1
View File
@@ -12,7 +12,7 @@ Translation source: meirm (#312).
- The apostrophe is always ʼ (U+02BC): обʼєкт, звʼязок, памʼять. Not ' or ’.
- Quotes inside Ukrainian text are «ялинки»; a button or layer name inside a sentence goes in them: Увімкніть «Вуличні знімки».
- In short labels, a standard abbreviation with a period beats a wrapped line: ПОПЕР., ДАЛЬН., КАЛІБР.
- Units: км, м, км/год, м/с, вуз (knots), фт (feet), год, хв, с, МГц, дБ, гПа; in UPPERCASE text КМ, М, КМ/С, ВУЗ, ФТ. MW is МВт in any case. `°` and `%` stay. Decimal comma in coordinates written as text: 28,2710° пн. ш.
- Units: км, м, км/год, м/с, вуз (knots), фт (feet), год, хв, с, МГц, дБ, гПа; in UPPERCASE text КМ, М, КМ/С, ВУЗ, ФТ. Nautical miles on the bridge radar are «мор. миля», a noun that follows the count: «3 МОР. МИЛІ», «12 МОР. МИЛЬ», «0,75 МОР. МИЛІ». MW is МВт in any case. `°` and `%` stay. Decimal comma in coordinates written as text: 28,2710° пн. ш.
- Coordinates: пн. ш. / пд. ш. / сх. д. / зх. д.; the HUD hemisphere letters are Пн, Пд, Сх, Зх.
## Plurals
@@ -45,6 +45,7 @@ A `tn()` entry needs four forms. `Intl.PluralRules('uk')` picks:
| aircraft / flight / military flights | літак (short HUD: борт) / рейс / військові рейси |
| vessel, ship / vessels | судно / судна (gen. pl. суден) |
| satellite | супутник |
| CURRENTLY OVER (orbit, before a place name) | ПРОЛІТ |
| launch (rocket) / space mission | запуск / космічна місія |
| ascent (rocket) / booster FLIGHT {n} | виведення / ПОЛІТ {n} (not рейс) |
| contact / tracking | контакт / стеження |
+1 -1
View File
@@ -43,7 +43,7 @@ Translation sources: abiyeenzo (#914) and EDIT-Aeterna (#979).
| briefing / panel / dock | 简报 / 面板 / 停靠栏 |
| preset / visual preset | 预设 / 视觉预设 |
| Display / HUD layout | 显示 / HUD 布局 |
| Tactical / Minimal / Cyber | 战术 / 精简 / 赛博 |
| Tactical / Minimal | 战术 / 精简 |
| Scope (circular viewport mask) / keyhole | 视域 |
| Clean UI | 纯净界面 |
| cockpit | 座舱 |
+12 -4
View File
@@ -2,16 +2,24 @@
Catalog: `src/i18n/locales/zh-Hant.json`. General rules: [TRANSLATORS.md](../TRANSLATORS.md).
`zh-Hant` is the Simplified Chinese catalog (`zh-CN`, credited to abiyeenzo, #914, and EDIT-Aeterna, #979) written in Traditional characters with OpenCC character conversion. Wording and terminology are the same as in `zh-CN`: change a term in [zh-CN.md](./zh-CN.md) and the `zh-CN` catalog first, then convert. Only the script differs.
**Do not translate or edit this catalog: it is generated.** `zh-Hant` is the Simplified Chinese catalog (`zh-CN`, credited to abiyeenzo, #914, and EDIT-Aeterna, #979) written in Traditional characters. Wording and terminology are the same as in `zh-CN`; only the script differs. To add or change an entry, edit [zh-CN.md](./zh-CN.md) and the `zh-CN` catalog, then run:
After `s2tw` conversion, fix the characters OpenCC picks wrongly: 年曆史 → 年歷史, 下遊 → 下游, 並道 → 併道, 發佈 → 發布, 公佈 → 公布, 控制檯 → 控制台, and 周 → 週 where it means a week (1 週/秒).
```sh
npm run i18n -- --zh-hant # rewrite zh-Hant.json from zh-CN.json
```
`npm test` fails when `zh-Hant.json` differs from the conversion of `zh-CN.json`, naming the entry, and `npm run i18n -- --missing zh-Hant` points to this command instead of printing a template.
The command converts with OpenCC `s2tw` ([opencc-js](https://github.com/nk2028/opencc-js), `cn` → `tw`), which changes characters only. Never `s2twp`: it also swaps in Taiwan vocabulary (影片, 伺服器, 載入, 圖示), which this catalog does not use. After the conversion it fixes the characters OpenCC picks wrongly here: 年曆史 → 年歷史, 下遊 → 下游, 並道 → 併道 (only in entries whose English key says merge), 發佈 → 發布, 公佈 → 公布, 宣佈 → 宣布, 控制檯 → 控制台, 箇中 → 個中 (全部 {n} 個中), and 周 → 週 in ` 周/秒` (1 週/秒, weeks per second). OpenCC writes 週 itself in 每週, 本週, 上週, 一週 and 兩週, but not after a number (過去 2 周, {count} 周前): a new string like that needs its own pair. The list is `ZH_HANT_CORRECTIONS` in `scripts/i18n.mjs`; when the conversion picks another wrong character, add the pair there (with a key pattern if it is right only in some entries) and run the command.
An entry `zh-CN` keeps in English on purpose needs the same line under `zh-Hant` in `src/i18n/same-as-english.json`.
## Style
- Follow [zh-CN.md](./zh-CN.md) for wording, punctuation, spacing, units and the glossary, written in Traditional characters.
- Wording, punctuation, spacing, units and the glossary are those of [zh-CN.md](./zh-CN.md), written in Traditional characters.
- Relative-time placeholders may already include 前. In `LIVE · updated {age}`, the caller supplies the complete relative age; do not append another 前.
- The picker displays 中文(繁體) / Chinese (Traditional); explicit Hans tags select Simplified Chinese.
## Plurals
`Intl.PluralRules('zh-Hant')` uses only `other`. Keep the measure words of the `zh-CN` entry: 「{count} 架飛機」、「{count} 艘船」.
`Intl.PluralRules('zh-Hant')` uses only `other`. The measure words come from the `zh-CN` entry: 「{count} 架飛機」、「{count} 艘船」.