Merge main through #1532 into the renderer seam

Brings in voice camera tilt (#1520) and free look with globe-in-view
recovery (#1532). The tilt and look maths in cameraVerbs.js and
globeInView.js run on camera poses and the geo helpers instead of Cesium.
The free-look height limit lives in the Cesium adapter
(render/cesium/freeLookLimit.js), installed through the application viewer
hooks; the globe-in-view recovery that main added to app/viewer.js runs on
the camera port in app/globeInViewRecovery.js. The scene-mode checks are
gone with the 2D and Columbus modes the seam does not draw.
This commit is contained in:
Sameh Khamis committed 2026-11-09 21:34:03 -08:00
commit 96764f85ca
28 files changed
+4764 -145

No files matched your search

+6
View File
@@ -0,0 +1,6 @@
- Voice "tilt the camera" works from the top-down view a fly-to lands on: the
camera swings about the place under the crosshair, keeps its heading, and can
tilt to a spoken angle ("tilt 45 degrees") or a default oblique view. A tilt,
orbit, pan or rotate said with a fly-to ("fly to Paris and orbit it") now
waits for the flight to land, and is dropped if you move the map meanwhile
(Manjunath, @manjunath22466, #1520).
+11
View File
@@ -0,0 +1,11 @@
- Keep the globe in view from orbit. Cesium's free look (Shift+drag) turned
the camera in place, so a few drags from the whole-globe view left only
stars, and the pose stayed in the share link. Free look now works only below
1,000 km, and above it a drag that starts on the stars orbits the globe
instead of turning the camera; a camera move that ends above it with no
planet surface in view (inside the scope keyhole when the scope is on) turns
straight down; and voice tilt and turns from orbit stop while the planet is
still on screen and say so instead of reporting a turn they could not make.
Thanks to [Chad Elliott](https://github.com/THEtheChad) for the review that
closed the drag path and kept authored scenes framed (Manjunath,
@manjunath22466, #1532).
+82 -29
View File
@@ -65,6 +65,59 @@ settling. Oblique views below 300 km are left alone.
`QA_BASE_URL=http://localhost:4173 node scripts/qa-zoom-out-guard.mjs` exercises `QA_BASE_URL=http://localhost:4173 node scripts/qa-zoom-out-guard.mjs` exercises
the real browser controller at desktop and phone widths with keyless fixtures. the real browser controller at desktop and phone widths with keyless fixtures.
Cesium's free look (Shift+drag, which turns the camera in place) works only
below 1,000 km. Above that height a few drags could turn the whole planet out of
frame and leave only stars, so Shift+drag does nothing there. Cesium also turns
the camera in place for a drag that starts on the stars below its trackball
height (7,500 km by default); that height is lowered to 1,000 km, so such a drag
orbits the globe above it, as it does higher up, and a tilt (drag or touch)
while the screen centre is on the stars there tilts about the planet's edge or
does nothing, wherever it starts. Rotation drags that start on the planet, and
zoom, are unchanged. How much of the frame shows the planet's surface is
measured by casting a 32×18 grid of view rays at the ellipsoid; while the scope
mask is on (the default) only the rays inside its keyhole count, since the mask
hides or dims the rest. Voice tilt and in-place turns of a free camera above
1,000 km stop when about a tenth of the frame still shows the surface (or about
as much as it showed when it started), never less than about 1% of the visible
frame, and a view that already shows less only keeps or gains what it has. A
turn that cannot go half a degree further without crossing that limit is refused
with a reason instead of reported as done, and a turn it accepts turns at least
that half degree. A voice tilt to an angle (or a bare tilt, to -45°) that the
limit stops short of is aimed at the angle where it stops, and its result names
that angle (`pitchDeg`) with a `note`. A turn that keeps or gains surface is not refused, even after
the window has been resized, except that near the limit, where the planet's edge
crosses the sample grid, sampling wobble can occasionally refuse one (most often
above about 15,000 km and on phone or ultrawide frames); nothing then turns away
from the planet. A turn that starts where the last voice turn left the camera
keeps that turn's limit, or a higher one if the planet now fills more, so
repeating the request does not take any more; once anything else has moved or
turned the camera, a turn is measured from what is on screen. When a camera move
ends above 1,000 km with no ray on the surface, the camera turns straight down
at the same position and heading. The end of a move is taken from Cesium's
move-end event and from a check of its own that samples the pose every 250 ms
after a move starts and acts once it has held for half a second, because at some
of these poses the camera drifts by a rounding error every frame and Cesium
never sees it stop. That check keeps watching until move-end arrives, recovering
once after each move that comes to rest, and gives up five minutes after the
camera last moved. Limb glow, and a surface sliver up to about one grid cell
thick (some 50 px on a 900 px tall frame), can count as out of view. The
zoom-out guard above keeps wheel and pinch zoom-outs in view; this catches the
other ways a move can end looking away, such as a saved or shared view that did.
Views with more surface than that, such as the oblique orbital Director shots,
are left as they are, and so are tracked or locked cameras, a camera flight in
progress, a Director scene while it plays (holds included), a pointer held
down on the globe (a drag held still; with several fingers down, until the
last is released); a check a flight, scene or
held pointer defers runs once it ends. A release outside the window that the
page never sees counts as given once the window loses focus, the page is
hidden, the canvas loses the pointer's capture, or the pointer moves with no
button down. A Director
shot loaded or replayed outside a run is not a playing scene. A view that loses
its surface without a camera move (a resize, or turning the scope on) is left as
it is until the next move. A voice turn requested while the camera is tracked is
judged by the pose voice's release of the follow camera will leave, before that
release, so a refused turn keeps the tracking.
Analyst region queries resolve unique Natural Earth names offline without Analyst region queries resolve unique Natural Earth names offline without
geocoding, so Gold Coast and Ivory Coast name the West African natural regions. geocoding, so Gold Coast and Ivory Coast name the West African natural regions.
Duplicate names require a geocoded containment anchor; when several entries for Duplicate names require a geocoded containment anchor; when several entries for
@@ -4291,34 +4344,34 @@ nearby place—always use station selection. Unqualified “turn on/start the ra
requests use Play; a qualified Play-shaped tool call is normalized to Select so requests use Play; a qualified Play-shaped tool call is normalized to Select so
its criteria cannot be silently ignored. its criteria cannot be silently ignored.
| Layer | Source | File | Proxy | Update Interval | | Layer | Source | File | Proxy | Update Interval |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------- | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Live Flights ✈️ | OpenSky Network; bounded adsb.lol regional fallback | `src/data/flights.js` | `/api/flights` (OAuth + fallback) | 30s | | Live Flights ✈️ | OpenSky Network; bounded adsb.lol regional fallback | `src/data/flights.js` | `/api/flights` (OAuth + fallback) | 30s |
| Military Flights 🎖️ | adsb.lol /v2/mil | `src/data/militaryFlights.js` | `/api/military` | 15s | | Military Flights 🎖️ | adsb.lol /v2/mil | `src/data/militaryFlights.js` | `/api/military` | 15s |
| Live AIS Vessels 🚢 | AISStream websocket | `src/data/aisLiveVessels.js` | `/api/vessels` | 60s (+800ms visibility pass) | | Live AIS Vessels 🚢 | AISStream websocket | `src/data/aisLiveVessels.js` | `/api/vessels` | 60s (+800ms visibility pass) |
| Mapped Installations ⌖ | OpenFreeMap military areas; optional configured Overpass names and Google Places search | `src/data/militaryInstallations.js` | OpenFreeMap tiles, `/api/military-installations`, `/api/google/text-search` | viewport-driven; transient errors back off, missing capability switches to tiles | | Mapped Installations ⌖ | OpenFreeMap military areas; optional configured Overpass names and Google Places search | `src/data/militaryInstallations.js` | OpenFreeMap tiles, `/api/military-installations`, `/api/google/text-search` | viewport-driven; transient errors back off, missing capability switches to tiles |
| Earthquakes | USGS | `src/data/earthquakes.js` | — | 60s | | Earthquakes | USGS | `src/data/earthquakes.js` | — | 60s |
| Air quality | ECCC MSC GeoMet OGC API (AQHI, Canada only) | `src/layers/airQuality/` | — | 20 min readings, 12 h station catalog | | Air quality | ECCC MSC GeoMet OGC API (AQHI, Canada only) | `src/layers/airQuality/` | — | 20 min readings, 12 h station catalog |
| Satellites | CelesTrak | `src/data/satellites.js` | `/api/celestrak` | 120s | | Satellites | CelesTrak | `src/data/satellites.js` | `/api/celestrak` | 120s |
| Space Missions (30d) | Launch Library 2 + CelesTrak | `src/data/rocketLaunches.js` | `/api/launches` + `/api/celestrak/active` | 5 min | | Space Missions (30d) | Launch Library 2 + CelesTrak | `src/data/rocketLaunches.js` | `/api/launches` + `/api/celestrak/active` | 5 min |
| Traffic | Selectable TomTom / OpenStreetMap / Hybrid roads; optional TomTom flow (BYOK) | `src/data/traffic.js` | browser-direct OpenFreeMap tiles; `/api/tomtom` for flow | viewport-driven; capped tile cache | | Traffic | Selectable TomTom / OpenStreetMap / Hybrid roads; optional TomTom flow (BYOK) | `src/data/traffic.js` | browser-direct OpenFreeMap tiles; `/api/tomtom` for flow | viewport-driven; capped tile cache |
| CCTV | Austin + Caltrans (CA) + TfL London + Ontario 511 + Fintraffic (FI) + DriveBC (BC) + TxDOT (TX) + Estonia (Tallinn, Tarktee) + Live Traffic NSW + Open Calgary Open Data + Statens vegvesen (NO, stills + live HLS, Kartverket ground heights) + King County (WA) Open Data + WSDOT (WA) Open Data + NYC DOT TMC (opt-in) + City of Toronto RESCU + Catalonia (Servei Català de Trànsit) + Hong Kong Transport Department + FL511 (FL, opt-in) + Freeway Bureau, MOTC (Taiwan) + Houston TranStar (opt-in) + Autostrada del Brennero (IT, A22 stills) + Street View fallback | `src/data/cctv.js` | `/api/cctv` | 10s (active) | | CCTV | Austin + Caltrans (CA) + TfL London + Ontario 511 + Fintraffic (FI) + DriveBC (BC) + TxDOT (TX) + Estonia (Tallinn, Tarktee) + Live Traffic NSW + Open Calgary Open Data + Statens vegvesen (NO, stills + live HLS, Kartverket ground heights) + King County (WA) Open Data + WSDOT (WA) Open Data + NYC DOT TMC (opt-in) + City of Toronto RESCU + Catalonia (Servei Català de Trànsit) + Hong Kong Transport Department + FL511 (FL, opt-in) + Freeway Bureau, MOTC (Taiwan) + Houston TranStar (opt-in) + Autostrada del Brennero (IT, A22 stills) + Street View fallback | `src/data/cctv.js` | `/api/cctv` | 10s (active) |
| Radio | Radio Browser (public-domain station directory) | `src/data/radio.js` | `/api/radio/stations`, `/api/radio/click/:uuid` | 45 min directory refresh | | Radio | Radio Browser (public-domain station directory) | `src/data/radio.js` | `/api/radio/stations`, `/api/radio/click/:uuid` | 45 min directory refresh |
| Transit 🚌 | Operator GTFS-Realtime VehiclePositions (7 keyless regions, `src/data/transitFeeds.js`) | `src/layers/transit/` via `src/app/layers/transit.js` | `/api/transit` | 15s (poll + delayed playback) | | Transit 🚌 | Operator GTFS-Realtime VehiclePositions (7 keyless regions, `src/data/transitFeeds.js`) | `src/layers/transit/` via `src/app/layers/transit.js` | `/api/transit` | 15s (poll + delayed playback) |
| Bikeshare 🚲 | GBFS (Lyft + BCycle + Social Bicycles + PBSC incl. Bike Share Toronto, Bike Itaú (Brazil), Bicing (Barcelona) and seven other Spanish cities + Urban Sharing, Entur, JCDecaux (Lillestrøm, Valencia, Seville) + nextbike (AMBici)) | `src/data/bikeshare.js` | `/api/gbfs` | 60s | | Bikeshare 🚲 | GBFS (Lyft + BCycle + Social Bicycles + PBSC incl. Bike Share Toronto, Bike Itaú (Brazil), Bicing (Barcelona) and seven other Spanish cities + Urban Sharing, Entur, JCDecaux (Lillestrøm, Valencia, Seville) + nextbike (AMBici)) | `src/data/bikeshare.js` | `/api/gbfs` | 60s |
| Directions 🧭 | OSRM on FOSSGIS servers (OpenStreetMap) | `src/data/directions.js` | `/api/route` (`steps=1`) | on placement / mode change | | Directions 🧭 | OSRM on FOSSGIS servers (OpenStreetMap) | `src/data/directions.js` | `/api/route` (`steps=1`) | on placement / mode change |
| Datacenters ▣ | OSM extract (bundled) | `src/data/infrastructure.js` | — | static | | Datacenters ▣ | OSM extract (bundled) | `src/data/infrastructure.js` | — | static |
| Dams ▰ | OpenInfraMap/OSM extract (bundled) | `src/data/infrastructure.js` | — | static | | Dams ▰ | OpenInfraMap/OSM extract (bundled) | `src/data/infrastructure.js` | — | static |
| Submarine Cables ◠ | TeleGeography public map (bundled) | `src/data/telegeographySubmarineCables.js` | — | static | | Submarine Cables ◠ | TeleGeography public map (bundled) | `src/data/telegeographySubmarineCables.js` | — | static |
| FIRMS Active Fires ▲ | NASA FIRMS live (VIIRS ×3 NRT + MODIS NRT, trailing 24h) | `src/data/firmsHeatmap.js` | `/api/firms` (`FIRMS_MAP_KEY`) | 10 min (proxy TTL 30 min) | | FIRMS Active Fires ▲ | NASA FIRMS live (VIIRS ×3 NRT + MODIS NRT, trailing 24h) | `src/data/firmsHeatmap.js` | `/api/firms` (`FIRMS_MAP_KEY`) | 10 min (proxy TTL 30 min) |
| Street Level 📷 | Mapillary street-level imagery (vector tiles, Graph API, MapillaryJS) | `src/layers/streetLevel/` via `src/app/layers/streetLevel.js` | `/api/mapillary/status`, `/api/mapillary/tiles/coverage/{z}/{x}/{y}` (`MAPILLARY_CLIENT_TOKEN`) | camera-driven (320 ms debounce, ≤9 tiles, server memory cache 24 h) | | Street Level 📷 | Mapillary street-level imagery (vector tiles, Graph API, MapillaryJS) | `src/layers/streetLevel/` via `src/app/layers/streetLevel.js` | `/api/mapillary/status`, `/api/mapillary/tiles/coverage/{z}/{x}/{y}` (`MAPILLARY_CLIENT_TOKEN`) | camera-driven (320 ms debounce, ≤9 tiles, server memory cache 24 h) |
| Wind 🌬 | NOAA GFS 10 m wind (keyless, 0.25°→1° grid; animated particles) | `src/data/wind.js` | `/api/wind` | 1 h (forecast cycle) | | Wind 🌬 | NOAA GFS 10 m wind (keyless, 0.25°→1° grid; animated particles) | `src/data/wind.js` | `/api/wind` | 1 h (forecast cycle) |
| GNSS Integrity 📡 (`gnss-integrity`) | adsb.lol point snapshot, low navigation accuracy binned per 0.5° cell (GEV NIC/NACp threshold + gpsjam.org formula and bands, keyless, ODbL) | `src/layers/gnss/` via `src/app/layers/gnss.js` | `/api/gnss-integrity` | camera-driven (600 ms debounce, minimum 2.5 s between reads) + 60s poll (server cache 60 s; 30 min rolling window) | | GNSS Integrity 📡 (`gnss-integrity`) | adsb.lol point snapshot, low navigation accuracy binned per 0.5° cell (GEV NIC/NACp threshold + gpsjam.org formula and bands, keyless, ODbL) | `src/layers/gnss/` via `src/app/layers/gnss.js` | `/api/gnss-integrity` | camera-driven (600 ms debounce, minimum 2.5 s between reads) + 60s poll (server cache 60 s; 30 min rolling window) |
| S2 GhostMaps 👻 (`s2-ghostmaps`) | S2 Underground's public GhostMaps repository on GitHub (KMZ intel products, keyless, CC BY-NC-SA 4.0) | `src/layers/ghostMaps/` via `src/app/layers/ghostMaps.js` | `/api/ghostmaps/catalog`, `/api/ghostmaps/events` (server-sent events), `/api/ghostmaps/file/{product}` | branch head checked every 15 s; new commits pushed to the page; 5 min catalog backstop | | S2 GhostMaps 👻 (`s2-ghostmaps`) | S2 Underground's public GhostMaps repository on GitHub (KMZ intel products, keyless, CC BY-NC-SA 4.0) | `src/layers/ghostMaps/` via `src/app/layers/ghostMaps.js` | `/api/ghostmaps/catalog`, `/api/ghostmaps/events` (server-sent events), `/api/ghostmaps/file/{product}` | branch head checked every 15 s; new commits pushed to the page; 5 min catalog backstop |
| Sea Marks ⚓ (`sea-marks`) | OpenSeaMap seamark raster tiles (keyless; CC BY-SA 2.0 tiles, OSM data ODbL) | `src/data/osmOverlays.js` | — (browser-direct tiles) | on view (Cesium tile requests; no polling) | | Sea Marks ⚓ (`sea-marks`) | OpenSeaMap seamark raster tiles (keyless; CC BY-SA 2.0 tiles, OSM data ODbL) | `src/data/osmOverlays.js` | — (browser-direct tiles) | on view (Cesium tile requests; no polling) |
| Ski Pistes ⛷ (`ski-pistes`) | OpenSnowMap piste raster tiles (keyless; CC BY-SA tiles, OSM data ODbL; no bulk download) | `src/data/osmOverlays.js` | — (browser-direct tiles) | on view (Cesium tile requests; no polling) | | Ski Pistes ⛷ (`ski-pistes`) | OpenSnowMap piste raster tiles (keyless; CC BY-SA tiles, OSM data ODbL; no bulk download) | `src/data/osmOverlays.js` | — (browser-direct tiles) | on view (Cesium tile requests; no polling) |
| Fire Perimeters 🔥 | NIFC WFIGS current interagency perimeters (keyless, paged past the 2000-record cap); InciWeb catalog + incident page origin and update time checks for verified incident-page links | `src/layers/perimeters/` via `src/app/layers/perimeters.js` | `/api/fire-perimeters` + `/api/fire-perimeters/inciweb/*` | 5 min (server caches: catalog 1 h; publication 30 min) | | Fire Perimeters 🔥 | NIFC WFIGS current interagency perimeters (keyless, paged past the 2000-record cap); InciWeb catalog + incident page origin and update time checks for verified incident-page links | `src/layers/perimeters/` via `src/app/layers/perimeters.js` | `/api/fire-perimeters` + `/api/fire-perimeters/inciweb/*` | 5 min (server caches: catalog 1 h; publication 30 min) |
| Prohibited & Restricted Airspace 🚫 | FAA Special Use Airspace prohibited (P) and restricted (R) zones (keyless FeatureServer, simplified geometry) | `src/layers/droneAirspace/` via `src/app/layers/droneAirspace.js` | `/api/drone-airspace` | 1 h (server cache 1 h; stale-on-error) | | Prohibited & Restricted Airspace 🚫 | FAA Special Use Airspace prohibited (P) and restricted (R) zones (keyless FeatureServer, simplified geometry) | `src/layers/droneAirspace/` via `src/app/layers/droneAirspace.js` | `/api/drone-airspace` | 1 h (server cache 1 h; stale-on-error) |
GNSS Integrity samples a 250 nm circle around the Earth point under the screen GNSS Integrity samples a 250 nm circle around the Earth point under the screen
centre. Camera reads debounce for 600 ms with a monotonic 2.5 s minimum gap; centre. Camera reads debounce for 600 ms with a monotonic 2.5 s minimum gap;
@@ -5711,7 +5764,7 @@ and unreachable upstream (502/504) separately from road geometry.
> branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on > branch: **2,281 on Node 25.6.1** (allocation suites skipped) = 2,255 on
> `main` + 26 route pins; the same tree on Node 24 reports 2,295. > `main` + 26 route pins; the same tree on Node 24 reports 2,295.
- **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid altitude varied. A close-up or overlap refuses without moving the camera. When the unchanged Globe View preset fits, voice says “Globe rotation isn’t available from this view. You can say ‘Reset to Globe View and rotate the globe.’” without asking a permission question or automatically resetting. Explicit Reset/Show Globe View commands remain direct; an explicit reset-and-rotate request waits for reset success before requesting rotation. If OpenAI dispatches both tools together, rotation waits for earlier same-response resets and is skipped if any fails or is cancelled. OpenAI rejects later tool calls in the same response after a globe refusal, including calls arriving while globe admission is pending, and preserves response-scoped `tool_choice: none` for the refusal follow-up; Gemini rejects further tool execution, including queued sibling calls, until fresh typed input or admitted speech. Model interruption, advisory captions and microphone toggles do not release that guard. There is no pending Yes/No offer. Outside the refused response, explicit-command interpretation and avoiding repeated resets remain model-guided; a distinct model-issued reset call is not an app-enforced proof of user intent. A failed standalone reset can still be retried by the model, and a reset result does not guarantee the camera has fully settled. Before suggesting a reset, a cloned camera checks the unchanged Globe View destination against the same keyhole/depth rules without moving the live camera. If that preset cannot fit, `globe-reset-unavailable` asks for further zoom and the refusal instructs further zoom instead of a reset; this also covers ultrawide views. Unsupported view geometry or non-WGS84 projection assumptions fail closed without the closer-zoom instruction. Supported camera inputs/navigation intents cancel rotation before their action. Finite radius greater than the ellipsoid's maximum radius proves whole-arc clearance at constant centre-distance; no low-altitude swept solver is needed. The unchanged Globe View reset preset remains 18,000,000 m. Terrain and buildings remain outside the guarantee. - **Camera verbs** (`src/cameraVerbs.js`) — one motion slot, driven per clock tick. `move_camera` orbits/pans/tilts/rotates; `fly_route` is a cinematic dolly along an existing route annotation. `rotate_globe` rotates the world-space camera rigidly around Earth's center using its screen-up axis, preserving geocentric range and framing. Left/right describe visible globe motion, while `rotate` turns the camera in place. `tilt` swings the camera about the ground under the crosshair, so the place stays centred and the heading is kept. It tilts in place instead with no ground under the crosshair, from beyond 1,000 km of range, or while an entity is tracked (voice releases the follow camera before moving, so a voice tilt from a tracked view still pivots); pitch stays within -89° to -5°, clamped only in the direction of travel so a top-down (-90°) view can tilt up out of it. Angles and limits are the camera's own pitch; at regional range the pivot's pitch is up to about 8° shallower (the Earth curves away), so the swing solves for the pivot pitch that gives the camera the angle asked for. A pivot swing toward the horizon lowers the camera (height above the pivot is range × sin|pitch|), so the swing stops lowering it at 150 m above the pivot (not above the terrain behind the camera) and the rest of the tilt happens in place. Beyond about 17 km of range the swing never hands over to an in-place tilt (that would lift the crosshair onto the sky); it keeps the camera at least 0.5° above the place's own horizon, which from roughly 500 km stops it short of -5° with the place still centred: a tilt to an angle beyond that stops at the angle reached and says so (`pitchDeg` is the angle reached, with a `note`), a continuous tilt stops there, and a further tilt up is refused as at the limit. A zoom during a pivoting tilt scales the range it holds, as for orbit, but a zoom in stops at the range that keeps that 150 m clearance; a zoom that can move no further (that floor, the 80 m floor, or the cap: 1,000 km for a tilt, where pivoting stops, and 5,000 km for an orbit) is reported as not zoomed. A zoom during a tilt to an angle re-judges the place's horizon limit at the new range: when that moves where the tilt ends, the tilt eases from where it is to the new end (holding the camera's pitch through the range change; a camera the zoom leaves past the new range's limit steps down to it with the zoom, since past it the place would drop behind the Earth), and the zoom's result names that angle (`pitchDeg`) with a `note`. Once the tilt continues in place, a zoom moves the camera like any zoom. A tilt with `pitchDeg` (or with neither angle nor direction, which means -45°) eases to that angle; a positive angle means the same angle below the horizon. `pitchDeg` is absolute, not a step: sent with a `direction` it contradicts, the tilt is refused. An angle the camera already holds answers `unchanged` but still takes navigation, so it stops a running motion and releases the follow camera. A tilt left or right is refused. A voice tilt, orbit, pan or rotate sent while a voice `fly_to_location` is still looking up or flying ("fly to London and tilt the camera" or "fly to Paris and orbit it" arrives as two sibling calls) waits for that flight to land, up to 15 s (moving to a later fly-to in the same reply as soon as it begins, whatever the earlier one reports), so it neither cancels the flight nor gets replaced by it; if the flight is cancelled, finds nothing or times out, the user grabs, touches or scrolls the map during it, or another navigation (a location-panel search, share link or file import, which leave the flight flying) takes the camera during it, the motion is not run and says so. A motion that runs after a fly-to of the same reply has already found nothing (Gemini runs one turn's calls one by one, and passes its turn as the reply) is refused the same way rather than moving the old view; a motion in a later reply runs. `stop` and `rotate_globe` do not wait, and a motion sent before its fly-to is not reordered: it runs at once, and the fly-to's result names the motion it stopped (`stoppedMotion`). Orbit still arms (`armed: 'waiting-for-arrival'`) when it starts during any other camera flight, and captures its target once the tween queue has been quiet for 0.8 s. Omitted globe direction/mode default to right/continuous; explicit values prevail. Other camera motions keep their once default. Admission requires 3D, no Cockpit/tracking owner and the whole globe inside the existing keyhole circle, using the shared keyhole/projection geometry and vertical camera FOV with a rotation-local bounding-sphere cone for off-axis containment. Canvas-edge clipping alone does not block a rigid rotation or its unchanged Globe View preset. There is no altitude cutoff. An already smaller, fully framed globe rotates directly; repeated nudges, direction and speed changes recheck current framing without demanding a reset merely because ellipsoid aLine truncated
- **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing. - **The route dolly is shaped, not linear** (2026-08-20). A trapezoid speed profile (smoothstep up, cruise, smoothstep down, distance taken as the closed-form integral) eases both ends without changing the pace — duration is still `totalM / ROUTE_M_S[speed]`, with one exception: a 0.5 s minimum keeps a degenerate route from being an instant teleport, so routes under 10 m (slow) / 20 m (normal) / 45 m (fast) fly SLOWER than the speed word, never faster. Turns bank up to **10°** (a 90° street corner settles near 7.5°), measured as a triangular pulse over a 4 s window centred on the camera so the roll leads in and unwinds after. Altitude breathes ±20 m around the 260 m mean and lifts up to 26 m into turns. Pitch is LOCKED at −32°; heading comes from a gaze that leads the path by 6.5 s of travel. `prefers-reduced-motion` zeroes the roll and the altitude shaping and keeps the easing.
- **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped. - **Invariants — do not "fix" these.** (1) **Every** release levels the roll: completion unwinds it through the ease-out envelope, and `interruptCameraMotion` zeroes it synchronously (heading/pitch/position preserved). Cesium keeps the last up vector it was handed, so skipping this leaves the user holding a tilted horizon. (2) Heading is interpolated as an ANGLE about the local up, never as a Cartesian lerp — a lerp cannot cross an antipodal pair, so an out-and-back route looked backwards for the entire return leg; `signedTurnRad` branches the exact-180° case deterministically because the cross product's sign there is a floating-point coin toss. (3) A COLD floor cell is missing data, not flat ground: route vertices carry height 0, so trusting them flew a mountain corridor at 260 m above the ELLIPSOID. The corridor warm is fire-and-forget, so the dolly ARMS — camera untouched, no teleport onto the route — for up to 1.2 s waiting for real floor data, falls back to a rendered-mesh probe (`scene.sampleHeight`) when the DEM stays cold — latched to ONE firing per flight, for exactly the cells the cache could not answer, so a route costs at most 8 `sampleHeight` calls however long it arms — and otherwise holds the launch altitude for the whole route. A corridor is only RESOLVED when every cell is accounted for: one warm cell says nothing about the ground under the other seven, and treating it as an answer let the dolly descend to 460 m over a 1,600 m rendered surface. The probe reads the rendered surface at the current LOD (rooftops and primitives included) — a better estimate than nothing, not a guaranteed upper bound. Never descend blind. The floor is SMOOTHED in both directions for the ride while the hard clearance clamp reads the RAW sample, so a cell boundary cannot pop the eye but a cliff is still cleared on the frame it is seen. A pre-departure floor is adopted whole; one arriving mid-flight is eased onto, and the eye's descent rate is capped.
- Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet). - Pins: `src/routeCinematics.test.mjs` (26 tests), with `scripts/qa-flyroute-mutations.mjs` reverting each fix individually to prove they are load-bearing (19 named defects); rendered proof `scripts/qa-flyroute-cinema.mjs` (drives the real voice runner, measures the real Cesium camera every frame, writes a labelled contact sheet).
+2
View File
@@ -1177,6 +1177,8 @@
"scripts/qa-status-badges.mjs", "scripts/qa-status-badges.mjs",
"src/dockerTrustedPeers.test.mjs", "src/dockerTrustedPeers.test.mjs",
"src/cameraGlobeRotation.test.mjs", "src/cameraGlobeRotation.test.mjs",
"src/cameraTilt.test.mjs",
"src/ui/shellFacade.test.mjs",
"src/voice/globeResetConfirmation.test.mjs", "src/voice/globeResetConfirmation.test.mjs",
"src/hudDms.test.mjs", "src/hudDms.test.mjs",
"server/providers/common/rateLimitKeys.test.mjs", "server/providers/common/rateLimitKeys.test.mjs",
+10 -3
View File
@@ -216,7 +216,8 @@
"src/sky/stars.js", "src/sky/stars.js",
"src/data/bundledJson.js", "src/data/bundledJson.js",
"src/renderGovernor.js", "src/renderGovernor.js",
"src/sky/icrf.js" "src/sky/icrf.js",
"src/globeInView.js"
], ],
"external": ["cesium"] "external": ["cesium"]
}, },
@@ -4384,7 +4385,10 @@
"src/layers/firms/heatImagery.js", "src/layers/firms/heatImagery.js",
"src/ui/layerPanel/RowSwitch.vue", "src/ui/layerPanel/RowSwitch.vue",
"src/ui/layerPanel/RowSlider.vue", "src/ui/layerPanel/RowSlider.vue",
"src/data/rioRouteNames.js" "src/data/rioRouteNames.js",
"src/globeInView.js",
"src/app/globeInViewRecovery.js",
"src/render/cesium/freeLookLimit.js"
], ],
"external": [ "external": [
"hls.js", "hls.js",
@@ -5087,7 +5091,10 @@
"src/data/firmsIntensity.js", "src/data/firmsIntensity.js",
"src/data/firmsHeatRaster.js", "src/data/firmsHeatRaster.js",
"src/layers/firms/heatImagery.js", "src/layers/firms/heatImagery.js",
"src/data/rioRouteNames.js" "src/data/rioRouteNames.js",
"src/globeInView.js",
"src/scopeMaskPolicy.js",
"src/scopeMask.js"
], ],
"external": [ "external": [
"hls.js", "hls.js",
+5 -1
View File
@@ -523,7 +523,7 @@ export const ACTION_DESCRIPTIONS = {
properties: { properties: {
direction: { direction: {
description: description:
'Required for pan/tilt/rotate; orbit/rotate_globe default right.', 'Pan/rotate/tilt steps; orbit/rotate_globe default right.',
$position: 2, $position: 2,
}, },
mode: { mode: {
@@ -531,6 +531,10 @@ export const ACTION_DESCRIPTIONS = {
'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.', 'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.',
$position: 2, $position: 2,
}, },
pitchDeg: {
description: 'Absolute; -45 default, -89 top-down.',
$position: 1,
},
}, },
}, },
}, },
+726
View File
@@ -3,6 +3,72 @@ import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process'; import { spawnSync } from 'node:child_process';
import { createApplication } from './application.js'; import { createApplication } from './application.js';
import { installTrackpadPinchZoom } from '../render/cesium/ctrlWheelZoom.js'; import { installTrackpadPinchZoom } from '../render/cesium/ctrlWheelZoom.js';
import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
import * as Cesium from 'cesium';
import { installFreeLookHeightLimit } from '../render/cesium/freeLookLimit.js';
import { installGlobeInViewRecovery } from './globeInViewRecovery.js';
import { FREE_LOOK_MAX_HEIGHT_METERS } from '../globeInView.js';
import * as globeInView from '../globeInView.js';
import { createCesiumCamera } from '../render/cesium/camera.js';
import { bindRenderer } from '../render/rendererOf.js';
/** The camera port bound over each real Cesium camera a test makes. */
const cameraPorts = new WeakMap();
/**
* Bind `viewer` the Cesium renderer's own camera port over its real camera,
* with the camera's own `moveStart` and `moveEnd` so a test raises them, and
* a frame port that counts render requests on the scene.
*/
function bindCameraPorts(viewer) {
const { camera, scene } = viewer;
const noEvent = { addEventListener: () => () => {} };
const real = createCesiumCamera({
scene: {
postUpdate: noEvent,
preUpdate: noEvent,
get screenSpaceCameraController() {
return scene.screenSpaceCameraController;
},
requestRender: () => scene.requestRender?.(),
},
camera,
report: (error) => {
throw error;
},
}).port;
const port = Object.create(real, {
on: { value: (event, cb) => camera[event].addEventListener(cb) },
});
cameraPorts.set(camera, port);
bindRenderer(viewer, {
camera: port,
get canvas() {
return scene.canvas;
},
frame: {
on: () => () => {},
requestRender: () => scene.requestRender?.(),
},
});
}
// The frame measures take a camera pose; these take the test's camera.
const poseOf = (camera) => cameraPorts.get(camera).pose();
const LOOKS = {
lookUp: 'up',
lookDown: 'down',
lookLeft: 'left',
lookRight: 'right',
};
const globeFrameShare = (camera, options) =>
globeInView.globeFrameShare(poseOf(camera), options);
const globeOutOfFrame = (camera, options) =>
globeInView.globeOutOfFrame(poseOf(camera), options);
const lookAngleWithinFrame = (camera, look, angle, options) =>
globeInView.lookAngleWithinFrame(poseOf(camera), LOOKS[look], angle, options);
const lookStepLosesGlobe = (camera, look, angle, options) =>
globeInView.lookStepLosesGlobe(poseOf(camera), LOOKS[look], angle, options);
const phases = ['Scene', 'Controls', 'Data', 'Tools']; const phases = ['Scene', 'Controls', 'Data', 'Tools'];
function fixture(overrides = {}) { function fixture(overrides = {}) {
@@ -344,3 +410,663 @@ test('trackpad pinch falls back to the original event when relay construction fa
assert.equal(event.propagationStopped, false); assert.equal(event.propagationStopped, false);
assert.equal(f.relayed.length, 0); assert.equal(f.relayed.length, 0);
}); });
function freeLookFixture({ enableLook = true, height = 0 } = {}) {
const listeners = new Set();
const controller = { enableLook, minimumTrackBallHeight: 7_500_000 };
const camera = { positionCartographic: { height } };
const viewer = {
camera,
scene: {
screenSpaceCameraController: controller,
preUpdate: {
addEventListener(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
},
},
},
};
const frame = (nextHeight) => {
camera.positionCartographic = { height: nextHeight };
for (const listener of listeners) listener();
};
return { viewer, controller, listeners, frame };
}
test('free look follows camera height and is restored on dispose', () => {
const f = freeLookFixture({ height: 500 });
const dispose = installFreeLookHeightLimit(
f.viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
assert.equal(f.controller.enableLook, true);
f.frame(FREE_LOOK_MAX_HEIGHT_METERS + 1);
assert.equal(f.controller.enableLook, false);
f.frame(FREE_LOOK_MAX_HEIGHT_METERS);
assert.equal(f.controller.enableLook, true);
f.frame(Number.NaN);
assert.equal(f.controller.enableLook, true);
f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
dispose();
dispose();
assert.equal(f.controller.enableLook, true);
assert.equal(f.listeners.size, 0);
});
test('drags that start on the stars orbit above the free-look height', () => {
// Below Cesium's trackball height such a drag turns the camera in place.
const f = freeLookFixture({ height: 500 });
const dispose = installFreeLookHeightLimit(
f.viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
assert.equal(
f.controller.minimumTrackBallHeight,
FREE_LOOK_MAX_HEIGHT_METERS,
);
dispose();
assert.equal(f.controller.minimumTrackBallHeight, 7_500_000);
const lower = freeLookFixture({ height: 500 });
lower.controller.minimumTrackBallHeight = 500_000;
const disposeLower = installFreeLookHeightLimit(
lower.viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
assert.equal(
lower.controller.minimumTrackBallHeight,
500_000,
'never raised',
);
disposeLower();
assert.equal(lower.controller.minimumTrackBallHeight, 500_000);
const later = freeLookFixture({ height: 500 });
const disposeLater = installFreeLookHeightLimit(
later.viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
later.controller.minimumTrackBallHeight = 2_000_000;
disposeLater();
assert.equal(
later.controller.minimumTrackBallHeight,
2_000_000,
'dispose keeps a value set after install',
);
});
test('free look keeps a setting other code makes after it is installed', () => {
const f = freeLookFixture({ height: 500 });
const dispose = installFreeLookHeightLimit(
f.viewer,
FREE_LOOK_MAX_HEIGHT_METERS,
);
f.controller.enableLook = false;
f.frame(10);
assert.equal(f.controller.enableLook, false, 'turned off stays off');
f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
f.frame(10);
assert.equal(f.controller.enableLook, false, 'and stays off after orbit');
f.controller.enableLook = true;
f.frame(10);
assert.equal(f.controller.enableLook, true, 'turned back on');
f.frame(FREE_LOOK_MAX_HEIGHT_METERS * 20);
assert.equal(f.controller.enableLook, false, 'still limited from orbit');
f.frame(10);
f.controller.enableLook = false;
dispose();
assert.equal(f.controller.enableLook, false, 'dispose keeps a later setting');
});
test('free look stays off when the viewer had it disabled', () => {
const f = freeLookFixture({ enableLook: false, height: 500 });
installFreeLookHeightLimit(f.viewer, FREE_LOOK_MAX_HEIGHT_METERS);
f.frame(10);
assert.equal(f.controller.enableLook, false);
});
// A real Cesium camera on the smallest scene its constructor reads, so the
// frustum test runs on Cesium's own view math rather than a stub.
function realCamera({ width = 1600, height = 900, mode } = {}) {
const scene = {
canvas: { clientWidth: width, clientHeight: height },
drawingBufferWidth: width,
drawingBufferHeight: height,
mapProjection: new Cesium.GeographicProjection(),
mode: mode ?? Cesium.SceneMode.SCENE3D,
pixelRatio: 1,
ellipsoid: Cesium.Ellipsoid.WGS84,
mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
tweens: new Cesium.TweenCollection(),
renders: 0,
requestRender() {
this.renders += 1;
},
};
const camera = new Cesium.Camera(scene);
camera.frustum.aspectRatio = width / height;
const viewer = { camera, scene };
bindCameraPorts(viewer);
return { camera, scene, viewer };
}
function aim(
camera,
{ lon = -94.69, lat = 18.87, alt, heading = 0, pitch, roll = 0 },
) {
camera.setView({
destination: Cesium.Cartesian3.fromDegrees(lon, lat, alt),
orientation: {
heading: Cesium.Math.toRadians(heading),
pitch: Cesium.Math.toRadians(pitch),
roll: Cesium.Math.toRadians(roll),
},
});
}
const reportedStuckView = {
alt: 17_996_811,
heading: 180,
pitch: -42,
roll: 180,
};
// Oblique poses that still show part of the planet: Director recipe shots
// (Global Flights Radar, Omniscience Pullback) and a voice tilt from orbit.
const partialGlobeViews = [
{ lon: -30, lat: 20, alt: 19_000_000, pitch: -65 },
{ lon: 2, lat: 46, alt: 8_000_000, pitch: -52 },
{ lon: 110, lat: 20, alt: 9_500_000, pitch: -66 },
{ lon: 0, lat: 0, alt: 2_000_000, pitch: -30 },
];
// Stars and a few pixels of limb, no surface: where a frame limit measured
// against a sphere of the planet's largest radius used to stop a voice tilt.
const limbOnlyView = { alt: 18_000_000, pitch: -56.75 };
/**
* An oracle independent of the code under test: the share of an 80×45 grid of
* Cesium pick rays across the canvas that hit the ellipsoid surface.
*/
function surfacePixelShare(camera, width, height, { keyhole = false } = {}) {
const radius = (KEYHOLE_OUTER_RADIUS * height) / 2;
let hits = 0;
let counted = 0;
for (let row = 0; row < 45; row += 1) {
for (let column = 0; column < 80; column += 1) {
const x = ((column + 0.5) * width) / 80;
const y = ((row + 0.5) * height) / 45;
if (keyhole && Math.hypot(x - width / 2, y - height / 2) > radius)
continue;
counted += 1;
const ray = camera.getPickRay(new Cesium.Cartesian2(x, y));
if (Cesium.IntersectionTests.rayEllipsoid(ray, Cesium.Ellipsoid.WGS84))
hits += 1;
}
}
return hits / counted;
}
test('the globe is out of frame only when no surface is on screen', () => {
const cases = [
[reportedStuckView, 1225, 923, true],
[limbOnlyView, 1600, 900, true],
[{ alt: 17_996_811, pitch: -90 }, 1225, 923, false],
...partialGlobeViews.map((view) => [view, 1600, 900, false]),
];
for (const [view, width, height, out] of cases) {
const { camera } = realCamera({ width, height });
aim(camera, view);
const label = JSON.stringify(view);
assert.equal(globeOutOfFrame(camera), out, label);
assert.equal(surfacePixelShare(camera, width, height) === 0, out, label);
assert.ok(
Math.abs(
globeFrameShare(camera) - surfacePixelShare(camera, width, height),
) < 0.03,
`${label}: the frame share matches the pick-ray oracle`,
);
}
});
test('a move that ends with the globe out of frame turns back to nadir', () => {
const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
const dispose = installGlobeInViewRecovery(viewer);
aim(camera, reportedStuckView);
const position = Cesium.Cartesian3.clone(camera.positionWC);
const heading = camera.heading;
camera.moveEnd.raiseEvent();
assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
assert.ok(Cesium.Math.equalsEpsilon(camera.heading, heading, 1e-6));
assert.ok(
Cesium.Cartesian3.equalsEpsilon(camera.positionWC, position, 0, 1e-3),
);
assert.equal(globeOutOfFrame(camera), false);
// One render for the new view, one the recovery asks for itself.
assert.equal(scene.renders, 2, 'the turned view is drawn');
// Looking up near the ground, then zoomed out past the limit.
aim(camera, { alt: 3_834_000, pitch: 10 });
camera.moveEnd.raiseEvent();
assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
// Only the limb on a 16:9 screen still counts as lost.
const wide = realCamera({ width: 1600, height: 900 });
const disposeWide = installGlobeInViewRecovery(wide.viewer);
aim(wide.camera, limbOnlyView);
wide.camera.moveEnd.raiseEvent();
assert.ok(Cesium.Math.equalsEpsilon(wide.camera.pitch, -Math.PI / 2, 1e-6));
disposeWide();
dispose();
dispose();
aim(camera, reportedStuckView);
camera.moveEnd.raiseEvent();
assert.equal(globeOutOfFrame(camera), true, 'disposed recovery is inert');
});
// True when a moveEnd leaves the camera's view direction as it was.
function moveEndKeepsView(camera) {
const direction = Cesium.Cartesian3.clone(camera.directionWC);
camera.moveEnd.raiseEvent();
return Cesium.Cartesian3.equalsEpsilon(camera.directionWC, direction, 1e-9);
}
test('globe recovery leaves partial, low, locked and following views alone', () => {
for (const view of partialGlobeViews) {
const { camera, viewer } = realCamera();
installGlobeInViewRecovery(viewer);
aim(camera, view);
assert.ok(moveEndKeepsView(camera), JSON.stringify(view));
}
const low = realCamera();
installGlobeInViewRecovery(low.viewer);
aim(low.camera, { alt: 900_000, pitch: 85 });
assert.equal(globeOutOfFrame(low.camera), true);
assert.ok(moveEndKeepsView(low.camera), 'below the limit');
// Locked on a point in space, between it and the planet, facing away.
const locked = realCamera();
installGlobeInViewRecovery(locked.viewer);
locked.camera.lookAtTransform(
Cesium.Matrix4.fromTranslation(new Cesium.Cartesian3(30_000_000, 0, 0)),
new Cesium.Cartesian3(-1_000_000, 0, 0),
);
assert.equal(globeOutOfFrame(locked.camera), true);
assert.ok(moveEndKeepsView(locked.camera), 'locked camera');
// Tracking an entity that has no position yet keeps an identity transform.
const tracked = realCamera();
tracked.viewer.trackedEntity = { id: 'pending-fix' };
installGlobeInViewRecovery(tracked.viewer);
aim(tracked.camera, reportedStuckView);
assert.ok(moveEndKeepsView(tracked.camera), 'tracked camera');
});
test('the look limit from orbit tolerates grid noise and never reaches zero', () => {
const radians = Cesium.Math.toRadians;
// About 2% of a 16:9 frame on the planet, below the 10% limit.
const sliver = { alt: 18_000_000, pitch: -60 };
const { camera } = realCamera();
aim(camera, sliver);
const start = surfacePixelShare(camera, 1600, 900);
assert.ok(start > 0 && start < 0.1, `starts below the limit: ${start}`);
// Sideways across the sliver: the share wobbles by a cell, the planet stays.
assert.equal(lookStepLosesGlobe(camera, 'lookLeft', radians(0.5)), false);
const startShare = globeFrameShare(camera);
for (let i = 0; i < 20; i += 1) {
const step = lookAngleWithinFrame(camera, 'lookLeft', radians(0.25), {
startShare,
});
assert.equal(step, radians(0.25), `sideways step ${i + 1}`);
camera.lookLeft(step);
}
assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
// Toward the planet is always allowed.
aim(camera, sliver);
assert.equal(
lookAngleWithinFrame(camera, 'lookDown', radians(10)),
radians(10),
);
// Away from it stops short of losing it.
aim(camera, sliver);
const away = lookAngleWithinFrame(camera, 'lookUp', radians(30));
assert.ok(away < radians(30));
camera.lookUp(away);
assert.ok(globeFrameShare(camera) > 0);
assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
});
test('the look limit leaves a view with no surface to the move-end recovery', () => {
const { camera } = realCamera({ width: 1225, height: 923 });
aim(camera, reportedStuckView);
assert.equal(
lookAngleWithinFrame(camera, 'lookUp', Cesium.Math.toRadians(5)),
Cesium.Math.toRadians(5),
);
});
// Surface only in the corners of a 16:9 frame, all of it outside the scope's
// keyhole: the full frame shows some planet, the scope shows none.
const cornerOnlyView = { alt: 18_000_000, pitch: -52, roll: 60 };
test('with a scope keyhole, surface hidden in the masked corners counts as none', () => {
const { camera } = realCamera();
aim(camera, cornerOnlyView);
const keyhole = { keyholeRadius: KEYHOLE_OUTER_RADIUS };
assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
assert.equal(surfacePixelShare(camera, 1600, 900, { keyhole: true }), 0);
assert.equal(globeOutOfFrame(camera), false);
assert.equal(globeOutOfFrame(camera, keyhole), true);
aim(camera, { alt: 18_000_000, pitch: -90 });
assert.ok(
Math.abs(
globeFrameShare(camera, keyhole) -
surfacePixelShare(camera, 1600, 900, { keyhole: true }),
) < 0.03,
'the keyhole share matches the pick-ray oracle',
);
});
test('the recovery follows the scope: corner-only views are turned back only behind it', () => {
for (const [scopeOn, expectRecovery] of [
[true, true],
[false, false],
]) {
const { camera, viewer } = realCamera();
installGlobeInViewRecovery(viewer, {
keyholeRadius: () => (scopeOn ? KEYHOLE_OUTER_RADIUS : 0),
});
aim(camera, cornerOnlyView);
camera.moveEnd.raiseEvent();
assert.equal(
Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
expectRecovery,
`scope ${scopeOn ? 'on' : 'off'}`,
);
}
});
test('the recovery leaves a camera flight and an authored scene alone', () => {
let playing = true;
const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
scene.camera = camera;
scene.screenSpaceCameraController = { enableInputs: true };
installGlobeInViewRecovery(viewer, { paused: () => playing });
aim(camera, reportedStuckView);
camera.moveEnd.raiseEvent();
assert.equal(globeOutOfFrame(camera), true, 'a playing scene is left alone');
playing = false;
// A flight that pauses looking away is left alone until it ends.
camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(10, 20, 18_000_000),
duration: 5,
});
camera.moveEnd.raiseEvent();
assert.equal(globeOutOfFrame(camera), true, 'a flight is left alone');
camera.cancelFlight();
camera.moveEnd.raiseEvent();
assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
});
test('a check a scene or flight defers runs once it ends', () => {
for (const viaMoveEnd of [false, true]) {
let playing = true;
const timers = fakeTimers();
const { camera, viewer } = realCamera({ width: 1225, height: 923 });
installGlobeInViewRecovery(viewer, {
paused: () => playing,
...timers,
});
aim(camera, reportedStuckView);
camera.moveStart.raiseEvent();
// A hold on a stars-only shot: quiet, with or without Cesium's moveEnd.
for (let i = 0; i < 4; i += 1) timers.tick();
if (viaMoveEnd) camera.moveEnd.raiseEvent();
// Longer than the settle check's five-minute bound.
for (let i = 0; i < 1500; i += 1) timers.tick();
assert.equal(globeOutOfFrame(camera), true, 'left alone while it plays');
assert.equal(timers.pending(), 1, 'still watching');
playing = false;
timers.tick();
assert.ok(
Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
`recovered once the scene ends (${viaMoveEnd ? 'after moveEnd' : 'no moveEnd'})`,
);
}
});
// Holding a drag still for half a second on a view that already showed no
// surface looked like a settled camera, and the view was turned down under
// the user's hand.
test('the recovery waits while a pointer is held on the globe', () => {
const timers = fakeTimers();
const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
const document = new EventTarget();
scene.canvas = Object.assign(new EventTarget(), {
clientWidth: 1225,
clientHeight: 923,
ownerDocument: document,
});
const dispose = installGlobeInViewRecovery(viewer, timers);
aim(camera, reportedStuckView);
scene.canvas.dispatchEvent(new Event('pointerdown'));
camera.moveStart.raiseEvent();
for (let i = 0; i < 8; i += 1) timers.tick();
camera.moveEnd.raiseEvent();
for (let i = 0; i < 8; i += 1) timers.tick();
assert.equal(globeOutOfFrame(camera), true, 'left alone while held');
document.dispatchEvent(new Event('pointerup'));
for (let i = 0; i < 3; i += 1) timers.tick();
assert.ok(
Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
'recovered once the pointer is released',
);
dispose();
aim(camera, reportedStuckView);
scene.canvas.dispatchEvent(new Event('pointerdown'));
document.dispatchEvent(new Event('pointerup'));
assert.equal(timers.pending(), 0, 'disposed recovery holds no listeners');
});
/** A held-pointer recovery over a canvas in a document in a window. */
function heldPointerRecovery() {
const timers = fakeTimers();
const { camera, scene, viewer } = realCamera({ width: 1225, height: 923 });
const window = new EventTarget();
const document = Object.assign(new EventTarget(), {
defaultView: window,
visibilityState: 'visible',
});
scene.canvas = Object.assign(new EventTarget(), {
clientWidth: 1225,
clientHeight: 923,
ownerDocument: document,
});
const dispose = installGlobeInViewRecovery(viewer, timers);
const pointer = (target, type, pointerId, init = {}) =>
target.dispatchEvent(
Object.assign(new Event(type), { pointerId, ...init }),
);
/** Press, move and hold still: the check defers while a pointer is held. */
const holdStill = () => {
aim(camera, reportedStuckView);
camera.moveStart.raiseEvent();
for (let i = 0; i < 8; i += 1) timers.tick();
camera.moveEnd.raiseEvent();
for (let i = 0; i < 8; i += 1) timers.tick();
};
const settle = () => {
for (let i = 0; i < 3; i += 1) timers.tick();
};
const recovered = () =>
Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6);
return {
camera,
document,
window,
dispose,
pointer,
holdStill,
settle,
recovered,
canvas: scene.canvas,
};
}
// Releasing one of two fingers cleared the held flag, and the recovery
// turned the view down under the finger still on the glass.
test('the recovery waits until every held pointer is released', () => {
const h = heldPointerRecovery();
h.pointer(h.canvas, 'pointerdown', 1);
h.pointer(h.canvas, 'pointerdown', 2);
h.holdStill();
h.pointer(h.document, 'pointerup', 1);
h.settle();
assert.equal(h.recovered(), false, 'left alone under the second finger');
assert.equal(globeOutOfFrame(h.camera), true);
h.pointer(h.document, 'pointercancel', 2);
h.settle();
assert.equal(h.recovered(), true, 'recovered once both are released');
h.dispose();
});
// A release the page never sees (the pointer let go outside the window)
// must not hold the recovery off for good.
for (const [label, lose] of [
['the window loses focus', (h) => h.window.dispatchEvent(new Event('blur'))],
[
'the page is hidden',
(h) => {
h.document.visibilityState = 'hidden';
h.document.dispatchEvent(new Event('visibilitychange'));
},
],
[
'the canvas loses the pointer capture',
(h) => h.pointer(h.canvas, 'lostpointercapture', 1),
],
[
'the pointer moves with no button down',
(h) => h.pointer(h.document, 'pointermove', 1, { buttons: 0 }),
],
]) {
test(`a held pointer whose release is lost stops deferring when ${label}`, () => {
const h = heldPointerRecovery();
h.pointer(h.canvas, 'pointerdown', 1);
h.holdStill();
h.pointer(h.document, 'pointermove', 1, { buttons: 1 });
h.settle();
assert.equal(h.recovered(), false, 'left alone while held');
lose(h);
h.settle();
assert.equal(h.recovered(), true, 'recovered once the hold is let go');
h.dispose();
});
}
function fakeTimers() {
let next = 1;
const pending = new Map();
return {
setTimeout: (callback) => {
const id = next++;
pending.set(id, callback);
return id;
},
clearTimeout: (id) => pending.delete(id),
pending: () => pending.size,
/** Run the earliest pending callback, as 250 ms passing would. */
tick() {
const [id, callback] = pending.entries().next().value ?? [];
if (id === undefined) return false;
pending.delete(id);
callback();
return true;
},
};
}
test('a stuck view is recovered once it has held still, without waiting for moveEnd', () => {
// At this pose the camera can drift by a rounding error every frame, so
// Cesium never sees it stop and never raises moveEnd for it.
const timers = fakeTimers();
const { camera, viewer } = realCamera({ width: 1225, height: 923 });
installGlobeInViewRecovery(viewer, timers);
aim(camera, reportedStuckView);
camera.moveStart.raiseEvent();
timers.tick();
assert.equal(globeOutOfFrame(camera), true, 'one quiet sample is not enough');
// A rounding-error drift between samples still counts as at rest.
camera.lookUp(1e-15);
timers.tick();
assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
// Under that drift Cesium raises no new moveStart, so a later move that
// ends looking away is caught by the same check.
aim(camera, reportedStuckView);
timers.tick();
timers.tick();
assert.equal(globeOutOfFrame(camera), true, 'not yet at rest');
timers.tick();
assert.ok(Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6));
camera.moveEnd.raiseEvent();
assert.equal(timers.pending(), 0, 'moveEnd ends the check');
});
test('the settle check follows a long move and gives up five minutes after the last one', () => {
// A drag of half a minute that stops at a stuck pose is still recovered.
const long = fakeTimers();
const dragged = realCamera({ width: 1225, height: 923 });
installGlobeInViewRecovery(dragged.viewer, long);
aim(dragged.camera, reportedStuckView);
dragged.camera.moveStart.raiseEvent();
for (let i = 0; i < 120; i += 1) {
dragged.camera.moveLeft(0.01);
long.tick();
}
assert.equal(globeOutOfFrame(dragged.camera), true, 'still moving');
while (long.tick());
assert.ok(
Cesium.Math.equalsEpsilon(dragged.camera.pitch, -Math.PI / 2, 1e-6),
'recovered once it stopped',
);
// A camera that keeps moving is followed, and left alone, for as long as it
// moves; once it rests the check gives up five minutes later.
const timers = fakeTimers();
const { camera, viewer } = realCamera({ width: 1225, height: 923 });
installGlobeInViewRecovery(viewer, timers);
aim(camera, reportedStuckView);
camera.moveStart.raiseEvent();
for (let i = 0; i < 2000; i += 1) {
camera.moveLeft(0.01);
timers.tick();
}
assert.equal(timers.pending(), 1, 'still following after eight minutes');
assert.equal(globeOutOfFrame(camera), true, 'a moving camera is left alone');
let idleSamples = 0;
while (timers.tick()) idleSamples += 1;
assert.ok(
Cesium.Math.equalsEpsilon(camera.pitch, -Math.PI / 2, 1e-6),
'recovered once it stopped',
);
assert.ok(
idleSamples >= 1200 && idleSamples <= 1205,
`gave up ${idleSamples} samples after it stopped`,
);
const disposed = fakeTimers();
const other = realCamera({ width: 1225, height: 923 });
const dispose = installGlobeInViewRecovery(other.viewer, disposed);
aim(other.camera, reportedStuckView);
other.camera.moveStart.raiseEvent();
dispose();
assert.equal(disposed.pending(), 0, 'dispose cancels the pending check');
});
+181
View File
@@ -0,0 +1,181 @@
/**
* @module app/globeInViewRecovery
* @description Turns the camera back to the planet when a move ends looking
* away from it, through the renderer's camera and frame ports.
*/
import { PI_OVER_TWO } from '../geo/vector.js';
import {
FREE_LOOK_MAX_HEIGHT_METERS,
globeOutOfFrame,
isFreeGlobeCamera,
} from '../globeInView.js';
import { canvasOf, findCamera, findFrame } from '../render/rendererOf.js';
/** Whether two vectors agree to `tolerance` in every component. */
const within = (a, b, tolerance) =>
Math.abs(a.x - b.x) <= tolerance &&
Math.abs(a.y - b.y) <= tolerance &&
Math.abs(a.z - b.z) <= tolerance;
// How often a moving camera is sampled to see whether it has come to rest, how
// far a pose may drift between samples and still count as at rest, and how
// long after the camera last moved the check gives up if the camera never
// raises moveEnd.
const SETTLE_SAMPLE_MS = 250;
const SETTLE_POSITION_TOLERANCE_M = 1e-3;
const SETTLE_DIRECTION_TOLERANCE = 1e-9;
const SETTLE_GIVE_UP_MS = 5 * 60_000;
/**
* Turn the camera back to the planet when a move ends above `minHeight` with
* no surface on screen (`globeOutOfFrame`: limb glow and slivers up to about
* one sample cell thick can count as none), and return the disposer. Views with
* more surface, such as an oblique orbital shot, are left as they are. This
* catches a saved or shared view that looked away, or any other move that ends
* looking away from the planet.
* Heading and position are kept. Following cameras, locked ones (a target's
* frame), a camera flight in progress, a pointer held down on the canvas
* (a drag held still), and any time `paused`
* returns true (an authored scene playing) are left alone; a check they defer
* runs once they end, however long they last.
* `keyholeRadius`
* returns the radius of the visible circle when a scope mask hides the rest of
* the frame (see `globeFrameShare`), or 0; it is read at every check.
*
* The camera's `moveEnd` alone is not enough: the default renderer compares
* the camera with the last frame's to the last rounding error, and at some of
* these poses the camera drifts by a rounding error every frame, so it never
* sees it stop.
* So each `moveStart` also starts a check of its own that samples the pose
* every 250 ms, with a tolerance for that drift, and once the pose has held
* for half a second after moving runs the same recovery. It keeps watching
* until the camera raises `moveEnd`, since under that drift it raises no new
* `moveStart` for a later move, and gives up five minutes after the camera
* last moved.
* `setTimeout` and `clearTimeout` can be injected for tests.
*/
export function installGlobeInViewRecovery(
viewer,
{
minHeight = FREE_LOOK_MAX_HEIGHT_METERS,
keyholeRadius = () => 0,
paused = () => false,
setTimeout: schedule = globalThis.setTimeout,
clearTimeout: unschedule = globalThis.clearTimeout,
} = {},
) {
const camera = findCamera(viewer);
if (!camera) throw new TypeError('A viewer with a camera is required');
// A pointer held on the globe is a gesture in progress, even when it holds
// still for half a second: the check waits until every pointer pressed on
// it (each finger of a pinch) is released. A release the page never sees,
// outside the window, is taken as given when the window loses focus, the
// page is hidden, the canvas loses the pointer's capture, or the pointer
// moves with no button down.
const canvas = canvasOf(viewer);
const releaseTarget = canvas?.ownerDocument ?? canvas;
const releaseWindow = canvas?.ownerDocument?.defaultView;
const heldPointers = new Set();
const onPointerDown = (event) => heldPointers.add(event?.pointerId);
const onPointerUp = (event) => heldPointers.delete(event?.pointerId);
const onPointerMove = (event) => {
if (event?.buttons === 0) heldPointers.delete(event.pointerId);
};
const releaseAll = () => heldPointers.clear();
const onVisibilityChange = () => {
if (canvas.ownerDocument.visibilityState === 'hidden') releaseAll();
};
const listeners = [
[canvas, 'pointerdown', onPointerDown],
[canvas, 'lostpointercapture', onPointerUp],
[releaseTarget, 'pointerup', onPointerUp],
[releaseTarget, 'pointercancel', onPointerUp],
[releaseTarget, 'pointermove', onPointerMove],
[canvas?.ownerDocument, 'visibilitychange', onVisibilityChange],
[releaseWindow, 'blur', releaseAll],
];
for (const [target, type, listener] of listeners)
target?.addEventListener?.(type, listener);
// Returns false while a flight, a paused scene or a held pointer defers the
// check, so the caller can try again once it ends.
const recover = () => {
if (!isFreeGlobeCamera(viewer)) return true;
if (camera.flying || paused() || heldPointers.size > 0) return false;
const pose = camera.pose();
if (
!(pose.height > minHeight) ||
!globeOutOfFrame(pose, { keyholeRadius: keyholeRadius() })
)
return true;
camera.setView({
orientation: { heading: pose.heading, pitch: -PI_OVER_TWO, roll: 0 },
});
findFrame(viewer)?.requestRender?.('globe-in-view');
return true;
};
let lastPosition = null;
let lastDirection = null;
const remember = () => {
({ position: lastPosition, direction: lastDirection } = camera.pose());
};
let settleTimer = null;
let settleElapsed = 0;
let restingSamples = 0;
let movedSinceCheck = false;
const stopSettling = () => {
if (settleTimer !== null) unschedule(settleTimer);
settleTimer = null;
};
const sample = () => {
settleTimer = null;
settleElapsed += SETTLE_SAMPLE_MS;
const now = camera.pose();
const atRest =
within(now.position, lastPosition, SETTLE_POSITION_TOLERANCE_M) &&
within(now.direction, lastDirection, SETTLE_DIRECTION_TOLERANCE);
restingSamples = atRest ? restingSamples + 1 : 0;
if (!atRest) {
movedSinceCheck = true;
settleElapsed = 0;
}
// Two quiet samples in a row after a move: at rest for half a second, as
// for moveEnd.
if (restingSamples >= 2 && movedSinceCheck) {
if (recover()) movedSinceCheck = false;
// A flight or a playing scene bounds its own deferral.
else settleElapsed = 0;
}
if (settleElapsed >= SETTLE_GIVE_UP_MS) return;
remember();
settleTimer = schedule(sample, SETTLE_SAMPLE_MS);
};
const startSettling = () => {
stopSettling();
settleElapsed = 0;
restingSamples = 0;
movedSinceCheck = true;
remember();
settleTimer = schedule(sample, SETTLE_SAMPLE_MS);
};
const removeMoveEnd = camera.on('moveEnd', () => {
if (recover()) stopSettling();
// Deferred: keep sampling so the check runs once the flight or scene ends.
else if (settleTimer === null) startSettling();
});
const removeMoveStart = camera.on('moveStart', startSettling);
let active = true;
return () => {
if (!active) return;
active = false;
stopSettling();
removeMoveEnd();
removeMoveStart();
for (const [target, type, listener] of listeners)
target?.removeEventListener?.(type, listener);
heldPointers.clear();
};
}
+6 -1
View File
@@ -21,6 +21,7 @@ import {
governorRequestRender, governorRequestRender,
} from '../renderGovernor.js'; } from '../renderGovernor.js';
import { describeError } from './errors.js'; import { describeError } from './errors.js';
import { FREE_LOOK_MAX_HEIGHT_METERS } from '../globeInView.js';
import { onLocaleChange, t } from '../i18n/index.js'; import { onLocaleChange, t } from '../i18n/index.js';
/** /**
@@ -92,6 +93,10 @@ export async function createApplicationScene({
defer(() => input.destroy()); defer(() => input.destroy());
// Ctrl+wheel and trackpad pinches zoom the globe, not the page. // Ctrl+wheel and trackpad pinches zoom the globe, not the page.
renderer.input.ctrlWheelZoom = true; renderer.input.ctrlWheelZoom = true;
// What the adapter hands the application about its viewer; free look is
// limited to low heights from the start.
const viewerHooks = applicationViewerHooks(viewer);
defer(viewerHooks.installFreeLookHeightLimit(FREE_LOOK_MAX_HEIGHT_METERS));
registerDataCredits(viewer, credits); registerDataCredits(viewer, credits);
configureCreditKeyboardAccess(document); configureCreditKeyboardAccess(document);
defer(onLocaleChange(() => configureCreditKeyboardAccess(document))); defer(onLocaleChange(() => configureCreditKeyboardAccess(document)));
@@ -168,6 +173,6 @@ export async function createApplicationScene({
// Trims stale draw commands, keeps an inline panel drawing, says // Trims stale draw commands, keeps an inline panel drawing, says
// whether an entity is the viewer's own, and installs the zoom-out // whether an entity is the viewer's own, and installs the zoom-out
// guard (render/cesium/application.js). // guard (render/cesium/application.js).
...applicationViewerHooks(viewer), ...viewerHooks,
}; };
} }
+15 -1
View File
@@ -9,7 +9,13 @@ import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
import { createRecentImageryPanel } from '../ui/recentImagery.js'; import { createRecentImageryPanel } from '../ui/recentImagery.js';
import { initGevVoiceCommands } from '../voice/gevRealtime.js'; import { initGevVoiceCommands } from '../voice/gevRealtime.js';
import { installViews, isEmbeddedInline } from './embed.js'; import { installViews, isEmbeddedInline } from './embed.js';
import { installScopeMask, destroyScopeMask } from '../scopeMask.js'; import {
installScopeMask,
destroyScopeMask,
isScopeMaskEnabled,
} from '../scopeMask.js';
import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
import { installGlobeInViewRecovery } from './globeInViewRecovery.js';
import { installLayerReleaseTrim } from '../sceneCommandRelease.js'; import { installLayerReleaseTrim } from '../sceneCommandRelease.js';
import { import {
getRenderGovernorDiagnostics, getRenderGovernorDiagnostics,
@@ -50,6 +56,14 @@ export function createApplicationTools({
.get('bhote-koshi-2026') .get('bhote-koshi-2026')
?.module.attachSceneController(sceneDirector); ?.module.attachSceneController(sceneDirector);
defer(() => sceneDirector.destroy()); defer(() => sceneDirector.destroy());
defer(
installGlobeInViewRecovery(viewer, {
// The scope mask hides everything outside its keyhole.
keyholeRadius: () => (isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0),
// An authored scene frames its own shots, holds included.
paused: () => sceneDirector.running,
}),
);
onSceneDirector?.(sceneDirector); onSceneDirector?.(sceneDirector);
const annotations = initAnnotations({ const annotations = initAnnotations({
viewer, viewer,
+661
View File
@@ -18,8 +18,29 @@ import {
moveCamera, moveCamera,
} from './cameraVerbs.js'; } from './cameraVerbs.js';
import { getRenderGovernorDiagnostics } from './renderGovernor.js'; import { getRenderGovernorDiagnostics } from './renderGovernor.js';
import { MIN_GLOBE_FRAME_SHARE } from './globeInView.js';
import * as globeInView from './globeInView.js';
// The frame measures take a camera pose; these read it off the real camera.
const framePose = (camera) => ({
position: camera.positionWC,
direction: camera.directionWC,
up: camera.upWC,
right: camera.rightWC,
fovy: camera.frustum.fovy,
aspectRatio: camera.frustum.aspectRatio,
height: camera.positionCartographic.height,
pitch: camera.pitch,
});
const globeFrameShare = (camera, options) =>
globeInView.globeFrameShare(framePose(camera), options);
const globeOutOfFrame = (camera, options) =>
globeInView.globeOutOfFrame(framePose(camera), options);
import { KEYHOLE_OUTER_RADIUS } from './celestialRing.js';
import { setScopeMaskEnabled } from './scopeMask.js';
const radians = Cesium.Math.toRadians; const radians = Cesium.Math.toRadians;
const degrees = Cesium.Math.toDegrees;
const clone = (value) => Cesium.Cartesian3.clone(value); const clone = (value) => Cesium.Cartesian3.clone(value);
const longitude = (camera) => const longitude = (camera) =>
Cesium.Cartographic.fromCartesian(camera.positionWC).longitude; Cesium.Cartographic.fromCartesian(camera.positionWC).longitude;
@@ -1266,3 +1287,643 @@ test('close-up ultrawide refusal does not offer an unfit reset or move the camer
samePose(h.camera, before); samePose(h.camera, before);
assert.equal(hasRenderHold(), false); assert.equal(hasRenderHold(), false);
}); });
/**
* An oracle independent of the code under test: the share of an 80×45 grid of
* Cesium pick rays across the canvas that hit the ellipsoid surface. With
* `keyhole`, only the pixels inside the scope's visible circle count.
*/
function surfacePixelShare(camera, width, height, { keyhole = false } = {}) {
const radius = (KEYHOLE_OUTER_RADIUS * height) / 2;
let hits = 0;
let counted = 0;
for (let row = 0; row < 45; row += 1) {
for (let column = 0; column < 80; column += 1) {
const x = ((column + 0.5) * width) / 80;
const y = ((row + 0.5) * height) / 45;
if (keyhole && Math.hypot(x - width / 2, y - height / 2) > radius)
continue;
counted += 1;
const ray = camera.getPickRay(new Cesium.Cartesian2(x, y));
if (Cesium.IntersectionTests.rayEllipsoid(ray, Cesium.Ellipsoid.WGS84))
hits += 1;
}
}
return hits / counted;
}
/** Run a test with the scope mask on or off, restoring the default after. */
function withScope(t, enabled) {
setScopeMaskEnabled(enabled);
t.after(() => setScopeMaskEnabled(true));
}
// The frame limit is measured on a coarser grid than the oracle.
const SHARE_SLACK = 0.02;
// Far-out poses, height in metres and pitch in degrees, where a few tilts up
// are accepted before the limit refuses the next one.
const FAR_OUT_POSES = [
[35_884_000, -86.26],
[35_884_000, -89],
[30_000_000, -86],
[25_000_000, -80],
[40_000_000, -88],
];
test('voice tilt from orbit stops with the planet still on screen and then says so', (t) => {
withScope(t, false); // the whole frame is visible
// Slightly off nadir: from straight down a tilt is clamped before it moves.
const { camera, finishOnce } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
const results = [];
for (let i = 0; i < 4; i += 1) {
const result = moveCamera({
motion: 'tilt',
direction: 'up',
mode: 'once',
});
results.push(result);
if (result.ok) finishOnce();
assert.ok(
surfacePixelShare(camera, 1600, 900) >=
MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
`after tilt ${i + 1}`,
);
}
// From 18,000 km a 16:9 frame keeps a tenth of its area on the planet down
// to about -67°: the first tilt stops there, and later ones are refused.
assert.deepEqual(
results.map((result) => result.ok),
[true, false, false, false],
);
assert.match(results[1].error, /globe out of view/);
assert.ok(camera.pitch > radians(-68.5) && camera.pitch < radians(-66));
});
// The frame limit judges a tilt by the way its pitch moves, not by the
// direction word: a tilt down or to a steeper angle turns toward the planet.
for (const args of [{ direction: 'down' }, { pitchDeg: -80 }]) {
test(`a tilt ${JSON.stringify(args)} from the frame limit is judged as the look down it is`, (t) => {
withScope(t, false);
const { camera, finishOnce } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
finishOnce();
const atLimit = camera.pitch;
const result = moveCamera({ motion: 'tilt', ...args });
assert.equal(result.ok, true, result.error);
finishOnce();
assert.ok(camera.pitch < atLimit - radians(5), 'the tilt turned down');
});
}
for (const args of [{ pitchDeg: -10 }, {}]) {
test(`a tilt ${JSON.stringify(args)} up from the frame limit is refused, not reported as done`, (t) => {
withScope(t, false);
const { camera, finishOnce } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
finishOnce();
const atLimit = camera.pitch;
// A bare tilt means -45°: up from the -67° limit.
const result = moveCamera({ motion: 'tilt', ...args });
assert.equal(result.ok, false);
assert.match(result.error, /globe out of view/);
assert.equal(camera.pitch, atLimit);
});
}
// A tilt to an angle, or a bare tilt (-45°), from orbit turns in place like
// a nudge and must keep the planet in frame the whole way, or the globe
// recovery would snap the view back down.
for (const [label, args, options] of [
['a bare tilt', { motion: 'tilt' }, { pitch: -90 }],
['a tilt to -10°', { motion: 'tilt', pitchDeg: -10 }, { pitch: -90 }],
[
'a continuous tilt up',
{ motion: 'tilt', direction: 'up', mode: 'continuous' },
{ pitch: -90 },
],
[
'a tilt to -5° from 2,000 km',
{ motion: 'tilt', pitchDeg: -5 },
{ pitch: -90, height: 2_000_000 },
],
]) {
test(`${label} from top-down never turns the planet out of frame`, (t) => {
withScope(t, false);
const { camera, tick } = harness(t, {
...options,
viewportWidth: 1600,
viewportHeight: 900,
});
const startPitch = camera.pitch;
const result = moveCamera(args);
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
tick();
assert.ok(
surfacePixelShare(camera, 1600, 900) >=
MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
`frame ${i}: the planet left the frame`,
);
}
assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
assert.equal(globeOutOfFrame(camera), false, 'no snap-back');
if (result.ok) assert.ok(camera.pitch > startPitch, 'the tilt moved');
});
}
// The frame limit stops a tilt to an angle short of it: the reply names the
// angle the camera reaches, not the one asked for (a tilt to -10° from
// top-down reported -10° and ended at -66.5°).
for (const [label, args, options] of [
['a bare tilt', { motion: 'tilt' }, { pitch: -90 }],
['a tilt to -10°', { motion: 'tilt', pitchDeg: -10 }, { pitch: -90 }],
[
'a tilt to -10° from -80°',
{ motion: 'tilt', pitchDeg: -10 },
{ pitch: -80 },
],
[
'a tilt to -5° from 2,000 km',
{ motion: 'tilt', pitchDeg: -5 },
{ pitch: -90, height: 2_000_000 },
],
// A rolled camera's look turns its pitch by less than the look angle:
// reported -25°, ended at -27.3°.
[
'a tilt to -5° from 2,000 km rolled 30°',
{ motion: 'tilt', pitchDeg: -5 },
{ pitch: -70, roll: 30, height: 2_000_000 },
],
]) {
test(`${label} from orbit reports the angle it reaches`, (t) => {
withScope(t, false);
const { camera, tick } = harness(t, {
...options,
viewportWidth: 1600,
viewportHeight: 900,
});
const result = moveCamera(args);
assert.equal(result.ok, true, result.error);
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
const reached = degrees(camera.pitch);
assert.ok(
Math.abs(reached - result.pitchDeg) < 1,
`reported ${result.pitchDeg}°, reached ${reached}°`,
);
const asked = args.pitchDeg ?? -45;
if (Math.abs(reached - asked) >= 1)
assert.match(result.note ?? '', /globe out of view/);
else assert.equal(result.note, undefined);
});
}
// A continuous tilt promises no angle: it runs until stopped or the frame
// limit ends it.
test('a continuous tilt up from orbit claims no angle it may not reach', (t) => {
withScope(t, false);
const { tick } = harness(t, {
pitch: -90,
viewportWidth: 1600,
viewportHeight: 900,
});
const result = moveCamera({
motion: 'tilt',
direction: 'up',
mode: 'continuous',
});
assert.equal(result.ok, true, result.error);
assert.equal('pitchDeg' in result, false);
assert.equal(result.mode, 'continuous');
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
assert.equal(getActiveCameraMotion(), null, 'the frame limit ends it');
});
test('voice turn in place from orbit stops with the planet still on screen', (t) => {
withScope(t, false); // the whole frame is visible
const { camera, tick } = harness(t, { pitch: -75 });
assert.equal(
moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' }).ok,
true,
);
const heading = camera.heading;
for (let i = 0; i < 400 && getActiveCameraMotion(); i += 1) {
tick();
assert.ok(
surfacePixelShare(camera, 1280, 800) >=
MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
`tick ${i + 1}`,
);
}
assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
assert.notEqual(camera.heading, heading, 'the turn moved before stopping');
});
test('a long voice turn below the limit keeps the share it started with', (t) => {
withScope(t, false); // the whole frame is visible
// About 2% of a 16:9 frame on the planet: the limit is that share, less two
// grid cells of sampling noise, for the whole motion rather than per step.
const { camera, tick } = harness(t, {
pitch: -60,
viewportWidth: 1600,
viewportHeight: 900,
});
const start = globeFrameShare(camera);
assert.ok(start > 0 && start < MIN_GLOBE_FRAME_SHARE);
assert.equal(
moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' }).ok,
true,
);
for (let i = 0; i < 400 && getActiveCameraMotion(); i += 1) {
tick();
assert.ok(
globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9,
`tick ${i + 1}`,
);
}
assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
});
test('repeated voice turns from one spot cannot each take a little more', (t) => {
withScope(t, false); // the whole frame is visible
// About 2% of a 16:9 frame on the planet. Every turn from this position is
// measured against the same baseline, so asking again stops being allowed.
const { camera, finishOnce, tick } = harness(t, {
pitch: -60,
viewportWidth: 1600,
viewportHeight: 900,
});
const start = globeFrameShare(camera);
const floor = start - 2 / (32 * 18) - 1e-9;
const results = [];
for (const mode of ['once', 'once', 'continuous', 'once', 'continuous']) {
for (let i = 0; i < 4; i += 1) {
const result = moveCamera({ motion: 'rotate', direction: 'left', mode });
results.push(result.ok);
if (!result.ok) continue;
if (mode === 'once') finishOnce();
else for (let j = 0; j < 400 && getActiveCameraMotion(); j += 1) tick();
assert.ok(globeFrameShare(camera) >= floor, `${mode} turn ${i + 1}`);
}
}
assert.ok(results.includes(false), 'a turn at the limit is refused');
assert.equal(results.at(-1), false);
assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
});
test('a voice turn after something else turned the camera starts over', (t) => {
withScope(t, false); // the whole frame is visible
// The same spot, first framed straight down, then turned to about 2% of the
// frame by something other than voice: a turn left is measured from there.
const { camera, finishOnce } = harness(t, {
pitch: -90,
viewportWidth: 1600,
viewportHeight: 900,
});
assert.equal(
moveCamera({ motion: 'rotate', direction: 'left', mode: 'once' }).ok,
true,
);
finishOnce();
camera.setView({
orientation: { heading: 0, pitch: radians(-60), roll: 0 },
});
const start = globeFrameShare(camera);
assert.ok(start > 0 && start < MIN_GLOBE_FRAME_SHARE);
assert.equal(
moveCamera({ motion: 'rotate', direction: 'left', mode: 'once' }).ok,
true,
);
finishOnce();
assert.ok(globeFrameShare(camera) >= start - 2 / (32 * 18) - 1e-9);
});
test('nudging the camera between voice turns cannot take the planet below the 1% floor', (t) => {
withScope(t, false); // the whole frame is visible
// A wheel notch or an orbit drag between requests starts each turn afresh;
// the 1% floor still holds, and below it a turn may only keep what it has.
for (const [nudge, pitch] of [
[(camera) => camera.moveBackward(2), -60],
[(camera) => camera.rotateRight(radians(0.2)), -60],
[(camera) => camera.moveBackward(2), -58],
]) {
const { camera, tick } = harness(t, {
pitch,
viewportWidth: 1600,
viewportHeight: 900,
});
const start = globeFrameShare(camera);
const floor = Math.min(0.01, start) - 1e-9;
for (let i = 0; i < 12; i += 1) {
nudge(camera);
if (
moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' })
.ok
)
for (let j = 0; j < 400 && getActiveCameraMotion(); j += 1) tick();
assert.ok(
globeFrameShare(camera) >= floor,
`start ${start}, turn ${i + 1}`,
);
}
assert.ok(surfacePixelShare(camera, 1600, 900) > 0);
}
});
test('after the frame changes size, a voice turn toward the planet is allowed', (t) => {
withScope(t, false); // the whole frame is visible
// A tilt stops at its limit; then the window widens at the same pose, so the
// frame shows less than the carried limit. Toward the planet must still go.
const { camera, canvas, viewer, finishOnce } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
assert.equal(
moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok,
true,
);
finishOnce();
canvas.clientWidth = canvas.width = viewer.scene.drawingBufferWidth = 3200;
camera.frustum.aspectRatio = 3200 / 900;
const narrowed = globeFrameShare(camera);
assert.ok(narrowed < MIN_GLOBE_FRAME_SHARE, `frame now shows ${narrowed}`);
const down = moveCamera({ motion: 'tilt', direction: 'down', mode: 'once' });
assert.equal(down.ok, true, down.error);
finishOnce();
assert.ok(globeFrameShare(camera) > narrowed);
assert.equal(
moveCamera({ motion: 'tilt', direction: 'down', mode: 'once' }).ok,
true,
);
finishOnce();
const up = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
if (up.ok) finishOnce();
assert.ok(surfacePixelShare(camera, 3200, 900) > 0);
});
test('with the scope on, a voice tilt stops while the keyhole still shows the planet', (t) => {
withScope(t, true);
const { camera, finishOnce } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
const results = [];
for (let i = 0; i < 4; i += 1) {
const result = moveCamera({
motion: 'tilt',
direction: 'up',
mode: 'once',
});
results.push(result.ok);
if (result.ok) finishOnce();
assert.ok(
surfacePixelShare(camera, 1600, 900, { keyhole: true }) >=
MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
`after tilt ${i + 1}`,
);
}
assert.equal(results[0], true);
assert.equal(results.at(-1), false, 'a tilt past the limit is refused');
});
test('with the scope on, a voice turn cannot leave the planet only in the masked corners', (t) => {
// An oblique orbit view: turning in place swings the planet toward a corner,
// where the full frame still shows it but the scope mask hides it.
for (const [height, pitch] of [
[5_000_000, -70],
[3_000_000, -75],
[18_000_000, -80],
]) {
withScope(t, true);
const { camera, tick } = harness(t, {
height,
pitch,
viewportWidth: 1600,
viewportHeight: 900,
});
assert.equal(
moveCamera({ motion: 'rotate', direction: 'left', mode: 'continuous' })
.ok,
true,
);
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
assert.equal(getActiveCameraMotion(), null, 'the turn stops at the limit');
assert.ok(
surfacePixelShare(camera, 1600, 900, { keyhole: true }) >=
MIN_GLOBE_FRAME_SHARE - SHARE_SLACK,
`${height / 1000} km at ${pitch}°`,
);
}
});
test('far out, a voice tilt is either refused or really moves, at display frame rates', (t) => {
// A small planet disc: its sampled share wobbles as it crosses the grid.
// Whatever the limit decides, "done" must mean the camera turned, and some
// of these tilts must be accepted for that to be checked at all.
let accepted = 0;
for (const [height, pitch] of FAR_OUT_POSES) {
withScope(t, true);
const { camera, tick } = harness(t, {
latitude: 45.37,
longitudeDeg: -33.33,
height,
heading: 89.9,
pitch,
viewportWidth: 1280,
viewportHeight: 1024,
});
for (let i = 0; i < 4; i += 1) {
const before = camera.pitch;
const result = moveCamera({
motion: 'tilt',
direction: 'up',
mode: 'once',
});
if (!result.ok) {
assert.match(result.error, /zoom in first/);
continue;
}
accepted += 1;
for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
assert.ok(
camera.pitch - before > radians(0.5) - 1e-9,
`${height / 1000} km at ${pitch}°: tilt ${i + 1} reported done but moved ${Cesium.Math.toDegrees(camera.pitch - before)}°`,
);
}
assert.ok(surfacePixelShare(camera, 1280, 1024, { keyhole: true }) > 0);
}
assert.ok(accepted > 0, 'no far-out tilt was accepted');
});
test('a voice turn reported as done turns at least the half degree its check proved', (t) => {
// A grazing sliver: the first frame's small step lands in a dip of the
// sampled share, which used to stop the turn before it moved at all.
for (const scope of [true, false]) {
withScope(t, scope);
const { camera, tick } = harness(t, {
latitude: 20,
longitudeDeg: 10,
height: 18_000_000,
pitch: -58,
heading: 37,
viewportWidth: 1600,
viewportHeight: 900,
});
const before = Cesium.Cartesian3.clone(camera.directionWC);
const result = moveCamera({
motion: 'rotate',
direction: 'left',
mode: 'once',
});
if (!result.ok) {
assert.match(result.error, /globe out of view/);
continue;
}
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(1 / 60);
const turned = Cesium.Cartesian3.angleBetween(before, camera.directionWC);
assert.ok(
turned >= radians(0.5) - 1e-9,
`scope ${scope ? 'on' : 'off'}: turned ${Cesium.Math.toDegrees(turned)}°`,
);
assert.ok(surfacePixelShare(camera, 1600, 900, { keyhole: scope }) > 0);
}
});
/** Track an entity below `camera`, locking it into that entity's frame. */
function trackFrom(viewer, camera) {
viewer.trackedEntity = { id: 'high-satellite' };
const below = Cesium.Cartesian3.fromDegrees(10, 20, 400_000);
camera.lookAtTransform(Cesium.Transforms.eastNorthUpToFixedFrame(below));
}
test('a voice turn that releases a tracked camera is checked as released', (t) => {
// Voice releases the follow camera inside the navigation that runs the
// motion, so the request is judged by the pose the release will leave.
let accepted = 0;
for (const [scope, direction, motion] of [
[true, 'up', 'tilt'],
[false, 'up', 'tilt'],
[false, 'left', 'rotate'],
]) {
withScope(t, scope);
const { camera, viewer, tick } = harness(t, {
latitude: 20,
longitudeDeg: 10,
height: 18_000_000,
pitch: -58,
heading: 37,
viewportWidth: 1600,
viewportHeight: 900,
});
trackFrom(viewer, camera);
const releaseThenRun = (start) => {
viewer.trackedEntity = undefined;
camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
return start();
};
const before = Cesium.Cartesian3.clone(camera.directionWC);
const result = moveCamera(
{ motion, direction, mode: 'once' },
releaseThenRun,
);
const label = `${motion} ${direction}, scope ${scope ? 'on' : 'off'}`;
if (!result.ok) {
assert.match(result.error, /globe out of view/, label);
continue;
}
accepted += 1;
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick(1 / 60);
const turned = Cesium.Cartesian3.angleBetween(before, camera.directionWC);
assert.ok(turned >= radians(0.5) - 1e-9, `${label}: turned ${turned}`);
assert.ok(
surfacePixelShare(camera, 1600, 900, { keyhole: scope }) > 0,
`${label}: the planet stays on screen`,
);
}
assert.ok(accepted > 0, 'no released turn was accepted');
});
test('a refused voice turn leaves a tracked camera tracking', (t) => {
for (const scope of [true, false]) {
withScope(t, scope);
const { camera, viewer, tick } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
// Tilt up to the limit untracked, then track from there.
for (let i = 0; i < 40; i += 1) {
if (!moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok)
break;
for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
}
trackFrom(viewer, camera);
const tracked = viewer.trackedEntity;
const transform = Cesium.Matrix4.clone(camera.transform);
let released = false;
const result = moveCamera(
{ motion: 'tilt', direction: 'up', mode: 'once' },
(start) => {
released = true;
viewer.trackedEntity = undefined;
camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
return start();
},
);
const label = `scope ${scope ? 'on' : 'off'}`;
assert.equal(result.ok, false, label);
assert.match(result.error, /globe out of view/, label);
assert.equal(released, false, label);
assert.equal(viewer.trackedEntity, tracked, label);
assert.ok(Cesium.Matrix4.equals(camera.transform, transform), label);
}
});
test('a turn proven at one position is checked again after a release moves the camera', (t) => {
withScope(t, false);
const { camera, tick } = harness(t, {
pitch: -80,
viewportWidth: 1600,
viewportHeight: 900,
});
// Tilt up to the limit, then check from 4,000 km closer along the same view
// direction, where the next tilt fits; the release moves the camera back.
for (let i = 0; i < 40; i += 1) {
if (!moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' }).ok)
break;
for (let j = 0; j < 600 && getActiveCameraMotion(); j += 1) tick(1 / 60);
}
camera.moveForward(4_000_000);
const result = moveCamera(
{ motion: 'tilt', direction: 'up', mode: 'once' },
(start) => {
camera.moveBackward(4_000_000);
return start();
},
);
assert.equal(result.ok, false);
assert.match(result.error, /globe out of view/);
});
test('voice tilt below the free-look height is not limited by the frame', (t) => {
const { camera, finishOnce } = harness(t, { height: 500_000, pitch: -60 });
const result = moveCamera({ motion: 'tilt', direction: 'up', mode: 'once' });
assert.equal(result.ok, true);
finishOnce();
near(camera.pitch, radians(-45), 1e-6, 'full 15° tilt');
});
+10 -1
View File
@@ -223,11 +223,20 @@ test('validated voice camera destinations share the UI navigation authority faca
'move camera', 'move camera',
); );
ordered(move, [ ordered(move, [
"if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))", 'if (argsError) return argsError;',
'const start = () => {', 'const start = () => {',
/const preserveCameraFlight =\s*motion === 'orbit'/, /const preserveCameraFlight =\s*motion === 'orbit'/,
'runNavigation(start, { preserveCameraFlight })', 'runNavigation(start, { preserveCameraFlight })',
], 'move validation before handoff'); ], 'move validation before handoff');
const moveArgs = body(
cameraVerbs,
/export function moveCameraArgsError\(args = \{\}\) \{([\s\S]*?)\n\}/,
'move camera argument checks',
);
assert.ok(
moveArgs.includes("if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion))"),
'unknown motions are refused before handoff',
);
const route = body( const route = body(
cameraVerbs, cameraVerbs,
+785
View File
@@ -0,0 +1,785 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as Cesium from 'cesium';
import {
adjustOrbitRange,
getActiveCameraMotion,
initCameraVerbs,
interruptCameraMotion,
moveCamera,
} from './cameraVerbs.js';
import { createGevActionRunner } from './voice/gevActions.js';
import { bindFakeCesiumCamera } from './testSupport/fakeCameraPort.mjs';
import {
fakeSceneFrame,
fakeSceneQuery,
} from './testSupport/fakeCesiumScene.mjs';
const radians = Cesium.Math.toRadians;
const degrees = Cesium.Math.toDegrees;
/** Real Cesium camera over London with no renderer: the voice fly-to frame. */
function harness(
t,
{ height = 4000, heading = 0, pitch = -90, pivot = true } = {},
) {
const realPerformance = globalThis.performance;
let nowMs = 0;
globalThis.performance = { now: () => nowMs };
const canvas = Object.assign(new EventTarget(), {
clientWidth: 1280,
clientHeight: 800,
width: 1280,
height: 800,
});
const ellipsoid = Cesium.Ellipsoid.WGS84;
const scene = {
canvas,
drawingBufferWidth: 1280,
drawingBufferHeight: 800,
frameState: { mode: Cesium.SceneMode.SCENE3D },
mapProjection: new Cesium.GeographicProjection(ellipsoid),
globe: { ellipsoid },
mapMode2D: Cesium.MapMode2D.INFINITE_SCROLL,
mode: Cesium.SceneMode.SCENE3D,
pixelRatio: 1,
tweens: [],
preUpdate: new Cesium.Event(),
requestRender() {},
};
const camera = new Cesium.Camera(scene);
scene.camera = camera;
camera.setView({
destination: Cesium.Cartesian3.fromDegrees(-0.1276, 51.5072, height),
orientation: { heading: radians(heading), pitch: radians(pitch), roll: 0 },
});
const double = {
camera,
scene,
trackedEntity: undefined,
trackedEntityChanged: new Cesium.Event(),
clock: { onTick: new Cesium.Event() },
};
// The Cesium renderer's own camera port over the real camera; frames from
// the scene's preUpdate.
const viewer = bindFakeCesiumCamera(double, {
query: fakeSceneQuery(double),
frame: fakeSceneFrame(double),
});
// The app's view target: the ground point under the screen centre.
const viewTarget = () => {
const ray = new Cesium.Ray(camera.positionWC, camera.directionWC);
const hit = Cesium.IntersectionTests.rayEllipsoid(ray, ellipsoid);
return hit ? Cesium.Ray.getPoint(ray, hit.start) : undefined;
};
const target = viewTarget();
initCameraVerbs(viewer, pivot ? viewTarget : () => undefined);
t.after(() => {
interruptCameraMotion('test-cleanup');
globalThis.performance = realPerformance;
});
const tick = (seconds = 1 / 30) => {
nowMs += seconds * 1000;
viewer.scene.preUpdate.raiseEvent(viewer.scene);
};
const finish = () => {
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) tick();
assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
};
return { viewer, camera, target, tick, finish, viewTarget };
}
const pitchDeg = (camera) => degrees(camera.pitch);
/** Tick until done() holds; a regression fails here instead of hanging. */
const tickUntil = (h, done, frames = 600) => {
for (let i = 0; i < frames && !done(); i += 1) h.tick();
assert.ok(done(), `not reached in ${frames} frames`);
};
const headingDeg = (camera) =>
degrees(Cesium.Math.negativePiToPi(camera.heading));
/** Metres between the original centre and the ground now under the crosshair. */
function centreDrift(h) {
return Cesium.Cartesian3.distance(h.viewTarget(), h.target);
}
test('tilt up leaves a top-down view and keeps the place centred', (t) => {
const h = harness(t);
const result = moveCamera({ motion: 'tilt', direction: 'up' });
assert.equal(result.ok, true);
h.finish();
assert.ok(
Math.abs(pitchDeg(h.camera) - -75) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
assert.ok(Cesium.Matrix4.equals(h.camera.transform, Cesium.Matrix4.IDENTITY));
});
test('continuous tilt up from top-down keeps moving', (t) => {
const h = harness(t);
assert.equal(
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' }).ok,
true,
);
for (let i = 0; i < 30; i += 1) h.tick();
assert.equal(getActiveCameraMotion()?.kind, 'tilt');
assert.ok(pitchDeg(h.camera) > -82, `pitch ${pitchDeg(h.camera)}`);
});
test('a requested angle tilts to that pitch', (t) => {
const h = harness(t);
const result = moveCamera({ motion: 'tilt', pitchDeg: -45 });
assert.equal(result.ok, true);
assert.equal(result.direction, 'up');
assert.equal(result.pitchDeg, -45);
h.finish();
assert.ok(
Math.abs(pitchDeg(h.camera) - -45) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
});
test('a bare tilt settles on the default oblique angle', (t) => {
const h = harness(t);
const result = moveCamera({ motion: 'tilt' });
assert.equal(result.ok, true);
assert.equal(result.pitchDeg, -45);
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
});
test('a requested angle can tilt back down toward top-down', (t) => {
const h = harness(t, { pitch: -30 });
const result = moveCamera({ motion: 'tilt', pitchDeg: -80 });
assert.equal(result.direction, 'down');
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
});
test('requested angles clamp to the tilt limits', (t) => {
const h = harness(t);
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -2 }).pitchDeg, -5);
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
});
test('a positive angle is read as the same angle below the horizon', (t) => {
const h = harness(t);
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: 45 }).pitchDeg, -45);
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
});
for (const pitch of ['', null, false, ' ', 'steep'])
test(`a blank or non-numeric angle ${JSON.stringify(pitch)} is ignored`, (t) => {
harness(t);
const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
// No angle and no direction: the default oblique view, never the horizon.
assert.equal(result.pitchDeg, -45);
});
test('a requested angle the camera already holds is a no-op', (t) => {
harness(t, { pitch: -45 });
const result = moveCamera({ motion: 'tilt', pitchDeg: -45 });
assert.equal(result.ok, true);
assert.equal(result.unchanged, true);
assert.equal(getActiveCameraMotion(), null);
});
for (const pitch of [-90, -89]) {
test(`a top-down view asked for ${pitch}° stays put`, (t) => {
// The tool description calls -89 top-down; the clamp must not tilt a
// -90° view up 1° and report it as a move up.
const h = harness(t);
const before = pitchDeg(h.camera);
const result = moveCamera({ motion: 'tilt', pitchDeg: pitch });
assert.equal(result.ok, true);
assert.equal(result.unchanged, true);
assert.equal(result.pitchDeg, Math.round(before));
assert.equal(getActiveCameraMotion(), null);
assert.equal(pitchDeg(h.camera), before);
});
}
test('tilt down from top-down still refuses honestly', (t) => {
harness(t);
const result = moveCamera({ motion: 'tilt', direction: 'down' });
assert.equal(result.ok, false);
assert.match(result.error, /straight down/);
});
test('a tilt up nudge stops at the horizon limit', (t) => {
const h = harness(t, { pitch: -12 });
assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
});
test('without a ground pivot a tilt still leaves top-down in place', (t) => {
const h = harness(t, { pivot: false });
const before = Cesium.Cartesian3.clone(h.camera.positionWC);
assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -75) < 0.5);
assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-6);
});
for (const heading of [0, 30, -120])
test(`tilt from top-down keeps the ${heading}° heading`, (t) => {
const h = harness(t, { heading, height: 67000 });
// Top-down float noise must not pick a new heading for the pivot.
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
h.finish();
assert.ok(
Math.abs(headingDeg(h.camera) - heading) < 1,
`heading ${headingDeg(h.camera)}`,
);
assert.ok(centreDrift(h) < 50, `centre drifted ${centreDrift(h)} m`);
});
test('an oblique tilt keeps its heading toward the pivot', (t) => {
const h = harness(t, { heading: 75, pitch: -60 });
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -30 }).ok, true);
h.finish();
assert.ok(Math.abs(headingDeg(h.camera) - 75) < 0.5);
assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
});
test('a pivoting tilt yields when tracking takes the camera', (t) => {
const h = harness(t);
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
h.tick();
const entity = { id: 'tracked' };
h.viewer.trackedEntity = entity;
h.viewer.trackedEntityChanged.raiseEvent(entity);
assert.equal(getActiveCameraMotion(), null);
});
/** Metres between the camera and the point it pivots about. */
const pivotRange = (h) =>
Cesium.Cartesian3.distance(h.camera.positionWC, h.target);
const heightM = (camera) =>
Cesium.Cartographic.fromCartesian(camera.positionWC).height;
test('a zoom during a pivoting tilt changes the range it holds', (t) => {
const h = harness(t);
assert.equal(
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' }).ok,
true,
);
h.tick();
const before = pivotRange(h);
assert.deepEqual(
adjustOrbitRange(0.5),
{ kind: 'tilt', changed: true },
'the tilt must take the zoom',
);
for (let i = 0; i < 5; i += 1) h.tick();
// The next frame's lookAt must not put the old range back.
assert.ok(
Math.abs(pivotRange(h) - before / 2) < 1,
`range ${pivotRange(h)} m, wanted ${before / 2} m`,
);
});
test('a zoom with no pivot to hold is left to the camera', (t) => {
harness(t, { pivot: false });
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
assert.equal(adjustOrbitRange(0.5), null);
});
test('a pivot tilt toward the horizon keeps its clearance above the ground', (t) => {
// A close top-down view: swinging 250 m of range to -5° would end ~22 m up.
const h = harness(t, { height: 250 });
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -5 }).ok, true);
let lowest = Infinity;
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
lowest = Math.min(lowest, heightM(h.camera));
}
assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
assert.ok(lowest > 149, `camera dropped to ${lowest} m`);
assert.ok(
Math.abs(pitchDeg(h.camera) - -5) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
assert.ok(Cesium.Matrix4.equals(h.camera.transform, Cesium.Matrix4.IDENTITY));
});
test('a continuous tilt up from close in keeps its clearance', (t) => {
const h = harness(t, { height: 250 });
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
}
assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
});
test('a city-scale pivot tilt keeps the place centred to the horizon limit', (t) => {
const h = harness(t);
moveCamera({ motion: 'tilt', pitchDeg: -5 });
h.finish();
// 4 km of range clears the floor at every pitch: all pivot, no drift.
assert.ok(centreDrift(h) < 5, `centre drifted ${centreDrift(h)} m`);
});
test('pitchDeg against a contradicting direction is refused', (t) => {
harness(t, { pitch: -45 });
// "tilt down 10 degrees": -10° is an absolute angle, which is up from -45°.
const result = moveCamera({
motion: 'tilt',
direction: 'down',
pitchDeg: 10,
});
assert.equal(result.ok, false);
assert.match(result.error, /absolute angle/);
assert.equal(getActiveCameraMotion(), null);
});
test('pitchDeg with a direction that agrees still tilts', (t) => {
const h = harness(t, { pitch: -45 });
const result = moveCamera({
motion: 'tilt',
direction: 'down',
pitchDeg: -80,
});
assert.equal(result.ok, true);
assert.equal(result.direction, 'down');
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -80) < 0.5);
});
test('the pitchDeg and direction check uses the camera pitch', (t) => {
// At regional range the Earth curves away and the pivot pitch is a degree
// or two shallower than the camera's (-30°); -29° is still up from it.
harness(t, { height: 150000, pitch: -30 });
const down = moveCamera({ motion: 'tilt', direction: 'down', pitchDeg: -29 });
assert.equal(down.ok, false);
assert.match(down.error, /tilts up, not down/);
const up = moveCamera({ motion: 'tilt', direction: 'up', pitchDeg: -29 });
assert.equal(up.ok, true);
assert.equal(up.direction, 'up');
});
test('after a zoom in, a pivoting tilt never lowers the camera further', (t) => {
const h = harness(t, { height: 1000 });
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
tickUntil(h, () => pitchDeg(h.camera) >= -30);
adjustOrbitRange(1 / 2.4);
adjustOrbitRange(1 / 2.4);
h.tick();
const afterZoom = heightM(h.camera);
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
assert.ok(
heightM(h.camera) > afterZoom - 1,
`camera fell from ${afterZoom} m to ${heightM(h.camera)} m`,
);
}
assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
});
test('a zoom in during a close pivot tilt never pushes the camera out', (t) => {
// 62 m of range, under the 80 m zoom floor.
const h = harness(t, { height: 40, pitch: -40 });
moveCamera({ motion: 'tilt', direction: 'down', mode: 'continuous' });
h.tick();
const before = pivotRange(h);
assert.ok(before < 80, `range ${before} m`);
adjustOrbitRange(1 / 1.6);
h.tick();
assert.ok(pivotRange(h) <= before + 0.01, `range grew to ${pivotRange(h)} m`);
});
test('a zoom out during a far orbit never pulls the camera in', (t) => {
// 15,000 km up, beyond the 5,000 km zoom cap.
const h = harness(t, { height: 15_000_000 });
assert.equal(moveCamera({ motion: 'orbit', mode: 'continuous' }).ok, true);
h.tick();
const before = pivotRange(h);
assert.ok(before > 5_000_000, `range ${before} m`);
assert.deepEqual(adjustOrbitRange(2.4), { kind: 'orbit', changed: false });
h.tick();
assert.ok(pivotRange(h) >= before - 1, `range fell to ${pivotRange(h)} m`);
});
test('an out-of-range pitchDeg is clamped to the tilt limits', (t) => {
// The schema carries no range; 120 reads as 120° below the horizon.
const h = harness(t, { pitch: -45 });
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: 120 }).ok, true);
h.finish();
assert.ok(
Math.abs(pitchDeg(h.camera) - -89) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
});
test('a zoom in during a pivot tilt stops at the clearance', (t) => {
// 400 m of range at -40°, then "zoom in a lot" twice: unfloored, that left
// the camera about 107 m up, then at the 80 m zoom floor.
const h = harness(t, { height: 400 });
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
tickUntil(h, () => pitchDeg(h.camera) >= -40);
assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: true });
// At -40° the floor is 150 / sin 40° ≈ 233 m, which the first zoom reached.
assert.deepEqual(adjustOrbitRange(1 / 2.4), { kind: 'tilt', changed: false });
// The camera must take that range, not just report it.
h.tick();
const floor = 150 / Math.sin(radians(40));
assert.ok(
Math.abs(pivotRange(h) - floor) < floor * 0.02,
`range ${pivotRange(h)} m, wanted about ${floor} m`,
);
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
}
assert.ok(Math.abs(pitchDeg(h.camera) - -5) < 0.5);
});
test('a voice zoom during a pivot tilt says what it changed', async (t) => {
const h = harness(t, { height: 400 });
const runner = createGevActionRunner({
viewer: h.viewer,
styleManager: {},
dataManager: { layers: new Map(), getAll: () => [] },
});
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
h.tick();
const zoom = { direction: 'in', amount: 'lot' };
const first = await runner('adjust_camera_zoom', zoom);
assert.equal(first.ok, true);
assert.equal(first.tiltRangeAdjusted, true);
assert.equal('orbitRadiusAdjusted' in first, false);
// 400 m → 167 m → the 150 m clearance; a third zoom in moves nothing, and
// says so.
assert.equal((await runner('adjust_camera_zoom', zoom)).ok, true);
const third = await runner('adjust_camera_zoom', zoom);
assert.equal(third.ok, false);
assert.match(third.error, /tilt is already at its closest range/);
});
test('from globe range a tilt happens in place', (t) => {
// A pivot 2,000 km out would swing the camera thousands of km.
const h = harness(t, { height: 2_000_000 });
const before = Cesium.Cartesian3.clone(h.camera.positionWC);
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -45 }).ok, true);
h.finish();
assert.ok(Math.abs(pitchDeg(h.camera) - -45) < 0.5);
assert.ok(Cesium.Cartesian3.distance(h.camera.positionWC, before) < 1e-3);
});
for (const height of [100_000, 400_000])
test(`from ${height / 1000} km a tilt to -5° ends with the camera at -5°`, (t) => {
// The pivot pitch is shallower than the camera's by up to 4° at this
// range; the camera reached only -5.9° and -8.6° when the swing stopped
// at a pivot pitch of -5°.
const h = harness(t, { height });
const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
assert.equal(result.pitchDeg, -5);
h.finish();
assert.ok(
Math.abs(pitchDeg(h.camera) - -5) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
const nudge = moveCamera({ motion: 'tilt', direction: 'up' });
assert.equal(nudge.ok, false);
assert.match(nudge.error, /upper tilt limit/);
});
// From 550 km out the camera's -5° lies beyond the place's own horizon: the
// swing ran into its clearance, let go of the pivot and tilted the rest in
// place, which put the crosshair on the sky (28 to 63 km up), and a return
// to top-down then landed 600 to 900 km from the place.
for (const height of [600_000, 700_000, 900_000]) {
test(`from ${height / 1000} km a tilt to -5° keeps the place centred`, (t) => {
const h = harness(t, { height });
const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
assert.equal(result.ok, true);
h.finish();
assert.ok(h.viewTarget(), 'the crosshair is on the sky');
assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
assert.ok(heightM(h.camera) > 149, `camera at ${heightM(h.camera)} m`);
// The reply names the angle the camera reached, not the one asked for.
assert.ok(result.pitchDeg < -5, `reported ${result.pitchDeg}°`);
assert.ok(
Math.abs(pitchDeg(h.camera) - result.pitchDeg) < 0.5,
`camera at ${pitchDeg(h.camera)}°, reported ${result.pitchDeg}°`,
);
assert.match(result.note, /horizon/);
const nudge = moveCamera({ motion: 'tilt', direction: 'up' });
assert.equal(nudge.ok, false);
assert.match(nudge.error, /upper tilt limit/);
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -89 }).ok, true);
h.finish();
assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
// Back over the place at the range it began with (-89° is ~1° off nadir).
const range = Cesium.Cartesian3.distance(h.camera.positionWC, h.target);
assert.ok(
Math.abs(range - height) < height * 0.01,
`top-down ${range} m from the place`,
);
});
test(`a continuous tilt up from ${height / 1000} km stops with the place centred`, (t) => {
const h = harness(t, { height });
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
for (let i = 0; i < 1200 && getActiveCameraMotion(); i += 1) {
h.tick();
assert.ok(h.viewTarget(), `the crosshair is on the sky at frame ${i}`);
}
assert.equal(getActiveCameraMotion(), null, 'tilt must stop at its limit');
assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
});
}
test('a pitchDeg tilt toward the horizon limit says it is already there', (t) => {
const h = harness(t, { height: 900_000 });
moveCamera({ motion: 'tilt', pitchDeg: 5 });
h.finish();
const again = moveCamera({ motion: 'tilt', pitchDeg: 5 });
assert.equal(again.ok, false);
assert.match(again.error, /upper tilt limit/);
});
test('a regional tilt-up nudge goes to the camera horizon limit', (t) => {
// 20 km up at -7°: the pivot 186 km out sits at -5.3°, but the camera can
// still tilt up 2°.
const h = harness(t, { height: 20000, pitch: -7 });
assert.equal(moveCamera({ motion: 'tilt', direction: 'up' }).ok, true);
h.finish();
assert.ok(
Math.abs(pitchDeg(h.camera) - -5) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
});
test('a voice tilt from a tracked view judges its limit from the camera pitch', (t) => {
const h = harness(t, { height: 20000, pitch: -5.2 });
h.viewer.trackedEntity = { id: 'tracked' };
// Voice releases the follow camera before the motion starts.
const release = (start) => {
h.viewer.trackedEntity = undefined;
return start();
};
const result = moveCamera({ motion: 'tilt', direction: 'up' }, release);
assert.equal(result.ok, false);
assert.match(result.error, /upper tilt limit/);
});
test('a zoom out during a pivoting tilt stops at the pivot range limit', (t) => {
// 900 km top-down, "tilt to 10°", then "zoom out a lot" twice: capped at
// the orbit's 5,000 km, the swing reached 2,386 km up at a real -44°.
const h = harness(t, { height: 900_000 });
assert.equal(moveCamera({ motion: 'tilt', pitchDeg: -10 }).ok, true);
h.tick();
assert.deepEqual(adjustOrbitRange(2.4), { kind: 'tilt', changed: true });
assert.deepEqual(adjustOrbitRange(2.4), { kind: 'tilt', changed: false });
let farthest = 0;
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
farthest = Math.max(farthest, pivotRange(h));
}
assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
assert.ok(farthest <= 1_000_001, `swung ${farthest} m from the pivot`);
assert.ok(
Math.abs(pitchDeg(h.camera) - -10) < 0.5,
`pitch ${pitchDeg(h.camera)}`,
);
});
test('an unchanged angle still stops a running motion through navigation', (t) => {
const h = harness(t);
moveCamera({ motion: 'tilt', direction: 'up', mode: 'continuous' });
tickUntil(h, () => pitchDeg(h.camera) >= -45.3);
let handoffs = 0;
const navigate = (start) => {
handoffs += 1;
return start();
};
const result = moveCamera({ motion: 'tilt', pitchDeg: -45 }, navigate);
assert.equal(result.ok, true);
assert.equal(result.unchanged, true);
assert.equal(handoffs, 1, 'the request must take navigation');
assert.equal(getActiveCameraMotion(), null, 'the tilt must stop');
const held = pitchDeg(h.camera);
for (let i = 0; i < 30; i += 1) h.tick();
assert.equal(pitchDeg(h.camera), held);
});
for (const direction of ['left', 'right'])
test(`a tilt ${direction} is refused`, (t) => {
harness(t, { pitch: -45 });
const result = moveCamera({ motion: 'tilt', direction });
assert.equal(result.ok, false);
assert.match(result.error, /tilt needs up or down/);
const angled = moveCamera({ motion: 'tilt', direction, pitchDeg: -30 });
assert.equal(angled.ok, false);
assert.match(angled.error, /pitchDeg alone/);
assert.equal(getActiveCameraMotion(), null);
});
// The 1,000 km pivot cutoff includes its boundary: at exactly 1,000 km the
// pivot range came back a hair over it, so the tilt ran in place and put the
// crosshair on the sky.
test('from exactly 1,000 km a tilt to -5° still pivots about the place', (t) => {
const h = harness(t, { height: 1_000_000 });
const result = moveCamera({ motion: 'tilt', pitchDeg: 5 });
assert.equal(result.ok, true);
h.finish();
assert.ok(h.viewTarget(), 'the crosshair is on the sky');
assert.ok(centreDrift(h) < 100, `centre drifted ${centreDrift(h)} m`);
assert.ok(
Math.abs(pitchDeg(h.camera) - result.pitchDeg) < 0.5,
`camera at ${pitchDeg(h.camera)}°, reported ${result.pitchDeg}°`,
);
assert.match(result.note, /horizon/);
});
// A zoom mid-tilt moves the pivot's horizon limit: the zoom's reply names the
// angle the tilt now ends at, and the camera ends there.
test('a zoom out during a tilt to an angle reports the angle it now ends at', (t) => {
const h = harness(t, { height: 400_000 });
const result = moveCamera({ motion: 'tilt', pitchDeg: -5 });
assert.equal(result.pitchDeg, -5);
assert.equal(result.note, undefined);
for (let i = 0; i < 10; i += 1) h.tick();
const zoom = adjustOrbitRange(2.5);
assert.equal(zoom.kind, 'tilt');
assert.equal(zoom.changed, true);
h.finish();
assert.ok(h.viewTarget(), 'the crosshair is on the sky');
assert.ok(zoom.pitchDeg < -5, `zoom reported ${zoom.pitchDeg}°`);
assert.ok(
Math.abs(pitchDeg(h.camera) - zoom.pitchDeg) < 0.5,
`camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
);
assert.match(zoom.note, /horizon/);
});
test('a zoom in during a horizon-limited tilt reports the angle it now reaches', (t) => {
const h = harness(t, { height: 900_000 });
const result = moveCamera({ motion: 'tilt', pitchDeg: -5 });
assert.ok(result.pitchDeg < -5, `reported ${result.pitchDeg}°`);
for (let i = 0; i < 10; i += 1) h.tick();
const zoom = adjustOrbitRange(1 / 2.4);
assert.equal(zoom.changed, true);
h.finish();
assert.equal(zoom.pitchDeg, -5);
assert.ok(
Math.abs(pitchDeg(h.camera) - -5) < 0.5,
`camera at ${pitchDeg(h.camera)}°`,
);
});
test('a voice zoom during a tilt to an angle passes on the new end angle', async (t) => {
const h = harness(t, { height: 400_000 });
const runner = createGevActionRunner({
viewer: h.viewer,
styleManager: {},
dataManager: { layers: new Map(), getAll: () => [] },
});
moveCamera({ motion: 'tilt', pitchDeg: -5 });
for (let i = 0; i < 10; i += 1) h.tick();
const zoom = await runner('adjust_camera_zoom', {
direction: 'out',
amount: 'lot',
});
assert.equal(zoom.ok, true);
assert.equal(zoom.tiltRangeAdjusted, true);
h.finish();
assert.ok(
Math.abs(pitchDeg(h.camera) - zoom.pitchDeg) < 0.5,
`camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
);
assert.match(zoom.note, /horizon/);
});
// Late in the tilt the camera is already past the angle the new range's
// horizon allows (from 400 km at -8°, a zoom out x2.5 reported -8°): past it
// the place is behind the Earth, so the camera steps down to that limit with
// the zoom, then holds it with no further jump, and the zoom's reply names
// the angle it ends at, not the one it stood at.
test('a late zoom out during a tilt steps to the new limit and reports it', (t) => {
const h = harness(t, { height: 400_000 });
moveCamera({ motion: 'tilt', pitchDeg: -5 });
for (let i = 0; i < 70; i += 1) h.tick();
const zoom = adjustOrbitRange(2.5);
assert.equal(zoom.changed, true);
h.tick();
assert.equal(zoom.pitchDeg, Math.round(pitchDeg(h.camera)));
let last = pitchDeg(h.camera);
let maxStep = 0;
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
maxStep = Math.max(maxStep, Math.abs(pitchDeg(h.camera) - last));
last = pitchDeg(h.camera);
}
assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
assert.ok(maxStep < 0.1, `pitch jumped ${maxStep}° in one frame`);
assert.ok(h.viewTarget(), 'the crosshair is on the sky');
// Replies give whole degrees: the reported angle is the reached one rounded.
assert.equal(
zoom.pitchDeg,
Math.round(pitchDeg(h.camera)),
`camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
);
assert.match(zoom.note, /horizon/);
});
// Easing from the camera's old pitch at the zoomed-out range put the camera
// below the place's horizon: the first frame's crosshair hit the ground
// 186 km from London, and London stayed hidden for ~11 frames.
test('a late zoom out during a tilt keeps the place under the crosshair', (t) => {
const h = harness(t, { height: 400_000 });
moveCamera({ motion: 'tilt', pitchDeg: -5 });
for (let i = 0; i < 70; i += 1) h.tick();
const zoom = adjustOrbitRange(2.5);
assert.equal(zoom.changed, true);
for (let i = 0; i < 600 && getActiveCameraMotion(); i += 1) {
h.tick();
const hit = h.viewTarget();
assert.ok(hit, `frame ${i}: the crosshair is on the sky`);
const drift = centreDrift(h);
assert.ok(
drift < 100,
`frame ${i}: crosshair ${Math.round(drift)} m off the place`,
);
}
assert.equal(getActiveCameraMotion(), null, 'tilt must finish');
assert.ok(
Math.abs(pivotRange(h) - 1_000_000) < 1,
`range ${pivotRange(h)} m`,
);
assert.equal(
zoom.pitchDeg,
Math.round(pitchDeg(h.camera)),
`camera at ${pitchDeg(h.camera)}°, zoom reported ${zoom.pitchDeg}°`,
);
assert.match(zoom.note, /horizon/);
});
// The zoom out left the pivot pitch level with the place, so the zoom in's
// clearance floor came out infinite and it was refused at 1,000 km.
test('a zoom in right after a late zoom out brings the tilt back in', (t) => {
const h = harness(t, { height: 400_000 });
moveCamera({ motion: 'tilt', pitchDeg: -5 });
for (let i = 0; i < 70; i += 1) h.tick();
const range = pivotRange(h);
assert.equal(adjustOrbitRange(2.5).changed, true);
const zoomIn = adjustOrbitRange(0.4);
assert.equal(zoomIn.changed, true, 'the zoom in must not be refused');
h.finish();
assert.ok(
Math.abs(pivotRange(h) - range) < 1,
`range ${pivotRange(h)} m, wanted ${range} m`,
);
assert.ok(
centreDrift(h) < 100,
`crosshair ${centreDrift(h)} m off the place`,
);
});
+710 -78
View File
@@ -20,31 +20,47 @@
import { followedOf, isFollowing, onFollowChanged } from './data/followed.js'; import { followedOf, isFollowing, onFollowChanged } from './data/followed.js';
import { GLOBE_VIEW } from './locations.js'; import { GLOBE_VIEW } from './locations.js';
import {
globeFrameShare,
isFreeGlobeCamera,
lookAngleWithinFrame,
lookStepLosesGlobe,
lookedPose,
} from './globeInView.js';
import { import {
projectEarthDiscToViewport, projectEarthDiscToViewport,
earthDiscScreenRadius, earthDiscScreenRadius,
getKeyholeGeometry, getKeyholeGeometry,
KEYHOLE_OUTER_RADIUS,
} from './celestialRing.js'; } from './celestialRing.js';
import { isScopeMaskEnabled } from './scopeMask.js';
import { import {
holdContinuousRender, holdContinuousRender,
releaseContinuousRender, releaseContinuousRender,
} from './renderGovernor.js'; } from './renderGovernor.js';
import { import {
PI_OVER_TWO,
WGS84, WGS84,
add, add,
clamp,
cross, cross,
distance, distance,
dot, dot,
eastNorthUp,
framePoint,
fromAxisAngle, fromAxisAngle,
fromDegrees, fromDegrees,
fromRadians, fromRadians,
frameVector, frameVector,
geodeticSurfaceNormal,
headingPitchRollFrame, headingPitchRollFrame,
inverseFramePoint,
lerpInto, lerpInto,
magnitude, magnitude,
negativePiToPi, negativePiToPi,
normalize, normalize,
scale, scale,
sub,
toAxes, toAxes,
toCartographicRadians, toCartographicRadians,
toDegrees, toDegrees,
@@ -77,6 +93,33 @@ const ONCE = {
}; };
const PITCH_MIN = toRadians(-89); const PITCH_MIN = toRadians(-89);
const PITCH_MAX = toRadians(-5); const PITCH_MAX = toRadians(-5);
/** A bare "tilt the camera" / "oblique view" settles here. */
const TILT_DEFAULT_PITCH_DEG = -45;
/** °/s for a tilt to a requested angle; short ones keep the once duration. */
const TILT_TO_DEG_S = 30;
/**
* A pivoting tilt keeps the range, so its height above the pivot is
* range × sin|pitch|. It swings no lower than this; the rest tilts in place.
*/
const TILT_MIN_CLEARANCE_M = 150;
/**
* Beyond this range a pivot would swing the camera thousands of km about the
* crosshair point, so the tilt happens in place instead.
*/
const TILT_PIVOT_MAX_RANGE_M = 1_000_000;
/**
* A pivot range rebuilt from the camera's position comes back a hair off the
* range it was set at: a range this close past the cutoff still counts as on
* it.
*/
const TILT_PIVOT_RANGE_SLACK_M = 1;
/**
* The shallowest a pivot swing goes when its clearance is not what stops it.
* From several hundred km the camera's own horizon limit lies past the
* place's horizon; tilting the rest in place there would lift the crosshair
* onto the sky, so the swing stops with the place this far above it.
*/
const TILT_MIN_PIVOT_ELEVATION = toRadians(0.5);
/* ── Route dolly: cinematic tuning ────────────────────────────────────────── /* ── Route dolly: cinematic tuning ──────────────────────────────────────────
* Every knob an owner may want to retune lives in this block. The shaping is * Every knob an owner may want to retune lives in this block. The shaping is
@@ -908,6 +951,17 @@ let _trackingRemover = null;
let _inputRemovers = []; let _inputRemovers = [];
/** Monotonic id for the motion currently running; 0 means "no motion". */ /** Monotonic id for the motion currently running; 0 means "no motion". */
let _motionSeq = 0; let _motionSeq = 0;
/** Canvas grabs, touches and wheel turns since load. */
let _manualInputCount = 0;
/**
* Lets a caller holding a motion back (behind a fly-to) see whether the user
* took the camera meanwhile; the camera does not cancel a flight on input.
* @returns {number} Manual camera inputs so far.
*/
export function manualCameraInputCount() {
return _manualInputCount;
}
/** /**
* Install a motion and stamp it with a fresh id. The id is what lets a caller * Install a motion and stamp it with a fresh id. The id is what lets a caller
@@ -964,6 +1018,177 @@ export function interruptCameraMotionIfActive(
return interruptCameraMotion(reason); return interruptCameraMotion(reason);
} }
// The frame share that in-place voice turns measure their limit against, with
// the pose the last voice turn left the camera in. A turn that starts where
// the last one left off keeps that baseline (raised if the planet now fills
// more of the frame), so repeating a request cannot take a little more each
// time. Once anything else has moved or turned the camera, a turn starts over
// from what is on screen.
let _lookBaseline = null;
// The pre-check's proof that a half-degree turn from this pose keeps the planet
// in view: which way, from which position and direction. A motion that starts from that
// pose turns at least that far, so a request reported as done really moves
// even when a smaller first step lands in a dip of the sampled share.
const PROVEN_TURN_RAD = toRadians(0.5);
let _provenLook = null;
/** The part of the frame a viewer can see: the scope keyhole when it is on. */
function visibleFrame() {
return { keyholeRadius: isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0 };
}
/** Whether two vectors agree to `tolerance` in every component. */
const within = (a, b, tolerance) =>
Math.abs(a.x - b.x) <= tolerance &&
Math.abs(a.y - b.y) <= tolerance &&
Math.abs(a.z - b.z) <= tolerance;
/** The frame share an in-place turn from `pose` is limited against. */
function lookBaselineShare(pose) {
const share = globeFrameShare(pose, visibleFrame());
const continues =
_lookBaseline &&
within(_lookBaseline.position, pose.position, 1) &&
within(_lookBaseline.direction, pose.direction, 1e-9);
_lookBaseline = {
position: pose.position,
direction: pose.direction,
share: continues ? Math.max(_lookBaseline.share, share) : share,
};
return _lookBaseline.share;
}
/**
* One in-place look step of motion `m` (`look`: 'up', 'down', 'left' or
* 'right'). From orbit a free globe camera turns only as far as keeps the
* planet in frame, measured against the baseline the turn started from, then
* the motion ends there.
*/
function lookWithinFrame(camera, m, look, angle) {
let allowed = angle;
if (isFreeGlobeCamera(_viewer)) {
const pose = camera.pose();
if (m.globeShareAtStart === undefined) {
m.globeShareAtStart = lookBaselineShare(pose);
m.provenTurnRad = lookProven(pose, look) ? PROVEN_TURN_RAD : 0;
m.turnedRad = 0;
}
_provenLook = null;
allowed = lookAngleWithinFrame(pose, look, angle, {
...visibleFrame(),
startShare: m.globeShareAtStart,
});
const owed = Math.min(angle, m.provenTurnRad - m.turnedRad);
if (allowed < owed) allowed = owed;
m.turnedRad += allowed;
}
if (allowed > 0) camera.look(look, allowed);
// The pose this turn leaves, for a turn that continues from it.
if (_lookBaseline) _lookBaseline.direction = camera.pose().direction;
if (allowed < angle) interruptCameraMotion('globe-out-of-frame');
}
/**
* The in-place look a pitch change from `fromPitch` to `goalPitch` makes:
* 'up', 'down', or null when it does not move. A tilt is judged by the way
* its pitch moves, whatever form or direction word it came in.
*/
function tiltLook(fromPitch, goalPitch) {
if (!Number.isFinite(fromPitch) || !Number.isFinite(goalPitch)) return null;
if (goalPitch > fromPitch) return 'up';
return goalPitch < fromPitch ? 'down' : null;
}
/** Tilt `m` in place to `goalPitch`, as far as the frame limit allows. */
function tiltInPlaceWithinFrame(camera, m, goalPitch) {
const pitch = camera.pose().pitch;
const look = tiltLook(pitch, goalPitch);
if (look) lookWithinFrame(camera, m, look, Math.abs(goalPitch - pitch));
}
/**
* The pitch an in-place tilt from the camera's pose toward `goalPitch`
* reaches before the frame limit stops it, judged as its steps will be:
* `goalPitch` itself when the planet stays in frame the whole way, or the
* camera is not a free globe camera. The steps run on a copy of the pose, each
* looking by the pitch still to go as the tilt's frames do, because a rolled
* camera's look turns its pitch by less than the look angle.
*/
function tiltPitchWithinFrame(camera, goalPitch) {
const pose = camera.pose();
const look = tiltLook(pose.pitch, goalPitch);
if (!look || !isFreeGlobeCamera(_viewer)) return goalPitch;
const frame = { ...visibleFrame(), startShare: lookBaselineShare(pose) };
// A proven half degree is turned whatever the sampled share says.
let owed = lookProven(pose, look) ? PROVEN_TURN_RAD : 0;
let probe = pose;
for (let i = 0; i < 32; i += 1) {
if (tiltLook(probe.pitch, goalPitch) !== look) return goalPitch;
const angle = Math.abs(goalPitch - probe.pitch);
if (angle < 1e-6) return goalPitch;
const allowed = Math.max(
lookAngleWithinFrame(probe, look, angle, frame),
Math.min(angle, owed),
);
owed -= allowed;
if (allowed > 0) probe = lookedPose(probe, look, allowed);
if (allowed < angle) return probe.pitch;
}
return probe.pitch;
}
/** The reply's note for a tilt the frame limit stops short of its angle. */
function tiltFrameNote(pitch) {
return `Stopped at ${Math.round(toDegrees(pitch))}°: from this height a shallower angle would turn the globe out of view. Zoom in to tilt further.`;
}
/** True when the pre-check proved a half-degree `look` from `pose`. */
function lookProven(pose, look) {
return (
_provenLook?.look === look &&
pose != null &&
within(_provenLook.position, pose.position, 1) &&
within(_provenLook.direction, pose.direction, 1e-9)
);
}
/**
* The check a voice in-place turn (`look`: 'up', 'down', 'left' or 'right')
* must pass from orbit: refused when even half a degree would
* cross the frame limit, otherwise proven for that half degree from this pose.
* With `released`, the turn runs through a navigation that first releases a
* tracked or locked camera and keeps its world pose. The frame measure and the
* turn are the same in any reference frame, so such a camera is judged as it
* is, before the release, and a refusal leaves tracking as it was. Otherwise a
* camera that is not a free globe camera is not checked. Returns the refusal,
* or null.
*/
function checkLookFromOrbit(look, { released = false } = {}) {
_provenLook = null;
if (!released && !isFreeGlobeCamera(_viewer)) return null;
const pose = findCamera(_viewer)?.pose();
if (!pose) return null;
if (
lookStepLosesGlobe(pose, look, PROVEN_TURN_RAD, {
...visibleFrame(),
startShare: lookBaselineShare(pose),
})
)
return {
ok: false,
action: 'move_camera',
error:
'From this height that would turn the globe out of view — zoom in first, or turn the other way.',
};
_provenLook = {
look,
position: pose.position,
direction: pose.direction,
};
return null;
}
function clearLookAt() { function clearLookAt() {
try { try {
findCamera(_viewer)?.release(); findCamera(_viewer)?.release();
@@ -1006,7 +1231,9 @@ export function interruptCameraMotion(reason = 'interrupt') {
if ( if (
wasActive && wasActive &&
!tracking && !tracking &&
(_active.kind === 'orbit' || _active.kind === 'route') (_active.kind === 'orbit' ||
_active.kind === 'route' ||
(_active.kind === 'tilt' && _active.hpr))
) )
clearLookAt(); clearLookAt();
// Instant, not eased: the user grabbed the camera, or the flight is over. // Instant, not eased: the user grabbed the camera, or the flight is over.
@@ -1060,7 +1287,7 @@ function onTick() {
let scale = 1; let scale = 1;
if (m.mode === 'once') { if (m.mode === 'once') {
m.elapsed = (m.elapsed || 0) + dt; m.elapsed = (m.elapsed || 0) + dt;
const t = Math.min(1, m.elapsed / ONCE.durationS); const t = Math.min(1, m.elapsed / (m.durationS || ONCE.durationS));
scale = 1 - (1 - t) * (1 - t); // ease-out progress share scale = 1 - (1 - t) * (1 - t); // ease-out progress share
if (t >= 1) { if (t >= 1) {
interruptCameraMotion('once-complete'); interruptCameraMotion('once-complete');
@@ -1117,16 +1344,13 @@ function onTick() {
: heightM * PAN_VIEW_FRACTION_S[m.speed] * dt; : heightM * PAN_VIEW_FRACTION_S[m.speed] * dt;
m.lastScale = scale; m.lastScale = scale;
camera.move(PAN_MOVES[m.direction] ?? 'down', step); camera.move(PAN_MOVES[m.direction] ?? 'down', step);
} else if ( } else if (m.kind === 'tilt') {
m.kind === 'tilt' || tickTilt(camera, m, scale, dt);
m.kind === 'rotate' || } else if (m.kind === 'rotate' || m.kind === 'rotate_globe') {
m.kind === 'rotate_globe'
) {
const degS = TILT_DEG_S[m.speed]; const degS = TILT_DEG_S[m.speed];
const stepRad = const stepRad =
m.mode === 'once' m.mode === 'once'
? toRadians(m.kind === 'tilt' ? ONCE.tiltDeg : ONCE.rotateDeg) * ? toRadians(ONCE.rotateDeg) * (scale - (m.lastScale || 0))
(scale - (m.lastScale || 0))
: toRadians(degS) * dt; : toRadians(degS) * dt;
m.lastScale = scale; m.lastScale = scale;
if (m.kind === 'rotate_globe') { if (m.kind === 'rotate_globe') {
@@ -1134,11 +1358,7 @@ function onTick() {
// Yield without resetting its pose/frame: the world-space arc proof // Yield without resetting its pose/frame: the world-space arc proof
// only describes the camera's rotation while the frame is identity. // only describes the camera's rotation while the frame is identity.
const pose = camera.pose(); const pose = camera.pose();
if ( if (!isFreeGlobeCamera(_viewer) || _isCockpitActive?.()) {
isFollowing(_viewer) ||
_isCockpitActive?.() ||
!pose.frameIsIdentity
) {
interruptCameraMotion('globe-camera-owner-changed'); interruptCameraMotion('globe-camera-owner-changed');
return; return;
} }
@@ -1158,16 +1378,14 @@ function onTick() {
return; return;
} }
camera.rotateAround(m.rotationAxis, angle); camera.rotateAround(m.rotationAxis, angle);
} else if (m.kind === 'tilt') { } else {
const up = m.direction === 'up'; lookWithinFrame(
// Clamp pitch to [-89°, -5°]: never through the ground, never at the sky. camera,
const next = camera.pose().pitch + (up ? stepRad : -stepRad); m,
if (next > PITCH_MAX || next < PITCH_MIN) { m.direction === 'left' ? 'left' : 'right',
interruptCameraMotion('tilt-clamp'); stepRad,
return; );
} }
camera.look(up ? 'up' : 'down', stepRad);
} else camera.look(m.direction === 'left' ? 'left' : 'right', stepRad);
} else if (m.kind === 'route') { } else if (m.kind === 'route') {
// The dolly's shaping lives in advanceRouteFlight(); the tick only // The dolly's shaping lives in advanceRouteFlight(); the tick only
// applies the pose and honours the same completion path as before. // applies the pose and honours the same completion path as before.
@@ -1209,6 +1427,169 @@ function orbitFraming(pose, target) {
}; };
} }
/**
* One frame of tilt. With a ground pivot the camera swings about it (lookAt),
* so the place under the crosshair stays centred; without one it looks up or
* down in place. Every angle and limit is the camera's own pitch, which at
* regional range is several degrees steeper than the pivot's (the Earth
* curves away), so the swing solves for the pivot pitch that gives it. Pitch
* is clamped to [-89°, -5°] only in the direction of travel: a top-down view
* sits at -90°, below the limit, and must still be able to tilt up out of it.
* A pivot swing toward the horizon lowers the camera, so it stops at
* TILT_MIN_CLEARANCE_M and the rest tilts in place. Farther out it stops with
* the camera TILT_MIN_PIVOT_ELEVATION above the place's horizon instead, and
* keeps the place centred: tilting in place there would lift the crosshair
* onto the sky.
*/
function tickTilt(camera, m, scale, dt) {
const pitchNow = () => camera.pose().pitch;
const from = pitchNow();
const want =
m.mode === 'once'
? m.startPitch + (m.goalPitch - m.startPitch) * scale
: from +
toRadians(TILT_DEG_S[m.speed]) * dt * (m.direction === 'up' ? 1 : -1);
const up = want > from;
const limited = up
? Math.min(want, Math.max(from, PITCH_MAX))
: Math.max(want, Math.min(from, PITCH_MIN));
let atLimit = false;
if (m.hpr) {
// Apply a range a zoom set since the last frame, even when the pitch
// then has nowhere to go (a zoom in to the clearance ends the pivot).
camera.lookAt(m.target, m.hpr);
// Up toward the horizon the swing lowers the camera: hold the clearance,
// and keep the place below the horizon.
const cap = up
? Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range))
: Infinity;
for (let i = 0; i < 3 && Math.abs(limited - pitchNow()) > 1e-6; i += 1) {
const pitch = Math.min(
cap,
Math.max(-PI_OVER_TWO, m.hpr.pitch + limited - pitchNow()),
);
if (pitch === m.hpr.pitch) break;
m.hpr.pitch = pitch;
camera.lookAt(m.target, m.hpr);
}
// A once motion that just completed released the lookAt frame before
// this last step re-took it.
if (_active !== m) clearLookAt();
if (up && m.hpr.pitch >= cap && pitchNow() < limited - 1e-6) {
if (tiltClearanceBinds(m.hpr.range)) {
// Down to its clearance: let go of the pivot and tilt the rest in
// place, which keeps the height.
if (_active === m) clearLookAt();
m.hpr = null;
m.target = null;
} else {
// The place is at its horizon limit: stop here, still centred.
atLimit = true;
}
}
}
if (!m.hpr) tiltInPlaceWithinFrame(camera, m, limited);
if (m.mode !== 'once' && (limited !== want || atLimit))
interruptCameraMotion('tilt-clamp');
}
/** The refusal for a tilt up the camera has no room left for. */
function tiltUpLimitRefusal() {
return {
ok: false,
action: 'move_camera',
error:
'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
};
}
/** Shallowest pivot pitch that keeps the clearance at this range. */
function tiltPivotPitchMax(range) {
return Math.min(
-Math.asin(Math.min(1, TILT_MIN_CLEARANCE_M / range)),
-TILT_MIN_PIVOT_ELEVATION,
);
}
/**
* Whether the clearance, not the horizon, stops a swing at this range. Only
* then does the rest of the tilt happen in place: that close in (under ~17
* km) the camera's -5° limit stays well below its own horizon.
*/
function tiltClearanceBinds(range) {
return TILT_MIN_CLEARANCE_M / range >= Math.sin(TILT_MIN_PIVOT_ELEVATION);
}
/**
* The shallowest camera pitch a tilt starting from this frame can reach with
* the place under the crosshair still in view: PITCH_MAX, or less where a
* far pivot meets its horizon limit first.
*/
function tiltUpLimit({ target, pivot }) {
if (!pivot || tiltClearanceBinds(pivot.range)) return PITCH_MAX;
return Math.min(
PITCH_MAX,
pivotCameraPitch(
target,
pivot,
Math.max(pivot.pitch, tiltPivotPitchMax(pivot.range)),
),
);
}
/** The camera pitch lookAt gives for this pivot at the given pivot pitch. */
function pivotCameraPitch(target, { heading, range }, pitch) {
const eye = framePoint(eastNorthUp(target), {
x: -range * Math.cos(pitch) * Math.sin(heading),
y: -range * Math.cos(pitch) * Math.cos(heading),
z: -range * Math.sin(pitch),
});
const look = normalize(sub(target, eye));
return Math.asin(clamp(dot(look, geodeticSurfaceNormal(eye)), -1, 1));
}
/**
* Where a tilt starts. It swings about the ground under the crosshair so the
* place stays centred. It tilts in place with no ground there, from globe
* range, or while something is followed (the follow camera owns that frame;
* voice releases it before moving, so a voice tilt still pivots).
*/
function tiltStartFrame(camera) {
const pose = camera.pose();
const target = isFollowing(_viewer) ? null : _getTarget?.(_viewer);
let pivot = target ? tiltPivot(pose, target) : null;
if (pivot && !tiltPivotInReach(pivot.range)) pivot = null;
return { target, pivot, from: pose.pitch };
}
/** Whether a tilt may pivot at this range: up to and including the cutoff. */
function tiltPivotInReach(range) {
return range <= TILT_PIVOT_MAX_RANGE_M + TILT_PIVOT_RANGE_SLACK_M;
}
/** The reply's note for a tilt the place's horizon stops short of its angle. */
function tiltHorizonNote(pitch) {
return `Stopped at ${Math.round(toDegrees(pitch))}°: from this range a shallower angle puts the place past the horizon. Zoom in to tilt further.`;
}
/** Ground pivot for a tilt: heading, pitch and range in the target's own frame. */
function tiltPivot(pose, target) {
const local = inverseFramePoint(eastNorthUp(target), pose.position);
const range = magnitude(local);
if (!(range > 1) || local.z <= 0) return null;
// Near straight overhead the offset's heading is float noise (it flipped a
// north-up London view to south); keep the camera's own.
const heading =
Math.hypot(local.x, local.y) > range * 0.01
? Math.atan2(-local.x, -local.y)
: pose.heading;
return {
heading,
pitch: -Math.asin(Math.min(1, local.z / range)),
range,
};
}
/** Rigid origin-centred rotation stays outside the ellipsoid's bounding sphere. */ /** Rigid origin-centred rotation stays outside the ellipsoid's bounding sphere. */
function globeRotationHasClearance(position) { function globeRotationHasClearance(position) {
const radius = magnitude(position); const radius = magnitude(position);
@@ -1381,6 +1762,7 @@ export function initCameraVerbs(
_isCockpitActive = _isCockpitActive =
typeof isCockpitActive === 'function' ? isCockpitActive : null; typeof isCockpitActive === 'function' ? isCockpitActive : null;
_viewer = viewer; _viewer = viewer;
_lookBaseline = null;
listenForFrames(); listenForFrames();
if (_trackingRemover) _trackingRemover(); if (_trackingRemover) _trackingRemover();
// Cockpit can acquire then clear tracking before the next clock tick. // Cockpit can acquire then clear tracking before the next clock tick.
@@ -1388,18 +1770,102 @@ export function initCameraVerbs(
_trackingRemover = onFollowChanged(viewer, (followed) => { _trackingRemover = onFollowChanged(viewer, (followed) => {
if (followed && _active?.kind === 'rotate_globe') if (followed && _active?.kind === 'rotate_globe')
interruptCameraMotion('globe-camera-owner-changed'); interruptCameraMotion('globe-camera-owner-changed');
// A pivoting tilt's lookAt would fight the follow camera every frame.
else if (followed && _active?.kind === 'tilt' && _active.hpr)
interruptCameraMotion('tilt-camera-owner-changed');
}); });
for (const rm of _inputRemovers) rm(); for (const rm of _inputRemovers) rm();
_inputRemovers = []; _inputRemovers = [];
const canvas = canvasOf(viewer); const canvas = canvasOf(viewer);
// ANY manual camera input reclaims control — the cancelFlight reflex. // ANY manual camera input reclaims control — the cancelFlight reflex.
for (const evt of ['pointerdown', 'touchstart', 'wheel']) { for (const evt of ['pointerdown', 'touchstart', 'wheel']) {
const h = () => interruptCameraMotion('manual-input'); const h = () => {
_manualInputCount += 1;
interruptCameraMotion('manual-input');
};
canvas.addEventListener(evt, h, { passive: true }); canvas.addEventListener(evt, h, { passive: true });
_inputRemovers.push(() => canvas.removeEventListener(evt, h)); _inputRemovers.push(() => canvas.removeEventListener(evt, h));
} }
} }
/**
* A tilt's angle: the one asked for, the default oblique view when a bare
* "tilt the camera" names neither angle nor direction, or null for a nudge.
*/
function requestedTiltPitch(args, direction) {
// Only a real number or numeric text: Number('') and Number(null) are 0,
// which would swing the camera to the horizon.
const raw = args.pitchDeg;
const requested =
typeof raw === 'number' || (typeof raw === 'string' && raw.trim() !== '')
? Number(raw)
: NaN;
// The camera never looks above the horizon, so a positive angle can only
// mean the same angle below it ("tilt 45 degrees" sent as 45).
if (Number.isFinite(requested))
return clamp(toRadians(-Math.abs(requested)), PITCH_MIN, PITCH_MAX);
return direction === null ? toRadians(TILT_DEFAULT_PITCH_DEG) : null;
}
/**
* Argument errors move_camera refuses whatever the camera is doing, so a
* caller holding a motion back behind a flight can refuse it before waiting.
* @param {Object} args
* @returns {Object|null} The refusal, or null when the arguments are usable.
*/
export function moveCameraArgsError(args = {}) {
const motion = String(args.motion || '').toLowerCase();
const direction = args.direction
? String(args.direction).toLowerCase()
: null;
if (motion === 'stop') return null;
if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) {
return {
ok: false,
action: 'move_camera',
error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`,
};
}
if (
motion !== 'orbit' &&
motion !== 'rotate_globe' &&
(motion !== 'tilt' || requestedTiltPitch(args, direction) === null) &&
!['left', 'right', 'up', 'down'].includes(direction)
) {
return {
ok: false,
action: 'move_camera',
error: `${motion} needs a direction (${motion === 'tilt' ? 'up/down' : motion === 'rotate' ? 'left/right' : 'left/right/up/down'}).`,
};
}
if (motion === 'tilt' && (direction === 'left' || direction === 'right')) {
return {
ok: false,
action: 'move_camera',
error: 'tilt needs up or down, or pitchDeg alone for an angle.',
};
}
if (motion === 'rotate' && !['left', 'right'].includes(direction)) {
return {
ok: false,
action: 'move_camera',
error: 'rotate needs left or right.',
};
}
if (
motion === 'rotate_globe' &&
direction !== null &&
!['left', 'right'].includes(direction)
) {
return {
ok: false,
action: 'move_camera',
error: 'rotate_globe needs left or right.',
};
}
return null;
}
/** /**
* move_camera implementation. Returns the house result shape; rejections are * move_camera implementation. Returns the house result shape; rejections are
* plain-English `ok:false` errors. * plain-English `ok:false` errors.
@@ -1432,54 +1898,59 @@ export function moveCamera(args = {}, runNavigation = null) {
}; };
return typeof runNavigation === 'function' ? runNavigation(stop) : stop(); return typeof runNavigation === 'function' ? runNavigation(stop) : stop();
} }
if (!['orbit', 'pan', 'tilt', 'rotate', 'rotate_globe'].includes(motion)) { const argsError = moveCameraArgsError(args);
return { if (argsError) return argsError;
ok: false, const tiltToPitch =
action: 'move_camera', motion === 'tilt' ? requestedTiltPitch(args, direction) : null;
error: `Unknown motion "${args.motion}" — use orbit, pan, tilt, rotate, rotate_globe, or stop.`, if (motion === 'tilt' && tiltToPitch !== null) {
}; // Angles and limits are the camera's own pitch, whatever the swing pivots
} // about; releasing the follow camera does not change it.
if ( const from = cameraOf(_viewer).pose().pitch;
motion !== 'orbit' && // -89 or -90 means top-down, which a -90° view already is: the clamp
motion !== 'rotate_globe' && // must not tilt it up 1°.
!['left', 'right', 'up', 'down'].includes(direction) const atTopDown = tiltToPitch <= PITCH_MIN && from <= PITCH_MIN;
) { if (atTopDown || Math.abs(tiltToPitch - from) < toRadians(0.5)) {
return { // Still a camera request: it stops a running motion and releases the
ok: false, // follow camera, as a tilt that moves would.
action: 'move_camera', const hold = () => {
error: `${motion} needs a direction (left/right${motion !== 'rotate' ? '/up/down' : ''}).`, interruptCameraMotion('replaced');
}; return {
} ok: true,
if (motion === 'rotate' && !['left', 'right'].includes(direction)) { action: 'move_camera',
return { motion,
ok: false, pitchDeg: Math.round(toDegrees(atTopDown ? from : tiltToPitch)),
action: 'move_camera', unchanged: true,
error: 'rotate needs left or right.', };
}; };
} return typeof runNavigation === 'function' ? runNavigation(hold) : hold();
if ( }
motion === 'rotate_globe' && // pitchDeg is an absolute angle, not a step: "tilt down 10 degrees" sent
direction !== null && // as {direction:'down', pitchDeg:10} would tilt up from -45°.
!['left', 'right'].includes(direction) const towards = tiltToPitch > from ? 'up' : 'down';
) { if ((direction === 'up' || direction === 'down') && direction !== towards) {
return { const target = Math.round(toDegrees(tiltToPitch));
ok: false, const now = Math.round(toDegrees(from));
action: 'move_camera',
error: 'rotate_globe needs left or right.',
};
}
if (motion === 'tilt') {
// Honest limits: at the clamp a tilt is a no-op — say so instead of
// reporting success and letting the model gaslight itself (field test).
const pitch = cameraOf(_viewer).pose().pitch;
if (direction === 'up' && pitch >= PITCH_MAX - toRadians(0.5)) {
return { return {
ok: false, ok: false,
action: 'move_camera', action: 'move_camera',
error: error: `pitchDeg is an absolute angle, not a step: ${target}° from ${now}° tilts ${towards}, not ${direction}. Send direction alone for a nudge, or pitchDeg alone for an angle.`,
'Already at the upper tilt limit (near the horizon) — tilt down, or zoom/pan instead.',
}; };
} }
if (
towards === 'up' &&
from >= tiltUpLimit(tiltStartFrame(cameraOf(_viewer))) - toRadians(0.5)
)
return tiltUpLimitRefusal();
} else if (motion === 'tilt') {
// Honest limits: at the clamp a tilt is a no-op — say so instead of
// reporting success and letting the model gaslight itself (field test).
const pitch = cameraOf(_viewer).pose().pitch;
if (
direction === 'up' &&
pitch >= tiltUpLimit(tiltStartFrame(cameraOf(_viewer))) - toRadians(0.5)
) {
return tiltUpLimitRefusal();
}
if (direction === 'down' && pitch <= PITCH_MIN + toRadians(0.5)) { if (direction === 'down' && pitch <= PITCH_MIN + toRadians(0.5)) {
return { return {
ok: false, ok: false,
@@ -1488,6 +1959,33 @@ export function moveCamera(args = {}, runNavigation = null) {
}; };
} }
} }
// A tilt is judged by the way its pitch will move: toward its angle, or a
// nudge up or down; a rotate turns left only when told to, as it runs.
const look =
motion === 'tilt'
? tiltLook(
cameraOf(_viewer).pose().pitch,
tiltToPitch ??
cameraOf(_viewer).pose().pitch +
toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1),
)
: motion === 'rotate'
? direction === 'left'
? 'left'
: 'right'
: null;
// Honest limits from orbit too: a stopped turn rests within 0.05° of its
// limit, so one that cannot go half a degree further is refused rather than
// run and reported as done, and one that can is then turned at least that
// far. Near the limit the sampled share wobbles as the planet's edge crosses
// the grid, so a turn that would keep the planet can occasionally be refused
// too.
// A camera that is tracked or locked now is judged as the navigation that
// runs the turn will release it, so a refusal keeps the tracking.
const lookRefusal =
look &&
checkLookFromOrbit(look, { released: typeof runNavigation === 'function' });
if (lookRefusal) return lookRefusal;
if ( if (
(motion === 'rotate_globe' || (motion === 'rotate_globe' ||
(motion === 'orbit' && typeof runNavigation !== 'function')) && (motion === 'orbit' && typeof runNavigation !== 'function')) &&
@@ -1567,14 +2065,69 @@ export function moveCamera(args = {}, runNavigation = null) {
error: 'Globe rotation requires a clear ellipsoid bounding sphere.', error: 'Globe rotation requires a clear ellipsoid bounding sphere.',
}; };
} }
// The angle a tilt to an angle stops at short of it, and why.
let stoppedAt = null;
let stopNote = null;
const start = () => { const start = () => {
interruptCameraMotion('replaced'); interruptCameraMotion('replaced');
// Checked again only if the release left the camera somewhere other than
// where the check above expected it.
if (look && !lookProven(findCamera(_viewer)?.pose(), look)) {
const refusal = checkLookFromOrbit(look);
if (refusal) return refusal;
}
const state = { const state = {
kind: motion, kind: motion,
direction: direction || 'right', direction: direction || 'right',
speed, speed,
mode, mode,
}; };
if (motion === 'tilt') {
const frame = tiltStartFrame(cameraOf(_viewer));
const { target, pivot, from } = frame;
if (pivot) {
state.target = target;
state.hpr = pivot;
}
state.startPitch = from;
const upLimit = tiltUpLimit(frame);
if (tiltToPitch !== null) {
// From far out the place reaches its horizon before the camera
// reaches the asked angle: stop there, and say so.
let goal =
tiltToPitch > from
? Math.min(tiltToPitch, Math.max(from, upLimit))
: tiltToPitch;
if (goal !== tiltToPitch) stopNote = tiltHorizonNote(goal);
// From orbit an in-place tilt stops where the planet would leave the
// frame: aim it there, and say so.
if (!pivot) {
const framed = tiltPitchWithinFrame(cameraOf(_viewer), goal);
if (framed !== goal) {
goal = framed;
stopNote = tiltFrameNote(goal);
}
}
state.mode = 'once';
state.direction = goal > from ? 'up' : 'down';
state.goalPitch = goal;
// A zoom mid-tilt moves the horizon limit; it re-judges the goal
// against the angle asked for.
state.askedPitch = tiltToPitch;
state.durationS = Math.max(
ONCE.durationS,
Math.abs(toDegrees(goal - from)) / TILT_TO_DEG_S,
);
if (goal !== tiltToPitch) stoppedAt = goal;
} else {
// A nudge stops at the limit it travels toward.
const step = toRadians(ONCE.tiltDeg) * (direction === 'up' ? 1 : -1);
state.goalPitch =
step > 0
? Math.min(from + step, Math.max(from, upLimit))
: Math.max(from + step, Math.min(from, PITCH_MIN));
}
}
if (motion === 'rotate_globe') { if (motion === 'rotate_globe') {
// Convert an inherited ground-target frame without changing the world // Convert an inherited ground-target frame without changing the world
// pose. Rotation must pivot about Earth, never the previous local target. // pose. Rotation must pivot about Earth, never the previous local target.
@@ -1600,9 +2153,11 @@ export function moveCamera(args = {}, runNavigation = null) {
} }
if (motion === 'orbit') { if (motion === 'orbit') {
if (cameraFlying()) { if (cameraFlying()) {
// A camera flight is in progress ("fly to X and orbit it") — ALWAYS arm // A camera flight is in progress — ALWAYS arm and capture at the
// and capture at the destination; a target existing right now is // destination; a target existing right now is meaningless (the globe
// meaningless (the globe is always under the crosshair). // is always under the crosshair). The voice runner already holds an
// orbit until its own fly-to lands; this covers any other
// flight.
setActiveMotion({ setActiveMotion({
kind: 'orbit', kind: 'orbit',
direction: direction || 'right', direction: direction || 'right',
@@ -1659,7 +2214,11 @@ export function moveCamera(args = {}, runNavigation = null) {
motion, motion,
direction: state.direction, direction: state.direction,
speed, speed,
mode, mode: state.mode,
...(tiltToPitch !== null && {
pitchDeg: Math.round(toDegrees(stoppedAt ?? tiltToPitch)),
}),
...(stopNote !== null && { note: stopNote }),
}; };
}; };
const preserveCameraFlight = const preserveCameraFlight =
@@ -1672,16 +2231,89 @@ export function moveCamera(args = {}, runNavigation = null) {
/** /**
* Zoom while orbiting: scale the orbit RADIUS instead of letting the zoom * Zoom while orbiting: scale the orbit RADIUS instead of letting the zoom
* fight the per-frame lookAt (field test: "zoom out did literally nothing"). * fight the per-frame lookAt (field test: "zoom out did literally nothing").
* A tilt swinging about its pivot holds a range the same way.
* @param {number} factor >1 zooms out (radius grows), <1 zooms in. * @param {number} factor >1 zooms out (radius grows), <1 zooms in.
* @returns {boolean} true when an orbit consumed the zoom. * @returns {{kind: string, changed: boolean, pitchDeg?: number,
* note?: string}|null} the motion that consumed the zoom, and whether its
* range moved; null when none did. A tilt to an angle whose end the new
* range moves also names the angle it now ends at (pitchDeg), with a note.
*/ */
export function adjustOrbitRange(factor) { export function adjustOrbitRange(factor) {
if (!_active || _active.kind !== 'orbit' || !_active.hpr) return false; if (!_active || !['orbit', 'tilt'].includes(_active.kind) || !_active.hpr)
_active.hpr.range = Math.max( return null;
80, // A tilt's zoom in stops at the range that keeps its clearance. The limits
Math.min(5_000_000, _active.hpr.range * factor), // never move a view the wrong way: a zoom in leaves a closer view in place,
// and a zoom out leaves a farther one.
const { kind, hpr } = _active;
const floor =
kind === 'tilt'
? Math.max(80, TILT_MIN_CLEARANCE_M / Math.abs(Math.sin(hpr.pitch)))
: 80;
// A tilt pivots only within TILT_PIVOT_MAX_RANGE_M; farther out the swing
// would carry the camera thousands of km.
const ceiling = kind === 'tilt' ? TILT_PIVOT_MAX_RANGE_M : 5_000_000;
const range = hpr.range;
hpr.range = Math.max(
Math.min(floor, range),
Math.min(Math.max(ceiling, range), range * factor),
); );
return true; // Under half a metre counts as not moved, as for a plain zoom.
const changed = Math.abs(hpr.range - range) >= 0.5;
return { kind, changed, ...(changed && retargetTiltAfterZoom(_active)) };
}
/**
* A zoom changed the range a tilt to an angle holds, and with it the place's
* horizon limit: aim the tilt at the angle asked for or the new limit,
* whichever comes first, from where the camera is now. The pivot pitch is
* re-solved so the new range keeps the camera's pitch, and a limit the camera
* is already past is eased down to rather than jumped to. Returns the end
* angle and a note for the reply when that end moved, otherwise nothing.
*/
function retargetTiltAfterZoom(m) {
if (m.kind !== 'tilt' || m.mode !== 'once' || m.askedPitch === undefined)
return {};
let from = cameraOf(_viewer).pose().pitch;
if (!(m.askedPitch > from)) return {};
if (m.hpr) {
// At the same pivot pitch a longer range looks down more steeply (the
// Earth curves away): find the pivot pitch that holds this camera pitch.
// It stays below the place's horizon limit (or where the pivot already
// was): past it the place drops behind the Earth, so a camera the zoom
// leaves past that limit steps down to it with the zoom.
const cap = Math.max(m.hpr.pitch, tiltPivotPitchMax(m.hpr.range));
for (let i = 0; i < 4; i += 1) {
const error = from - pivotCameraPitch(m.target, m.hpr, m.hpr.pitch);
if (Math.abs(error) < 1e-7) break;
const pitch = clamp(m.hpr.pitch + error, -PI_OVER_TWO, cap);
if (pitch === m.hpr.pitch) break;
m.hpr.pitch = pitch;
}
from = Math.min(from, pivotCameraPitch(m.target, m.hpr, m.hpr.pitch));
}
const limit =
m.hpr && !tiltClearanceBinds(m.hpr.range)
? Math.min(
PITCH_MAX,
pivotCameraPitch(m.target, m.hpr, tiltPivotPitchMax(m.hpr.range)),
)
: PITCH_MAX;
const goal = Math.min(m.askedPitch, limit);
if (Math.abs(goal - m.goalPitch) < 1e-6) return {};
m.goalPitch = goal;
m.startPitch = from;
m.elapsed = 0;
m.durationS = Math.max(
ONCE.durationS,
Math.abs(toDegrees(goal - from)) / TILT_TO_DEG_S,
);
const limited = goal !== m.askedPitch;
return {
pitchDeg: Math.round(toDegrees(goal)),
note: limited
? tiltHorizonNote(goal)
: `The tilt now reaches ${Math.round(toDegrees(goal))}°.`,
};
} }
/** /**
+8
View File
@@ -1020,6 +1020,14 @@ test('the voice TOOL SCHEMA matches the pinned contract — the mission mapping
'noir', 'noir',
]); ]);
visualStyle.enum = [...visualStyle.enum, 'snow']; visualStyle.enum = [...visualStyle.enum, 'snow'];
// Tilt to an angle adds pitchDeg and rewords direction; restore
// the legacy camera fields to keep the pin.
const camera = legacyTools.find((tool) => tool.name === 'move_camera')
.parameters.properties;
assert.equal(camera.pitchDeg.type, 'number');
delete camera.pitchDeg;
camera.direction.description =
'Required for pan/tilt/rotate; orbit/rotate_globe default right.';
const block = JSON.stringify(legacyTools); const block = JSON.stringify(legacyTools);
// Re-derived for the voice layer manifest (generated layer enums, alias and // Re-derived for the voice layer manifest (generated layer enums, alias and
// field hints), point-and-ask's pointer/referent arguments and the prompt // field hints), point-and-ask's pointer/referent arguments and the prompt
+200
View File
@@ -0,0 +1,200 @@
import { isFollowing } from './data/followed.js';
import { geodeticSurfaceNormal, rayEllipsoid } from './geo/ellipsoid.js';
import { rotate } from './geo/frames.js';
import { clamp, dot, normalize, toRadians } from './geo/vector.js';
import { findCamera } from './render/rendererOf.js';
// The camera's free look (Shift+drag) turns the camera in place. Near the
// ground that surveys a city; from orbit a few drags turn the whole planet out
// of frame and leave only stars.
export const FREE_LOOK_MAX_HEIGHT_METERS = 1_000_000;
// A voice turn from orbit stops when about this share of the frame still shows
// the planet's surface.
export const MIN_GLOBE_FRAME_SHARE = 0.1;
/**
* A free globe camera: the viewer follows nothing, and its camera is not
* locked to a reference frame.
*/
export function isFreeGlobeCamera(viewer) {
const camera = findCamera(viewer);
return (
Boolean(camera) && !isFollowing(viewer) && camera.pose().frameIsIdentity
);
}
const GRID_COLUMNS = 32;
const GRID_ROWS = 18;
// A turn across a sliver of planet moves its edge through sample points, so
// the share wobbles by a cell or two without the planet leaving.
const GRID_NOISE_CELLS = 2;
// Whatever the baseline, a voice turn never takes the planet below this share
// of the frame; a view that already shows less may only keep what it has.
const LOOK_ABSOLUTE_FLOOR_SHARE = 0.01;
const sampleRay = { origin: null, direction: { x: 0, y: 0, z: 0 } };
/**
* Cast a 32×18 grid of view rays, one through the centre of each cell, at the
* WGS84 ellipsoid. With `keyholeRadius` (a radius around the frame centre, in
* units of half the frame height) only the cells inside that circle count: the
* scope mask hides the rest. Returns the surface hits and the cells counted, or
* null for a pose with no perspective view to sample.
* @param {import('./render/contract/camera').CameraPose} pose
*/
function sampleFrame(pose, keyholeRadius) {
if (!Number.isFinite(pose?.fovy) || !Number.isFinite(pose.aspectRatio))
return null;
const aspect = pose.aspectRatio;
const tanY = Math.tan(pose.fovy / 2);
const tanX = tanY * aspect;
const keyholeSquared = keyholeRadius > 0 ? keyholeRadius * keyholeRadius : 0;
const { direction, right, up } = pose;
sampleRay.origin = pose.position;
const ray = sampleRay.direction;
let hits = 0;
let cells = 0;
for (let row = 0; row < GRID_ROWS; row += 1) {
const rowY = (2 * (row + 0.5)) / GRID_ROWS - 1;
for (let column = 0; column < GRID_COLUMNS; column += 1) {
const columnX = (2 * (column + 0.5)) / GRID_COLUMNS - 1;
if (
keyholeSquared &&
(columnX * aspect) ** 2 + rowY * rowY > keyholeSquared
)
continue;
cells += 1;
const x = columnX * tanX;
const y = rowY * tanY;
ray.x = direction.x + right.x * x + up.x * y;
ray.y = direction.y + right.y * x + up.y * y;
ray.z = direction.z + right.z * x + up.z * y;
const length = Math.hypot(ray.x, ray.y, ray.z);
ray.x /= length;
ray.y /= length;
ray.z /= length;
if (rayEllipsoid(sampleRay)) hits += 1;
}
}
return { hits, cells };
}
/**
* Share of the frame, from 0 to 1, that shows the planet's surface: the
* fraction of a 32×18 grid of view rays, one through the centre of each cell,
* that hit the WGS84 ellipsoid. With `keyholeRadius` (see `sampleFrame`) it is
* the share of the visible circle instead. A pose with no perspective view
* counts as fully covered.
* @param {import('./render/contract/camera').CameraPose} pose
*/
export function globeFrameShare(pose, { keyholeRadius = 0 } = {}) {
const sample = sampleFrame(pose, keyholeRadius);
if (!sample || sample.cells === 0) return 1;
return sample.hits / sample.cells;
}
/** True when none of the planet's surface is in `pose`'s visible frame. */
export function globeOutOfFrame(pose, options) {
return globeFrameShare(pose, options) === 0;
}
/**
* `pose` after an in-place look (`'up'`, `'down'`, `'left'` or `'right'`) by
* `angle` radians, as the camera port's `look` turns it: up and down about
* the view's right axis, left and right about its up axis. The eye stays.
* @param {import('./render/contract/camera').CameraPose} pose
* @returns {import('./render/contract/camera').CameraPose} With `direction`,
* `up`, `right` and `pitch` turned; the other angles are not recomputed.
*/
export function lookedPose(pose, look, angle) {
const vertical = look === 'up' || look === 'down';
const axis = vertical ? pose.right : pose.up;
const turn = look === 'up' || look === 'left' ? angle : -angle;
const direction = normalize(rotate(pose.direction, axis, turn));
const next = {
...pose,
direction,
...(vertical
? { up: normalize(rotate(pose.up, axis, turn)) }
: { right: normalize(rotate(pose.right, axis, turn)) }),
};
next.pitch = posePitch(next);
return next;
}
/**
* The pitch of a world-frame pose: its direction's angle above the local
* horizontal at the eye (negative looking down).
* @param {import('./render/contract/camera').CameraPose} pose
*/
export function posePitch(pose) {
return Math.asin(
clamp(dot(pose.direction, geodeticSurfaceNormal(pose.position)), -1, 1),
);
}
const LOOK_EDGE_TOLERANCE = toRadians(0.05);
/**
* How much of one in-place look step (`'up'`, `'down'`, `'left'` or `'right'`
* by a non-negative `angle` in radians) keeps the planet in frame from orbit.
* Above the free-look height the step may not leave less than
* `MIN_GLOBE_FRAME_SHARE` of the visible frame on the planet, or less than
* `startShare` when that is lower, give or take two grid cells of sampling
* noise. However the baseline was taken, it never leaves less than 1% of the
* frame, and a view that already shows less may only keep or gain what it has.
* `startShare` is the baseline the turn is measured against (the current share
* by default): callers pass one value to every step of a motion, and to every
* turn that continues from where the last one left off, so the limit cannot
* slide down a step or a command at a time. `keyholeRadius` limits the measure
* to the scope's visible circle, as in `globeFrameShare`.
* With nothing on screen the limit is nothing either, so the step is left to
* the move-end recovery. Returns `angle` when the whole step fits, otherwise a
* smaller angle that fits, found by bisection to within 0.05°, so a stopped
* motion rests at the limit. Steps are tried on the pose; no camera is moved.
* @param {import('./render/contract/camera').CameraPose} pose
*/
export function lookAngleWithinFrame(
pose,
look,
angle,
{ startShare, keyholeRadius = 0 } = {},
) {
if (!(angle > 0) || !(pose?.height > FREE_LOOK_MAX_HEIGHT_METERS))
return angle;
const sample = sampleFrame(pose, keyholeRadius);
if (!sample || sample.cells === 0) return angle;
const share = sample.hits / sample.cells;
const baseline = startShare ?? share;
// Capped at what is on screen now, so a step that keeps or gains surface is
// never refused, even when the frame has shrunk since the baseline was taken
// (a resized window or a turned phone).
const floor = Math.min(
share,
Math.max(
Math.min(MIN_GLOBE_FRAME_SHARE, baseline) -
GRID_NOISE_CELLS / sample.cells,
Math.min(LOOK_ABSOLUTE_FLOOR_SHARE, baseline),
),
);
// Shares are whole grid cells; the epsilon keeps rounding in `floor` from
// costing a cell.
const fits = (step) =>
globeFrameShare(lookedPose(pose, look, step), { keyholeRadius }) >=
floor - 1e-9;
if (fits(angle)) return angle;
let inside = 0;
let outside = angle;
while (outside - inside > LOOK_EDGE_TOLERANCE) {
const middle = (inside + outside) / 2;
if (fits(middle)) inside = middle;
else outside = middle;
}
return inside;
}
/** True when an in-place look step of `angle` would lose part of its turn. */
export function lookStepLosesGlobe(pose, look, angle, options) {
return lookAngleWithinFrame(pose, look, angle, options) < angle;
}
+8 -1
View File
@@ -232,10 +232,17 @@ test('no unchanged Realtime tool definition drifts silently', () => {
camera.description, camera.description,
'Direct the camera like a drone operator: orbit the current view target, pan, tilt, or rotate — one bounded nudge (mode=once) or continuous motion until stopped (mode=continuous). Continuous motion also stops on any manual camera input or when a navigation tool runs. Say the RESULTING state when confirming ("Orbiting slowly"). Globe rotation (rotate_globe) spins Earth right continuously by default; explicit direction, mode and speed take precedence. It checks fit and may refuse.', 'Direct the camera like a drone operator: orbit the current view target, pan, tilt, or rotate — one bounded nudge (mode=once) or continuous motion until stopped (mode=continuous). Continuous motion also stops on any manual camera input or when a navigation tool runs. Say the RESULTING state when confirming ("Orbiting slowly"). Globe rotation (rotate_globe) spins Earth right continuously by default; explicit direction, mode and speed take precedence. It checks fit and may refuse.',
); );
// Tilt to an angle adds an absolute pitchDeg with its -45° default, and
// names tilt steps among the direction's uses; check them, then restore
// the legacy fields for the pin.
assert.equal( assert.equal(
camera.parameters.properties.direction.description, camera.parameters.properties.direction.description,
'Required for pan/tilt/rotate; orbit/rotate_globe default right.', 'Pan/rotate/tilt steps; orbit/rotate_globe default right.',
); );
assert.equal(camera.parameters.properties.pitchDeg.type, 'number');
assert.match(camera.parameters.properties.pitchDeg.description, /^Absolute;/);
assert.match(camera.parameters.properties.pitchDeg.description, /-45 default/);
delete camera.parameters.properties.pitchDeg;
assert.equal(camera.parameters.properties.mode.description, 'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.'); assert.equal(camera.parameters.properties.mode.description, 'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.');
camera.parameters.properties.mode.description = 'once = bounded eased nudge (default); continuous = until stop/manual input.'; camera.parameters.properties.mode.description = 'once = bounded eased nudge (default); continuous = until stop/manual input.';
camera.parameters.properties.motion.enum = camera.parameters.properties.motion.enum =
+7 -1
View File
@@ -5,7 +5,8 @@
* the viewer behind a renderer it made, the photoreal base tileset the scene * the viewer behind a renderer it made, the photoreal base tileset the scene
* loads into that viewer, and the viewer hooks the scene hands the * loads into that viewer, and the viewer hooks the scene hands the
* application (stale command trimming, inline panel rendering, whether an * application (stale command trimming, inline panel rendering, whether an
* entity is the viewer's own, the zoom-out guard). The scene imports this module and no other * entity is the viewer's own, the zoom-out guard, the free-look height
* limit). The scene imports this module and no other
* part of the adapter (`src/render/noCesiumOutsideRender.test.mjs`). * part of the adapter (`src/render/noCesiumOutsideRender.test.mjs`).
*/ */
import * as Cesium from 'cesium'; import * as Cesium from 'cesium';
@@ -14,6 +15,7 @@ import { loadPhotorealisticTileset } from './google3d.js';
import { keepPanelRendering } from './panelRendering.js'; import { keepPanelRendering } from './panelRendering.js';
import { trimStaleSceneCommands } from './sceneCommandRelease.js'; import { trimStaleSceneCommands } from './sceneCommandRelease.js';
import { installZoomOutGuard } from './zoomOutGuard.js'; import { installZoomOutGuard } from './zoomOutGuard.js';
import { installFreeLookHeightLimit } from './freeLookLimit.js';
export { cesiumRenderer, cesiumViewerOf }; export { cesiumRenderer, cesiumViewerOf };
@@ -59,5 +61,9 @@ export function applicationViewerHooks(viewer) {
// Keeps outward user zooms bounded and the Earth framed; returns its // Keeps outward user zooms bounded and the Earth framed; returns its
// disposer (see zoomOutGuard.js). // disposer (see zoomOutGuard.js).
installZoomOutGuard: (options) => installZoomOutGuard(viewer, options), installZoomOutGuard: (options) => installZoomOutGuard(viewer, options),
// Allows the camera controller's free look only near the ground; returns
// its disposer (see freeLookLimit.js).
installFreeLookHeightLimit: (maxHeight) =>
installFreeLookHeightLimit(viewer, maxHeight),
}; };
} }
+50
View File
@@ -0,0 +1,50 @@
/**
* @module render/cesium/freeLookLimit
* @description Keeps the Cesium camera controller's free look to low
* heights. It writes that controller's own settings, so it lives in the
* adapter; the application installs it through the scene's viewer hooks
* (`application.js`).
*/
/**
* Allow Cesium's free look only below `maxHeight` and return its disposer.
* Orbit, tilt and zoom stay available at every height. A value other code
* sets later is kept as the one to allow below that height, and restored on
* dispose; a `false` written while the camera is above `maxHeight` cannot be
* told apart from this limit's own write, so dispose restores the earlier
* value then. `enableLook` gates the Shift+drag binding only: below its trackball
* height Cesium also turns the camera in place for a drag that starts on the
* stars. That height is lowered to `maxHeight` too, so above it such a drag
* orbits the globe, as it does above Cesium's own 7,500 km.
*/
export function installFreeLookHeightLimit(viewer, maxHeight) {
const scene = viewer?.scene;
const controller = scene?.screenSpaceCameraController;
const camera = viewer?.camera;
if (!controller || !camera || !scene?.preUpdate)
throw new TypeError('A complete Cesium viewer is required');
const originalTrackBallHeight = controller.minimumTrackBallHeight;
const trackBallHeight = Math.min(originalTrackBallHeight, maxHeight);
controller.minimumTrackBallHeight = trackBallHeight;
let wanted = controller.enableLook;
let written;
const sync = () => {
if (written !== undefined && controller.enableLook !== written)
wanted = controller.enableLook;
const height = camera.positionCartographic?.height;
written = wanted && !(Number.isFinite(height) && height > maxHeight);
controller.enableLook = written;
};
sync();
const removeListener = scene.preUpdate.addEventListener(sync);
let active = true;
return () => {
if (!active) return;
active = false;
removeListener();
if (controller.enableLook === written) controller.enableLook = wanted;
if (controller.minimumTrackBallHeight === trackBallHeight)
controller.minimumTrackBallHeight = originalTrackBallHeight;
};
}
+1 -1
View File
@@ -6,7 +6,7 @@
export class ShellFacade { export class ShellFacade {
/** Observe camera ownership transfers through the navigation owner. */ /** Observe camera ownership transfers through the navigation owner. */
subscribeCameraHandoff(listener) { subscribeCameraHandoff(listener) {
return this._navigation.subscribeCameraHandoff(listener); return this._navigation?.subscribeCameraHandoff(listener);
} }
get _models3dEnabled() { get _models3dEnabled() {
+33
View File
@@ -0,0 +1,33 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import { ShellFacade } from './shellFacade.js';
// A shell assembled without its navigation owner (as unit tests build one
// from the prototype) has no handoffs to report, like the facade's other
// optional owners; the voice runner subscribes as it is created.
test('camera handoffs without a navigation owner subscribe to nothing', () => {
const shell = Object.create(ShellFacade.prototype);
assert.equal(
shell.subscribeCameraHandoff(() => {}),
undefined,
);
});
test('camera handoffs reach listeners through the navigation owner', () => {
const listeners = new Set();
const shell = Object.create(ShellFacade.prototype);
shell._navigation = {
subscribeCameraHandoff(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
},
};
let handoffs = 0;
const unsubscribe = shell.subscribeCameraHandoff(() => {
handoffs += 1;
});
for (const listener of listeners) listener();
assert.equal(handoffs, 1);
unsubscribe();
assert.equal(listeners.size, 0);
});
+1
View File
@@ -753,6 +753,7 @@ const schemas = [
type: 'string', type: 'string',
enum: ['once', 'continuous'], enum: ['once', 'continuous'],
}, },
pitchDeg: { type: 'number' },
}, },
required: ['motion'], required: ['motion'],
}, },
+17 -1
View File
@@ -56,7 +56,9 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
// area scopes and the osm-places layer; natural-region candidates and the // area scopes and the osm-places layer; natural-region candidates and the
// tightened area tool wording follow review. // tightened area tool wording follow review.
// control_cockpit states the own-layer entry rule (Contacts not required). // control_cockpit states the own-layer entry rule (Contacts not required).
'9522ff6f6d640bede81c51cea6b9601439b08becc5bc20b7355aec24feb17e8d', // move_camera tilt takes an optional pitchDeg angle, described as
// absolute with its -45 default, with steps sent as a direction.
'6a0d154e68beb787c4e20f12d29a5c86577dc343f3e71d8b5651998ea45d8c3c',
); );
}); });
@@ -175,6 +177,8 @@ test('all legacy action arguments are byte-identical after removing the delibera
'stop', 'stop',
]); ]);
motion.enum = motion.enum.filter((value) => value !== 'rotate_globe'); motion.enum = motion.enum.filter((value) => value !== 'rotate_globe');
// Tilt to an angle is additive.
delete property('move_camera').pitchDeg;
const panels = property('set_panel_open').panelId; const panels = property('set_panel_open').panelId;
panels.enum = panels.enum.filter( panels.enum = panels.enum.filter(
(id) => (id) =>
@@ -320,3 +324,15 @@ test('direct voice timeout schema accepts None and exact integers, rejects malfo
for (const minutes of [-1, 61, 1.5, '5']) for (const minutes of [-1, 61, 1.5, '5'])
assert.ok(validateArgs(tool.parameters, { minutes }).length > 0); assert.ok(validateArgs(tool.parameters, { minutes }).length > 0);
}); });
test('tilt accepts an angle with no direction', () => {
const schema = GEV_ACTION_SCHEMAS.find(
(tool) => tool.name === 'move_camera',
).parameters;
assert.deepEqual(validateArgs(schema, { motion: 'tilt', pitchDeg: -45 }), []);
assert.deepEqual(validateArgs(schema, { motion: 'tilt' }), []);
// No range in the schema (prompt budget): the runner clamps to -89..-5.
assert.ok(
validateArgs(schema, { motion: 'tilt', pitchDeg: 'steep' }).length > 0,
);
});
+9
View File
@@ -184,6 +184,9 @@ export class GeminiSessionController {
this.model = null; this.model = null;
this.epoch = 0; this.epoch = 0;
this.turn = 0; this.turn = 0;
// Identifies one turn's tool calls to the runner as one reply; a new
// object each turn, so no two sessions or turns share it.
this.turnReply = {};
this.globeToolsBlocked = false; this.globeToolsBlocked = false;
this.globeResetFailed = false; this.globeResetFailed = false;
this.inputGeneration = 0; this.inputGeneration = 0;
@@ -971,6 +974,7 @@ export class GeminiSessionController {
const tools = [...this.tools.values()]; const tools = [...this.tools.values()];
this.turnAbort = new AbortController(); this.turnAbort = new AbortController();
this.turn++; this.turn++;
this.turnReply = {};
this.typedIntent = null; this.typedIntent = null;
this.radioStrongerCommit = null; this.radioStrongerCommit = null;
this.pruneControls(); this.pruneControls();
@@ -1544,6 +1548,7 @@ export class GeminiSessionController {
) )
throw new Error(msg('Gemini requested too many simultaneous actions')); throw new Error(msg('Gemini requested too many simultaneous actions'));
const turn = this.turn; const turn = this.turn;
const reply = this.turnReply;
this.userTurnPending = false; this.userTurnPending = false;
this.modelComplete = false; this.modelComplete = false;
// Admit each valid native call ID once per connection. // Admit each valid native call ID once per connection.
@@ -1565,6 +1570,7 @@ export class GeminiSessionController {
const action = new AbortController(); const action = new AbortController();
action.call = { id: call.id, name: call.name }; action.call = { id: call.id, name: call.name };
action.sequence = ++this.toolSequence; action.sequence = ++this.toolSequence;
action.reply = reply;
this.tools.set(call.id, action); this.tools.set(call.id, action);
const priorTools = this.toolQueue; const priorTools = this.toolQueue;
const args = const args =
@@ -1674,6 +1680,9 @@ export class GeminiSessionController {
this.runAction(call.name, args, { this.runAction(call.name, args, {
signal: toolSignal, signal: toolSignal,
callId: call.id, callId: call.id,
// Calls run one by one, so a motion can follow a fly-to of the
// same reply that already found nothing.
reply: action.reply,
progress: (update) => { progress: (update) => {
if (actionCurrent()) this.narration.progress(call.id, update); if (actionCurrent()) this.narration.progress(call.id, update);
}, },
+28
View File
@@ -1241,6 +1241,34 @@ test('successful stronger Radio stop still invalidates the prepared group', asyn
h.c.stop(); h.c.stop();
}); });
test('Gemini tools of one turn share a reply identity, and a new turn gets another', async () => {
const replies = [];
const h = harness({
runAction: (name, _args, next) => {
replies.push([name, next.reply]);
return { ok: true, action: name };
},
});
await h.c.start({ pushToTalk: true });
h.c.sendTextCommand('Fly to Xyzzyville and pan left');
const ws = h.sockets[0];
requestTool(ws, 'fly', 'fly_to_location', { query: 'Xyzzyville' });
requestTool(ws, 'pan', 'move_camera', { motion: 'pan', direction: 'left' });
await h.c.toolQueue;
assert.equal(replies.length, 2);
assert.ok(replies[0][1], 'a sequentially run call carries its reply');
assert.equal(replies[1][1], replies[0][1]);
drainRadioReply(h);
await tick();
assert.equal(h.c.sendTextCommand('Pan left'), true);
requestTool(ws, 'pan-2', 'move_camera', { motion: 'pan', direction: 'left' });
await h.c.toolQueue;
assert.equal(replies.length, 3);
assert.ok(replies[2][1]);
assert.notEqual(replies[2][1], replies[0][1]);
h.c.stop();
});
test('slow Gemini tools reuse shared progress timing without injecting a conversation turn', async () => { test('slow Gemini tools reuse shared progress timing without injecting a conversation turn', async () => {
const pending = deferred(); const pending = deferred();
let options; let options;
+328 -17
View File
@@ -62,6 +62,9 @@ import {
flyRoute, flyRoute,
interruptCameraMotion, interruptCameraMotion,
adjustOrbitRange, adjustOrbitRange,
manualCameraInputCount,
moveCameraArgsError,
getActiveCameraMotion,
} from '../cameraVerbs.js'; } from '../cameraVerbs.js';
import * as defaultFloorServices from '../data/groundFloor.js'; import * as defaultFloorServices from '../data/groundFloor.js';
import { isPickedWorldPosition } from '../data/scenePick.js'; import { isPickedWorldPosition } from '../data/scenePick.js';
@@ -301,6 +304,28 @@ export function createGevActionRunner({
? { ...SPEECH_BUILDERS, ...speechBuilders } ? { ...SPEECH_BUILDERS, ...speechBuilders }
: SPEECH_BUILDERS; : SPEECH_BUILDERS;
const _layerEnabledAt = new Map(); const _layerEnabledAt = new Map();
// The latest voice flight. A tilt, orbit, pan or rotate in the same reply
// as "fly to X" waits for it to land: run at once, its navigation
// cancelled the flight, or the flight (still geocoding) then replaced the
// motion. The wait follows later fly-tos (voiceFlightTarget).
let voiceFlight = null;
// Waiters to tell when a newer voice flight begins.
const voiceFlightWatchers = new Set();
// Camera handoffs (navigation stamps) seen, and how many of them voice
// fly-tos made. A search, share link or import that stamps during a flight
// leaves it flying; the motion queued behind it then yields to that one.
// The voice fly-tos of the latest reply that sent one: whether any moved
// the camera, and whether one found nothing. A motion of that reply run
// after its fly-to found nothing (Gemini runs a reply's calls one by one)
// has no flight to wait on, and must not move the old view instead.
let replyFlights = null;
let cameraHandoffs = 0;
let voiceFlightHandoffs = 0;
const otherHandoffs = () => cameraHandoffs - voiceFlightHandoffs;
const unsubscribeCameraHandoff =
styleManager?.subscribeCameraHandoff?.(() => {
cameraHandoffs += 1;
}) ?? null;
let analystEngine; let analystEngine;
// Area handles live for this runner (the page): resolve_area, the // Area handles live for this runner (the page): resolve_area, the
// analyst's region/area/drawn scopes, find_imagery and osm_query all read // analyst's region/area/drawn scopes, find_imagery and osm_query all read
@@ -442,13 +467,30 @@ export function createGevActionRunner({
const zoomOut = String(args.direction || '').toLowerCase() === 'out'; const zoomOut = String(args.direction || '').toLowerCase() === 'out';
const amt = String(args.amount || 'medium').toLowerCase(); const amt = String(args.amount || 'medium').toLowerCase();
const factor = { little: 1.25, medium: 1.6, lot: 2.4 }[amt] || 1.6; const factor = { little: 1.25, medium: 1.6, lot: 2.4 }[amt] || 1.6;
if (adjustOrbitRange(zoomOut ? factor : 1 / factor)) { const held = adjustOrbitRange(zoomOut ? factor : 1 / factor);
if (held) {
const direction = zoomOut ? 'out' : 'in';
if (!held.changed) {
return {
ok: false,
action: 'adjust_camera_zoom',
direction,
amount: amt,
error: `Not zoomed: the ${held.kind} is already at its ${zoomOut ? 'farthest' : 'closest'} range.`,
};
}
return { return {
ok: true, ok: true,
action: 'adjust_camera_zoom', action: 'adjust_camera_zoom',
direction: zoomOut ? 'out' : 'in', direction,
amount: amt, amount: amt,
orbitRadiusAdjusted: true, [held.kind === 'tilt' ? 'tiltRangeAdjusted' : 'orbitRadiusAdjusted']:
true,
// A tilt to an angle names the angle the new range now ends it at.
...(held.pitchDeg !== undefined && {
pitchDeg: held.pitchDeg,
note: held.note,
}),
}; };
} }
} }
@@ -1140,34 +1182,104 @@ export function createGevActionRunner({
runOptions, runOptions,
); );
} }
return flyToRequestedLocation(viewer, args, { // Chained fly-tos: a grab during an earlier one still flying counts.
// The flight replaced is the last one that moved, past lookups that
// found nothing.
const prior = voiceFlightTarget(voiceFlight);
const flight = trackVoiceFlight(
prior && !prior.done ? prior.inputCount : undefined,
prior,
);
// Navigation by anything but a voice fly-to since this one began.
flight.handoffs = otherHandoffs();
voiceFlight = flight;
const reply = voiceReplyOf(runOptions);
if (reply !== null && replyFlights?.reply !== reply)
replyFlights = { reply, moved: false, foundNothing: false };
const replyRecord = reply !== null ? replyFlights : null;
for (const notify of [...voiceFlightWatchers]) notify();
// A motion already running (one the model sent before this fly-to) is
// stopped when the flight takes navigation; the result says so.
let stoppedMotion = null;
const noteStop =
(hook) =>
(...hookArgs) => {
const before = getActiveCameraMotion();
const handoffsBefore = cameraHandoffs;
try {
return hook(...hookArgs);
} finally {
// A voice fly-to's own stamps are not another navigation, even
// for the flight it replaces (a later lookup may find nothing).
voiceFlightHandoffs += cameraHandoffs - handoffsBefore;
if (
before &&
!stoppedMotion &&
getActiveCameraMotion()?.motionId !== before.motionId
)
stoppedMotion = before.kind;
}
};
const flown = flyToRequestedLocation(viewer, args, {
onFlightEnd: flight.settle,
onProgress: reportProgress, onProgress: reportProgress,
placeSearch, placeSearch,
searchNavigation, searchNavigation,
signal: runOptions.signal, signal: runOptions.signal,
runImmediate: runImmediate:
typeof styleManager?.runImmediateLocationNavigation === 'function' typeof styleManager?.runImmediateLocationNavigation === 'function'
? (navigate) => ? noteStop((navigate) =>
styleManager.runImmediateLocationNavigation(navigate) styleManager.runImmediateLocationNavigation(navigate),
)
: null, : null,
beginDeferred: beginDeferred:
typeof styleManager?.beginDeferredLocationNavigation === 'function' typeof styleManager?.beginDeferredLocationNavigation === 'function'
? () => styleManager.beginDeferredLocationNavigation() ? noteStop(() => styleManager.beginDeferredLocationNavigation())
: null, : null,
reassertDeferred: reassertDeferred:
typeof styleManager?.reassertDeferredLocationNavigation === 'function' typeof styleManager?.reassertDeferredLocationNavigation === 'function'
? (generation) => ? noteStop((generation) =>
styleManager.reassertDeferredLocationNavigation(generation) styleManager.reassertDeferredLocationNavigation(generation),
)
: null, : null,
onStart: () => { onStart: noteStop(() => {
if (typeof styleManager?.beginLocationNavigation === 'function') { if (typeof styleManager?.beginLocationNavigation === 'function') {
styleManager.beginLocationNavigation(); styleManager.beginLocationNavigation();
return; return;
} }
interruptCameraMotion('nav:fly_to_location'); interruptCameraMotion('nav:fly_to_location');
if (isFollowing(viewer)) stopAllTracking(viewer, dataManager); if (isFollowing(viewer)) stopAllTracking(viewer, dataManager);
}, }),
}); });
// No flight started: nothing to wait for. A lookup that was not found,
// threw, or was cancelled once a newer voice fly-to had begun (which
// takes navigation from it) moved nothing, so a queued motion looks
// past it to the flight it replaced. One cancelled while still the
// latest voice flight lost navigation to something else (a search, a
// share link, Cockpit): the motion then refuses. A flight its own hooks
// already settled (cancelled mid-air) keeps its status.
const notStarted = () => {
if (!flight.done) flight.movedNothing = true;
flight.settle('failed');
};
flown.then((result) => {
if (result?.ok === true) return;
if (result?.cancelled && voiceFlight === flight)
flight.settle('failed');
else notStarted();
}, notStarted);
// After the outcome above, which marks a lookup that moved nothing.
const noteReply = (result) => {
if (!replyRecord) return;
if (result?.ok === true) replyRecord.moved = true;
else if (flight.movedNothing) replyRecord.foundNothing = true;
};
flown.then(noteReply, () => noteReply(null));
return flown.then((result) =>
stoppedMotion && result && typeof result === 'object'
? { ...result, stoppedMotion }
: result,
);
} }
if (name === 'adjust_camera_zoom') { if (name === 'adjust_camera_zoom') {
@@ -1269,6 +1381,85 @@ export function createGevActionRunner({
} }
if (name === 'move_camera') { if (name === 'move_camera') {
const motion = String(args.motion || '').toLowerCase();
// A lookup that already found nothing does not hide the last flight
// that moved: running now would cancel that flight mid-air.
const pending = voiceFlightTarget(voiceFlight);
const reply = voiceReplyOf(runOptions);
if (
VOICE_FLIGHT_WAITING_MOTIONS.has(motion) &&
!(pending && !pending.done) &&
reply !== null &&
replyFlights?.reply === reply &&
replyFlights.foundNothing &&
!replyFlights.moved
)
return {
ok: false,
action: 'move_camera',
motion,
error: `Not run: the fly-to in this reply found nothing, so the ${motion} was not run at the old view.`,
};
if (
VOICE_FLIGHT_WAITING_MOTIONS.has(motion) &&
pending &&
!pending.done
) {
// Bad arguments are refused now, not after waiting on the flight.
const argsError = moveCameraArgsError(args);
if (argsError) return argsError;
const deadline = Date.now() + VOICE_FLIGHT_WAIT_MS;
const start = pending;
// Act on where the camera lands. Whatever a flight reports, a later
// fly-to replaces it, and the wait moves to that one as soon as it
// begins (a stalled geocode must not hold the motion past a newer
// flight that landed). A geocode that loses navigation reports
// failed, and a flight left flying while the next place is looked up
// can still land; running there would take navigation and cancel the
// newer one. A later lookup that found nothing moved nothing, so the
// motion looks past it to the last flight that did move the camera.
let flight = start;
let status;
for (;;) {
status = await waitForVoiceFlight(
flight,
runOptions.signal,
deadline,
voiceFlightWatchers,
);
if (status === 'aborted' || status === 'timeout' || !current()) break;
const target = voiceFlightTarget(voiceFlight, start);
if (!target || (target === flight && status !== 'newer')) break;
flight = target;
}
if (!current())
return { ok: false, action: 'move_camera', cancelled: true };
if (status !== 'arrived' || flight.movedNothing)
return {
ok: false,
action: 'move_camera',
motion,
error: `Not run: the flight this ${motion} was waiting for did not arrive.`,
};
// The flight lands even when the user grabs the globe mid-flight;
// the queued motion must not take the camera back from them.
if (manualCameraInputCount() !== flight.inputCount)
return {
ok: false,
action: 'move_camera',
motion,
error: `Not run: the user moved the camera during the flight, so the ${motion} was dropped.`,
};
// A search, share link or import that took navigation during the
// flight leaves it flying; running now would cancel that navigation.
if (otherHandoffs() !== flight.handoffs)
return {
ok: false,
action: 'move_camera',
motion,
error: `Not run: another navigation took the camera during the flight, so the ${motion} was dropped.`,
};
}
return moveCamera(args, (navigate, releaseOptions) => return moveCamera(args, (navigate, releaseOptions) =>
runManagedVoiceNavigation( runManagedVoiceNavigation(
styleManager, styleManager,
@@ -1584,6 +1775,7 @@ export function createGevActionRunner({
* forget the analyst's "last answer". Area handles stay (page lifetime). * forget the analyst's "last answer". Area handles stay (page lifetime).
*/ */
runVoiceAction.resetConversation = () => { runVoiceAction.resetConversation = () => {
replyFlights = null;
conversationAbort.abort(); conversationAbort.abort();
conversationAbort = new AbortController(); conversationAbort = new AbortController();
conversation++; conversation++;
@@ -1597,6 +1789,7 @@ export function createGevActionRunner({
if (disposed) return; if (disposed) return;
runVoiceAction.resetConversation(); runVoiceAction.resetConversation();
disposed = true; disposed = true;
unsubscribeCameraHandoff?.();
voiceAreas.dispose(); voiceAreas.dispose();
}; };
return runVoiceAction; return runVoiceAction;
@@ -2872,6 +3065,116 @@ async function frameOverhead(viewer, dataManager, styleManager, args = {}) {
); );
} }
let voiceFlightCount = 0;
/**
* The model reply a voice call belongs to: Gemini's turn (`reply`), or the
* OpenAI response its sibling calls share (`authorityGroup`). Null when the
* caller names none.
*/
function voiceReplyOf(options) {
return options?.reply ?? options?.authorityGroup ?? null;
}
/**
* A voice flight's end: 'arrived', 'cancelled' or 'failed', settled once.
* `replaced` is the last flight that moved when this one began (past lookups
* that found nothing), landed or not. It is kept only while this one may turn
* out to have moved nothing (a lookup that found no place), so a queued
* motion can look past it to that flight and its outcome.
*/
function trackVoiceFlight(
inputCount = manualCameraInputCount(),
replaced = null,
) {
const flight = {
done: false,
seq: (voiceFlightCount += 1),
replaced,
movedNothing: false,
// Manual input after this means the user took the camera mid-flight.
inputCount,
status: null,
// Waiters to tell when this flight ends.
watchers: new Set(),
settle: (status) => {
if (flight.done) return;
flight.done = true;
flight.status = status;
// Kept only past a lookup that found nothing, and then straight to the
// flight that moved, so a run of such lookups holds no chain.
flight.replaced = flight.movedNothing
? voiceFlightTarget(flight.replaced)
: null;
for (const notify of [...flight.watchers]) notify(status);
flight.watchers.clear();
},
};
return flight;
}
/**
* The flight a motion queued since `start` acts on: the latest one that
* actually started. A lookup that found nothing moved nothing, so look past
* it to the flight it replaced, but never to one older than `start` (a flight
* from an earlier reply). Null when every later lookup found nothing. With
* no `start`, the latest flight that started, back through lookups that
* found nothing.
*/
function voiceFlightTarget(latest, start = null) {
let flight = latest;
while (flight?.movedNothing) flight = flight.replaced;
return flight && (!start || flight.seq >= start.seq) ? flight : null;
}
/**
* Longest a motion waits for its flight (geocode plus flight, which is about
* 2 s) before giving up. The wait also holds the tool output, and on Gemini
* the later tools in the turn.
*/
const VOICE_FLIGHT_WAIT_MS = 15_000;
/**
* Motions that act on the place the camera ends up at, so one sent beside a
* fly-to waits for it. Stop is not one, and rotate_globe turns the
* whole Earth from Globe View rather than at a place.
*/
const VOICE_FLIGHT_WAITING_MOTIONS = new Set([
'tilt',
'orbit',
'pan',
'rotate',
]);
/**
* Wait for a voice flight to end, or for a newer one to begin ('newer'):
* 'timeout' or 'aborted' if neither happens. A flight that has ended answers
* at once. Every listener is removed when the wait ends, so a flight that
* never settles holds nothing.
*/
function waitForVoiceFlight(flight, signal, deadline, newerWatchers) {
if (signal?.aborted) return Promise.resolve('aborted');
if (flight.done) return Promise.resolve(flight.status);
return new Promise((resolve) => {
const finish = (status) => {
clearTimeout(timer);
signal?.removeEventListener?.('abort', onAbort);
flight.watchers.delete(finish);
newerWatchers?.delete(onNewer);
resolve(status);
};
const onAbort = () => finish('aborted');
const onNewer = () => finish('newer');
const timer = setTimeout(
() => finish('timeout'),
Math.max(0, deadline - Date.now()),
);
signal?.addEventListener?.('abort', onAbort, { once: true });
flight.watchers.add(finish);
newerWatchers?.add(onNewer);
});
}
/** Run one validated voice camera mutation through the UI-owned authority seam. */ /** Run one validated voice camera mutation through the UI-owned authority seam. */
function runManagedVoiceNavigation( function runManagedVoiceNavigation(
styleManager, styleManager,
@@ -3454,6 +3757,7 @@ async function flyToRequestedLocation(
runImmediate = null, runImmediate = null,
beginDeferred = null, beginDeferred = null,
reassertDeferred = null, reassertDeferred = null,
onFlightEnd = null,
} = {}, } = {},
) { ) {
const requestedRangeM = Number(args.rangeM); const requestedRangeM = Number(args.rangeM);
@@ -3477,12 +3781,19 @@ async function flyToRequestedLocation(
settleArrival = resolve; settleArrival = resolve;
}) })
: null; : null;
const arrivalHooks = arrival const arrivalHooks =
? { arrival || onFlightEnd
onComplete: () => settleArrival?.('arrived'), ? {
onCancel: () => settleArrival?.('cancelled'), onComplete: () => {
} settleArrival?.('arrived');
: {}; onFlightEnd?.('arrived');
},
onCancel: () => {
settleArrival?.('cancelled');
onFlightEnd?.('cancelled');
},
}
: {};
const afterArrival = async (result, label) => { const afterArrival = async (result, label) => {
if (!arrival || result?.ok !== true) return result; if (!arrival || result?.ok !== true) return result;
onProgress('fly', label); onProgress('fly', label);
+853 -5
View File
@@ -148,6 +148,14 @@ test('track_entity runner narrates a callsign-less aircraft by its registration'
function createVoiceNavigationHarness({ cockpitActive = false } = {}) { function createVoiceNavigationHarness({ cockpitActive = false } = {}) {
const order = []; const order = [];
let generation = 0; let generation = 0;
// Camera handoffs, published on every navigation stamp as the shell does.
const handoffListeners = new Set();
const stamp = (noun) => {
generation += 1;
order.push(`stamp:${noun}`);
for (const listener of [...handoffListeners]) listener({ generation });
return generation;
};
const position = Cesium.Cartesian3.fromDegrees(-97.74, 30.26, 500); const position = Cesium.Cartesian3.fromDegrees(-97.74, 30.26, 500);
const viewer = { const viewer = {
trackedEntity: { id: 'prior-aircraft' }, trackedEntity: { id: 'prior-aircraft' },
@@ -185,11 +193,7 @@ function createVoiceNavigationHarness({ cockpitActive = false } = {}) {
return runExplicitNavigation({ return runExplicitNavigation({
cockpitActive, cockpitActive,
noun, noun,
stamp: () => { stamp: () => stamp(noun),
generation += 1;
order.push(`stamp:${noun}`);
return generation;
},
release: () => { release: () => {
order.push('release'); order.push('release');
viewer.trackedEntity = undefined; viewer.trackedEntity = undefined;
@@ -201,12 +205,21 @@ function createVoiceNavigationHarness({ cockpitActive = false } = {}) {
}); });
}, },
getDetectionState: () => ({ detectionMode: 'DENSE' }), getDetectionState: () => ({ detectionMode: 'DENSE' }),
subscribeCameraHandoff(listener) {
handoffListeners.add(listener);
return () => handoffListeners.delete(listener);
},
// A voice lookup stamps when it begins and leaves any flight flying.
beginDeferredLocationNavigation: () => stamp('location-lookup'),
reassertDeferredLocationNavigation: (stamped) => stamped === generation,
}; };
return { return {
order, order,
viewer, viewer,
styleManager, styleManager,
currentGeneration: () => generation, currentGeneration: () => generation,
// A location-panel search: a deferred stamp that leaves a flight flying.
panelSearch: () => stamp('panel-search'),
}; };
} }
@@ -282,6 +295,841 @@ test('dependent voice navigation waits for the destination viewport to arrive',
assert.equal(result.arrived, true); assert.equal(result.arrived, true);
}); });
// "fly to London and tilt the camera" arrives as two sibling calls.
// Run at once, the tilt's navigation cancelled the flight; with a geocoded
// place, the late flight replaced the tilt.
function tiltAfterFlightHarness() {
globalThis.window = globalThis.window || { clearTimeout, setTimeout, requestIdleCallback: null };
const harness = createVoiceNavigationHarness();
const { viewer, styleManager } = harness;
const flights = [];
viewer.camera.flyTo = (options) => {
harness.order.push('fly');
flights.push(options);
};
styleManager.runImmediateLocationNavigation = (navigate) => (
styleManager.runImmediateNavigation('location', navigate)
);
return { ...harness, flights };
}
const settledYet = (promise) => {
let settled = false;
promise.then(() => { settled = true; });
return () => settled;
};
test('a tilt in the same reply as a fly-to waits for the flight to land', async () => {
const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
const fly = await runner('fly_to_location', { locationId: 'austin' });
assert.equal(fly.ok, true);
const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
const tiltDone = settledYet(tilt);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(tiltDone(), false, 'the tilt must wait while the camera flies');
assert.equal(
order.slice(order.indexOf('fly')).includes('cancel'),
false,
'the tilt must not cancel the flight',
);
flights[0].complete();
const result = await tilt;
assert.equal(result.ok, true);
assert.equal(result.motion, 'tilt');
});
test('a tilt waits through a geocoded fly-to search, then for its flight', async () => {
const { viewer, styleManager } = tiltAfterFlightHarness();
let finishSearch;
let landFlight;
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
finishSearch = () => {
landFlight = options.onComplete;
resolve({ label: query, navigationMode: 'city-overview' });
};
}),
});
const fly = runner('fly_to_location', { query: 'Somewhere Far' });
const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
const tiltDone = settledYet(tilt);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(tiltDone(), false, 'the tilt must wait for the place lookup');
finishSearch();
assert.equal((await fly).ok, true);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(tiltDone(), false, 'the tilt must wait for the flight too');
landFlight();
assert.equal((await tilt).ok, true);
});
test('a tilt waiting on a flight that never lands is not run', async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
await runner('fly_to_location', { locationId: 'austin' });
const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
flights[0].cancel();
const result = await tilt;
assert.equal(result.ok, false);
assert.match(result.error, /did not arrive/);
});
test('a tilt beside a fly-to that found nothing is not run', async () => {
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: async () => null,
});
const fly = runner('fly_to_location', { query: 'Nowhere' });
const tilt = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
assert.equal((await fly).ok, false);
// Nothing flew: the tilt answers at once and honestly, never at the old view.
const result = await tilt;
assert.equal(result.ok, false);
assert.match(result.error, /did not arrive/);
// A later, separate tilt is not held by the failed lookup.
assert.equal((await runner('move_camera', { motion: 'tilt', pitchDeg: -45 })).ok, true);
});
test('a tilt with no voice flight pending runs at once', async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
await runner('fly_to_location', { locationId: 'austin' });
flights[0].complete();
const result = await runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
assert.equal(result.ok, true);
});
// Orbit, pan and rotate also act at the place the camera ends up, so "fly to
// Paris and orbit it" holds the orbit the same way.
for (const motion of [
{ motion: 'orbit' },
{ motion: 'pan', direction: 'left' },
{ motion: 'rotate', direction: 'right' },
]) {
test(`${motion.motion} in the same reply as a fly-to waits for the flight to land`, async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', motion);
const movedDone = settledYet(moved);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, `the ${motion.motion} must wait while the camera flies`);
assert.equal(
order.slice(order.indexOf('fly')).includes('cancel'),
false,
`the ${motion.motion} must not cancel the flight`,
);
flights[0].complete();
const result = await moved;
assert.equal(result.ok, true);
assert.equal(result.motion, motion.motion);
});
test(`${motion.motion} waits through a geocoded fly-to search, then for its flight`, async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager } = tiltAfterFlightHarness();
let finishSearch;
let landFlight;
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
finishSearch = () => {
landFlight = options.onComplete;
resolve({ label: query, navigationMode: 'city-overview' });
};
}),
});
const fly = runner('fly_to_location', { query: 'Somewhere Far' });
const moved = runner('move_camera', motion);
const movedDone = settledYet(moved);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, `the ${motion.motion} must wait for the place lookup`);
assert.equal(getActiveCameraMotion(), null, 'nothing moves before the flight');
finishSearch();
assert.equal((await fly).ok, true);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, `the ${motion.motion} must wait for the flight too`);
landFlight();
assert.equal((await moved).ok, true);
assert.equal(getActiveCameraMotion()?.kind, motion.motion);
});
test(`${motion.motion} waiting on a flight that never lands is not run`, async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
await runner('fly_to_location', { locationId: 'austin' });
const moved = runner('move_camera', motion);
flights[0].cancel();
const result = await moved;
assert.equal(result.ok, false);
assert.equal(result.motion, motion.motion);
assert.match(result.error, new RegExp(`this ${motion.motion} was waiting for did not arrive`));
assert.equal(getActiveCameraMotion(), null);
});
}
// Cesium lands a flight even when the user grabs the globe mid-flight, so the
// motion queued behind it must not then take the camera back.
for (const motion of [
{ motion: 'orbit' },
{ motion: 'tilt', pitchDeg: -45 },
]) {
test(`${motion.motion} queued behind a fly-to is dropped when the user drags mid-flight`, async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const canvasListeners = new Map();
viewer.scene.canvas.addEventListener = (type, listener) => {
canvasListeners.set(type, listener);
};
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', motion);
canvasListeners.get('pointerdown')();
flights[0].complete();
const result = await moved;
assert.equal(result.ok, false);
assert.equal(result.motion, motion.motion);
assert.match(result.error, /moved the camera during the flight/);
assert.equal(getActiveCameraMotion(), null);
});
}
test('a drag during the first of two chained fly-tos still drops the queued motion', async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const canvasListeners = new Map();
viewer.scene.canvas.addEventListener = (type, listener) => {
canvasListeners.set(type, listener);
};
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
canvasListeners.get('touchstart')();
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' });
flights.at(-1).complete();
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /moved the camera during the flight/);
});
test('input before a fly-to does not drop the motion queued behind it', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const canvasListeners = new Map();
viewer.scene.canvas.addEventListener = (type, listener) => {
canvasListeners.set(type, listener);
};
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
canvasListeners.get('wheel')();
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' });
flights[0].complete();
assert.equal((await moved).ok, true);
});
test('a motion follows a later fly-to in the same reply that cancels its flight', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' });
const movedDone = settledYet(moved);
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
// The second flight supersedes the first, as Cesium's flyTo does.
flights[0].cancel();
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, 'the orbit must wait for the second flight');
flights[1].complete();
const result = await moved;
assert.equal(result.ok, true);
assert.equal(result.motion, 'orbit');
});
test('a motion follows a later fly-to whose start cancels its geocode', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
const flyA = runner('fly_to_location', { query: 'Place A' });
const moved = runner('move_camera', { motion: 'orbit' });
const movedDone = settledYet(moved);
const flyB = runner('fly_to_location', { query: 'Place B' });
await new Promise((resolve) => setTimeout(resolve, 0));
// B takes navigation authority, so A's lookup comes back cancelled.
searches[0].resolve({ cancelled: true });
assert.equal((await flyA).cancelled, true);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, 'the orbit must follow B, not drop');
searches[1].resolve({ label: 'Place B', navigationMode: 'city-overview' });
assert.equal((await flyB).ok, true);
searches[1].options.onComplete();
const result = await moved;
assert.equal(result.ok, true);
assert.equal(result.motion, 'orbit');
});
test('a motion does not run at a flight that lands while the next place is looked up', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
const movedDone = settledYet(moved);
const flyB = runner('fly_to_location', { query: 'Place B' });
await new Promise((resolve) => setTimeout(resolve, 0));
// Deferred navigation leaves A flying while B is looked up, and A lands.
const before = order.length;
flights[0].complete();
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, 'the tilt must wait for B');
assert.equal(
order.slice(before).includes('cancel'),
false,
'the tilt must not take navigation and cancel B',
);
searches[0].resolve({ label: 'Place B', navigationMode: 'city-overview' });
assert.equal((await flyB).ok, true);
searches[0].options.onComplete();
const result = await moved;
assert.equal(result.ok, true);
assert.equal(result.motion, 'tilt');
});
// A later fly-to that finds nothing moves nothing: the motion still runs where
// the earlier flight lands, whether the lookup fails before or after that.
for (const order of ['lands first', 'not found first']) {
test(`a motion runs at its flight when a later fly-to finds nothing (${order})`, async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const harness = tiltAfterFlightHarness();
const { viewer, styleManager, flights } = harness;
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
const flyB = runner('fly_to_location', { query: 'Nowhere' });
await new Promise((resolve) => setTimeout(resolve, 0));
if (order === 'lands first') flights[0].complete();
searches[0].resolve(null);
assert.equal((await flyB).ok, false);
if (order !== 'lands first') flights[0].complete();
const result = await moved;
assert.equal(result.ok, true, result.error);
assert.equal(result.motion, 'tilt');
});
}
test('a motion beside a fly-to that finds nothing never acts at an earlier reply\'s flight', async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
// Reply 1: "fly to Austin", still flying.
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
// Reply 2: "fly to Nowhere and tilt".
const flyB = runner('fly_to_location', { query: 'Nowhere' });
const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
await new Promise((resolve) => setTimeout(resolve, 0));
searches[0].resolve(null);
assert.equal((await flyB).ok, false);
flights[0].complete();
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /did not arrive/);
});
// Two later lookups that both find nothing, in either order, leave the motion
// acting where the first flight landed.
for (const first of [0, 1]) {
test(`a motion looks past two lookups that found nothing (lookup ${first + 1} fails first)`, async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' });
const flyB = runner('fly_to_location', { query: 'Nowhere B' });
const flyC = runner('fly_to_location', { query: 'Nowhere C' });
await new Promise((resolve) => setTimeout(resolve, 0));
searches[first].resolve(null);
searches[1 - first].resolve(null);
assert.equal((await flyB).ok, false);
assert.equal((await flyC).ok, false);
flights[0].complete();
const result = await moved;
assert.equal(result.ok, true, result.error);
});
}
test('a lookup cancelled by a newer one that finds nothing does not hide the flight that landed', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
const flyB = runner('fly_to_location', { query: 'Place B' });
const flyC = runner('fly_to_location', { query: 'Nowhere C' });
await new Promise((resolve) => setTimeout(resolve, 0));
flights[0].complete();
// C's start takes navigation from B's lookup; C then finds nothing.
searches[0].resolve({ cancelled: true });
searches[1].resolve(null);
assert.equal((await flyB).cancelled, true);
assert.equal((await flyC).ok, false);
const result = await moved;
assert.equal(result.ok, true, result.error);
});
test('a motion sent after a fly-to that found nothing still waits for the flight before it', async (t) => {
// Serial dispatch: "fly to Austin, fly to Nowhere, tilt", one call at a time.
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: async () => null,
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
assert.equal((await runner('fly_to_location', { query: 'Nowhere' })).ok, false);
const before = order.length;
const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
const movedDone = settledYet(moved);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, 'the tilt must wait for the Austin flight');
assert.equal(order.slice(before).includes('cancel'), false);
flights[0].complete();
assert.equal((await moved).ok, true);
});
test('two lookups that found nothing in a row still leave the motion waiting for the flight', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, order, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: async () => null,
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
assert.equal((await runner('fly_to_location', { query: 'Nowhere' })).ok, false);
assert.equal((await runner('fly_to_location', { query: 'Nowhere 2' })).ok, false);
const before = order.length;
const moved = runner('move_camera', { motion: 'orbit' });
const movedDone = settledYet(moved);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), false, 'the orbit must wait for the Austin flight');
assert.equal(order.slice(before).includes('cancel'), false);
flights[0].complete();
assert.equal((await moved).ok, true);
});
// A flight that already settled is still what a later failed lookup replaced.
test('a motion acts at a landed flight that a later failed lookup replaced', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
const flyA = runner('fly_to_location', { query: 'Slow A' });
const moved = runner('move_camera', { motion: 'orbit' });
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
flights[0].complete();
const flyC = runner('fly_to_location', { query: 'Nowhere C' });
await new Promise((resolve) => setTimeout(resolve, 0));
// B's start made A's lookup stale; C then finds nothing.
searches[0].resolve({ cancelled: true });
searches[1].resolve(null);
assert.equal((await flyA).cancelled, true);
assert.equal((await flyC).ok, false);
const result = await moved;
assert.equal(result.ok, true, result.error);
});
test('a motion refuses when the flight a later failed lookup replaced was cancelled', async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' });
const flyA = runner('fly_to_location', { query: 'Slow A' });
await new Promise((resolve) => setTimeout(resolve, 0));
// The motion sees Austin land, then follows A's lookup.
flights[0].complete();
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
flights[1].cancel();
const flyC = runner('fly_to_location', { query: 'Nowhere C' });
await new Promise((resolve) => setTimeout(resolve, 0));
searches[0].resolve({ cancelled: true });
searches[1].resolve(null);
assert.equal((await flyA).cancelled, true);
assert.equal((await flyC).ok, false);
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /did not arrive/);
});
test('a stale motion does not follow a newer reply\'s fly-to', async () => {
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
let live = true;
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' }, { isCurrent: () => live });
// A newer reply takes over and flies elsewhere; this reply is stale.
live = false;
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
flights[0].cancel();
// The newer flight never lands here: following it would hold this answer.
const result = await Promise.race([
moved,
new Promise((resolve) => setTimeout(() => resolve('still waiting'), 50)),
]);
assert.notEqual(result, 'still waiting');
assert.equal(result.ok, false);
assert.equal(result.cancelled, true);
});
test('a motion gives up on a flight that has not landed in 15 s', async (t) => {
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
const moved = runner('move_camera', { motion: 'orbit' });
const movedDone = settledYet(moved);
await Promise.resolve();
t.mock.timers.tick(14_999);
await Promise.resolve();
assert.equal(movedDone(), false);
t.mock.timers.tick(1);
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /did not arrive/);
});
test('a motion follows a newer fly-to that lands while its own lookup stalls', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
// Place A's lookup never answers.
searchNavigation: () => new Promise(() => {}),
});
t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
runner('fly_to_location', { query: 'Place A' });
const moved = runner('move_camera', { motion: 'orbit' });
const movedDone = settledYet(moved);
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
t.mock.timers.tick(2_000);
await Promise.resolve();
assert.equal(movedDone(), false, 'the orbit must wait for the newer flight to land');
flights[0].complete();
for (let i = 0; i < 5 && !movedDone(); i += 1) await Promise.resolve();
assert.equal(movedDone(), true, 'the orbit must not wait out A');
const result = await moved;
assert.equal(result.ok, true);
assert.equal(result.motion, 'orbit');
});
// "Fly to Paris and orbit it", then a location-panel search while the camera
// flies: the search stamps a deferred navigation without stopping the flight.
// Run where the flight landed, the orbit took navigation and the search's
// reassert failed, so the search was silently dropped.
// Gemini runs one reply's calls one after another: by the time "pan left"
// runs, "fly to Xyzzyville" has already found nothing, so there is no flight
// to wait on, and the pan moved the old view with ok: true.
test('a motion run after its reply\'s fly-to found nothing is not run', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: async () => null,
});
const reply = { turn: 1 };
const fly = await runner('fly_to_location', { query: 'Xyzzyville' }, { reply });
assert.equal(fly.ok, false);
const pan = await runner(
'move_camera',
{ motion: 'pan', direction: 'left' },
{ reply },
);
assert.equal(pan.ok, false);
assert.match(pan.error, /Not run: the fly-to in this reply found nothing/);
assert.equal(getActiveCameraMotion(), null);
// The same holds for OpenAI's reply identity.
const group = 'response-1';
await runner('fly_to_location', { query: 'Xyzzyville' }, { authorityGroup: group });
const tilt = await runner(
'move_camera',
{ motion: 'tilt', pitchDeg: -45 },
{ authorityGroup: group },
);
assert.equal(tilt.ok, false);
assert.match(tilt.error, /found nothing/);
});
test('a motion in a later reply runs after a fly-to that found nothing', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: async () => null,
});
await runner('fly_to_location', { query: 'Xyzzyville' }, { reply: { turn: 1 } });
const pan = await runner(
'move_camera',
{ motion: 'pan', direction: 'left' },
{ reply: { turn: 2 } },
);
assert.equal(pan.ok, true, pan.error);
});
test('a motion runs at a flight of its reply that landed after another lookup found nothing', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: async () => null,
});
const reply = { turn: 1 };
await runner('fly_to_location', { query: 'Xyzzyville' }, { reply });
assert.equal((await runner('fly_to_location', { locationId: 'austin' }, { reply })).ok, true);
flights[0].complete();
const pan = await runner(
'move_camera',
{ motion: 'pan', direction: 'left' },
{ reply },
);
assert.equal(pan.ok, true, pan.error);
});
test('a motion queued behind a fly-to yields to a search started during the flight', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights, panelSearch, currentGeneration } =
tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'orbit' });
await new Promise((resolve) => setTimeout(resolve, 0));
const search = panelSearch();
flights[0].complete();
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /Not run: another navigation took the camera/);
assert.equal(getActiveCameraMotion(), null);
assert.equal(currentGeneration(), search, 'the search still owns navigation');
});
test('a motion behind a geocoded fly-to yields to a search started while it flies', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, panelSearch } = tiltAfterFlightHarness();
const searches = [];
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
searchNavigation: (_viewer, query, options) => new Promise((resolve) => {
searches.push({ query, options, resolve });
}),
});
const fly = runner('fly_to_location', { query: 'Place A' });
const moved = runner('move_camera', { motion: 'orbit' });
await new Promise((resolve) => setTimeout(resolve, 0));
searches[0].resolve({ label: 'Place A', navigationMode: 'city-overview' });
assert.equal((await fly).ok, true);
panelSearch();
searches[0].options.onComplete();
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /another navigation took the camera/);
assert.equal(getActiveCameraMotion(), null);
});
test('a search before the fly-to does not drop the motion queued behind it', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager, flights, panelSearch } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
panelSearch();
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'tilt', pitchDeg: -45 });
await new Promise((resolve) => setTimeout(resolve, 0));
flights[0].complete();
const result = await moved;
assert.equal(result.ok, true);
assert.equal(result.motion, 'tilt');
});
test('a fly-to that stops a running motion says so', async (t) => {
t.after(() => interruptCameraMotion('test-cleanup'));
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
// The model sent the orbit first, so it ran at once.
const orbit = await runner('move_camera', { motion: 'orbit', mode: 'continuous' });
assert.equal(orbit.ok, true);
const fly = await runner('fly_to_location', { locationId: 'austin' });
assert.equal(fly.ok, true);
assert.equal(fly.stoppedMotion, 'orbit');
const again = await runner('fly_to_location', { locationId: 'austin' });
assert.equal('stoppedMotion' in again, false);
});
test('bad move_camera arguments are refused without waiting for a flight', async () => {
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
assert.equal((await runner('fly_to_location', { locationId: 'austin' })).ok, true);
const moved = runner('move_camera', { motion: 'pan' });
const movedDone = settledYet(moved);
await new Promise((resolve) => setTimeout(resolve, 0));
assert.equal(movedDone(), true, 'the refusal must not wait on the flight');
const result = await moved;
assert.equal(result.ok, false);
assert.match(result.error, /needs a direction/);
});
test('stop does not wait for a voice flight', async () => {
const { viewer, styleManager } = tiltAfterFlightHarness();
const runner = createGevActionRunner({
viewer,
styleManager,
dataManager: { layers: new Map(), getAll: () => [] },
});
await runner('fly_to_location', { locationId: 'austin' });
const result = await runner('move_camera', { motion: 'stop' });
assert.equal(result.ok, true);
assert.equal(result.motion, 'stop');
});
test('nearest-aircraft voice action serializes layer enable, arrival, refresh, airborne query, and selection', async () => { test('nearest-aircraft voice action serializes layer enable, arrival, refresh, airborne query, and selection', async () => {
globalThis.window = globalThis.window || { globalThis.window = globalThis.window || {
clearTimeout, clearTimeout,
+11 -5
View File
@@ -309,7 +309,10 @@ test('markup: the chip sits under the user caption with a screen-reader separato
assert.equal(pointer.hidden, true); assert.equal(pointer.hidden, true);
const separator = pointer.querySelector('.gev-voice-card-sr'); const separator = pointer.querySelector('.gev-voice-card-sr');
assert.equal(separator.textContent, ': '); assert.equal(separator.textContent, ': ');
assert.equal(separator.previousElementSibling.id, 'gev-voice-card-pointer-kind'); assert.equal(
separator.previousElementSibling.id,
'gev-voice-card-pointer-kind',
);
}); });
test('deixis prompt lint: one short rule, and every sentinel it names exists in the schema', () => { test('deixis prompt lint: one short rule, and every sentinel it names exists in the schema', () => {
@@ -347,15 +350,18 @@ test('deixis prompt lint: one short rule, and every sentinel it names exists in
// the analyst area scopes) raised the ceiling to 55,500; tightening the // the analyst area scopes) raised the ceiling to 55,500; tightening the
// AREAS rule and the area tool descriptions left it at 55,103 as measured // AREAS rule and the area tool descriptions left it at 55,103 as measured
// below (every tool, osm_query included); main's Sea Marks and Ski Pistes // below (every tool, osm_query included); main's Sea Marks and Ski Pistes
// layers bring it to 55,210, ~290 under. A new tool or rule has to fit // layers bring it to 55,210, and the tilt pitchDeg argument (with its -45
// under this ceiling. // default) and main's cockpit entry rule to 55,339. integrationContract's
// Overpass prompt is the tightest, at 55,499 (1 under). A new tool or rule
// has to fit under this ceiling.
const size = instructions.length + JSON.stringify(GEV_REALTIME_TOOLS).length; const size = instructions.length + JSON.stringify(GEV_REALTIME_TOOLS).length;
assert.ok(size <= 55_500, `prompt size ${size}`); assert.ok(size <= 55_500, `prompt size ${size}`);
}); });
test('after-tool speech allows returned items to answer requested lists and rankings', () => { test('after-tool speech allows returned items to answer requested lists and rankings', () => {
const rule = realtimeInstructions().split('\n').find(line => line.startsWith('AFTER TOOLS:')); const rule = realtimeInstructions()
.split('\n')
.find((line) => line.startsWith('AFTER TOOLS:'));
assert.match(rule, /requested analyst list or ranking/); assert.match(rule, /requested analyst list or ranking/);
assert.match(rule, /returned items.*returned values/); assert.match(rule, /returned items.*returned values/);
assert.match(rule, /keep their order/); assert.match(rule, /keep their order/);