osmWorkflow/.trellis/tasks/archive/2026-08/08-03-smooth-cesium-preview-vehicle-cruise/report.md

Smooth Cesium preview vehicle cruise report

Root Cause

The first preview-only optimization helped but did not address the main load. User testing showed Follow still stuttered in scrub-heavy areas, while disabling Scene improved smoothness substantially.

Current nantaizi GLB before the scrub-density change:

• GLB nodes: 1271
• Scrub bush nodes: 707
• Scrub polygons: 5

The route data is small (9 route segments, preview uses at most 5 vehicles), so route interpolation is not the primary bottleneck.

Changes

• scripts/lib/cesium-preview.js
  • Route helper polyline is now opaque instead of alpha blended.
  • Route helper polyline uses arcType: Cesium.ArcType.NONE.
  • Vehicle orientation and chase-follow camera callbacks reuse scratch JulianDate, HeadingPitchRoll, Quaternion, and Matrix4 objects.
  • Default Cesium resolution and antialiasing are preserved; no blurry performance mode is enabled by default.
• blender/generate_scene.py
  • SCRUB_BUSH_SPACING: 0.82 -> 1.8
  • SCRUB_BUSH_LIMIT_PER_PATCH: 180 -> 60
  • Scrub ground cover remains unchanged.

Validation

Commands run:

node --check scripts/lib/cesium-preview.js
python3 -m py_compile blender/generate_scene.py
python3 -m unittest blender/tests/test_pure.py
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender,cesium,preview
node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --out /tmp/nantaizi-after-scrub-glb-digest.json

Results after rebuild:

• SCENE_DONE reports scrub_bushes: 266.
• GLB nodes: 830
• Scrub bush nodes: 266
• Scrub polygons in metadata: 5
• Route segments in preview route JSON: 9
• GLB size: about 31.96 MB

Deferred

If Follow still stutters after this density reduction, the next root-level work should target the bush asset itself: lower-poly bush mesh, explicit LOD, or a proper instancing path supported by Cesium/glTF.