Compare commits

..
Author SHA1 Message Date
Mazeyar Moeini FeizabadiandClaude Fable 5.2 72d9f91ad6 docs(performance): cables rewrite in #1722 and clouds shader in #1721
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 18:03:54 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 fda54f6611 docs(performance): detection overlay fixed in #1719
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 17:28:23 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 0760733780 docs(performance): NVG and FLIR measured and fixed in #1718
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 17:26:26 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 6b4b9e43c8 docs(performance): Wind server decode measured and fixed in #1717; Wind zoom stalls traced to Cesium's globe shaders
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 17:18:56 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 c16bfa5abd docs(performance): name the fix pull request for each finding
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 16:06:26 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 22bdf14be1 docs(performance): camera crash cause pinned to Cesium's centre-pixel zoom; detection cost re-measured
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 15:07:49 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 5aed9ce064 docs(performance): Wind re-measured and cleared; Shipwrecks and cables causes refined
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 15:06:37 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 96847d5856 docs(performance): pointer pick and imported geo files measured again and cleared
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 14:51:44 +01:00
Mazeyar Moeini FeizabadiandClaude Fable 5.2 5eb6515f44 docs(performance): slowdown audit of main, with the cause and fix for each finding
Co-Authored-By: Claude Fable 5.2 <[email protected]>
2026-11-13 14:23:35 +01:00
10 changed files with 340 additions and 626 deletions

No files matched your search

