From 4ba9b08a1b4452762b985bbe647b8256bae1fdf2 Mon Sep 17 00:00:00 2001 From: Kartios Date: Mon, 24 Aug 2026 19:16:08 -0700 Subject: [PATCH] fix: cull a district by where it stands, not by where its footprint is at sea level MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two independent reviewers found the same defect in `a2a04e0`, which is the only reason it is being fixed rather than shipped. `DetailRange.r` is `reach` from the lattice sweep: the half-diagonal of the district's lat/lng bounding box plus a lot. That is a **plan** radius, and it is a good one — measured over all 59,166 instances, every lot is inside its own district's `r` of the centre with metres to spare. It was then used as the radius of a sphere pinned at `y = 0`, which is a different claim, and one this board does not support: a lot's local y is the ground under it times `verticalExaggeration`, and that is 15 on the merged board. **39 of 97 district ranges had lots outside their own cull sphere**, the worst by 4.78 units — 9.2 km of scene height, in the San Gabriel foothills. Swept over 32,400 poses built the way `scene.ts` builds them, 61 dropped lots that project strictly inside the NDC cube. Hillside buildings vanishing while you look at them. So the range carries `y0`/`y1` — walked once per district at build, over lots that were just pushed — and the test is `Frustum.intersectsBox` instead of `intersectsSphere`. Same six plane tests, and exact for the volume being described rather than right in x/z and wrong in y. Measured, SF 2.5 km: 215,598 → 216,392 triangles. The fix *adds* 794, which is the shape of a correct answer here — it stops discarding geometry that was on screen. The whole-board pose is unchanged and draws are unchanged at 437. The doc comments that asserted the invariant this violated are rewritten rather than deleted; they were the part most likely to survive a fix and mislead. Also corrected there: the pack declares 99 detail districts but ten emit no lot and carry no range, so the quoted reach statistics are over 89, not 99 — the file and the hand-off report disagreed. `blocksDetail.test.ts` gains a peak board, because the existing fixture cannot express this: it exaggerates by 2 with a 200 m hill, so every district's height is a rounding error next to its plan radius and a y=0 volume contains it by accident. The new board is one small district on a 3,000 m peak at 15x — lots at y 36.09-39.28 on a 2.70-unit footprint. Verified to fail against the old volume and pass against the box, rather than assumed to. --- src/engine/blocks.ts | 77 ++++++++++++++++++++------- src/test/render/blocksDetail.test.ts | 79 ++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+), 18 deletions(-) diff --git a/src/engine/blocks.ts b/src/engine/blocks.ts index 05669d3..1dfb10d 100644 --- a/src/engine/blocks.ts +++ b/src/engine/blocks.ts @@ -389,16 +389,42 @@ export function createBlocks( } } if (boxes.length > districtStart) { + /* + * The vertical extent, walked here because the horizontal reach is not it. + * + * `reach` is the half-diagonal of the district's own lat/lng bounding box + * plus a lot, and it is a **plan** radius: measured over all 59,166 + * instances, every lot on the merged board is inside its district's + * `reach` of the centre with metres to spare. It was used as a 3-D radius + * on a sphere pinned at y=0, and that is a different claim — one this + * board does not support. A lot's local y is the ground it stands on + * times `verticalExaggeration`, which is 15 here, so a district in the San + * Gabriel foothills sits kilometres of scene height above the plane its + * cull sphere was centred on. **39 of 97 districts had lots outside their + * own sphere**, the worst by 4.78 units — 9.2 km — and the failure that + * produces is buildings on a hillside vanishing while they are on screen. + * + * So the test is an axis-aligned box and not a sphere. It costs the same + * — `Frustum.intersectsBox` is the same six plane tests as + * `intersectsSphere` — and it is *exact* for the volume being described + * rather than conservative in x/z and wrong in y. Walking the slice is one + * pass over lots that were just pushed, once per district at build. + */ + let y0 = Infinity; + let y1 = -Infinity; + for (let k = districtStart; k < boxes.length; k++) { + const box = boxes[k]!; + if (box.y < y0) y0 = box.y; + if (box.y + box.h > y1) y1 = box.y + box.h; + } districtRanges.push({ start: districtStart, count: boxes.length - districtStart, x: cx, z: cz, - // `reach` is the half-diagonal of the district's own bounding box plus a - // lot, computed a few lines above to size the lattice sweep and until - // now thrown away. It is exactly the radius a sphere around (cx, cz) - // needs to contain every lot this district emitted. r: reach, + y0, + y1, detail: district.detail === true, }); } @@ -538,17 +564,23 @@ export function createBlocks( } /** - * One district's lots, where that district is in scene units, and how far it - * reaches. + * One district's lots, and the box that contains them. * - * `r` is the radius of a sphere on the ground plane that contains every lot the - * district emitted, and it is what the frustum test is run against. Measured - * across the merged board's 99 detail districts it runs from **1.06 km to - * 15.53 km, median 3.82 km** — every one of them an order of magnitude larger - * than the tallest thing standing on it, which is why a sphere centred at y=0 - * needs no vertical pad for the buildings' own height. The eight base districts - * are far larger again; they are the state pack's own, and they are the reason - * a whole-board pose still draws everything. + * `r` is the **plan** radius: the half-diagonal of the district's own lat/lng + * bounding box plus a lot. Measured across the 89 detail districts that emit + * lots it runs from **1.06 km to 15.53 km, median 3.82 km**, and every lot on + * the board is inside its own district's `r` of `(x, z)`. (The pack declares 99 + * detail districts; ten emit no lot at all — every candidate falls in water, in + * a park or outside the coverage roll — and carry no range. The eight base + * districts are far larger again, which is why a whole-board pose still draws + * everything.) + * + * `y0`/`y1` are the vertical extent, and they exist because `r` is not it. A + * lot's local y is the ground under it times `verticalExaggeration` — 15 on the + * merged board — so `r` describes the district's footprint and says nothing + * about how far up the mountain it is. The two together are an axis-aligned box + * and that box is what the frustum test runs against; see the walk in + * `createBlocks` for the measurement that made this necessary. */ interface DetailRange { start: number; @@ -556,6 +588,10 @@ interface DetailRange { x: number; z: number; r: number; + /** Lowest ground any lot stands on, in local scene units. */ + y0: number; + /** Highest roof, in local scene units. */ + y1: number; /** Metro detail, revealed by stand-off; `false` for the base pack's own. */ detail: boolean; } @@ -603,7 +639,7 @@ interface DetailStore { const DETAIL_FRUSTUM_PAD = 0.02; /** Held rather than allocated: the frustum test runs once per district. */ -const REACH_SPHERE = new THREE.Sphere(); +const REACH_BOX = new THREE.Box3(); /** * Draw the cities near `(x, z)` and inside `view`, and no others. @@ -664,9 +700,14 @@ export function updateBlocksDetail( const visible = store.ranges.filter((r) => { if (r.detail && (reachUnits <= 0 || (x - r.x) ** 2 + (z - r.z) ** 2 >= reach2)) return false; if (view === undefined) return true; - REACH_SPHERE.center.set(r.x, 0, r.z); - REACH_SPHERE.radius = r.r + pad; - return view.intersectsSphere(REACH_SPHERE); + /* + * The pad goes on every axis, including the vertical, because the vertical + * is where the camera's own motion is least constrained: a descent changes + * altitude far faster than it changes the ground point being looked at. + */ + REACH_BOX.min.set(r.x - r.r - pad, r.y0 - pad, r.z - r.r - pad); + REACH_BOX.max.set(r.x + r.r + pad, r.y1 + pad, r.z + r.r + pad); + return view.intersectsBox(REACH_BOX); }); const key = visible.map((r) => r.start).join(","); if (key === store.key) return; diff --git a/src/test/render/blocksDetail.test.ts b/src/test/render/blocksDetail.test.ts index db1d665..3dcdb94 100644 --- a/src/test/render/blocksDetail.test.ts +++ b/src/test/render/blocksDetail.test.ts @@ -192,3 +192,82 @@ test("a board with no detail districts is never repacked at all", async () => { updateBlocksDetail(blocks, 0, 0, 0, looking(plain, 36.05, -122.95, 0.2), 1); assert.equal(blocks.count, drawn, "a board with no detail districts must not move"); }); + +/** + * A district on high ground is culled by where it *is*, not by where its + * footprint would be at sea level. + * + * This is a regression test for a real defect, and it is written as a separate + * board because the fixture above cannot express it: that board exaggerates by + * 2 and its tallest hill is 200 m, so every district's height above the ground + * plane is a rounding error next to its own plan radius and a cull volume + * pinned at y=0 contains it by accident. + * + * The merged California board exaggerates by 15. A lot's local y is the terrain + * under it times that, so a district in the San Gabriel foothills stands + * kilometres of scene height above y=0 while its plan radius stays a few units. + * Tested against a sphere centred on the ground plane, **39 of the merged + * board's 97 district ranges had lots outside their own cull volume** — the + * worst by 4.78 units, 9.2 km — and the picture that produces is hillside + * buildings vanishing while they are on screen. + * + * The board below reproduces that geometry rather than that city: one small + * detail district on a 3,000 m peak, exaggerated 15x, so its lots sit about + * forty units up on a footprint about three units across. A camera at the + * summit looking at the summit contains every one of those lots and misses a + * y=0 sphere entirely. + */ +const PEAK_CITY: City = { + ...CITY, + id: "peak-board", + verticalExaggeration: 15, + districts: [district("summit", 37, -122, 0.02, true)], + hills: [{ name: "peak", lat: 37, lng: -122, elevation: 3_000, radius: 0.25 }], +}; + +test("a district on high ground survives a frustum that contains it", async () => { + const world = new World(PEAK_CITY); + assert.equal(await world.ready(), true, "the peak board failed to build a heightfield"); + const blocks = createBlocks(world); + const store = blocks.userData.detail as { ranges: { r: number; y0: number; y1: number }[] }; + assert.ok(store !== undefined && store.ranges.length > 0, "the peak board built no district"); + + /* + * The fixture is only a test while this holds. If a pack edit ever flattens + * this board, the assertion below would pass against a y=0 volume too and + * would quietly stop testing anything. + */ + const range = store.ranges[0]!; + assert.ok( + range.y0 > range.r, + `the fixture is not off the ground plane: y0 ${range.y0.toFixed(2)} against r ${range.r.toFixed(2)}`, + ); + + /* + * Aimed at the summit, and reaching only as far as the summit. + * + * `looking()` above aims every camera at `y = 0` with a far plane ten times + * the stand-off, which is right for that board and useless here: it puts the + * ground plane in the middle of the frustum, so a cull volume pinned to the + * ground plane is contained whatever the terrain does and the defect cannot + * be expressed. This camera hangs eight units over the peak, looks at the + * peak, and stops twelve units short — so the lots at y 36.09-39.28 are in + * frame and the plane at y = 0, thirty-seven units below them, is not. + */ + const [x, z] = world.project(37, -122); + const summitY = world.groundAt(37, -122); + const camera = new THREE.PerspectiveCamera(42, 1, 0.01, 12); + camera.position.set(x, summitY + 8, z); + camera.lookAt(new THREE.Vector3(x, summitY, z)); + camera.updateMatrixWorld(true); + camera.updateProjectionMatrix(); + const view = new THREE.Frustum().setFromProjectionMatrix( + new THREE.Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse), + ); + + updateBlocksDetail(blocks, x, z, REACH, view, 0); + assert.ok( + blocks.count > 0, + "a district standing on a peak was culled by a frustum aimed straight at it", + ); +});