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

Shapespark tree variant experiment report

Current Trial

nantaizi-lake-innovation-valley now uses:

• scrub bush: assets/models/custom/shapespark_plants/bush-03/model.gltf
• tree style: shapespark
• Shapespark tree variants: 12 deterministic variants from assets/models/custom/shapespark_plants/tree-*/model.gltf
• lawn tufts: 3 Shapespark grass variants from assets/models/custom/shapespark_plants/grass-*/model.gltf
• Cesium export uses a gentler Shapespark foliage profile: gain=1.12, saturation=1.0, emission=0.06.

Variant selection is deterministic: it uses the stable tree instance index and the golden-turn sequence, not runtime random state.

Validation

Commands run:

python3 -m py_compile blender/generate_scene.py blender/osmassets/tree.py blender/export_cesium.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-shapespark-tree-glb-digest.json
node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --out /tmp/nantaizi-shapespark-grass-glb-digest.json
node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --out /tmp/nantaizi-shapespark-toned-glb-digest.json
node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --out /tmp/nantaizi-shapespark-toned-rebuild.json
node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --out /tmp/nantaizi-shapespark-cleanup.json
python3 ./.trellis/scripts/task.py validate .trellis/tasks/08-03-test-shapespark-tree-variants

Results:

• SCENE_DONE.tree_style: shapespark
• Trees planted: 197
• Grass tufts planted: 270
• Scrub bush nodes: 266
• GLB nodes: 830
• GLB meshes: 113
• GLB materials: 32
• GLB images: 18
• GLB accessors after final rebuild: 675 (accessor count is a known glTF exporter fluctuation and is ignored by parity)
• GLB size after color tuning: 20.50 MB
• Shapespark tree mesh datablocks: 12
• Shapespark tree materials: 7
• Shapespark tree images: 7
• Shapespark tree shared geometry: 6,255 vertices / 18,696 indices
• Shapespark lawn tuft mesh datablocks: 3
• Shapespark lawn tuft materials: 2
• Shapespark lawn tuft images: 2
• Shapespark lawn tuft shared geometry: 84 vertices / 90 indices

Assessment

The multi-tree cost is acceptable for this scene. Tree node count stays the same because the implementation links shared mesh datablocks per instance. The extra cost is only 11 more shared tree mesh datablocks than a single tree variant, plus 7 tree texture/material entries. The total GLB is still smaller than the previous apple-tree build because the Shapespark textures and meshes are lighter.

Replacing the former Poly Haven shrub_02 lawn tuft with Shapespark grass-01/02/03 further reduces shared tuft geometry from a high-detail plant asset to only 3 tiny grass-card variants. The lawn tuft instance count stays the same, so the visual density is comparable while the shared geometry cost is effectively negligible.

The color issue came from reusing the apple-tree export profile for every alpha-cut plant. Apple needs strong albedo gain / saturation / emission because its atlas is unusually dark. Shapespark foliage does not; using the apple profile made it read yellow-green and glowing. The final trial keeps the alpha-mask cleanup but uses much lower exposure and emission for Shapespark material names (branch-*, shrubbery-*, high-grass-*, hedge-*, clover-*, flowers-*).

Compared with the pre-Shapespark scrub-density baseline (31.96 MB GLB), this trial is about 11.46 MB smaller while keeping the same object count budget: 830 nodes, 197 trees, 270 lawn tufts, and 266 scrub bush instances. The main savings come from replacing the original heavy scrub bush, the high-detail lawn tuft asset, and the apple tree atlas with lighter shared Shapespark assets.

Cleanup

After user visual approval, the old vegetation assets and their runtime loaders were removed:

• retired tree styles: apple, fattree
• removed assets: SpeedTree apple, Lyrog fattree, Poly Haven shrub_02, original custom/bush, rejected custom/bush_low
• remaining model tree style: shapespark
• remaining external plant asset root: assets/models/custom/shapespark_plants/
• nantaizi rebuild after cleanup stayed at 20.50 MB, 830 nodes, 113 meshes, 32 materials, 18 images