# GLB compression experiment report

## Baseline

Target: `nantaizi-lake-innovation-valley`

- source GLB: `20.50 MB`
- embedded images: `17.72 MB`
- non-image buffers: `2.45 MB`
- counts: `830` nodes, `113` meshes, `32` materials, `18` images, `675` accessors

The file is texture-heavy, so texture resize / transcode is the primary lever.

## Implemented

Added `scripts/compress-glb.js` and `npm run compress:glb`.

Default chain:

```text
gltf-transform resize -> gltf-transform webp
```

The script:

- leaves source `.glb` intact
- writes a separate compressed `.glb`
- optionally copies metadata to point at the compressed GLB
- optionally copies the existing Cesium preview HTML to point at compressed
  metadata
- prints `GLB_COMPRESS_DONE` with before/after size, image/non-image size,
  counts, and extensions

After visual review accepted the WebP result, added an explicit `compress`
stage to `scripts/build-area.js`:

```bash
npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages compress
```

The stage calls the same script, writes `<fileStem>-compressed-webp768.*` by
default, and remains outside `all`.

## Results

Commands:

```bash
npm run compress:glb -- --input outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --output outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024.glb --metadata outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.json --preview outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-cesium-preview.html
npm run compress:glb -- --input outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.glb --output outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768.glb --texture-size 768 --metadata outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley.json --preview outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-cesium-preview.html
```

Results:

| Variant | Size | Image bytes | Non-image bytes | Structure |
|---|---:|---:|---:|---|
| source | `20.50 MB` | `17.72 MB` | `2.45 MB` | baseline |
| WebP 1024 | `5.48 MB` | `2.73 MB` | `2.45 MB` | unchanged counts |
| WebP 768 | `4.80 MB` | `2.04 MB` | `2.45 MB` | unchanged counts |

Both WebP outputs keep `830` nodes, `113` meshes, `32` materials, `18` images,
and `675` accessors. They introduce `EXT_texture_webp` and
`KHR_texture_transform`.

`scripts/glb-digest.js` can inspect both compressed GLBs and reports the same
node/mesh/material/image/accessor counts as the source.

Visual review in Cesium on 2026-08-03: the user compared the generated WebP
preview and reported no obvious visible difference from the source preview.

Extra experiments:

- `optimize --texture-compress webp --texture-size 1024`: `4.29 MB`, but mesh
  and material counts changed because `optimize` runs broader structural passes.
- `meshopt + WebP 1024`: `3.66 MB` with direct `meshopt`, introducing
  `EXT_meshopt_compression` and `KHR_mesh_quantization`.
- KTX2 was blocked locally because glTF Transform requires external
  KTX-Software `ktx`, which is not installed.

## Recommendation

Use the explicit `compress` stage for optional compressed Cesium review /
delivery candidates. Keep the uncompressed GLB as the baseline artifact. Do not
make Meshopt or KTX2 default until Cesium compatibility is verified visually.

Generated preview candidates:

- `outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024-cesium-preview.html`
- `outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768-cesium-preview.html`

Validation:

- `node --check scripts/compress-glb.js`
- `node --check scripts/build-area.js`
- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages compress`
- `node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768.glb`
- `node scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024.glb`
- `python3 ./.trellis/scripts/task.py validate .trellis/tasks/08-03-experiment-glb-compression`
- `git diff --check`