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

Smooth Cesium preview vehicle cruise

Goal

Improve perceived smoothness of vehicle cruise in the Cesium preview for nantaizi-lake-innovation-valley while the scene model is visible, especially when Follow passes through scrub-heavy areas.

The initial preview-layer optimization helped but did not solve the root cause: closing Scene helps a lot, and the current nantaizi GLB contains about 707 scrub bush nodes. The root fix is allowed to reduce scrub bush instance density while preserving the flat scrub ground cover and existing preview controls.

Requirements

1. Optimize scripts/lib/cesium-preview.js so vehicle animation does less per-frame work during cruise without reducing default visual clarity.
2. Preserve existing controls and behavior:
   • Play/Pause still drives viewer.clock.shouldAnimate.
   • Speed slider still maps m/s to clock multiplier.
   • Vehicle selection still chooses the follow target.
   • Scene/routes/vehicles/FPS/diagnostics toggles still work.
   • Follow mode still tracks the selected vehicle.
3. Keep the preview layer dependency-free and browser-native; no build step, npm dependency, module system, or hard-coded area filenames.
4. Reduce scrub edge bush instance density in blender/generate_scene.py to lower Cesium render load in scrub-heavy Follow views. Preserve deterministic sampling, scrub ground polygons, scrub tree sampling, and scene stats fields.
5. Regenerate or copy the updated preview JS into outputs/nantaizi-lake-innovation-valley/cesium-preview.js only if needed for local manual verification; do not commit generated outputs.
6. Rebuild nantaizi-lake-innovation-valley blender,cesium,preview outputs for manual validation. This task intentionally changes generated GLB structure, so full parity-identical output is not expected.

Acceptance Criteria

• scripts/lib/cesium-preview.js has a small, reviewable optimization that reduces per-frame allocations or render overhead for vehicle cruise.
• blender/generate_scene.py reduces nantaizi scrub bush node count by at least 50% while keeping scrub polygons present.
• Vehicle controls listed in Requirements continue to work by inspection and/or local smoke check.
• Blender/Cesium rebuild for nantaizi-lake-innovation-valley completes and generated metadata still includes scrub counts.
• node --check scripts/lib/cesium-preview.js passes.
• python3 -m py_compile blender/generate_scene.py passes.
• If local output preview JS is updated for testing, it remains ignored and is not committed.

Out Of Scope

• Full scene geometry/material optimization beyond scrub edge bush density.
• Reducing tree count or changing road/building/water assets.
• Replacing Cesium or adding profiling libraries.
• Visual design changes to the preview UI.

Technical Notes

• User confirmed closing Scene improves smoothness, so the scene render load is a real contributor.
• Current route data is small: nantaizi-lake-innovation-valley has 9 route segments and the preview uses at most 5 vehicles.
• Current nantaizi GLB has 1271 nodes; about 707 are scrub bush nodes. Lowering scrub edge sampling from 0.82m / 180 per patch to 1.8m / 60 per patch should reduce nantaizi bush samples to about 266 while leaving scrub ground cover intact.