100 lines
4.2 KiB
Markdown
100 lines
4.2 KiB
Markdown
# 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`
|