osmWorkflow/.trellis/tasks/archive/2026-08/08-03-test-shapespark-tree-variants/prd.md

Test Shapespark tree variants

Goal

Use the split Shapespark low-poly plant assets as tree, scrub bush, and lawn tuft variants, then validate nantaizi-lake-innovation-valley.

The user liked the Shapespark bush-03 scrub replacement and wants to evaluate whether the same kit can replace the current tree asset. If multiple tree variants are not too expensive, the scene should use varied trees while staying deterministic for the same OSM input.

Requirements

1. Prefer Shapespark tree assets from assets/models/custom/shapespark_plants/tree-*/model.gltf.
2. Use deterministic variant selection based on stable tree instance ordering; do not use unseeded random or time-dependent randomness.
3. Preserve existing tree placement count and route/road/building behavior.
4. Preserve the existing scrub bush bush-03 experiment.
5. Replace the old Poly Haven shrub_02 lawn tuft asset with suitable Shapespark grass assets.
6. Evaluate the cost of loading multiple tree and lawn tuft variants:
   • number of shared tree meshes introduced
   • number of shared lawn tuft meshes introduced
   • texture/image/material counts
   • output GLB size
   • total nodes
7. Rebuild only nantaizi-lake-innovation-valley stages blender,cesium,preview.

Acceptance Criteria

• Tree generation uses Shapespark tree variants deterministically.
• Lawn tufts use Shapespark grass-* variants instead of shrub_02.
• python3 -m py_compile blender/generate_scene.py blender/osmassets/tree.py passes.
• python3 -m unittest blender/tests/test_pure.py passes.
• nantaizi blender,cesium,preview rebuild passes.
• GLB digest reports tree mesh/material/image/node cost.
• User can open the local preview and compare visual result.

Out Of Scope

• Runtime LOD.
• hanyang validation.
• Texture compression / KTX2.
• Committing the experiment before user approval.