mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
Reuse retained tile triangles for CCTV's upcoming activation probe, with finite range, exclusions and honest misses. Correct nearest-hit ordering when the ray starts inside a mesh bound. Fifteen focused surface tests and all full keyless unit/allocation, boundary, format and build gates pass. CCTV renderer integration and existing acceptance gaps remain documented.
702 lines
34 KiB
JavaScript
702 lines
34 KiB
JavaScript
// The engine-neutral globe contract. The application shell talks to a globe
|
||
// engine (Cesium today, Navara next) only through these small capability
|
||
// objects. Positions are src/geo values in Earth-fixed metres, angles are
|
||
// radians and screen coordinates are CSS pixels from the canvas's top-left
|
||
// corner. This module and src/globe/testing/** never import cesium, three or
|
||
// @navaramap/*; see docs/CODE-BOUNDARIES.md.
|
||
|
||
/**
|
||
* @typedef {{ x: number, y: number }} Cartesian2
|
||
* @typedef {{ x: number, y: number, z: number }} Cartesian3
|
||
* @typedef {{ longitude: number, latitude: number, height: number }} Cartographic
|
||
* @typedef {number[]} Matrix4 16 numbers, column-major (m[column * 4 + row]).
|
||
* @typedef {(...args: any[]) => void} Listener
|
||
*
|
||
* @typedef {object} EngineEvent
|
||
* The contract's own event semantics (engines expose createEngineEvent()
|
||
* instances, never a raw Cesium.Event):
|
||
* - listeners run in registration order;
|
||
* - adding a function that is already registered is a no-op (it stays
|
||
* registered once and fires once), so re-initialisation cannot double-fire;
|
||
* - a listener removed during dispatch is not called in that dispatch;
|
||
* - a listener added during dispatch runs from the next dispatch, and one
|
||
* removed then re-added during dispatch stays registered;
|
||
* - every remover handle is idempotent and only removes the registration it
|
||
* was returned for.
|
||
* @property {(listener: Listener) => () => void} addEventListener
|
||
* @property {(listener: Listener) => boolean} removeEventListener
|
||
*
|
||
* @typedef {object} CameraPose
|
||
* Angles follow Cesium's camera: heading in [0, 2π) clockwise from north,
|
||
* pitch in [−π/2, π/2] (negative looks down), roll in [0, 2π) with positive
|
||
* roll tilting `up` toward the camera's right; roll is 0 and heading follows
|
||
* `up` when looking (nearly, within 1e-3) straight up or down.
|
||
* @property {Cartesian3} position World position (Cesium's positionWC).
|
||
* @property {Cartographic} cartographic
|
||
* @property {number} heading
|
||
* @property {number} pitch
|
||
* @property {number} roll
|
||
* @property {Cartesian3} direction
|
||
* @property {Cartesian3} up
|
||
* @property {Cartesian3} right direction × up
|
||
* @property {number} fovy Vertical field of view.
|
||
* @property {number} aspectRatio The view's width over its height (Cesium:
|
||
* the frustum's, from the drawing buffer).
|
||
*
|
||
* @typedef {{ heading: number, pitch: number, roll: number }
|
||
* | { direction: Cartesian3, up: Cartesian3 }} Orientation
|
||
*
|
||
* @typedef {{ west: number, south: number, east: number, north: number }} Rectangle
|
||
* Radians; west > east across the antimeridian. As a destination, the
|
||
* camera is placed so the rectangle fills the view (Cesium's
|
||
* getRectangleCameraCoordinates).
|
||
*
|
||
* @typedef {object} FlightOptions
|
||
* @property {Cartesian3 | Rectangle} destination
|
||
* @property {Orientation} [orientation] As in Cesium's setView and flyTo,
|
||
* missing angles default to heading 0, pitch −π/2 and roll 0 (they do not
|
||
* keep the current ones).
|
||
* @property {number} [duration] Seconds. 0 (or less) sets the view and calls
|
||
* `complete` synchronously, before flyTo returns, as Cesium does.
|
||
* @property {'cubicInOut'|'sinusoidalInOut'|'linear'} [easing] Omitted: the
|
||
* engine's own flight easing (Cesium picks one from the flight's heights).
|
||
* @property {Matrix4} [endTransform] The camera transform once the flight
|
||
* lands; IDENTITY releases a lookAt lock.
|
||
* @property {() => void} [complete]
|
||
* @property {() => void} [cancel] Called by cancelFlight or a newer flight.
|
||
*
|
||
* @typedef {{ heading: number, pitch: number, range: number }} HeadingPitchRange
|
||
* Offset from a target in its local east-north-up frame; the camera looks at
|
||
* the target along heading/pitch from `range` metres away.
|
||
*
|
||
* @typedef {object} SphereFlightOptions
|
||
* Defaults are Cesium's: heading 0, pitch −π/4 and, when range is missing or
|
||
* 0, range = 100 m for a sphere of radius 0, otherwise
|
||
* max(r / tan(fovx/2), r / tan(fovy/2)) clamped to the camera controller's
|
||
* zoom distances (Cesium: minimumZoomDistance 1 m to maximumZoomDistance ∞
|
||
* by default).
|
||
* @property {number} [heading]
|
||
* @property {number} [pitch]
|
||
* @property {number} [range]
|
||
* @property {number} [duration]
|
||
* @property {'cubicInOut'|'sinusoidalInOut'|'linear'} [easing] As in FlightOptions.
|
||
* @property {() => void} [complete]
|
||
* @property {() => void} [cancel]
|
||
*
|
||
* @typedef {object} GlobeCamera
|
||
* @property {() => CameraPose} pose Fresh values on every call.
|
||
* @property {Cartesian3} livePosition The pose's world position as one
|
||
* engine-owned object: the same object on every read, holding the current
|
||
* position (at the latest when read). For per-frame readers, which must not
|
||
* allocate; read-only, copy it to keep a value.
|
||
* @property {() => number} height The camera's height above the WGS84
|
||
* ellipsoid (the pose's cartographic height), without building a pose.
|
||
* @property {(view: { destination: Cartesian3 | Rectangle, orientation?: Orientation }) => void} setView
|
||
* Missing angles default to heading 0, pitch −π/2, roll 0.
|
||
* @property {(options: FlightOptions) => void} flyTo Cancels a running flight first.
|
||
* @property {(sphere: { center: Cartesian3, radius: number }, options?: SphereFlightOptions) => void} flyToSphere
|
||
* Ends unlocked (identity transform).
|
||
* @property {() => boolean} flightActive
|
||
* @property {(target: Cartesian3, offset: HeadingPitchRange) => void} lookAt
|
||
* lookAtTransform(eastNorthUp(target), offset).
|
||
* @property {(transform: Matrix4, offset?: HeadingPitchRange | Cartesian3) => void} lookAtTransform
|
||
* Locks the camera to `transform`; a Cartesian3 offset is the camera position
|
||
* in that frame, looking at its origin with the frame's +Z as "up". Without
|
||
* an offset the camera keeps its world pose.
|
||
* @property {() => Matrix4} transform A copy of the current camera transform.
|
||
* @property {() => void} release lookAtTransform(IDENTITY).
|
||
* @property {() => void} cancelFlight
|
||
* @property {(amount?: number) => void} zoomIn Moves `amount` metres along direction.
|
||
* @property {(amount?: number) => void} zoomOut Moves `amount` metres against direction.
|
||
* @property {() => ({ west: number, south: number, east: number, north: number } | undefined)} viewRectangle
|
||
* Cesium's computeViewRectangle: undefined when the globe is out of view;
|
||
* west > east across the antimeridian; ±π longitudes and a ±π/2 latitude
|
||
* over a pole; the whole globe when fewer than two canvas corners hit it.
|
||
* @property {(screen: Cartesian2) => (Cartesian3 | undefined)} pickEllipsoid
|
||
* @property {(screen: Cartesian2) => { origin: Cartesian3, direction: Cartesian3 }} pickRay
|
||
* @property {EngineEvent} changed Listener receives the change fraction.
|
||
* @property {EngineEvent} moveStart Fires when the camera starts moving from rest.
|
||
* @property {EngineEvent} moveEnd Fires once the camera has been still for a
|
||
* while (Cesium: scene.cameraEventWaitTime, 500 ms), so a move that follows
|
||
* within that time continues the same movement and raises no new moveStart.
|
||
* @property {EngineEvent} commanded Fires (no arguments) when a command, not a
|
||
* user gesture, is about to take the camera: setView, flyTo, flyToSphere,
|
||
* lookAt and cancelFlight. Cesium also raises it for those calls made on the
|
||
* viewer's own camera and when the viewer's tracked entity changes, so a
|
||
* pending correction yields to every new camera owner.
|
||
* @property {(options: FollowOptions) => FollowHandle} follow Keeps a moving
|
||
* target in the centre (Cesium: trackedEntity; Navara and the fake engine:
|
||
* src/globe/follow.js each frame). The user may turn and zoom around it;
|
||
* a command that takes the camera (setView, flyTo, flyToSphere, lookAt,
|
||
* cancelFlight) ends it. A new follow replaces the current one.
|
||
* @property {() => (FollowHandle | null)} following The current follow
|
||
* (Cesium: also one the app started on viewer.trackedEntity itself).
|
||
* @property {EngineEvent} followChanged Listener receives the new handle or
|
||
* null (Cesium: viewer.trackedEntityChanged).
|
||
* @property {number} percentageChanged
|
||
*
|
||
* @typedef {object} FollowOptions
|
||
* @property {() => Cartesian3} position Where the target is (read each frame).
|
||
* @property {Cartesian3 | (() => Cartesian3)} viewFrom The camera's offset
|
||
* from the target in its east-north-up frame, metres.
|
||
* @property {number} [minRange] Closest the camera comes (150 m).
|
||
* @property {'enu'} [frame]
|
||
* @property {any} [native] Cesium only (layers' render/cesium.js): the
|
||
* Entity to put on viewer.trackedEntity instead of a proxy.
|
||
* @property {{ id: string, model: object | (() => object), position: () => Cartesian3 }} [label]
|
||
* The tracked readout's card (src/data/trackedReadout.js): its id, label
|
||
* model ({ title, details, accent, ... }) and anchor, as plain data.
|
||
*
|
||
* @typedef {object} FollowHandle
|
||
* @property {() => void} stop
|
||
* @property {(next: Partial<FollowOptions>) => void} retarget
|
||
* @property {() => (Cartesian3 | undefined)} target Where the followed
|
||
* target is now (what the follow centres).
|
||
* @property {any} [native]
|
||
* @property {object} [label] FollowOptions.label.
|
||
*
|
||
* @typedef {'click'|'doubleClick'|'move'|'down'|'up'} InputType
|
||
* @typedef {'ctrl'|'shift'|'alt'} InputModifier
|
||
* @typedef {object} InputEvent
|
||
* @property {Cartesian2} [position] click, doubleClick, down, up.
|
||
* @property {Cartesian2} [startPosition] move.
|
||
* @property {Cartesian2} [endPosition] move.
|
||
* @property {PickResult} [picked] With `pick`: what is drawn under the
|
||
* position (move: the end position), undefined for the map or nothing.
|
||
* Cesium picks at once; Navara answers a click from its GPU pick of the
|
||
* same gesture (a frame or two later; undefined after a timeout), a move
|
||
* from a CPU pick of movers and lines, at most once per frame.
|
||
* @property {PickResult[]} [drilled] With `drill`: up to that many objects
|
||
* under the position, nearest first.
|
||
*
|
||
* @typedef {object} InputOptions
|
||
* @property {InputModifier} [modifier]
|
||
* @property {boolean} [pick] click, doubleClick and move only. A move
|
||
* listener with pick gets at most one payload per frame (the latest).
|
||
* @property {number} [drill] A positive integer (click and doubleClick).
|
||
*
|
||
* @typedef {object} GlobeProjector
|
||
* @property {(position: Cartesian3, result?: Cartesian2) => (Cartesian2 | undefined)} worldToWindow
|
||
* Undefined behind the camera; fills and returns `result` when given.
|
||
* @property {(result?: Matrix4) => Matrix4} viewProjection
|
||
* World → clip matrix consistent with worldToWindow: clip = M·[x, y, z, 1],
|
||
* in front when clip.w > 0, window = ((clip.x/clip.w + 1)/2 · width,
|
||
* (1 − clip.y/clip.w)/2 · height).
|
||
* @property {(position: Cartesian3) => boolean} horizonVisible
|
||
* False when the WGS84 ellipsoid hides the point from the camera
|
||
* (Cesium's EllipsoidalOccluder.isPointVisible).
|
||
*
|
||
* @typedef {object} GlobeSurface
|
||
* @property {(cartographic: Cartographic, exclude?: any[]) => (number | undefined)} sampleHeight
|
||
* Height of the rendered scene (tiles, models) under a point.
|
||
* @property {(cartographic: Cartographic, options?: { exclude?: any[], lod?: 'visible' | 'finest' }) => (SurfaceHeight | undefined)} sampleHeightDetailed
|
||
* sampleHeight with the answer's quality (src/globe/surfaceDetail.js):
|
||
* lod 'visible' (default) answers from the tiles drawn now, 'finest' from
|
||
* the finest loaded ones (Navara; Cesium samples what it has loaded).
|
||
* Where no tile answers, the terrain. `exclude` takes this engine's mover
|
||
* sets as well as engine objects.
|
||
* @property {boolean} supported Whether sampleHeight works.
|
||
* @property {(cartographic: Cartographic) => (number | undefined)} terrainHeight
|
||
* Height of the terrain/globe surface only (Cesium's globe.getHeight).
|
||
* @property {boolean} terrainHeightSupported
|
||
* @property {(position: Cartesian3, exclude?: any[]) => (Cartesian3 | undefined)} clampToHeight
|
||
* The position moved onto the rendered scene along the geodetic normal.
|
||
* @property {boolean} clampToHeightSupported
|
||
* @property {() => boolean} tilesLoaded
|
||
* @property {boolean} [raycastSupported] Optional visible-tile obstruction probe.
|
||
* @property {(ray: { origin: Cartesian3, direction: Cartesian3, far: number, exclude?: any[] }) => ({ position: Cartesian3, distance: number, object: any } | undefined)} [raycast]
|
||
* Nearest visible tile triangle within finite positive `far` metres. Direction
|
||
* is normalized by the adapter. Excluded roots/meshes and hidden objects do
|
||
* not obstruct; a miss or unsupported geometry returns undefined, not terrain.
|
||
*
|
||
* @typedef {object} SurfaceHeight
|
||
* @property {number} height Metres above the ellipsoid.
|
||
* @property {'tiles' | 'terrain'} source
|
||
* @property {number} [tileSizeM] The size of the tile that answered
|
||
* (Navara): the quality signal; Cesium does not say.
|
||
*
|
||
* @typedef {object} GlobeRender
|
||
* @property {(reason?: string) => void} request Renders a frame soon in
|
||
* request mode; `reason` is for diagnostics only.
|
||
* @property {(enabled: boolean) => void} setContinuous
|
||
* Owns whatever the engine needs to render every frame or only on request
|
||
* (Cesium: requestRenderMode and maximumRenderTimeChange = Infinity).
|
||
* @property {() => boolean} isContinuous
|
||
* @property {(options: { enabled?: boolean, amount?: number }) => void} setSharpen
|
||
* An unsharp mask on the final image, after tone mapping and before
|
||
* anti-aliasing: each pixel moves away from its 3×3 box blur by `amount`
|
||
* (the maths of the app's Cesium sharpen stage, whose `amount` uniform the
|
||
* Sharpen slider sets in 0.1..2.1). Omitted fields keep their value; a
|
||
* non-boolean `enabled` or a negative or non-finite `amount` throws a
|
||
* TypeError. Off with amount 1 until set. The Cesium engine only keeps the
|
||
* state: in Cesium mode the app's own post stage sharpens and mirrors its
|
||
* state here (src/ui/visualEffects.js).
|
||
* @property {() => { enabled: boolean, amount: number }} sharpen
|
||
* The sharpening last set (a copy).
|
||
*
|
||
* @typedef {object} PickResult
|
||
* @property {any} id The picked entity or object id (a mover's or line's
|
||
* pickId); undefined for map tiles.
|
||
* @property {string} [owner] The mover set or line the pick belongs to.
|
||
* @property {number} [instance] The mover instance index.
|
||
* @property {any} [primitive] Cesium only, for compatibility.
|
||
* @property {any} [content] 3D tile content when map tiles were picked (what
|
||
* a surface-pick check reads), else undefined.
|
||
* @property {any} [object] The engine's own pick result, for engine-specific code.
|
||
*
|
||
* @typedef {object} GlobeMaps
|
||
* Map sources are engine-neutral descriptions, as maps/registry.js sources
|
||
* carry them; each engine builds its own providers from them:
|
||
* - imagery `{ kind: 'osm'|'esri-imagery'|'ion', style?, accessToken?,
|
||
* credit?, descriptor? }`;
|
||
* - photoreal tiles `{ kind: 'photoreal', googleApiKey?, cesiumToken?,
|
||
* credit?, descriptor? }`;
|
||
* - terrain `{ kind: 'ellipsoid'|'keyless'|'world', accessToken?, id? }`.
|
||
* Optional prebuilt members (`provider`, `tileset`, terrain `create`, an
|
||
* `imagery()` factory) are engine objects their caller built and owns: only
|
||
* the engine kind that built them uses them (the Cesium engine for the
|
||
* registry's Cesium factories), any other ignores them and builds from the
|
||
* description. The engine neither caches nor disposes them.
|
||
* Each setter settles once the source is on screen and rejects when it
|
||
* cannot be built (the current source then stays). Base imagery and
|
||
* photoreal tiles share one switch order: the call made last decides what
|
||
* shows, and a superseded call settles without showing anything.
|
||
* @property {(source: object) => Promise<void>} setBaseImagery
|
||
* @property {(source: object) => Promise<void>} setTerrain
|
||
* @property {(source: object | null) => Promise<void>} setPhotorealTiles
|
||
* Tiles replace the base imagery and hide the globe; null hides every
|
||
* tileset and shows the globe again with the last base imagery and its
|
||
* credit (no credit when none was set).
|
||
* @property {(source: object) => void} releasePhotorealTiles Forgets a
|
||
* photoreal source shown before (it no longer counts for photorealActive)
|
||
* and takes engine-added tiles out of the scene; its caller disposes them.
|
||
* @property {() => boolean} photorealActive
|
||
* @property {() => { baseImagery: object | null, photoreal: object | null }} current
|
||
* The source objects on screen, as passed: the base imagery layer on the
|
||
* globe and the photoreal tiles shown (null for none).
|
||
*
|
||
* @typedef {object} GlobeClock
|
||
* The app's own time (src/time/clock.js), in milliseconds since the Unix
|
||
* epoch: the one time source for layers and the engine's own time-driven
|
||
* drawing (Navara's sun). By default it is the wall clock (Date.now); QA
|
||
* and tests may freeze, offset or speed it up on the app clock: now()
|
||
* follows at once, frameTime() and ticked from the engine's next frame, and
|
||
* in request-render mode nothing draws until a render is requested, so a
|
||
* QA helper that moves the clock calls render.request() after it.
|
||
* Not on this clock yet (each moves when its layer or code moves):
|
||
* - Cesium's viewer.clock: the app never animates it (shouldAnimate false,
|
||
* its time frozen at boot); Cesium's sun and lighting and every entity
|
||
* property read at viewer.clock.currentTime stay on that time;
|
||
* - wall-clock throttles and feed receipt stamps everywhere (they measure
|
||
* real elapsed time, not scene time).
|
||
* Launch replay, satellite propagation and orbit GMST now use this clock.
|
||
* @property {() => number} now The current app time.
|
||
* @property {() => number} frameTime The app time latched at the start of the
|
||
* engine's current frame: every reader in one frame gets the same value; it
|
||
* does not decrease from frame to frame while the app clock runs forward.
|
||
* Before the first frame, the current time.
|
||
* @property {EngineEvent} ticked Raised once per engine frame, with the
|
||
* frame time, before that frame's preUpdate (and so before preRender). A
|
||
* frame is one turn of the engine's update loop, also when it draws
|
||
* nothing: Cesium raises it on the viewer clock's tick, right before
|
||
* scene.render (which raises preUpdate on every animation frame, drawn or
|
||
* not); Navara on the view's preUpdate, which it emits on every turn of
|
||
* its loop.
|
||
*
|
||
* @typedef {object} MoverSetOptions
|
||
* A set of moving objects drawn as one batch (src/globe/movers.js checks
|
||
* and defaults these):
|
||
* @property {string} id Unique among the engine's live sets.
|
||
* @property {'sprite'|'point'|'model'} kind
|
||
* @property {number} capacity The most instances the set holds.
|
||
* @property {number} [order] Draw order among sets (higher draws later, on
|
||
* top); 0 by default.
|
||
* @property {'normal'|'always'|{ disableWithinM: number }} [depthTest]
|
||
* 'always' draws over the scene; { disableWithinM } skips the depth test for
|
||
* instances closer to the camera than that (Cesium's
|
||
* disableDepthTestDistance). 'normal' by default.
|
||
* @property {{ atlas: { url?: string, canvas?: object, cells: Object<string, number[]> },
|
||
* sizePx: number, scaleByDistance?: number[] }} [sprite] An image atlas
|
||
* whose cells are [u0, v0, u1, v1] in 0..1 (v down from the image top);
|
||
* each sprite is a square of sizePx CSS px times its scale, times the
|
||
* NearFarScalar [nearM, nearScale, farM, farScale] when given (Cesium's
|
||
* interpolation: over the squared camera distance, eased by ^0.2).
|
||
* @property {{ sizePx: number, outlinePx?: number, outlineColor?: number[], scaleByDistance?: number[], translucencyByDistance?: number[] }} [point]
|
||
* A filled disc of sizePx CSS px diameter plus outlinePx on each side;
|
||
* outlineColor is rgba in 0..1 (opaque black by default).
|
||
* @property {{ url: string, minimumPixelSize?: number, maximumScale?: number,
|
||
* colorBlend?: { mode: 'mix'|'replace', amount: number }, unlit?: boolean }} [model]
|
||
* A glTF drawn per instance in metres, at least minimumPixelSize px.
|
||
* @property {boolean} [pickable]
|
||
* @property {boolean} [sharpen] Sprites/points: include the glyph in the
|
||
* sharpen/AA stage after tone mapping, for translucent fields such as FIRMS.
|
||
* Navara defaults to the later display stage used by W1; Cesium retains its
|
||
* native billboard stage. Does not enable sharpening or change its amount.
|
||
*
|
||
* @typedef {object} MoverFields
|
||
* One instance; omitted fields keep their value (defaults: white, scale 1,
|
||
* rotation 0, the first atlas cell, shown, identity orientation).
|
||
* @property {Cartesian3} [position]
|
||
* @property {number} [rotation] Sprites: screen angle in radians,
|
||
* counter-clockwise from screen up (Cesium's Billboard.rotation).
|
||
* @property {{ x: number, y: number, z: number, w: number }} [orientation]
|
||
* Models: the model frame's rotation into Earth-fixed axes.
|
||
* @property {number[]} [color] rgba in 0..1; multiplies the sprite's texels.
|
||
* @property {number} [scale]
|
||
* @property {string} [cell] An atlas cell key.
|
||
* @property {boolean} [show]
|
||
* @property {string|number} [pickId] What a pick of this instance returns.
|
||
*
|
||
* @typedef {object} MoverSet
|
||
* @property {(index: number, fields: MoverFields) => void} set Stored only;
|
||
* drawn after commit().
|
||
* @property {(count: number) => void} setCount Instances [0, count) draw.
|
||
* @property {() => number} count
|
||
* @property {() => void} commit Uploads what changed (one buffer write) and
|
||
* requests a render; nothing else draws a frame.
|
||
* @property {() => Float64Array} positionsView x, y, z of the drawn
|
||
* instances (a view on the set's own array; read-only).
|
||
* @property {() => boolean} ready Whether what the set draws has loaded: a
|
||
* model set's glTF (Cesium: every instance's model), a sprite set's atlas.
|
||
* A layer keeps its fallback visual until then.
|
||
* @property {() => void} destroy
|
||
*
|
||
* @typedef {object} GlobeMovers
|
||
* @property {(options: MoverSetOptions) => MoverSet} createSet
|
||
* @property {() => { id: string, kind: string, count: number, capacity: number }[]} list
|
||
*
|
||
* @typedef {object} LineOptions
|
||
* A dynamic polyline (src/globe/lines.js checks and defaults these).
|
||
* @property {string} id Unique among the engine's live lines.
|
||
* @property {number} widthPx Width in CSS pixels.
|
||
* @property {number[]} color rgba in 0..1.
|
||
* @property {number} [depthFailAlpha] 0..1: where the scene hides the line, a
|
||
* copy drawn with its alpha scaled by this (Cesium's depthFailAppearance);
|
||
* 0 (the default) draws nothing there.
|
||
* @property {{ lengthPx: number, gapPx: number } | 'tactical'} [dash]
|
||
* Dashes in pixels along the screen direction (Cesium's PolylineDash), or
|
||
* the launches' selected-orbit pattern over the whole line.
|
||
* @property {'none'|'geodesic'} [arc] 'geodesic' follows great circles
|
||
* between points (Cesium's ArcType.GEODESIC); 'none' (default) draws
|
||
* straight segments.
|
||
* @property {Matrix4} [modelMatrix] Applied to the positions (an orbit ring
|
||
* turned by GMST).
|
||
* @property {any} [pickId] What a pick of the line returns (Navara uses
|
||
* CPU segment picks; lines do not participate in its GPU pass).
|
||
*
|
||
* @typedef {object} Line
|
||
* @property {(positions: Cartesian3[] | Float64Array) => void} setPositions
|
||
* @property {(color: number[]) => void} setColor
|
||
* @property {(matrix: Matrix4) => void} setModelMatrix
|
||
* @property {(visible: boolean) => void} show
|
||
* @property {() => void} destroy
|
||
* Every call requests a render; nothing animates on its own.
|
||
*
|
||
* @typedef {object} GlobeLines
|
||
* @property {(options: LineOptions) => Line} createLine
|
||
* @property {() => { id: string, points: number, shown: boolean }[]} list
|
||
*
|
||
* @typedef {object} GlobeEngine
|
||
* @property {'cesium'|'navara'} kind
|
||
* @property {{ container: object, canvas: object, size: () => { width: number, height: number } }} host
|
||
* @property {GlobeCamera} camera
|
||
* @property {{ pick: (screen: Cartesian2, width?: number, height?: number) => (PickResult | undefined), drillPick: (screen: Cartesian2, limit?: number, width?: number, height?: number) => PickResult[], pickPosition: (screen: Cartesian2) => (Cartesian3 | undefined), pickPositionSupported: boolean, pickGlobe: (screen: Cartesian2) => (Cartesian3 | undefined) }} picker
|
||
* pickGlobe: where the ray through a window position meets the globe
|
||
* surface (terrain, not tiles or models; Cesium's globe.pick of the camera's
|
||
* pick ray); an engine without a terrain surface answers the ellipsoid.
|
||
* pickPosition reads the depth of the last drawn frame: after a camera change,
|
||
* request a render and wait a frame before reading it.
|
||
* @property {GlobeProjector} projector
|
||
* @property {{ preUpdate: EngineEvent, preRender: EngineEvent, postRender: EngineEvent }} frames Listeners receive a timestamp in ms.
|
||
* @property {GlobeRender} render
|
||
* @property {GlobeSurface} surface
|
||
* @property {{ on: (type: InputType, listener: (event: InputEvent) => void, options?: { modifier?: InputModifier }) => () => void, setCameraInputs: (enabled: boolean) => void }} input
|
||
* As in Cesium, a listener with a modifier fires only while that key is
|
||
* held and one without fires only while no modifier is held.
|
||
* @property {{ addStatic: (html: string, options?: { onScreen?: boolean }) => () => void }} credits
|
||
* @property {GlobeMaps} maps
|
||
* @property {GlobeClock} clock
|
||
* @property {GlobeMovers} movers
|
||
* @property {GlobeLines} lines
|
||
* @property {() => void} destroy
|
||
* @property {() => boolean} isDestroyed True once destroy() has run.
|
||
*/
|
||
|
||
export const ENGINE_KINDS = Object.freeze(['cesium', 'navara']);
|
||
export const INPUT_TYPES = Object.freeze([
|
||
'click',
|
||
'doubleClick',
|
||
'move',
|
||
'down',
|
||
'up',
|
||
]);
|
||
export const MODIFIERS = Object.freeze(['ctrl', 'shift', 'alt']);
|
||
/** Input types whose listeners may ask for picks. */
|
||
export const PICK_INPUT_TYPES = Object.freeze(['click', 'doubleClick', 'move']);
|
||
|
||
/**
|
||
* input.on options checked and defaulted: { modifier, pick, drill } (drill
|
||
* 0 when not asked), or a TypeError.
|
||
*/
|
||
export function normalizeInputOptions(type, options = {}) {
|
||
const { modifier, pick = false, drill = 0 } = options ?? {};
|
||
if (!INPUT_TYPES.includes(type))
|
||
throw new TypeError(`Unknown input type: ${type}`);
|
||
if (modifier !== undefined && !MODIFIERS.includes(modifier))
|
||
throw new TypeError(`Unknown input modifier: ${modifier}`);
|
||
if (typeof pick !== 'boolean')
|
||
throw new TypeError(`Input pick must be a boolean: ${pick}`);
|
||
if (!(Number.isInteger(drill) && drill >= 0))
|
||
throw new TypeError(`Input drill must be a whole number: ${drill}`);
|
||
if ((pick || drill) && !PICK_INPUT_TYPES.includes(type))
|
||
throw new TypeError(`Input ${type} cannot pick`);
|
||
if (drill && type === 'move') throw new TypeError('A move cannot drill');
|
||
return { modifier, pick: pick || drill > 0, drill };
|
||
}
|
||
export const FLIGHT_EASINGS = Object.freeze([
|
||
'cubicInOut',
|
||
'sinusoidalInOut',
|
||
'linear',
|
||
]);
|
||
|
||
const ENGINE_EVENT = Symbol('gev.globe.engineEvent');
|
||
|
||
/** Whether a value is an event made by createEngineEvent. */
|
||
export const isEngineEvent = (value) =>
|
||
value != null && value[ENGINE_EVENT] === true;
|
||
|
||
/**
|
||
* An event with the contract's semantics (see EngineEvent). `raiseEvent` and
|
||
* `raiseValue` (one argument, no argument list: for per-frame events) are for
|
||
* engine implementations; a listener that throws propagates, and the event
|
||
* stays usable.
|
||
*/
|
||
export function createEngineEvent() {
|
||
let entries = [];
|
||
let depth = 0;
|
||
let removedDuringRaise = false;
|
||
const active = (listener) =>
|
||
entries.find((entry) => entry.listener === listener);
|
||
const removeEntry = (entry) => {
|
||
if (!entry.listener) return false;
|
||
entry.listener = null;
|
||
if (depth) removedDuringRaise = true;
|
||
else entries.splice(entries.indexOf(entry), 1);
|
||
return true;
|
||
};
|
||
const settle = () => {
|
||
depth--;
|
||
if (!depth && removedDuringRaise) {
|
||
entries = entries.filter((entry) => entry.listener);
|
||
removedDuringRaise = false;
|
||
}
|
||
};
|
||
const event = {
|
||
get numberOfListeners() {
|
||
return entries.reduce(
|
||
(count, entry) => count + (entry.listener ? 1 : 0),
|
||
0,
|
||
);
|
||
},
|
||
addEventListener(listener) {
|
||
if (typeof listener !== 'function')
|
||
throw new TypeError('Engine event listener must be a function');
|
||
let entry = active(listener);
|
||
if (!entry) {
|
||
entry = { listener };
|
||
entries.push(entry);
|
||
}
|
||
return () => {
|
||
removeEntry(entry);
|
||
};
|
||
},
|
||
removeEventListener(listener) {
|
||
const entry = active(listener);
|
||
return entry ? removeEntry(entry) : false;
|
||
},
|
||
raiseEvent(...args) {
|
||
const snapshot = entries;
|
||
const length = snapshot.length;
|
||
depth++;
|
||
try {
|
||
for (let index = 0; index < length; index++) {
|
||
const listener = snapshot[index].listener;
|
||
if (listener) listener(...args);
|
||
}
|
||
} finally {
|
||
settle();
|
||
}
|
||
},
|
||
// raiseEvent(value) without an argument list, for per-frame events.
|
||
raiseValue(value) {
|
||
const snapshot = entries;
|
||
const length = snapshot.length;
|
||
depth++;
|
||
try {
|
||
for (let index = 0; index < length; index++) {
|
||
const listener = snapshot[index].listener;
|
||
if (listener) listener(value);
|
||
}
|
||
} finally {
|
||
settle();
|
||
}
|
||
},
|
||
};
|
||
Object.defineProperty(event, ENGINE_EVENT, { value: true });
|
||
return event;
|
||
}
|
||
|
||
const isFunction = (value) => typeof value === 'function';
|
||
const isObject = (value) =>
|
||
value != null && (typeof value === 'object' || typeof value === 'function');
|
||
const isBoolean = (value) => typeof value === 'boolean';
|
||
const isNumber = (value) => typeof value === 'number' && Number.isFinite(value);
|
||
|
||
// Capability → member → predicate. Members not listed here are free extensions.
|
||
const SHAPE = {
|
||
host: { container: isObject, canvas: isObject, size: isFunction },
|
||
camera: {
|
||
pose: isFunction,
|
||
livePosition: (value) =>
|
||
value != null &&
|
||
isNumber(value.x) &&
|
||
isNumber(value.y) &&
|
||
isNumber(value.z),
|
||
height: isFunction,
|
||
setView: isFunction,
|
||
flyTo: isFunction,
|
||
flyToSphere: isFunction,
|
||
flightActive: isFunction,
|
||
lookAt: isFunction,
|
||
lookAtTransform: isFunction,
|
||
transform: isFunction,
|
||
release: isFunction,
|
||
cancelFlight: isFunction,
|
||
zoomIn: isFunction,
|
||
zoomOut: isFunction,
|
||
viewRectangle: isFunction,
|
||
pickEllipsoid: isFunction,
|
||
pickRay: isFunction,
|
||
changed: isEngineEvent,
|
||
moveStart: isEngineEvent,
|
||
moveEnd: isEngineEvent,
|
||
commanded: isEngineEvent,
|
||
follow: isFunction,
|
||
following: isFunction,
|
||
followChanged: isEngineEvent,
|
||
percentageChanged: isNumber,
|
||
},
|
||
picker: {
|
||
pick: isFunction,
|
||
drillPick: isFunction,
|
||
pickPosition: isFunction,
|
||
pickPositionSupported: isBoolean,
|
||
pickGlobe: isFunction,
|
||
},
|
||
projector: {
|
||
worldToWindow: isFunction,
|
||
viewProjection: isFunction,
|
||
horizonVisible: isFunction,
|
||
},
|
||
frames: {
|
||
preUpdate: isEngineEvent,
|
||
preRender: isEngineEvent,
|
||
postRender: isEngineEvent,
|
||
},
|
||
render: {
|
||
request: isFunction,
|
||
setContinuous: isFunction,
|
||
isContinuous: isFunction,
|
||
setSharpen: isFunction,
|
||
sharpen: isFunction,
|
||
},
|
||
surface: {
|
||
sampleHeight: isFunction,
|
||
sampleHeightDetailed: isFunction,
|
||
supported: isBoolean,
|
||
terrainHeight: isFunction,
|
||
terrainHeightSupported: isBoolean,
|
||
clampToHeight: isFunction,
|
||
clampToHeightSupported: isBoolean,
|
||
tilesLoaded: isFunction,
|
||
},
|
||
input: { on: isFunction, setCameraInputs: isFunction },
|
||
credits: { addStatic: isFunction },
|
||
clock: { now: isFunction, frameTime: isFunction, ticked: isEngineEvent },
|
||
movers: { createSet: isFunction, list: isFunction },
|
||
lines: { createLine: isFunction, list: isFunction },
|
||
maps: {
|
||
setBaseImagery: isFunction,
|
||
setTerrain: isFunction,
|
||
setPhotorealTiles: isFunction,
|
||
releasePhotorealTiles: isFunction,
|
||
photorealActive: isFunction,
|
||
current: isFunction,
|
||
},
|
||
};
|
||
|
||
/** The capability paths the contract requires, e.g. 'camera.flyTo'. */
|
||
export const GLOBE_ENGINE_MEMBERS = Object.freeze([
|
||
'kind',
|
||
...Object.entries(SHAPE).flatMap(([capability, members]) =>
|
||
Object.keys(members).map((member) => `${capability}.${member}`),
|
||
),
|
||
'destroy',
|
||
'isDestroyed',
|
||
]);
|
||
|
||
/**
|
||
* Whether a value is a globe engine rather than, say, a Cesium viewer (a
|
||
* cheap structural test; assertGlobeEngine checks every member).
|
||
*/
|
||
export const isGlobeEngine = (value) =>
|
||
isObject(value) &&
|
||
ENGINE_KINDS.includes(value.kind) &&
|
||
isObject(value.camera) &&
|
||
isObject(value.projector) &&
|
||
isObject(value.frames) &&
|
||
isFunction(value.destroy);
|
||
|
||
/** Throws a TypeError naming every missing or mistyped member; returns the engine. */
|
||
export function assertGlobeEngine(engine) {
|
||
if (!isObject(engine)) throw new TypeError('GlobeEngine must be an object');
|
||
const problems = [];
|
||
if (!ENGINE_KINDS.includes(engine.kind)) problems.push('kind');
|
||
for (const [capability, members] of Object.entries(SHAPE)) {
|
||
const value = engine[capability];
|
||
if (!isObject(value)) {
|
||
problems.push(capability);
|
||
continue;
|
||
}
|
||
for (const [member, valid] of Object.entries(members))
|
||
if (!valid(value[member])) problems.push(`${capability}.${member}`);
|
||
}
|
||
if (!isFunction(engine.destroy)) problems.push('destroy');
|
||
if (!isFunction(engine.isDestroyed)) problems.push('isDestroyed');
|
||
if (problems.length)
|
||
throw new TypeError(
|
||
`GlobeEngine is missing or mistypes: ${problems.join(', ')}`,
|
||
);
|
||
return engine;
|
||
}
|
||
|
||
/** The sharpening an engine starts with (GlobeRender.sharpen). */
|
||
export const SHARPEN_INITIAL = Object.freeze({ enabled: false, amount: 1 });
|
||
|
||
/**
|
||
* GlobeRender.setSharpen's argument merged onto `current`: a new state, or a
|
||
* TypeError for a non-boolean `enabled` or a negative or non-finite `amount`.
|
||
*/
|
||
export function mergeSharpen(current, { enabled, amount } = {}) {
|
||
if (enabled !== undefined && !isBoolean(enabled))
|
||
throw new TypeError(`Sharpen enabled must be a boolean: ${enabled}`);
|
||
if (amount !== undefined && !(isNumber(amount) && amount >= 0))
|
||
throw new TypeError(
|
||
`Sharpen amount must be a finite number >= 0: ${amount}`,
|
||
);
|
||
return {
|
||
enabled: enabled ?? current.enabled,
|
||
amount: amount ?? current.amount,
|
||
};
|
||
}
|