gods-eye-view/docs/GLOBE-PRIMITIVES.md

Globe primitives

A layer draws through the globe-engine contract (src/globe/contract.js), not through Cesium or Navara. The contract has five drawing primitives:

• engine.movers: things at points;
• engine.lines: lines in the air;
• engine.ground: fills on the ground;
• engine.imagery: rasters on the ground;
• engine.meshes: textured or coloured world triangles.

Each engine implements all five. Cesium's are in src/globe/cesium/, Navara's in src/globe/navara/, and the fake engine's in src/globe/testing/fakeEngine.js. The checks every engine must pass are in src/globe/testing/contractSuite/index.mjs.

A new contract member lands in one change with its implementation on Cesium, Navara and the fake engine, a behavioral check in the contract suite, and a mutant that the check kills. Keep check names prefixed with the member they exercise; optional behavior belongs in engineCapabilities.

Movers: things at a point

engine.movers.createSet({ id, kind, capacity, ... }) makes a set of up to capacity instances drawn as one batch. Write them with set(index, fields) and setCount(n), then upload the changes with one commit().

There are three kinds:

• sprite: an image from an atlas, a square of sizePx, turned by rotation;
• point: a filled disc with an outline;
• model: a glTF in metres, at least minimumPixelSize on screen.

Use movers for aircraft, vessels, satellites, cameras, stations: anything that has a position and is drawn the same size on screen (or as a model).

Point instances may also set outlineColor independently of the fill, so an expanding callout can fade its outline without changing its width.

Instances move every frame without a rebuild. With depthTest: 'normal' (the default), terrain surface depth never hides a mover, even just below the surface. The Earth's horizon, 3D tiles and models still occlude it. Sprites and points can use 'always' to draw over the scene, or { disableWithinM } to skip depth testing within that camera distance; models always use normal depth. A pick returns the instance's pickId when the set is pickable. ready(index?) says whether a model's glTF or a sprite atlas has loaded and failed(index?) whether it failed to: a failed set is not loaded again, so a layer that retries makes a new set. Cesium loads a model per instance: an index written with another pickId loads its own model, so an instance moved into a failed index does not inherit the failure.

Lines: polylines in the air

engine.lines.createLine({ id, widthPx, color, ... }) makes one polyline. You can change its positions, colour and model matrix at any time.

The width is in CSS pixels. The line follows the 3D positions it is given; it does not follow the ground. Options:

• arc: 'geodesic' bends it along great circles;
• dash draws dashes;
• depthFailAlpha draws a dimmer copy where the scene hides it.

Use lines for trails, orbits, launch paths, a ring at a fixed height, and leader lines.

Ground: fills on the ground

engine.ground.createSet({ id, kind, order, pickable, drape }) makes a set of flat fills that drape over the terrain and the 3D tiles. Nothing is extruded.

Work with a set like this:

• replace(items) checks and stores all its items at once;
• commit() draws them in place of the last ones;
• show(visible) shows or hides the whole set;
• list() names the sets.

Positions are [longitude, latitude] in degrees, as GeoJSON stores them. Edges follow great circles.

There are four kinds:

kind	item	for
polygon	rings: [outer, ...holes], fill, outline	perimeters, airspace, footprints, cones, KML polygons
disc	center, radiusM (metres along the ground)	earthquakes, air-quality stations, a pad zone
cell	west, south, east, north (meridians, parallels)	GNSS and FIRMS cells, privacy cells
corridor	positions, color, widthPx or widthM	routes, cables, roads, coverage lines, outlines in metres

Item options:

• Every item has its own colours, rgba in 0..1; the alpha is the opacity.
• fill and outline ({ color, widthPx }) are optional; an outline runs along every ring.
• Within a set, a later item draws on top. Between sets, a higher order draws on top. All ground fills draw under movers, lines and models.
• pickable: true makes picks return an item's pickId, with owner (the set) and instance (the item's index).
• drape is 'both' (the default), 'terrain' or 'tiles'. Both engines honour it: Navara tells 3D tiles from terrain by its globe depth, and its CPU picks skip a set draped only on the surface not shown (terrain while photoreal tiles show, tiles otherwise).

