Skip to content

feat: Three.js 3D asset overlay with QuadTree LOD and Mapbox camera sync - #84

Merged
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/three-asset-overlay
Jun 25, 2026
Merged

feat: Three.js 3D asset overlay with QuadTree LOD and Mapbox camera sync#84
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/three-asset-overlay

Conversation

@real-venus

Copy link
Copy Markdown
Contributor

Three.js 3D Utility Asset Overlay with QuadTree LOD and Mapbox Camera Sync (#54)

Closes #54

What's included

File Responsibility
src/types/spatial.ts Coordinate3D/AABB/BoundingSphere/FrustumPlane/LODLevel/AssetInstance and invariants: LOD 100/300/500 m, 100 km region, depth 8, 20k cap → 10k batch cull, 512 MB GPU budget.
src/utils/frustum.ts Gribb–Hartmann plane extraction from a column-major VP matrix + conservative sphere/point tests. Three-free → runs in a Worker and is unit-tested.
src/utils/cameraMatrix.ts perspective/lookAt/multiply + web-mercator meters; builds the view-projection without a WebGL context.
src/components/map/lod/QuadTree.ts Capacity-subdividing quadtree with aggregated bounding spheres; queryFrustum returns visible assets tagged by LOD, with nearest-N batch culling past the cap; getLODLevel.
src/workers/frustumCull.worker.ts Owns the tree and runs the per-frame cull off the render thread (matrix in → visible ids + LOD out).
src/hooks/useMapCameraSync.ts Reads map.transform (center/elevation/bearing/pitch) each rAF, maps the mercator center to world meters, emits camera state + VP matrix. Injectable map/rAF.
src/components/map/lod/AssetMesh.ts THREE.LOD factory (detail → box → impostor sprite, empty past 500 m) + InstancedMesh to collapse draw calls. GLTF is injectable (no examples-subpath coupling).
src/components/map/ThreeOverlay.tsx alpha:true renderer on a pointer-events:none canvas over the map container; worker culling, camera sync, and a GPU-memory watchdog that degrades the LOD0 distance to 50 m over budget.
src/components/map/shaders/assetInstancing.vert Per-instance position/yaw/scale vertex shader.
tests/unit/*, tests/hooks/* Frustum math (NDC-cube extraction, sphere/point), camera matrices (frustum round-trip, mercator), QuadTree (subdivision, LOD bucketing, frustum exclusion, batch cull, clear), and camera-sync (rAF loop + pure helpers).

…ync (Utility-Protocol#54)

Adds an immersive 3D overlay over the Mapbox canvas for assessing vertical
clearance and infrastructure density, with frustum-culled Level-of-Detail.

- types/spatial.ts: Coordinate3D/AABB/BoundingSphere/FrustumPlane/LODLevel/
  AssetInstance and invariants (LOD 100/300/500m, 100km region, depth 8, 20k
  cap → 10k batch cull, 512MB GPU budget)
- utils/frustum.ts: Gribb-Hartmann plane extraction from a column-major VP
  matrix + conservative sphere/point tests (Three-free, worker-safe)
- utils/cameraMatrix.ts: perspective/lookAt/multiply + web-mercator meters, used
  to build the view-projection without a WebGL context
- components/map/lod/QuadTree.ts: capacity-subdividing quadtree with aggregated
  bounding spheres; queryFrustum returns visible assets tagged by LOD, with
  nearest-N batch culling past the cap
- workers/frustumCull.worker.ts: owns the tree and runs the per-frame query off
  the render thread
- hooks/useMapCameraSync.ts: reads map.transform each rAF, maps mercator center
  to world meters, emits camera state + VP matrix (injectable map/rAF)
- components/map/lod/AssetMesh.ts: THREE.LOD factory (detail/box/sprite) +
  InstancedMesh; components/map/ThreeOverlay.tsx: alpha renderer overlaid with
  pointer-events:none, worker culling, camera sync, GPU-memory LOD degrade
- shaders/assetInstancing.vert: per-instance position/yaw/scale vertex shader
- adds three + @types/three
- tests for frustum math, camera matrices, QuadTree LOD/cull, and camera sync
@elizabetheonoja-art
elizabetheonoja-art merged commit d284e00 into Utility-Protocol:main Jun 25, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Three.js 3D Utility Asset Overlay with QuadTree LOD and Mapbox Camera Synchronization

2 participants