Adopt Shapespark vegetation assets

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

@@ -0,0 +1,99 @@
+# 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:
+
+```bash
+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