The ring, its sonar fronts and the band behind them leave Cesium: the
ring and each front are one solid line with an outline, the band is one
flat unpickable ellipse at the rim filled with a canvas painted from the
pulse radii. rangeRingCesium.js goes, and the Cesium allow-list is empty.
Solid lines take an optional outline ({color, widthPx}, inside the
line's width on each side), drawn in the line's own pass so a
translucent halo never darkens where it meets the core; both colours
change in place, and outlined lines never settle into the static batch.
An unclamped image fill takes a new canvas in place: copied into its
texture when the size is the same.
A parked view steps the pulses from the 80 ms timer before it asks for
the frame that draws them, so it draws one frame a step; frames the
camera moves in, or held drawing, step them every frame, and the band is
painted at most every 80 ms. The lines reference scene gains an outlined
line.
Shapes take their radii in metres; the world annotation ring follows the
camera height itself (ringRadiusAt), resizing on preRender. The radial rim
preset and depthBias go: the launch pad zone draws a canvas image fill made
by the layer. Solid and dashed lines take one depthFail look (solid or
dash) in place of depthFailColor and depthFailDash. sonarCadenceHz goes from
the quality settings: nothing set it, and the sweep moves every 80 ms.
Camera move, look, rotateAround and zoom leave the camera port: the app's pans,
in-place turns, globe turns and zooms are setView views summed over the pose
(geo/eyeMoves), and the Cesium port places a view by direction and up
exactly rather than through heading, pitch and roll. The conformance driver
runs those script steps through setView; the lookAt script turns in place
where it turned about the frame-local axis, and its reference is recorded
again.
Quality no longer switches clouds or water (their ports are gone) and its
atmosphere and post-processing settings are low or high detail; whether the
sky or a pass shows stays with globe.sky and effects. The separate
input.ctrlWheelZoom switch is gone: 'ctrlWheel' in the camera's zoomInputs
also relays trackpad pinches, which the application turns on.
Drops from the contract, the stub, the Cesium renderer and the
conformance suite: agent paths, renderer-propagated orbits and celestial
draws (orbits stay drawn as icons and inertial lines), scalar raster
fields, lodGroup, volume classification, icon eye offsets, the dash gap
colour, box shapes, courseBlendMs (courseGlide covers easing), relief
surface shading, globe clouds and water, sky atmosphere tuning, heightmap
and quantized-mesh terrain, WMTS and ArcGIS imagery, the batched cached
height read, the quality benchmark and the animated-style and overlay
pixel-ratio knobs. Capabilities clouds, water, celestial, agents, orbits
and benchmark go with them.
The lodGroup check becomes a displayRange check across two sets, the
height-query check uses an extruded polygon in place of a box, the shape
scenes draw extruded blocks where they drew boxes, and the fields scene
draws a raster shell. The shape references are recorded again.
Brings in the CCTV opening camera, the Iceland, Giroc HLS, Taiwan, Quebec,
Ottawa and world camera packs, the world clock and timeline, the zoom-out
limit and registered-only layer state, ported onto the renderer contract:
the sky follows the world time through the frame port's setTime in
preUpdate, the Quebec overlay reads the eye, projects and redraws through
the camera, query and frame ports, launches hide pending missions through
their draw records, and mission orbit rings turn on the scene clock.
Five new camera conformance scripts move the camera by user input: a
left drag that coasts, thirty pixel-mode and thirty line-mode wheel
notches from 5 km, a middle-drag tilt, and Shift and Ctrl drags held too
long to coast. The runner turns input steps into pointer events for a
driver: a move starts where the pointer last pressed or moved and carries
the held button. The golden recorder now drives Cesium's own screen-space
camera controller on a stand-in canvas, with Date on the virtual clock so
inertia is deterministic. The existing goldens are unchanged.
A harness that answers pointer input sets cameraInput and a pointer hook.
Harnesses without it, such as the stub, skip the input scripts.
The input port reported a line-mode wheel at 33 1/3 pixels a line. It now
counts lines as the reference does, 40 pixels a line and 3 lines a page,
so a pixel or line wheel converts back to the same pixels.
ModulationSector gains radius and floor and says what it dims and what it
leaves alone; picks are unchanged and setting or clearing a sector asks
for one frame. The stub names its pass screenModulation, and a
conformance check covers the pass, the frame request and the pick.
windStreamlines takes alpha and paused; rasterShell replaces detailWindow
with a detail image and rectangle and says how shells stack, blend and
update; FieldHandle.on('drawn') says once per change that it is drawn,
never while hidden. The stub fires it on the render after a change, and a
conformance check covers it. The Cesium adapter has no fields yet.
The globe port takes the globe's material only when it is free, follows a
terrain change, lets go of a material someone replaced, and takes it again
once it comes free; idle ticks ask for no frame.
A new capability, surfaceIdentity, adds globe.surfaceVersion(): a number
that changes whenever what surface heights answer against changes (base,
terrain or photoreal swapped, the globe shown or hidden) and never on
camera moves or tile loads, so the app can key cached heights by it. The
settle kind 'surface' says whether that surface has loaded what is in
view: the terrain while the globe is shown, otherwise the drawn tiles,
false with neither; a renderer without the capability answers it as base.
The Cesium globe port reads both off the scene, so a base changed around
the port counts too; its versions come from one counter shared by every
port. The stub bumps on real base, terrain, photoreal and visibility
changes. A conformance check and a globe port test cover them.
ShapeItem.lit picks the renderer's fixed light or a flat colour; omitted,
extruded shapes and boxes are lit and the rest flat, as they were. The
Cesium draw port lights unclamped colour and image fills by it; clamped
shapes still drape unlit. A new reference scene, shapes-lit, draws a lit
and a flat box and square.
LineItem.mode now says a renderer that cannot drape at all draws draped
lines and clamped shapes as overlay, and clampState() says overlay. The
Cesium port says overlay when its context has no depth textures, which
only a WebGL 1 context can lack.
Among sets that skip the depth test, a higher drawOrder draws over a lower
one whatever order they were made in, and picks name them topmost first.
Cesium draws the earlier of two opaque near-plane icons on top and picks
it, so the draw port stacks the sets' hosts with a higher order earlier,
ties in the order the sets were made. Hosts trade places only among the
slots draw-set hosts already hold, so no other primitive moves; nothing
moves while every set is at 0. Translucent items blend
order-independently in Cesium and are not ordered by it.
The stub sorts its hits the same way. A conformance check draws two icon
sets at one spot and swaps their orders.
The query contract now says picks answer against the scene as drawn before
effects, and that a drillPick limit bounds the work as well as the answer:
the renderer stops at `limit` hits and looks through at most
max(limit, 16) things under the pointer. The Cesium query port passes that
depth to Cesium's drill (a pick looking under something unpickable stays
unbounded), a click's drill caches one pass per depth, and the stub counts
unpickable items toward the depth.
CameraPose says fovy and aspectRatio describe the nearest centred
perspective frustum, the exact projection being in matrices().
A changed listener's own threshold is now the capability
cameraChangeThreshold; without it every listener fires at 0.5. The Cesium
and stub cameras have it, measured per listener without touching Cesium's
shared percentageChanged.
Conformance: draw.drillPick checks limit 0, never the surface, nothing over
the bare globe, an unpickable cover, nearest first and a bounded prefix;
query.pickBeforeStyles picks an icon under a mirroring style; the threshold
trace is skipped without its capability.
A rectangle shape gains an optional rotation: radians counter-clockwise,
turning it about its centre in longitude and latitude, as a KML ground
overlay turns; an image fill turns with it. A renderer that predates it
draws the rectangle unturned. The Cesium draw port passes it as the
rectangle's rotation and texture rotation, and now drapes image fills on
clamped shapes, each on a ground primitive of its own that owns its
material, where it refused them before. Hidden image fills are not built
until they show. The stub picks draped rectangles, turned and across the
antimeridian, and a conformance check picks a quarter-turned overlay on
both renderers. The KML importer still draws its overlays itself.
A line item gains an optional depthFailDash ({ length, pattern16? }): the
parts behind the surface are dashed in depthFailColor, as a dash style
dashes a line. Without a depthFailColor, and on draped lines, it is
ignored; a renderer that predates it draws those parts solid. The Cesium
draw port gives the depth-fail appearance a PolylineDash material, and a
change of dash is a new look. The Draw tool's rubber band uses
{ length: 16 }, the dash its old entity asked for (that entity, a dynamic
polyline, never drew its depth-fail material, so the parts behind the
surface were hidden before the tool moved onto the draw port).
The camera port gains an optional followFrame() (capability followFrame):
the frame the eye is placed in now, as a column-major 4x4 matrix to ECEF.
Once a follow has framed the camera it is the follow's own frame
(east-north-up, or the orbit frame an autodetect follow chose), under
lookAt the target's east-north-up frame, otherwise the identity. setView
places a world pose and keeps that frame. The Cesium port reads it from
camera.transform, only when the capability is on; the stub from its own
eye frame. A conformance check covers the world, lookAt and enu-follow
frames, the offset in it, and setView keeping it.
src/ui/shareFollow.js now reads the pose, the frame and the follow offset
through the camera and frame ports: a shared offset is re-expressed in the
follow's own frame as before, satellites included, and the eye is placed
with setView at exact heading, pitch and roll, so a near-vertical view
keeps its roll. placeFollowEye returns false on a camera that cannot say
its frame. offsetFromHeadingPitchRange moves to src/geo/frames.js, shared
with the stub.
The renderer contract gains an optional event on model draw sets,
`on('loadFailed', (id, message) => ...)`, beside `ready`: a model's url
failed to load, once per failed load. The item stays in the set drawing
what it drew before; removing it and adding it again tries at once. A
renderer that cannot tell a failure may never fire it.
The Cesium draw port fires it once Cesium is done with the frame it
raised the error in, and not for a load that was superseded or whose item
went. The stub fails urls under `stub-fail:`, telling each load once. A
conformance check (`draw.models.loadFailed`) runs on both, with a model
url the dev server does not serve for Cesium.
The flights and military layers use it in place of rewriting every
unloaded model every 5 s. A fleet model whose load failed is removed and
added again 5 s later. The tracked model gets back its per-selection
budget: a failed load is let go and tried again 1.5 s later, and after
three failures the contact stays 2D until another is selected, as
before the models moved onto the draw port. A good load retires the
budget, and a model that loads after all is kept.
The globe port could show or hide the globe surface but not say whether it
is shown. It now has an optional isGlobeVisible(), gated by a new
globeVisibility capability, in the Cesium adapter, the stub and a
conformance check. A Cesium scene without a globe does not offer it, so
callers keep their own default for an unknown surface.
The OSM overlays, the CCTV ground regime and the submarine cable drape now
read the getter instead of the scene's globe. cableClassificationTypeForScene
takes the viewer rather than its scene.
The effects port puts each style the app defines on its own post-process
stage, takes the scene's bloom stage and adds a sharpen stage, with the
mappings the application uses today. An animated style holds frames and
advances its time uniform while it draws. A replaced style keeps drawing
until its intensity is 0, so the app can crossfade; the contract, the stub
and a new conformance check say so. The conformance renderer has the
port; the application renderer does not yet.
The Cesium camera port follows a target with Cesium's own entity
tracking, on a hidden helper entity per target, and gains followed,
followFramed, followOffset and followChanged. A target with a minimum
range gets GEV's close-range rules, moved here from trackedCamera.js:
an exact first framing, no zoom coasting, a zoom floor, and an eye that
never crosses through the target. followChanged now fires only when
what is followed changes, on the stub too. No layer follows through the
port yet.
The embed view, the celestial-ring focus, the ground-guard lift, the
Bhote Koshi approach and orbit, launch selection and replay flights, and
the cockpit's view and takeover now drive the renderer's camera port.
The contract gains a sineInOut easing, pinned by a conformance trace.
A viewer with no renderer bound, such as one a caller of a public
export brings, now gets a camera port too, as it already got an input
port: cameraOf builds one over the viewer's own Cesium camera and keeps
it for the viewer's life, until a renderer is bound. The Cesium adapter
provides the factory as it loads; code that reaches Cesium takes cameraOf
from the adapter so the factory comes with it, and findCamera answers
null where a missing camera is not an error (HUD, share link, world
focus, Recent Imagery's ZOOM IN). A test walks every package export and
fails one that can reach the bridge without loading the factory.
A destroyed viewer gets no camera and lets go of a built one, and the
application renderer stays bound until its viewer is destroyed.
flyToBounds takes an easing, as flyTo does: in the contract, the Cesium
port and the reference recorder, pinned by a new conformance trace.
The flights of radio, awareness, CCTV, submarine cables, cyclones, the
launch preview, installations, ALPR, street-level framing, recent
imagery, weather and world focus now go through the renderer's camera
port. Street-level framing cancels its own flight handle rather than
whatever flight is current. worldFocus.js no longer reaches Cesium and
leaves the allow-list.
Layer pose reads stay for each layer's own slice. The local GeoJSON
flight stays on Cesium: gods-eye-view/infrastructure is used with plain
Cesium viewers that have no renderer bound.
The frame port now does everything the contract asks of it on Cesium:
preUpdate says whether the tick draws (Cesium's own render test, read
live until the tick is over), holds are counted per reason, and suspend,
target fps, renderNow and diagnostics are real. Releasing the last hold
asks for one more frame.
whenSettled also waits until Cesium stops redrawing on its own. Each
request or worker task Cesium completes queues a redraw (a terrain
picker build after the camera moved, say), which no loading flag shows,
so it now waits for quiet frames and then a short stretch in which the
loop draws nothing by itself. It is bounded by its timeout, names a
stopped loop, and ends on destroy.
The app renderer still leaves out the members that steer the loop:
the render governor and the page's visibility handling own those
settings until they move onto the port.
The new frame.prediction check compares the preUpdate answer with what
each tick drew.
- setFrames takes a timed source (URL frames, or video tiles in
segments) on the scene clock by default or its own; frameReady fires
once each time the shown frame is drawn.
- drapeOn is 'surface' | 'objects' | 'all' plus lit; imagery.host() and
onHostChange go, and the drape rule the app derives is written out.
- ImagerySpec.fetchTile answers bytes, missing or defer on every
renderer; tileTransform, admit and canvas imagery need imageHooks, and
add() throws for them without it.
- Generic names for the default renderer's world data: worldDataToken,
the photoreal fallback route, and world terrain and imagery.
- clouds and water capabilities, with globe.setClouds and setWater.
- claimPointer takes a grab filter, asked on each down: a lease takes
only the presses it grabs, and wheel, pinch and every other press stay
with the camera and everyone else. Each event of a press goes where its
down went, per button, so a claim never takes a press under way.
- The app owns the styles: effects.defineStyle passes a GLSL (and optionally
WGSL) full-screen pass, with the shader interface written out.
- Credits are plain data ({ text, href, logoUrl, inline }) that the app
renders; CreateOptions.creditContainer goes.
- controls.coast { drag, zoom } in seconds replaces the inertia trio; the
stub's defaults are the default renderer's, converted.
- The frame order is the default renderer's own: a move made by follow or
in preUpdate reaches changed on the next frame.
- lodGroup links items across sets as one thing at different detail;
picks name the member shown and report the group. displayRange is
half-open.
- An orbits capability: the renderer propagates two-line elements with
SGP4 on the set's motion clock. The stub propagates with satellite.js.
- Height queries see draw sets only with includeInHeightQueries (was
excludeFromHeightQueries); HeightSample.source gains 'set'.
- courseGlide is a capability; courseBlendMs eases the course on every
renderer.
- Arc segments climb at climbMps; a negative minDtS stays for the
aircraft warm-up.
- The star catalogue is optional, a hidden column row keeps its motion,
and draw.clampState() reports the drape fallback.
Checks cover the climb and warm-up, lodGroup ranges, orbits against SGP4
(with and without motionSegments), hidden rows resuming, and sets not
answering height queries by default.
The renderer contract is what the application asks of a 3D renderer. It is nine ports
(frame, globe, draw, camera, query, input, effects, credits, quality) plus
the renderer itself, one strict .d.ts per port in src/render/contract/.
PORTS lists every member at run time, and a TypeScript-compiler test fails
when the list and the types disagree on one member. An optional member
exists only with its capability; a required one answers null or empty
without it. Nothing in the application uses the contract yet.
The stub renderer (src/render/stub/) implements every port in memory and
draws nothing. Its camera is a port of the default camera's maths: views,
lookAt, flights with their height arc and easing, rectangle framing on the
geodesic midpoint, the view rectangle with its horizon and pole cases,
changed thresholds, follows, and flights that finish inside the call.
The conformance suite (src/render/conformance/) runs 59 checks against
a renderer through the contract alone, in Node or in a browser page. The
camera checks compare traces recorded from Cesium's own Camera, headless on
a virtual clock (scripts/record-camera-goldens.mjs), to 1 mm, 1e-9 and
1e-3 px. The other checks cover listener rules on every subscription, the
frame loop, draw sets, picks, motion clocks, heights, leases, imagery,
styles, credits and quality knobs. The stub passes all of them but the
model check, which needs a glTF asset.
Reference scenes draw one scene per primitive family, a city and a
calibration path from orbit to the street, from contract calls only and
with no network. /dev/conformance/ draws them on the Cesium scene renderer
(src/render/cesium/sceneRenderer.js), records references through a
dev-server-only, loopback-only endpoint, and compares captures with
pixelmatch's antialias detection plus a solid-pixel count. Measured on
Cesium: every MSAA setting passes, and a dropped 4 px point, a dropped 2 px
line and a 1 px shift of the view fail. visual.js states the limits.
The package exports ./render/contract, ./render/stub and
./render/conformance. Documented in docs/RENDERER-CONTRACT.md,
docs/CODE-BOUNDARIES.md and docs/CURRENT-STATE.md.