Discs with a fill may use radial: { fillAlpha, rimAlpha, rimStart, rimEnd, emission }. Alpha multipliers are in 0..1; the radius fractions satisfy 0 <= rimStart < rimEnd < 1; emission is nonnegative. The rim grows with smoothstep between the two radii, then fades smoothly to zero at the outer edge. Space Missions uses a 500 m disc with alpha 0.105 inside and 0.72 at the rim, transitions at 0.952 and 0.985, and emission 0.35. Cesium retains its textured ground material and polygon depth bias. Navara composes the same radial envelope in its ground pass after tone mapping.

An unpickable pixel corridor set with reveal: true accepts setReveal(fraction) in 0..1. Each path is clipped at that fraction of its length. Geometry stays intact: Cesium updates material uniforms and Navara updates the corridor item texture. Hiding, showing and committing a new path retain the fraction. A corridor may have backing: { widthPx, color }: a wider edge with its own colour, with the core blended only once.

Transit drapes its history and active head through ground corridors. Its completed runs retain their age bands, 5 px dark backing and 3 px colour, with band updates once per displayed second. The active head is one backed corridor revealed along the whole current segment; only a segment crossing rebuilds its geometry. Transit uses dynamic sets so new history and head corridors build synchronously once Cesium's terrain bounds are available. The ground pass handles occlusion on both engines.

Cesium also builds reveal sets synchronously after loading those bounds. For nonempty sets, ready() includes the visible globe's tile readiness: classification needs the current surface depth as well as built geometry.

A widthPx corridor can also take the looks Cesium's ground polyline materials gave it. The GPU works them out every frame from the time, so a commit never rebuilds them:

look	fields	Cesium's
glow	power, taper (1: none)	PolylineGlow's glowPower and taperPower
pulse	periodMs, min, max	the alpha times a factor from min to max and back, a sine
dash	cells, duty, speed, gapAlpha, emission	the annotation route's GevRouteFlow: dashes flowing to the end

• glow brightens the line toward white along its centre and fades it to nothing at its edges.
• pulse follows the page's monotonic clock (performance.now()), as the old materials did, not the app clock.
• dash lays cells dashes along the whole line. Each is lit for its first duty, with soft edges of 0.08 of a cell, and brightened by emission times its colour. Between them the alpha is times gapAlpha. The dashes move toward the line's end at speed cells a second.
• A shown set with a pulse or a dash makes the engine draw a frame after every frame, as Cesium's continuous render did. list() reports it as animated. A glow alone does not animate.

Traffic's jam heat lines glow (power 0.25) and pulse (alpha 0.35 to 0.75, 1.63 s). The Directions route's 64 dashes flow at 0.55 cells a second.

A pixel corridor may instead use dashPattern: { lengthPx, pattern: 255 }, a static 16-bit screen-space dash mask with transparent gaps, as Cesium's PolylineDash material. It cannot combine with the other corridor looks. Bhote Koshi uses an 18 px dash behind its 5 px glowing flood core.

Use dynamic: true on a set whose path changes each frame. Cesium waits for its shared terrain-height bounds, then builds these small reveals synchronously so successive frames do not discard unfinished worker jobs. Other sets retain asynchronous building.

Radial pulse fields

engine.ground.createPulseField({ id, center, radiusM, heightM, color, lineColor, haloColor, depth, lineWidth, haloWidth }) draws up to four concentric pulse fronts. The centre is Earth-fixed metres; the radius is metres along the surface. The disc lies on the ellipsoid raised by heightM (default 0), with normal scene depth testing. Colours are rgba in 0..1, widths are CSS pixels, and depth is the inward band depth as a fraction of the radius. A band's opacity falls quadratically to zero.

