4.2 KiB
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:
830nodes,113meshes,32materials,18images,675accessors
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:
gltf-transform resize -> gltf-transform webp
The script:
- leaves source
.glbintact - 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_DONEwith 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:
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:
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 becauseoptimizeruns broader structural passes.meshopt + WebP 1024:3.66 MBwith directmeshopt, introducingEXT_meshopt_compressionandKHR_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.htmloutputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768-cesium-preview.html
Validation:
node --check scripts/compress-glb.jsnode --check scripts/build-area.jsnpm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages compressnode scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp768.glbnode scripts/glb-digest.js outputs/nantaizi-lake-innovation-valley/nantaizi-lake-innovation-valley-compressed-webp1024.glbpython3 ./.trellis/scripts/task.py validate .trellis/tasks/08-03-experiment-glb-compressiongit diff --check