# 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