Call draw({ radii, alphas, level }) with up to four radius fractions and opacities in 0..1. Missing fronts are zero. level controls visibility; the caller includes it in the alphas. The field starts hidden. move(center) follows a new centre; destroy() releases it and is safe to repeat. ground.list() includes it as kind: 'pulse-field'. The caller owns its clock and render requests; the field starts no animation loop.

Global Context keeps its 2,500 m pulse height, fixed-width front and halo, wake and rest windows, reduced-motion behaviour and 80 ms frame cadence. Cesium retains one material disc, updating its uniforms and rotating for small moves. Navara evaluates the same bands after tone mapping against a raised ellipsoid and scene depth; its shader lives in src/globe/navara/ground/pulse.js. The fake engine records the same state.

Bhote Koshi's event and locator share src/layers/bhoteKoshi/render/story.js: the authored reveal properties feed ground corridors and polygons, and point movers retain their independent fill and outline opacity. No story backend is selected by engine. The authored model still uses its existing property records; removing that model dependency is separate work.

Ground drawing guarantees

Both engines preserve item order, fill and outline colours, pixel and metre widths, visibility, and pick ownership. Non-pickable sets let picks through. ready() reports when committed geometry is ready to draw. Animated corridor looks use the shared ground time and request frames while shown.

Cesium translates ground items to classified fills and polylines. Navara classifies visible scene depth and blends the ground in display space. Navara picks ground items at the surface under the pointer. Packing, tiling and bin sizes are implementation details in src/globe/navara/ground/.

Imagery: rasters on the ground

engine.imagery.createLayer({ id, source, alpha, show, split, order, raise }) makes one raster layer draped over the terrain and the 3D tiles, under every ground fill, mover, line and model. Its colours are the image's own, blended by the texel's alpha times the layer's alpha.

There are two kinds of source:

kind	source	for
tiles	url with {z}, {x}, {y} (and {s} of subdomains), minLevel, maxLevel, tileSize	Recent Imagery's GIBS days, weather tiles, open overlays
image	image: a canvas, an ImageBitmap or image element, or { width, height, data } RGBA bytes; or url	the FIRMS heat raster, a field image, event imagery

Both take:

• rectangle ({ west, south, east, north } in degrees; west > east crosses the antimeridian): where the layer draws, the globe when omitted;
• credit: HTML shown while the layer is.

