Commit Graph
14 Commits
Author SHA1 Message Date
Sameh Khamis 46ad53aa35 A renderer's roles: per-layer lighting is part of the look, and roleOf knows only real members
imageryLayer.lit (a layer shaded by the sun) joins the look with surface
shading. roleOf answers undefined for a member its port does not have, and
the port's own role without a member. The test now fails when two roles
claim the same entry.
2026-11-11 13:43:28 -08:00
Sameh Khamis 21fdc6a332 The renderer contract names what a renderer does, by role
ROLES sorts every member of PORTS into one of six roles: the Earth (streaming
and building the globe from map sources), scene contents, camera and input,
world queries, the look, and the host and frame loop. The ports follow the
API's shape; the roles say what the engine behind them does, and that the app
keeps the data while the renderer owns everything from a source spec or a
draw set down to the pixels. roleOf resolves a member to its role, the most
specific entry winning. No member changes; a test keeps every member in
exactly one role and every entry naming a real member.
2026-11-11 13:36:06 -08:00
Sameh Khamis 619c19ea67 Application extras come from the renderer plugin; framing, occlusion and panel drawing are contract ports
A renderer plugin may supply applicationHooks(renderer) for what only its
renderer has (map engine, own credits, stale commands, QA handles). What every
renderer should do moves onto the contract: controls.keepEarthFramed (behind
the keepEarthFramed capability), query.occlusionTest (behind occlusionTest),
and panel drawing, which keepPanelRendering now does through resize and
frame.renderNow through the contract. renderNow throws when the frame fails to draw.

The Cesium port installs its zoom-out guard through keepEarthFramed (a setView
no longer cancels its turn) and answers occlusionTest with the scene's probe;
the stub answers it with a horizon test.
2026-11-10 21:17:56 -08:00
Sameh Khamis c8346c9fda Keep shape radii, rim gradients, depth-fail looks, sweep cadence and step camera moves out of the renderer contract
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.
2026-11-10 04:08:41 -08:00
Sameh Khamis 7a376ebefc Make quality settings detail only and fold ctrl-wheel zoom into the camera's zoom inputs
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.
2026-11-10 03:35:35 -08:00
Sameh Khamis 46cdeba7fa Remove renderer contract members nothing in the application uses
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.
2026-11-10 03:27:10 -08:00
Sameh Khamis 456645f291 Name the surface heights answer against: globe.surfaceVersion and the surface settle kind
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.
2026-11-08 13:31:03 -08:00
Sameh Khamis 45302e9fbf Bound drillPick's work, pick before styles, and put changed thresholds behind a capability
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.
2026-11-08 12:37:04 -08:00
Sameh Khamis 90e73f2ef2 Read the eye's follow frame through the camera port and take share-follow off the Cesium list
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.
2026-11-07 21:49:25 -08:00
Sameh Khamis 2e91579f8f Add a globe visibility getter to the renderer contract
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.
2026-11-07 19:44:15 -08:00
Sameh Khamis 3dc79515bb Settle imagery, world data and sky capabilities in the renderer contract
- 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.
2026-11-05 13:26:14 -08:00
Sameh Khamis a7aeeb558a Settle leases, styles, credits and controls in the renderer contract
- 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.
2026-11-05 13:11:59 -08:00
Sameh Khamis b7c26351f7 Settle the draw decisions in the renderer contract
- 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.
2026-11-05 12:50:58 -08:00
Sameh Khamis 8db995acfc Define the renderer contract, with a stub renderer and a conformance suite
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.
2026-11-04 14:21:48 -08:00