@@ -1,4 +0,0 @@
- Make a whole-globe view of Live Flights about three times faster on a slow
CPU. Aircraft at cruise altitude no longer ask for the ground under them on
every pass, and a ground floor read no longer formats numbers into text
(mazy1998, #1708).
+1 -7
View File
@@ -2949,13 +2949,7 @@ visits to one place share a key but does not bound how many distinct places a
session visits, and the cache previously had no eviction, so a long session
retained every coordinate it ever resolved. Eviction is least-recently-used:
a consumer read, including a warm hit in a batch lookup, promotes its entry, so
the cell being watched is not dropped for having been resolved early. A
synchronous read (`cachedEllipsoidalGround`, `cachedRealEllipsoidalGround`)
promotes its entry only once half the bound's worth of stores and promotions
have passed since the entry was last newest, so an entry read at least that
often is still never evicted while the per-frame floor reads no longer rewrite
the cache; those reads find entries through a numeric key and format no
strings. The bound sits far above a city-scale session, so
the cell being watched is not dropped for having been resolved early. The bound sits far above a city-scale session, so
normal use never evicts and issues no additional proxy requests. A batch's
results are assembled from what that call resolved or found warm, so eviction
during a large batch cannot report one of its points as unresolved. Re:Earth and
+322
View File
@@ -0,0 +1,322 @@
# Slowdown audit, November 2026
A sweep of `main` (`c02ede3bb`, 13 November 2026) for bugs that freeze the page
or hold the frame rate down. This page lists what was found, why it happens and
how to fix it, and names the pull request that carries each fix.
[PERFORMANCE.md](PERFORMANCE.md) is the measured baseline of a healthy build;
this page is the list of things that fall outside it.
## How it was measured
- Keyless dev server, headless Chrome at 1440 x 900 on Apple silicon (Metal
through ANGLE), default globe map.
- Per scenario: load, a spell at rest, scripted drags and wheel zooms, then a
settle. Long tasks were counted with a `PerformanceObserver`, the hot function
named from a CPU profile, and `globe.getHeight`, `scene.sampleHeight`,
`scene.pick` and friends wrapped to count calls and time.
- A long task is one main-thread task over 50 ms. With no layers on, the
baseline is two at load (longest about 240 ms) and none afterwards, with zero
frames rendered while the camera is still.
- Four profiling sessions ran on one machine at the same time, so absolute
timings carry some noise. Ratios against the baseline are what to read.
Nothing here was measured on Google Photorealistic 3D Tiles, on a discrete or
integrated PC GPU, or with keyed feeds (AISStream, FIRMS, TomTom). Those rows
are marked "read in code".
## Findings and fixes
Worst first. "Fix" names the pull request that carries the fix.
### Measured
| # | Where | What happens | Fix |
| ---: | --- | --- | --- |
| 1 | Bike Share, local data layers, Transit, Rail | 18 s freeze switching Bike Share on over New York (2,519 stations); 2.7 s on Data Centers; multi-second freezes with Transit while zooming | #1688, #1689 |
| 2 | Shipwrecks | 3 to 5 s freeze when the markers are built over loaded terrain; a share link with the layer on held the loading screen for 22.9 s in one run | #1703 |
| 3 | Camera | Rendering stops until reload: at a whole-globe view looking straight down, pan a few times, then scroll one notch | #1704 |
| 4 | Street Traffic | Zooming at 250 m over Manhattan: 25 long tasks in 24 s, longest 746 ms, 6.6 s in total | #1705 |
| 5 | ALPR cameras | Depth samples inside the overlay paint, repeated on every re-enable: 240 samples and about 1 s across eight toggles. A first-sample freeze of up to 1.9 s was seen in the sweep but not on a second day | #1706 |
| 6 | Wind | First zoom after load: up to 14 long tasks (longest 414 ms). Re-measured as one-off shader links, not a standing cost: see below | none proposed |
| 7 | Submarine cables | About 2 s of long tasks on load, heap briefly at 1 GB, about 0.5 s again on each re-enable | #1707 (first step), #1722 (batched primitives) |
| 8 | Live Flights at whole-globe view with detection labels | Fine on the test machine; at 4x CPU throttle, 8 fps with 143 long tasks in 15 s | #1708 (fleet pass), #1719 (overlay) |
| 9 | Radio | 7 to 10 long tasks when the directory loads, longest 447 ms | #1709 |
| 10 | Pointer pick | Not reproduced on a second look: see below | none needed |
| 11 | CCTV | A still-image camera holds continuous rendering at 60 frames a second although its picture changes about every 10 s | #1710 |
### Read in code
| # | Where | What happens | Fix |
| ---: | --- | --- | --- |
| 12 | `/api/firms` | The whole fire set is filtered, serialised and sent uncompressed on every request; 15 to 55 MB estimated in a heavy season | #1711 |
| 13 | AIS store | Both vessel maps are walked on every position message, and sorted whole once past the cap | #1712 |
| 14 | Satellite clouds on the 3D Tiles map | A CPU pass over a 4096 x 2048 image, 90 to 180 ms measured on a synthetic canvas, twice in a row | #1713 (canvas path), #1721 (shader) |
| 15 | NVG and FLIR styles | Over 100 texture reads per pixel, and 60 renders a second while the style is on. Measured afterwards: the reads cost 0.4 ms a frame at 1440 x 900 and 1.2 ms at 2560 x 1440 | #1718 |
| 16 | Wind server | Full 0.25 degree GRIB fields decoded on the event loop. Measured afterwards: 68 ms blocked per warm refresh, about 250 ms on the first, about 400 ms when all six keys refresh together | #1717 |
| 17 | Imported geo files and other per-feature ground clamps | Measured afterwards: imported files do not freeze; see below | none needed |
## Cause and fix, per finding
### 1. Terrain height reads
`globe.getHeight` casts a ray against the mesh of the tile under the point, and
`scene.sampleHeight` renders a depth pass. Transit asked for every trail fix of
every vehicle several times per poll; Bike Share sampled every station in one
go. The fix keeps heights per point in one shared reader with a read budget
(`src/services/terrainSurface.js`) and spreads the depth samples across frames.
### 2. Shipwrecks
`rebuild()` in `src/layers/shipwrecks/index.js` adds 7,958 billboards with
`heightReference: CLAMP_TO_GROUND`. Each constructor runs
`Billboard._updateClamping`, which intersects a ray with the terrain mesh,
synchronously: 4.8 of the 4.9 s. The cost is only paid when terrain is loaded
at the time the markers are built, so a cold start with the layer in the URL
sometimes escapes it.
Fix: do not clamp. Wrecks are at sea and the markers already ignore the depth
test, so place them on the ellipsoid with `HeightReference.NONE`.
### 3. Camera: rendering stops after pan then zoom
Pure Cesium; no application code is involved. Above 1,000 km,
`ScreenSpaceCameraController` `handleZoom` rotates the camera about the cross
product of the picked point's normal and the screen centre's normal whenever
their dot product is between 0 and 1. With the pointer on the exact centre pixel
the two are the same vector, yet `n · n` often rounds to `0.9999999999999999`,
so the check passes with a zero axis. `Camera.rotate` then throws
`DeveloperError: normalized result is not a number` from
`Scene.initializeFrame`, outside the scene's own try/catch, so
`scene.renderError` never fires and Cesium stops its render loop for good. The
pans in the first reproduction only moved the camera to a pose where the
rounding goes that way.
Fix: make `camera.rotate` ignore a zero or non-finite axis, and recover from any
stopped loop by restoring the last drawn camera pose and restarting it a bounded
number of times before showing Cesium's error panel.
### 4. Street Traffic road loading
Three costs in one task after the detail tiles arrive, in
`src/layers/traffic/source.js`:
- `outsideDetailTiles` clips every coarse z12 road against every loaded detail
tile (up to 16) for four regions.
- The composed set is then handed on with `replace: true`, so
`ingestion.js` parses every road again although each tile was parsed as it
streamed.
- `parseRoads` (`model.js`) asks `cachedGroundFloor` once per coordinate, and
each call builds several string keys.
Fix: clip once per coarse tile against the detail tiles' union box and slice the
work across frames (or do it in the vector-tile worker); reuse the roads parsed
while streaming and parse only the clipped coarse remainder; look the floor up
once per floor cell within a parse.
This is separate from the one-viewport-tile-at-a-time loading recorded in
[KNOWN-ISSUES.md](KNOWN-ISSUES.md).
### 5. ALPR cameras
`refineAnchors` and `anchorFor` in `src/layers/alpr/overlay.js` call
`scene.sampleHeight` from the overlay's paint, four per paint. Each is a depth
render and a `readPixels`; the first one also compiles the pick shader. Results
are kept on the entity, so a rebuild or a re-enable samples everything again.
Fix: on a terrain globe read `globe.getHeight` through the shared terrain reader
instead of sampling; keep the answers in a map keyed by camera that outlives the
entities; move what sampling remains out of the paint into a queue of one per
frame.
### 6. Wind
The first reading blamed the layer's 916,476 vertices for slow depth reads
during zoom. Measuring again did not support that: depth reads cost the same
with and without Wind, hiding every wind primitive left pick time unchanged, and
the stalls appear on the first zoom only, as shader programs link (seven
programs, about 0.5 s, long tasks up to 166 ms). Later zooms had none.
The roughly 30 renders a second are the animation itself. It is already capped
at 30 Hz and stops when paused, hidden, out of view or under reduced motion;
lowering the rate would change how the layer looks. `disable()` releases the
baked geometry on purpose, at the price of one task of about 130 ms on
re-enable.
A third look, timing every program link on a preview build, settled it: Wind
owns two shader programs, both link during load in 9 to 18 ms, and none ever
linked during a zoom. The programs that do link on a zoom are Cesium's own
globe-surface variants, with Wind on or off, and Cesium links them
synchronously. No fix is proposed.
### 7. Submarine cables
`src/layers/submarineCables/ingestion.js` loads both collections through
`Cesium.GeoJsonDataSource` with `clampToGround`. Switching the layer on is one
task of about 1.4 s, and 1.2 s of it is Cesium reading the terrain height for
the 1,917 ground-clamped landing markers, all created in the first frame,
including the ones behind the globe.
Fix, first step: start the landing markers hidden and let the existing horizon
sweep show the visible ones a few dozen per frame.
Fix, second step: draw from batched primitives in place of the entity data
sources: one ground polyline primitive for the lines, one billboard collection
for the landing markers, one point collection and one static polyline primitive
for the reference stems, all kept while the layer is off. That removes the
visualiser tasks, the stall on switch-off and on re-enable, and about 900 MB of
heap. The first switch-on still links shaders and builds the ground-line
geometry once.
### 8. Live Flights at whole-globe view
Two costs that scale with the 7,500 aircraft of a full poll:
- The fleet pass (`src/layers/flights/rendering.js`, every 80 ms) dead-reckons
each visible aircraft and asks `cachedGroundFloor` for it, including aircraft
at cruise altitude that can never touch the floor. Each lookup formats numbers
to strings several times and rewrites a cache entry: 40% of the busy time.
- The detection overlay (`src/data/detection.js` `_drawOverlay`) collects every
detectable object and strokes every bracket on every frame.
Fix for the first: skip the floor path for a contact clearly above any terrain,
make the floor-cell key a number, and stop promoting the cache entry on every
read.
The second turned out smaller than it looked. The bracket strokes are already
one path per colour, and collecting the objects is about 3 ms of a 56 ms frame
at 4x throttle once the first fix is in. What costs is the per-object loop in
`_drawOverlay` (projection, occlusion, alpha, twelve path calls per bracket).
Fix for the second: keep what a sweep built and reuse it on the next paint when
the view and every contact are exactly what it was built from, compared value
by value so no layer has to announce a change. Between two fleet passes most
paints qualify, which cuts frame work by a fifth to a third on a still camera
at full speed. At 4x throttle a frame outlasts a fleet pass, no paint
qualifies, and the gain is a few milliseconds; the fleet pass is what
dominates there.
### 9. Radio
`stationTags()` in `src/layers/radio/categories.js` splits and normalises a
station's tags on every `hasTag` call, and `buildRadioCategories` runs that for
every station against every category, twice.
Fix: normalise once per station at ingest and count categories from that.
### 10. Pointer pick
Three sessions saw a single `scene.pick` of 207 to 342 ms during a gesture and
attributed it to `pickPointer` in `src/voice/pointerPick.js`. Timing every pick
across pointer rests, drags and wheel bursts did not bear that out: of 78 picks
with CCTV on over London all but two took 3 to 8 ms, and with five heavy layers
on, 81 picks took 5 to 30 ms apart from the first (135 ms). `pickPointer` picks
at most once per pointer rest.
The slow pick is the first pick after a layer appears, once per page load, most
likely the pick shader compiling, and its stack is CCTV's own hover pick
(`src/layers/cctv/hover.js`). No fix is proposed: removing the dwell pick would
only move the one-off cost to the next click.
### 11. CCTV still-image cameras
`src/layers/cctv/projection.js` holds continuous rendering for as long as any
projected camera is active and redraws the projection every frame.
Fix: hold only for video. For a still image, request one render when a new image
lands or while a focus fade runs.
### 12. `/api/firms`
`server/providers/firms.js` builds the payload and calls `JSON.stringify` per
request, with no kept body and no compression, and the client refetches every
ten minutes.
Fix: keep the response bytes and their gzip and serve those, as the OpenSky
provider does. The route filters to the trailing 24 hours at serve time, so the
bytes can only be reused while that filter keeps the same records (about a
minute at a time): bursts and several clients gain most, and every response is
about seven times smaller.
### 13. AIS store
`server/providers/vessels/ais-store.js` calls `pruneAisStreamCache()` for every
message; the static-data map is never pruned.
Fix: prune on a timer, evict in insertion order, and drop a vessel's static
entry with the vessel.
### 14. Satellite clouds on the 3D Tiles map
`src/layers/weather/infraredImage.js` runs `getImageData`, a per-pixel power
curve and `putImageData` over the whole canvas.
Fix: a 256-entry lookup table applied in place for the canvas path, which
halves it; then, for the shell on the 3D Tiles map, the same curve in its
fragment shader from a strength uniform, so the image is never read back and a
strength change builds no new image.
### 15. NVG and FLIR styles
`src/styles/surveillance.js` loops 11 x 11 texture reads per pixel and
`src/styles/thermal.js` totals 106. Timed on the GPU, those loops cost about
0.4 ms a frame at 1440 x 900 and 1.2 ms at 2560 x 1440 on the test machine:
real, but small there. The standing cost is that a style with animated grain
holds continuous rendering at 60 frames a second.
Fix: split the bloom into a row pass and a column pass, which gives the same
picture from a fifth to a half of the reads, and step the grain's clock at
15 Hz, asking for one frame per step instead of holding the render loop. The
grain then changes 15 times a second, which is visible in motion.
Switching on any style stage at all costs more than the bloom did (1.8 ms a
frame at 1440 x 900 for the one-line noir style). That was not looked into.
### 16. Wind server
`server/providers/wind/decode.js` decodes about a million doubles per message
synchronously, hourly, for six keys.
Fix: decode on a worker thread, and keep the sampled U and V of the last
forecast file per model so that choosing an overlay fetches only its field.
### 17. Per-feature ground clamps
`heightReference: CLAMP_TO_GROUND` per feature is also set in
`installations/rendering.js`, `alpr/presentation.js`, `ghostMaps/index.js`,
`earthquakes/index.js`, `airQuality/index.js`, `news/index.js` and
`osmPlaces/index.js`. Their counts were small in these runs (30 to 1,500) and
none froze.
Imported geo files were the one unbounded case, and measuring them cleared
them: 20,000 generated points (the import cap) finish in about 1.5 s with a
longest task near 0.5 s, because `settleGroundPins` in
`src/data/geoFileImport.js` already places pins with `HeightReference.NONE` and
resolves heights 256 at a time with a yield between batches. No fix is needed.
## Checked and fine
- Start-up of a production build: viewer ready in about 0.5 s, loading screen
gone at 1.6 s, three long tasks totalling about 300 ms.
- Idle: no frames rendered with no layers on; every render hold was released
when its layer went off.
- Leaks: all 41 layers toggled three times and ten of them eight times; no
timer, scene listener, primitive or data source grew per cycle. The heap
levelled off near 320 MB over 7.5 minutes of toggling eleven layers.
- At most one long task after load: Military, Satellites (including 11,903
Starlink points), Earthquakes, News, Wildlife, GNSS, Drone Airspace, Military
Installations, Fire Perimeters, rain radar, lightning, and satellite clouds on
the globe map.
- Live Flights at city scale with the same 7,500 aircraft loaded: 60 fps, no
long tasks.
## Not covered
- Google Photorealistic 3D Tiles: nothing was run there. Depth sampling is the
only height source on that map, so findings 4, 5 and 17 may be worse.
- Live Vessels, FIRMS with data, TomTom traffic, Local ADS-B.
- Frame rate on anything but one Apple silicon machine.
- One all-layers run over Manhattan grew the heap from 346 to 638 MB in 60 s;
whether that is retained was not established.
- One Satellites load showed a 5.2 s long task once and never again in four more
loads.
+3
View File
@@ -6,6 +6,9 @@ specification and should not be used to predict performance on untested systems.
The original capture artifacts are not included here, so this page records
results rather than defining a runnable benchmark.
For slowdowns found since, with their causes and fixes, see
[PERFORMANCE-AUDIT-2026-11.md](PERFORMANCE-AUDIT-2026-11.md).
## Test context
The baseline was captured on 22 August 2026 with these conditions:
-34
View File
@@ -311,10 +311,6 @@ export const COAST_FLOOR_LIFT_M = 1.5;
*/
export function floorCoastedPosition(position, cachedGroundFloor) {
if (typeof cachedGroundFloor !== 'function') return position;
// Most coasting contacts are at cruise, and this runs for each of them on
// every fleet pass. One above COAST_FLOOR_CEILING_M cannot be lifted by any
// ground, so it needs neither the geodetic conversion nor the floor read.
if (clearOfAllGround(position)) return position;
const carto = Cesium.Cartographic.fromCartesian(
position,
Cesium.Ellipsoid.WGS84,
@@ -338,36 +334,6 @@ export function floorCoastedPosition(position, cachedGroundFloor) {
const _coastCarto = new Cesium.Cartographic();
/**
* @constant {number} No ground reaches this height above the ellipsoid:
* Everest's summit is about 8,821 m (8,849 m above a geoid that sits 28 m
* below the ellipsoid there).
*/
export const COAST_FLOOR_CEILING_M = 9000;
const _oneOverRadiiSq = Cesium.Ellipsoid.WGS84.oneOverRadiiSquared;
const COAST_CLEAR_SCALED_SQ =
(1 + COAST_FLOOR_CEILING_M / Cesium.Ellipsoid.WGS84.minimumRadius) ** 2;
/**
* Whether a position is certainly more than COAST_FLOOR_CEILING_M above the
* ellipsoid, from three multiplications. Scale the axes so the ellipsoid is
* the unit sphere: a point h metres up its surface normal is then at most
* 1 + h / (polar radius) from the centre, so one further out than
* 1 + ceiling / (polar radius) is above the ceiling. At the equator this
* answers yes from about 30 m above the ceiling; at the poles, from the
* ceiling itself.
* @param {Cesium.Cartesian3} position
* @returns {boolean}
*/
function clearOfAllGround(position) {
return (
position.x * position.x * _oneOverRadiiSq.x +
position.y * position.y * _oneOverRadiiSq.y +
position.z * position.z * _oneOverRadiiSq.z >
COAST_CLEAR_SCALED_SQ
);
}
/**
* Seconds to coast past the last report: the elapsed time, bounded by the
* source's coast limit and STALE_COAST_MAX_SEC; none for a contact that
-77
View File
@@ -10,7 +10,6 @@ import {
liftRepeatedGroundFix, synthesizeForwardKinematicsFix,
projectGroundArcLatLon, corridorPathLatLon,
COURSE_TRACK_ONLY_MPS, COURSE_CHORD_ONLY_MPS, COURSE_MIN_DPS, TURN_MIN_SPEED_MPS,
floorCoastedPosition, COAST_FLOOR_CEILING_M, COAST_FLOOR_LIFT_M,
} from './motionModel.js';
const AUSTIN = { lat: 30.2672, lon: -97.7431, alt: 9000 };
@@ -342,79 +341,3 @@ test('corridorPathLatLon returns nothing without a display position', () => {
extrapolating: true, displayLat: NaN, displayLon: -97.66, courseDeg: 0, speedMps: 10, lookaheadSec: 60,
}), []);
});
/** floorCoastedPosition as it was before the cruise skip: always converts and reads. */
function floorCoastedReference(position, groundAt) {
const carto = Cesium.Cartographic.fromCartesian(position);
if (!carto) return position;
const ground = groundAt(
Cesium.Math.toDegrees(carto.latitude),
Cesium.Math.toDegrees(carto.longitude),
);
if (!Number.isFinite(ground) || carto.height >= ground + COAST_FLOOR_LIFT_M)
return position;
return Cesium.Cartesian3.fromRadians(carto.longitude, carto.latitude, ground + COAST_FLOOR_LIFT_M);
}
test('a coasting contact above any terrain is not looked up against the ground', () => {
let reads = 0;
const ground = () => {
reads += 1;
return 8821; // Everest's summit, the highest floor there is
};
// Just over the ceiling and at cruise, from pole to equator.
for (let lat = -90; lat <= 90; lat += 7.5) {
for (const lon of [0, 86.925, -78.8, 179.9]) {
for (const height of [COAST_FLOOR_CEILING_M + 35, 10_000, 12_500, 40_000]) {
const position = Cesium.Cartesian3.fromDegrees(lon, lat, height);
const before = Cesium.Cartesian3.clone(position);
assert.equal(floorCoastedPosition(position, ground), position);
assert.ok(Cesium.Cartesian3.equals(position, before));
}
}
}
assert.equal(reads, 0);
});
test('below the ceiling a coast is floored exactly as before', () => {
// Terrain that rises under the coast, known in some places and not others.
const ground = (lat, lon) => (Math.floor(lat * 10 + lon) % 3 === 0 ? null : 1500 + ((lat * 7 + lon * 3) % 900));
let lifted = 0;
let checked = 0;
for (let lat = -89; lat <= 89; lat += 5.5) {
for (let lon = -180; lon < 180; lon += 17) {
for (const height of [-40, 0, 800, 1499, 1501.4, 2399, 2402, 5000, 8990, 9000, 9010, 11_000, 30_000]) {
const position = Cesium.Cartesian3.fromDegrees(lon, lat, height);
const expected = floorCoastedReference(Cesium.Cartesian3.clone(position), ground);
const actual = floorCoastedPosition(position, ground);
assert.ok(
Cesium.Cartesian3.equals(actual, expected),
`coast at ${lat}, ${lon}, ${height} m`,
);
checked += 1;
if (!Cesium.Cartesian3.equals(expected, Cesium.Cartesian3.fromDegrees(lon, lat, height))) lifted += 1;
}
}
}
assert.ok(lifted > 500, `${lifted} of ${checked} coasts were lifted onto the ground`);
});
test('nothing at or below the ceiling skips the ground', () => {
let reads = 0;
const ground = () => {
reads += 1;
return null;
};
let asked = 0;
for (let lat = -90; lat <= 90; lat += 2.5) {
for (const height of [-400, 0, 4000, 8821, COAST_FLOOR_CEILING_M - 1, COAST_FLOOR_CEILING_M]) {
floorCoastedPosition(Cesium.Cartesian3.fromDegrees(33, lat, height), ground);
asked += 1;
}
}
assert.equal(reads, asked);
});
test('the ceiling clears the highest ground with room to spare', () => {
assert.ok(COAST_FLOOR_CEILING_M > 8849 + 100);
});
+11 -55
View File
@@ -45,39 +45,6 @@ export function createGroundFloor({ terrain, signal }) {
return { lat: Number(lat.toFixed(3)), lon: Number(lon.toFixed(3)) };
}
/**
* One coordinate's coarse cell as an integer: `Number(deg.toFixed(3))` in
* thousandths of a degree, without the trip through a string. The floor is
* read for every aircraft on every fleet pass, and `coarseFloorCoord`'s two
* `toFixed` calls and the string keys built from them were most of the cost.
* `toFixed` rounds the exact decimal value; `deg * 1000` is within 1e-10 of
* it for |deg| < 1000, so the two can only round differently right at a
* half, and there the string decides.
* @param {number} deg
* @returns {number}
*/
function coarseCellIndex(deg) {
const scaled = deg * 1000;
if (
!(Math.abs(deg) < 1000) ||
Math.abs(scaled - Math.floor(scaled) - 0.5) < 1e-6
)
return Math.round(Number(deg.toFixed(3)) * 1000);
return Math.round(scaled);
}
/**
* Key of a coarse cell in `_meshCells`: the two indices packed into one
* number, or the text form for a longitude too far out of range to pack.
* @param {number} latIndex @param {number} lonIndex
* @returns {number|string}
*/
function meshCellKey(latIndex, lonIndex) {
return Math.abs(lonIndex) < 500_000 && Math.abs(latIndex) < 1e9
? latIndex * 1_000_000 + lonIndex
: `${latIndex},${lonIndex}`;
}
/**
* Pure floor clamp.
* - finite alt + finite ground → max(alt, ground + lift)
@@ -457,8 +424,8 @@ export function createGroundFloor({ terrain, signal }) {
// reported here by meshFloorSampler.js. Design principle (owner): NEVER
// below the visible surface; slightly above is always fine. The DEM stays
// the instant global prior/fallback and the sanity gate for samples.
/** @type {Map<number|string, Array<{lat: number, lon: number, h: number}>>}
* coarse cell key (`meshCellKey`) -> rendered-surface readings (m, ellipsoidal), each kept
/** @type {Map<string, Array<{lat: number, lon: number, h: number}>>}
* coarse cell key -> rendered-surface readings (m, ellipsoidal), each kept
* at the point it was probed. A read answers from the reading nearest the
* asked point, so a viaduct and the street beside it in one cell keep their
* own heights. */
@@ -501,7 +468,8 @@ export function createGroundFloor({ terrain, signal }) {
!Number.isFinite(heightM)
)
return;
const key = meshCellKey(coarseCellIndex(lat), coarseCellIndex(lon));
const c = coarseFloorCoord(lat, lon);
const key = `${c.lat},${c.lon}`;
if (!_meshCells.has(key)) _meshCells.set(key, [{ lat, lon, h: heightM }]);
}
@@ -529,7 +497,7 @@ export function createGroundFloor({ terrain, signal }) {
const cell = coarseFloorCoord(lat, lon);
const prior = cachedRealEllipsoidalGround(cell.lat, cell.lon);
if (!meshFloorSampleWithinPrior(heightM, prior)) return false;
const key = meshCellKey(coarseCellIndex(lat), coarseCellIndex(lon));
const key = `${cell.lat},${cell.lon}`;
const readings = _meshCells.get(key);
if (!readings) {
_meshCells.set(key, [{ lat, lon, h: heightM }]);
@@ -570,16 +538,8 @@ export function createGroundFloor({ terrain, signal }) {
function cachedMeshFloor(lat, lon) {
if (!_meshPreferred) return null;
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
return meshFloorInCell(
lat,
lon,
meshCellKey(coarseCellIndex(lat), coarseCellIndex(lon)),
);
}
/** `cachedMeshFloor` for a caller that already has the point's cell key. */
function meshFloorInCell(lat, lon, key) {
const readings = _meshCells.get(key);
const c = coarseFloorCoord(lat, lon);
const readings = _meshCells.get(`${c.lat},${c.lon}`);
if (!readings) return null;
if (readings.length === 1) return readings[0].h;
const k = Math.cos((lat * Math.PI) / 180) ** 2;
@@ -612,14 +572,10 @@ export function createGroundFloor({ terrain, signal }) {
*/
function cachedGroundFloor(lat, lon) {
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
// The cell is worked out once, as integers, for both reads.
const latIndex = coarseCellIndex(lat);
const lonIndex = coarseCellIndex(lon);
if (_meshPreferred) {
const mesh = meshFloorInCell(lat, lon, meshCellKey(latIndex, lonIndex));
if (mesh != null) return mesh;
}
return cachedRealEllipsoidalGround(latIndex / 1000, lonIndex / 1000);
const mesh = cachedMeshFloor(lat, lon);
if (mesh != null) return mesh;
const c = coarseFloorCoord(lat, lon);
return cachedRealEllipsoidalGround(c.lat, c.lon);
}
/**
-176
View File
@@ -1,176 +0,0 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createGroundFloor } from './groundFloor.js';
import { createTerrainHeights } from './terrainHeights.js';
/** Counts Number.prototype.toFixed calls made while `run` executes. */
function countToFixed(run) {
const original = Number.prototype.toFixed;
let calls = 0;
Number.prototype.toFixed = function (...args) {
calls += 1;
return original.apply(this, args);
};
try {
run();
} finally {
Number.prototype.toFixed = original;
}
return calls;
}
/**
* The floor read as it was before the cell became an integer: the coarse cell
* through `toFixed(3)`, mesh cells and DEM cells under string keys.
*/
function referenceFloor() {
const mesh = new Map();
const dem = new Map();
const coarse = (lat, lon) => ({
lat: Number(lat.toFixed(3)),
lon: Number(lon.toFixed(3)),
});
const demKey = (lat, lon) => `${lat.toFixed(5)},${lon.toFixed(5)}`;
return {
reportMesh(lat, lon, h) {
const c = coarse(lat, lon);
const key = `${c.lat},${c.lon}`;
if (!mesh.has(key)) mesh.set(key, [{ lat, lon, h }]);
},
storeDem(lat, lon, h) {
dem.set(demKey(lat, lon), h);
},
read(lat, lon, meshPreferred = true) {
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
const c = coarse(lat, lon);
const readings = meshPreferred ? mesh.get(`${c.lat},${c.lon}`) : null;
if (readings) return readings[0].h;
return dem.get(demKey(c.lat, c.lon)) ?? null;
},
};
}
/** A real terrain cache whose every resolved point takes the height asked for. */
async function warmTerrain(points) {
const heights = new Map(points.map((p) => [`${p.lat},${p.lon}`, p.h]));
const terrain = createTerrainHeights({
source: {
async getHeights(chunk) {
return chunk.map((item) => ({
ellipsoid: heights.get(`${item.lat},${item.lon}`),
}));
},
},
});
await terrain.resolveEllipsoidalGround(
points.map(({ lat, lon }) => ({ lat, lon })),
);
return terrain;
}
/** Deterministic pseudo-random numbers in [0, 1). */
function random(seed) {
let state = seed;
return () => {
state = (state * 1664525 + 1013904223) % 4294967296;
return state / 4294967296;
};
}
/** Coordinates that land on, and just either side of, a coarse-cell edge. */
function edgeCoordinates() {
const out = [];
for (const base of [0, 0.0005, -0.0005, 12.3455, -12.3455, 89.9995, 179.9995])
for (const nudge of [0, 1e-13, -1e-13, 1e-9, -1e-9, 1e-7, -1e-7, 4e-4])
out.push(base + nudge);
// Thousandths whose doubles sit a hair either side of the half.
for (let k = -40; k <= 40; k += 1) out.push((k + 0.5) / 1000);
out.push(-0, 1.0005, 1.0015, 2.5, -2.5, 1e-7, -1e-7);
return out;
}
test('the floor read answers exactly as the string-keyed read did', async () => {
const next = random(20261113);
const cells = [];
for (let i = 0; i < 400; i += 1) {
cells.push({
lat: Number((next() * 170 - 85).toFixed(3)),
lon: Number((next() * 360 - 180).toFixed(3)),
h: Math.round(next() * 4000),
});
}
// Cells along the equator and the prime meridian, where a cell index is 0.
for (const edge of edgeCoordinates()) {
const lat = Number(edge.toFixed(3));
cells.push({ lat: Math.max(-89, Math.min(89, lat)), lon: 10, h: 77 });
cells.push({ lat: 10, lon: lat, h: 88 });
}
const reference = referenceFloor();
for (const c of cells) reference.storeDem(c.lat, c.lon, c.h);
const terrain = await warmTerrain(cells);
const groundFloor = createGroundFloor({ terrain });
// A rendered-surface reading in every seventh cell, taken off its centre.
cells.forEach((c, i) => {
if (i % 7) return;
const lat = c.lat + 0.0002;
const lon = c.lon - 0.0003;
reference.reportMesh(lat, lon, c.h + 3);
groundFloor.reportMeshFloorCell(lat, lon, c.h + 3);
});
const probes = [];
for (const c of cells) {
probes.push([c.lat, c.lon]);
probes.push([c.lat + (next() - 0.5) * 0.002, c.lon + (next() - 0.5) * 0.002]);
}
for (const a of edgeCoordinates())
for (const b of [10, 10.0004, -0, 0.0005, -0.0005]) {
probes.push([a, b]);
probes.push([b, a]);
}
probes.push([NaN, 1], [1, Infinity], [95, 400], [10, 720.1234]);
for (const meshPreferred of [true, false]) {
groundFloor.setMeshFloorPreferred(meshPreferred);
let hits = 0;
for (const [lat, lon] of probes) {
const expected = reference.read(lat, lon, meshPreferred);
assert.equal(
groundFloor.cachedGroundFloor(lat, lon),
expected,
`floor at ${lat}, ${lon} (mesh ${meshPreferred})`,
);
if (expected !== null) hits += 1;
}
assert.ok(hits > 400, `${hits} probes found a floor`);
}
});
test('reading a floor formats no numbers, hit or miss', async () => {
const cell = { lat: 51.47, lon: -0.454, h: 25 };
const terrain = await warmTerrain([cell]);
const groundFloor = createGroundFloor({ terrain });
groundFloor.reportMeshFloorCell(48.3537, 11.7861, 453);
const calls = countToFixed(() => {
// The DEM cell, a rendered-surface cell, and open ocean with neither.
assert.equal(groundFloor.cachedGroundFloor(51.4702, -0.4541), 25);
assert.equal(groundFloor.cachedGroundFloor(48.3538, 11.7862), 453);
for (let i = 0; i < 1000; i += 1)
assert.equal(groundFloor.cachedGroundFloor(30 + i * 0.011, -40.2), null);
});
// Before, each read made six toFixed calls (the cell twice, the DEM key).
assert.equal(calls, 0);
});
test('a reading reported at a point is found from anywhere in its cell', async () => {
const terrain = await warmTerrain([{ lat: 41.5, lon: -97.66, h: 120 }]);
const groundFloor = createGroundFloor({ terrain });
assert.equal(groundFloor.reportValidatedMeshFloorCell(41.5003, -97.6602, 129), true);
assert.equal(groundFloor.cachedMeshFloor(41.4996, -97.6598), 129);
assert.equal(groundFloor.cachedGroundFloor(41.4996, -97.6598), 129);
// The next cell over has no reading and no DEM entry.
assert.equal(groundFloor.cachedMeshFloor(41.5006, -97.6602), null);
assert.equal(groundFloor.cachedGroundFloor(41.5006, -97.6602), null);
});
+3 -125
View File
@@ -86,89 +86,6 @@ export function createTerrainHeights({
*/
const cache = new Map();
/**
* The same entries under a numeric key, for the synchronous reads. Those run
* for every aircraft on every fleet pass (about 94,000 a second with 7,500
* aircraft in view), nearly all of them misses, and building the string key
* (two `toFixed` calls and a concatenation) was most of what a read cost.
* Kept in step with `cache` by `cacheStore`, eviction and the abort handler.
* `at` is the value of `moves` when the entry last became the newest.
* @type {Map<number, {key: string, entry: object, at: number}>}
*/
const cells = new Map();
/** Counts every move to the newest end of `cache`: stores and promotions. */
let moves = 0;
/**
* A read promotes its entry only once this many moves have passed since it
* was last the newest. An entry cannot reach the cold end in fewer than
* CACHE_MAX_ENTRIES - 1 moves, so one read at least this often is never
* evicted, without rewriting the Map on every read.
*/
const PROMOTE_AFTER_MOVES = Math.floor(CACHE_MAX_ENTRIES / 2);
/**
* `value.toFixed(5)` as an integer count of 1e-5 steps, or null when the
* fast arithmetic cannot be trusted to match it. `toFixed` rounds the exact
* decimal value; `value * 1e5` is within 2e-8 of it for |value| < 1000, so
* the two can only round differently this close to a half. A negative value
* that rounds to zero is left to the string too: it formats as "-0.00000",
* a different key from "0.00000".
* @param {number} value
* @returns {number|null}
*/
function fixed5Index(value) {
if (!(Math.abs(value) < 1000)) return null;
const scaled = value * 1e5;
if (Math.abs(scaled - Math.floor(scaled) - 0.5) < 1e-6) return null;
const index = Math.round(scaled);
return Object.is(index, -0) ? null : index;
}
/** Indices at or past this (500 degrees) do not pack into one integer. */
const CELL_INDEX_LIMIT = 5e7;
/**
* The numeric key for a coordinate: its two 5-decimal indices packed into
* one integer (below 2^53), or null when the coordinate has to go through
* its string key instead.
* @param {number} lat
* @param {number} lon
* @returns {number|null}
*/
function cellKey(lat, lon) {
const latIndex = fixed5Index(lat);
const lonIndex = fixed5Index(lon);
if (
latIndex === null ||
lonIndex === null ||
Math.abs(latIndex) >= CELL_INDEX_LIMIT ||
Math.abs(lonIndex) >= CELL_INDEX_LIMIT
)
return null;
return latIndex * 1e8 + lonIndex;
}
/**
* The numeric key of a stored string key. The text is the rounded
* coordinate itself, so this is exact. Null for a key `cellKey` never
* produces; such a key is only ever read through its string.
* @param {string} key
* @returns {number|null}
*/
function cellKeyOf(key) {
const comma = key.indexOf(',');
const latIndex = Math.round(Number(key.slice(0, comma)) * 1e5);
const lonIndex = Math.round(Number(key.slice(comma + 1)) * 1e5);
if (
!(Math.abs(latIndex) < CELL_INDEX_LIMIT) ||
!(Math.abs(lonIndex) < CELL_INDEX_LIMIT) ||
Object.is(latIndex, -0) ||
Object.is(lonIndex, -0)
)
return null;
return latIndex * 1e8 + lonIndex;
}
/**
* Store an entry and drop the coldest ones once past the cap. `Map` iterates
* in insertion order, so deleting the first key evicts the least recently
@@ -184,15 +101,10 @@ export function createTerrainHeights({
function cacheStore(key, entry) {
cache.delete(key);
cache.set(key, entry);
moves += 1;
const cell = cellKeyOf(key);
if (cell !== null) cells.set(cell, { key, entry, at: moves });
while (cache.size > CACHE_MAX_ENTRIES) {
const coldest = cache.keys().next().value;
if (coldest === undefined) break;
cache.delete(coldest);
const coldestCell = cellKeyOf(coldest);
if (coldestCell !== null) cells.delete(coldestCell);
}
}
@@ -207,36 +119,9 @@ export function createTerrainHeights({
if (entry === undefined) return undefined;
cache.delete(key);
cache.set(key, entry);
moves += 1;
const cell = cellKeyOf(key);
const held = cell === null ? undefined : cells.get(cell);
if (held) held.at = moves;
return entry;
}
/**
* The synchronous read: the entry for a coordinate, or undefined on a miss.
* Same answer as `cacheTouch(cacheKey(lat, lon))`, without building the
* string, and promoting only an entry that has drifted towards the cold end
* (see PROMOTE_AFTER_MOVES).
* @param {number} lat
* @param {number} lon
* @returns {{ellipsoid: number, source: 'reearth'|'geoid-fallback', retryAt?: number}|undefined}
*/
function cacheRead(lat, lon) {
const cell = cellKey(lat, lon);
if (cell === null) return cacheTouch(cacheKey(lat, lon));
const held = cells.get(cell);
if (held === undefined) return undefined;
if (moves - held.at > PROMOTE_AFTER_MOVES) {
cache.delete(held.key);
cache.set(held.key, held.entry);
moves += 1;
held.at = moves;
}
return held.entry;
}
/**
* Builds the rounded cache key shared between the in-memory cache and the
* `points` string sent to the proxy (see file header, point 2).
@@ -257,7 +142,7 @@ export function createTerrainHeights({
* @returns {number|null}
*/
function cachedEllipsoidalGround(lat, lon) {
const entry = cacheRead(lat, lon);
const entry = cacheTouch(cacheKey(lat, lon));
return entry ? entry.ellipsoid : null;
}
@@ -274,7 +159,7 @@ export function createTerrainHeights({
* @returns {number|null}
*/
function cachedRealEllipsoidalGround(lat, lon) {
const entry = cacheRead(lat, lon);
const entry = cacheTouch(cacheKey(lat, lon));
return entry && entry.source === 'reearth' ? entry.ellipsoid : null;
}
@@ -485,14 +370,7 @@ export function createTerrainHeights({
});
}
signal?.addEventListener(
'abort',
() => {
cache.clear();
cells.clear();
},
{ once: true },
);
signal?.addEventListener('abort', () => cache.clear(), { once: true });
return {
cachedEllipsoidalGround,
cachedRealEllipsoidalGround,
-148
View File
@@ -169,151 +169,3 @@ test('an out-of-range cache bound falls back to the default instead of disabling
);
}
});
/** Counts Number.prototype.toFixed calls made while `run` executes. */
function countToFixed(run) {
const original = Number.prototype.toFixed;
let calls = 0;
Number.prototype.toFixed = function (...args) {
calls += 1;
return original.apply(this, args);
};
try {
run();
} finally {
Number.prototype.toFixed = original;
}
return calls;
}
test('a synchronous read finds exactly the entry its 5-decimal key names', async () => {
// Stored coordinates, and for each the reads that must and must not reach it.
// The expectation is the string key the cache has always used.
const stored = [
[0, 0.001],
[51.47, -0.454],
[-33.94611, 151.17722],
[0.00001, 0.00002],
[-0.00001, 0.00003],
[89.99999, 179.99999],
[-89.99999, -179.99999],
[12.345675, 98.765435],
[1e-7, 5],
[-1e-7, 6],
[7, -1e-7],
[200.5, 361.25],
[10, 500],
[10, 499.999999],
];
const key = (lat, lon) => `${lat.toFixed(5)},${lon.toFixed(5)}`;
const heights = new Map(
stored.map(([lat, lon], i) => [key(lat, lon), 100 + i]),
);
const terrain = createTerrainHeights({
source: {
async getHeights(chunk) {
return chunk.map((item) => ({ ellipsoid: heights.get(item.key) }));
},
},
});
await terrain.resolveEllipsoidalGround(
stored.map(([lat, lon]) => ({ lat, lon })),
);
const probes = [];
const nudges = [
0, 1e-13, -1e-13, 1e-9, -1e-9, 4e-6, -4e-6, 4.9999e-6, 5e-6, -5e-6,
5.0001e-6, 1e-5, -1e-5,
];
for (const [lat, lon] of stored)
for (const a of nudges)
for (const b of [0, 4e-6, -5e-6])
probes.push([lat + a, lon + b], [lat + b, lon + a]);
probes.push([0, 0], [-0, 0.001], [0, -0], [NaN, 1], [1, Infinity], [1e21, 2]);
let hits = 0;
for (const [lat, lon] of probes) {
const expected = heights.get(key(lat, lon)) ?? null;
assert.equal(
terrain.cachedEllipsoidalGround(lat, lon),
expected,
`plain read at ${lat}, ${lon}`,
);
assert.equal(
terrain.cachedRealEllipsoidalGround(lat, lon),
expected,
`real read at ${lat}, ${lon}`,
);
if (expected !== null) hits += 1;
}
assert.ok(
hits > 100 && hits < probes.length,
`${hits} of ${probes.length} reads hit`,
);
});
test('a synchronous read of an ordinary coordinate formats no numbers', async () => {
const terrain = createTerrainHeights({ source: stubSource() });
await terrain.resolveEllipsoidalGround([pointAt(1), pointAt(2)]);
const calls = countToFixed(() => {
assert.equal(
terrain.cachedRealEllipsoidalGround(0, lonAt(1)),
heightAt(lonAt(1)),
);
assert.equal(
terrain.cachedEllipsoidalGround(0, lonAt(2)),
heightAt(lonAt(2)),
);
// Misses are the common case: an aircraft over a cell nobody resolved.
for (let i = 10; i < 1010; i += 1)
assert.equal(terrain.cachedRealEllipsoidalGround(45.123, lonAt(i)), null);
});
// Before, every read built its key with two toFixed calls.
assert.equal(calls, 0);
});
test('an entry read again and again is not rewritten on each read, and still outlives the rest', async () => {
const terrain = createTerrainHeights({
source: stubSource(),
maxCacheEntries: 8,
});
for (let i = 0; i < 8; i += 1)
await terrain.resolveEllipsoidalGround([pointAt(i)]);
// Coordinate 0 is the coldest. Read it between stores, as a parked contact
// would; the seven newer ones are never read.
for (let i = 8; i < 15; i += 1) {
for (let read = 0; read < 50; read += 1)
assert.equal(
terrain.cachedEllipsoidalGround(0, lonAt(0)),
heightAt(lonAt(0)),
);
await terrain.resolveEllipsoidalGround([pointAt(i)]);
}
assert.equal(
terrain.cachedEllipsoidalGround(0, lonAt(0)),
heightAt(lonAt(0)),
);
for (let i = 1; i < 8; i += 1)
assert.equal(
terrain.cachedEllipsoidalGround(0, lonAt(i)),
null,
`unread coordinate ${i} was evicted`,
);
});
test('an evicted coordinate is gone from the synchronous read too', async () => {
const terrain = createTerrainHeights({
source: stubSource(),
maxCacheEntries: 2,
});
for (let i = 0; i < 5; i += 1)
await terrain.resolveEllipsoidalGround([pointAt(i)]);
for (let i = 0; i < 3; i += 1)
assert.equal(terrain.cachedRealEllipsoidalGround(0, lonAt(i)), null);
for (let i = 3; i < 5; i += 1)
assert.equal(
terrain.cachedRealEllipsoidalGround(0, lonAt(i)),
heightAt(lonAt(i)),
);
});