Tiles are Web Mercator XYZ tiles, which stop at ±85.05°, or with scheme: 'geographic' EPSG:4326 tiles (2×1 at level 0, y down from 90°N, Cesium's GeographicTilingScheme). opaque tiles have no alpha channel, and maxRequests caps the layer's tile requests in flight. transform(image) turns each decoded tile (row 0 on the north edge) into the canvas or image that draws: the weather's infrared mask. An image is stretched over its rectangle in longitude and latitude, row 0 on the north edge; one over the whole globe wraps across 180°.

raise: heightM puts an image layer on a shell that high above the ellipsoid instead of draping it: it draws over terrain, 3D tiles and the sky's edge, hidden only by what is nearer. The shell rises with the camera (4 m per kilometre of camera height, at most 60 km, in 500 m steps) so the coarse 3D tiles seen from far never hide it. Raised layers take image sources only.

Work with a layer like this:

• setSource(source) draws another source in its place, at its place in the order; the same canvas or bytes again draw their new pixels, and a source that differs only in its credit keeps its pixels;
• setSource(source, { staged: true, signal }) keeps the drawn source until the new one is complete (the image loaded; the tiles in view in), then swaps them. It resolves true then, and false when the new source failed, signal aborted it, or another setSource replaced it first. A hidden layer takes it at once. staging() says one is on its way;
• setDetail({ image, rectangle } | null) (raised layers): inside the rectangle the layer draws the detail image in place of its own (a sharper view of the area in view). The last detail draws until the new one is uploaded; it resolves true once it draws. null clears it;
• setAlpha(alpha) fades it: at 0 it draws nothing but stays on its surface, so it comes back without a gap (the FIRMS hand-off);
• show(visible) shows or hides it (Cesium unmaps a hidden layer's tiles);
• setSplit('left' | 'right' | 'none') puts it on one side of the split;
• ready() says the source is built (an image URL loaded); tiles arrive after it;
• destroy().

On the engine:

• list() names the layers in draw order, bottom first: a higher order draws on top, then the later layer;
• setSplitPosition(fraction) sets where the split runs, a fraction of the canvas width from the left (one per engine, Cesium's scene.splitPosition); splitPosition() reads it;
• surface() says where imagery drapes now: 'globe', 'tiles' (3D tiles) or 'none'.

Imagery drawing guarantees

Both engines draw imagery below ground shapes, movers, lines and models, in layer order. Each texel blends by its alpha times the layer alpha. Visibility, split position, rectangle bounds and raised-shell height follow the imagery contract. Replacing or destroying a source releases its owned resources; stale loads cannot replace the current source.

Cesium translates sources to imagery providers and raised shells. Navara samples imagery in its surface pass, including raised ellipsoid intersections. The adapters own texture storage, tile selection and depth reconstruction.

Cesium moves draped layers between the visible globe and tileset surfaces; without either surface, layers wait. Its split applies to globe imagery, not raised shells. Navara draws the top eight visible imagery slots, with detail images consuming a slot. Staged sources keep the current image visible until their replacement is ready; a failed source leaves it intact.

Open map overlays use engine.imagery when maps.addOverlay is absent. Navara's optional native raster path retains terrain detail, but does not provide rectangle bounds, split, alpha, order, or drawing on 3D tiles.

Who draws through imagery

• FIRMS heat (src/layers/firms/render/display.js): one image.

• Recent Imagery (src/layers/recentImagery/render/display.js): two Web Mercator tile layers under a split.

• Weather radar, satellite clouds and lightning (src/layers/weather/render/display.js): on the globe, the product's geographic tiles (the regional infrared through its mask, a tile transform), or the global infrared mosaic as one image; each new frame a staged source; clouds, radar and lightning at orders 21, 22, 23. On 3D tiles, a raised layer at the product's shell height (shellRendering.js WEATHER_SHELL_HEIGHTS) with the detail window around the view as its detail.

• The wind field (src/layers/wind/render/display.js): one image over the globe at order 20, faded with the camera's height while streamlines draw, raised at 5 km on 3D tiles. The streamlines stay each engine's, behind the display's flow backend, loaded by the manifest: src/globe/cesium/windFlow.js supplies Cesium's streamlines (src/layers/wind/rendering.js), and src/globe/navara/windFlow.js supplies Navara's flow mesh.

• The Bhote Koshi event imagery (src/layers/bhoteKoshi/render/display.js): two url images over the event's rectangle at alpha 0.96, split left and right at the engine's split position, order 15. The event's and the locator's story graphics use the shared ground and mover display described above.

• Imported KML/KMZ ground images (src/data/geoImportDisplay.js): one image layer per rectangle at order 30, with the authored alpha capped at 0.99 as on Cesium; a tinted or rotated image is drawn on a canvas first, and an absolute one is raised to its altitude.

• Sea Marks and Ski Pistes (src/data/osmOverlays.js): tile layers at order 10 on engines without maps.addOverlay.

Imported files

geoFileImport.js reads GeoJSON, GPX, KML and KMZ into the plain records in src/data/geoImportRecords.js. geoImportKml.js resolves KML styles with Cesium's precedence; its tests compare the records with KmlDataSource. No import loads the Cesium SDK. One geoImportDisplay.js draws the records on every engine: points on movers, ground paths and polygon fills on ground, raised paths and outlines on lines, raised polygon fills on meshes, and packed ground images on imagery. Every owned id starts with geo-import-; the file controller owns visibility, framing, refresh and destruction across engine switches.

Pins use composed square sprites to retain Cesium's pin tip, hot spot, subregion, colour, scale and rotation; a KML heading turns with the camera's heading, so it stays measured from north. Icon textures share a per-file budget of 16 million pixels: many distinct styles get lower-resolution textures at the same size. Ground heights come from the loaded surface, refreshed after the camera or map settles, in batches of 256; on 3D tiles only pins in the window are clamped to the tiles drawn. Ground pins ignore scene depth and are culled beyond the horizon; absolute pins retain their height.

Raised polygons (KML absolute or relative) draw their fills as meshes and their outlines as lines at the vertices' heights. A ground overlay's colour tints its image and its alpha fades it; a rotated overlay's image is turned on a canvas over the box around it, as Cesium turns its rectangle in degrees, and an absolute image or plain-colour overlay is a mesh at its altitude, including negative heights (Cesium raises only absolute ones). The shared display has known limits against Cesium: wall fills and extruded prisms are omitted (their top geometry remains), and gx:LatLonQuad and a rotated overlay whose box passes a pole are omitted. These are counted as undrawn. Ground edges use great circles rather than rhumb lines.

Input ownership

engine.input.on(type, listener, { pick, drill, pickWindow }) accepts pickWindow: { width, height } with positive integer dimensions passed to the picker. Omitted dimensions keep the engine default. Listeners share a pick only when their windows match, and each receives its requested drill limit. Pointer-down picks are synchronous. Moves, including drills, coalesce to the latest position per frame. Navara clicks still use one GPU answer from the gesture; a missing hit falls back to the requested CPU window. Street Level requests 9 × 9 px; CCTV's gizmo requests its own window and limit for presses and hover. Pointer ownership and removal still suppress delivery while a pick is pending.

engine.projector.horizonVisible(position, { ellipsoid }) accepts a plain ellipsoid with positive finite radii: { x, y, z } in metres. Without the option it uses WGS84. Street Level supplies WGS84 radii reduced by 1,000 m so nearby cones remain visible below sea level. The shared math is tested against the native ellipsoidal occluder, including points near the limb.

engine.input.suspendCameraInputs() disables camera gestures and returns an idempotent resume function. Suspensions are counted: only the last resume restores the state captured before the first suspension. This preserves an already-disabled camera. cameraInputsEnabled() reads the current state. Cockpit, imagery-box drawing, CCTV calibration and infrastructure flights use these methods on every engine. Pointer claims remain separate from camera input suspension.

Pick ownership belongs to the scene attachment, not to an engine implementation. scene.services.picking owns its predicates and scene.services.selection owns its shared click dispatcher. Layer entry points resolve these services using their attached engine (sceneServicesFor(engine)); the pick-registry helper functions take that engine as their final argument. Standalone entries acquire the same services on first use. The application destroys them on detach and creates fresh services when reattaching a parked engine. Identical layer IDs in simultaneous scenes cannot replace or unregister one another's picks.

Render demand

scene.services.render owns continuous-render holds and the last 16 idle request reasons for one attachment. holdContinuousRender(id) and releaseContinuousRender(id) are idempotent per owner; the last release requests one settling frame. governorRequestRender(reason) forwards a one-shot request even while another owner holds continuous rendering. The tools call install() after scene consumers have registered their holds.

The governor drives engine.render on every engine. Cesium implements setContinuous with its scene's requestRenderMode and disables automatic simulation-time renders with maximumRenderTimeChange = Infinity. Engine internals request their own scene directly and never import the governor. Layer service helpers take their attached engine as the final argument; attachment-bound callbacks can capture renderGovernorFor(engine) directly. Destroying the scene clears its holds and makes the captured service inert. A parked engine gets a fresh service when reattached.

World overlays

scene.services.overlay owns one attachment's world labels and cards. It keeps its sources, collision domains, paint lanes, canvases, frame listeners, observers, timers and accessible action subscribers. init() installs its DOM inside engine.host.container; the detection blend surface stays beside the card root so it can blend against the scene.

Publish with setEntries(sourceId, entries, options), setVisible(sourceId, visible) and clearSource(sourceId). Read painted rectangles with getPaintRect(sourceId, entryId) and register custom painters with registerPaintLane(laneId, painter, options). subscribeActions(listener) provides the accessible mirror; activateAction(owner, key) rejects an old host's actions. The shell reconnects these operations on every attachment.

worldOverlayFor(engine) resolves the same service for standalone consumers. The module helper functions take the engine first. Retained layer models use bindOverlayHost with their attached-engine getter; injected hosts without a forEngine resolver keep their own operations. Publications can buffer before init(). Destruction is terminal, including before initialization; a parked engine needs fresh scene services. An old paint-lane handle cannot mutate its replacement. Font measurements are shared until the last live host releases them.

scene.services.trackedReadout bridges the follow handle's label and selected ALPR or Local ADS-B card into this overlay. init() subscribes to that engine's follow changes and that attachment's context events; refresh(entity) republishes changed label text, and activeId() resolves the card for annotation placement. Positions stay live cached visual anchors. trackedReadoutFor(engine) resolves the service; destruction removes its listeners and clears only its own source.

scene.services.context owns selection records and notifications. Layer publishers use bindOverlayHost with their current engine, or a context service captured by their display. It mirrors records to the page context slot and preserves the gev:entity-selected, gev:entity-selection-cleared and aircraft awareness event payloads for page consumers. A clear reaches the page only when that attachment owns the page's selected record. Readouts listen only to their scene's event target. Identical IDs in different scenes cannot share a card or clear one another's selection. Retired context services cannot publish into a replacement attachment. An engine handoff carries the page-selected record through the layer session. The incoming context adopts it only while the page still selects that record; a clear between attachments wins. Rebuilt markers replace the retained carrier in the incoming readout without announcing another page selection. Readout initialization reads the retained record without testing the outgoing carrier's visibility; layers rebuild their carriers after camera restoration. The page chrome and detection controller still have page lifetimes.

Render effects

The optional visualStyles, bloom and contactSonar capabilities are available on Cesium and Navara through engine.render. Cesium implements styles, sharpening, borrowed bloom and the Anime Milky Way fade in src/globe/cesium/postStages.js; contact sonar is in sonar.js and sonarCommands.js. Cesium does not advertise cloudCover.

VisualEffects drives transitions through the render contract. UI teardown stops animation and disables effects; engine destruction removes its stages and restores the borrowed bloom state. Sharpen intensity zero disables sharpening on both engines, following Cesium.

Wildlife privacy cells

Wildlife privacy cells use one cell ground set for distinct bounds and taxon accents. The fill is 25% opaque and the 2 px outline is 80% opaque, matching Cesium's original ground geometry. Both drape on terrain and tiles and pass picks through to the badges. Wide views and detach release the set.

Batched line segments

engine.lines.createSegments({ id, widthPx, color, order }) groups independent straight segments in one batch. replace(items) copies pairs of Earth-fixed endpoints and optional per-item widthPx, color and pickId; commit() rebuilds the drawing once. Segments never connect to one another. show() and destroy() affect the whole batch; an empty replacement clears it. The batch shares createLine's id namespace and list(), which includes its endpoint count and committed pickIds in item order.

Cesium draws one synchronous primitive with per-instance colours and widths. Navara draws one ribbon mesh in the overlay after tone mapping, with scene depth and independent segment picks. Batches are solid and depth-tested; curved, dashed, transformed and depth-fail lines still use createLine. Infrastructure and cable references each use one batch for their visible stems, preserving Cesium's colours, widths, label winners and update cadence. Infrastructure excludes the whole stem batch while sampling its bases.

Choosing a primitive

• A position and an on-screen size: a mover.
• A line at given heights, or one that moves or is restyled every frame (trails, orbits, a ring at the terrain height): a line.
• Anything that lies on the ground and follows its relief:
  • an area: polygon, or disc or cell when that is its shape (they are exact and cheaper);
  • a line on the ground: corridor, with widthM when its width is a real width (an outline in metres) and widthPx otherwise.
• Group items that change together into one set, and replace them in bulk. A ground set rebuilds on commit. Small paths revealed each frame use dynamic: true; corridor looks animate without a rebuild, and radial fronts use ground.createPulseField.
• Pixels on the ground (tiles, a raster, a photo): an imagery layer. Fade it with setAlpha, and give a new raster to setSource.

Meshes: world triangles

engine.meshes.createMesh({ id, positions, indices, uv, image, color, show, depthTest, pickId }) draws indexed triangles on both sides. Positions are flat Earth-fixed xyz metres and indices name their vertices. Optional UVs run from (0, 0) at the image's bottom left to (1, 1) at its top right. The engine copies geometry arrays; the caller owns the canvas, image or video.

update(patch) replaces only supplied fields. Repeating image uploads new canvas pixels; videos update on rendered frames. RGBA color multiplies the image, white by default. show() reads visibility and show(boolean) changes it. depthTest is normal or always; null pickId disables picking. Picks return the authored id and the mesh id as owner. destroy() is idempotent; engine.meshes.list() returns live ids in creation order.

Cesium draws a synchronous Primitive with a flat material, no back-face culling and no depth writes. Colour, image and visibility changes retain the primitive; geometry, pick-id and depth-test changes replace it. The engine requests frames while the primitive or its image is preparing. Navara draws local coordinates relative to a double-precision world origin in the shared overlay pass after tone mapping and anti-aliasing, the pass that draws sprites and lines, with scene depth and triangle picking. Their authored colours are blended in display space. Both engines own geometry, material and texture disposal. The fake engine keeps the same state and tests triangle intersections for picks.

CCTV's render/meshes.js describes its live monitor quad and viewshed pyramid through this primitive. Its markers and outlines remain movers and lines. Obstruction probes use engine.surface.raycast; exclusions accept owned mesh, line and mover handles on Cesium and restore their visibility after the query.

Data packs use one src/scenes/dataPacks/display.js: points on movers, straight raised paths on lines, raised polygons and image rectangles on meshes, and media markers with captions in a composed sprite. Polygon holes and authored vertex heights are retained. Shared triangulation uses earcut, with tests comparing its area to Cesium's polygon geometry. Images retain Cesium's one-degree rectangle grid. Scene detach releases drawn resources and pick targets; reattach redraws the retained decoded assets.

Annotation drapes still use their existing renderers. Their bounded building classification volumes, animated fills and wire cages are not ordinary world triangles; they need a classification contract before that migration can preserve Cesium's behaviour.

Shared follow offsets and manual drawing

engine.camera.follow({ position, viewFrom, swingTo }) can swing from the initial follow frame to swingTo, an east/north/up offset in metres. Each frame turns at most 60 degrees and interpolates range, preserving Cesium's tracked-camera crossing guard. handle.retarget({ swingTo }) changes only the pending swing; null cancels it. Stopping or replacing the follow, a camera command or engine destruction ends it. Share links read the current handle's target and label identity and the camera pose through the contract.

engine.input.acquirePointer() returns an exclusive claim, or null if one is held. Pass it to input.on(type, listener, { pointer: claim }) and call claim.release() when done. Other screen subscriptions yield, including picks that settle after ownership changes. Camera gestures stay enabled. Cesium suspends its stock select and track clicks and restores the original functions when the claim is released or the engine is destroyed.

The Draw tool uses one drawSurface.js on every engine: a dashed geodesic line and a point mover set at the clicked heights. The dim, occluded band uses the selected colour as well as the visible band. Finished geometry still goes through the annotation board. Detaching the scene releases the claim, listeners and preview while retaining the chosen shape and colour. The page's pointer lease still arbitrates Draw against other tools.

How to add an engine

Put the implementation in a new src/globe/<name>/ folder. Keep SDK classes, shaders, resource disposal and SDK workarounds there. Use src/globe/testing/fakeEngine.js as the contract model, and src/globe/contract.js as the authoritative member and data-shape reference. Coordinates, colours, picks and display options crossing the boundary are plain data; displays do not receive native viewers or SDK types.

Implement the required host, camera, picker, projector, frame, render, surface, input, credit, clock and map interfaces, plus all five drawing primitives: movers, lines, ground, imagery and meshes. assertGlobeEngine(engine) checks these required interfaces. engineCapabilities(engine) reports only the optional visualStyles, bloom, cloudCover and contactSonar groups. An optional group must be complete or absent. Do not advertise a capability with a no-op implementation. Match Cesium's behavior where the contract permits both engines to implement it.

Run createContractSuite(engine, { waitFrames, ... }) from src/globe/testing/contractSuite.mjs. Supply real pointer delivery, canvases and pixel reads for browser checks; keep the fake-engine tests as fast contract checks. Test ownership and repeated destruction as well as visible output. The browser harness is scripts/qa-contract-suite.mjs; use --only=ground.,imagery. for ground and imagery pixel checks.

Three reports keep migration debt from growing: scripts/report-engine-coupling.mjs counts application coupling, scripts/report-qa-harness.mjs counts browser QA duplication, and src/globe/testing/contractCoverage.test.mjs reports contract members the fake-engine suite leaves uncalled. After removing coupling or moving QA work to scripts/qa-strict-harness.mjs helpers, run the matching report with --write-baseline and keep only decreases in its baseline. After adding behavioral contract checks, remove the newly exercised names from src/globe/testing/contract-uncalled-baseline.json; keep it sorted, and remove members that no longer exist too. Run the matching tests with node --import=./build/registerVue.js --test followed by their paths; the numeric baselines reject growth, and the contract baseline also rejects stale entries.

The application currently registers two kinds: adding another still requires registration in ENGINE_KINDS, scene construction/choice and the corresponding QA harnesses. assertGlobeEngine currently validates that registration. The folder and passing contract suite are the implementation boundary, not a claim that arbitrary engine folders are auto-discovered today. Layers and their fixtures should need no new drawing implementation.

The layer manifest (src/app/layers/renderers.js) loads shared factories through display. Every valid engine implements all five primitives; the manifest has no per-kind primitive lists or needs declarations. backends supplies optional engine-specific display options, currently only wind's flow, loaded dynamically from its engine folder. A missing wind backend leaves the shared raster field available. Self-drawing layers and map overlays use the same contract and do not register supported engine kinds in the manifest.

Run src/app/layers/displayRehearsal.test.mjs: it loads every manifest display on the fake engine with an unknown kind and empty extensions. Its small fixtures exercise attachment, drawing, hiding or release, and destruction; primitive registries, frame/camera/input subscriptions, follow state and service records must be clean before the engine itself is destroyed. New display entries need a fixture. Wildlife Sightings and the two map overlays are explicit skips because they have no display factory; their layer tests remain the coverage for those controllers. Native wind streamlines, DOM rasterization and GPU pixels are not covered by this rehearsal.

node scripts/check-import-directions.mjs enforces SDK ownership for static imports, re-exports and literal dynamic imports, including package subpaths. Cesium packages belong in src/globe/cesium/; three, postprocessing and Navara packages belong in src/globe/navara/. Add the new SDK's ownership rule when registering it. Contract graphs cannot reach any engine, and the existing engines cannot reach one another. The temporary exact file/package exceptions in scripts/package-boundaries.json must have reasons and must still be used; the checker prints them. They are migration debt, not a pattern for new layers. Run package boundaries, formatting, the full unit suite and the coupling report as well; engine coupling counts may not grow.