@threeops/optimize

The part of ThreeOps that runs inside a customer's project: analyze and optimize glTF models in place, as a step in their asset pipeline. Small on purpose: no browser, no CLI framework.

threeops-optimize public/content/models --cap 2048

• Textures: KTX2, with KTX-Software 4.3+ (ktx): ETC1S for colour, UASTC for normal maps (at half the cap, 512 px minimum), so they stay compressed in GPU memory. ktx is found on PATH, in the standard install folders, or at THREEOPS_KTX. Without it, threeops-optimize stops (exit 2) instead of quietly making WebP, which would use 4-8x more GPU memory. --allow-webp makes WebP on purpose; KTX2 files already made are never downgraded by a machine without KTX.
• Texture outliers: a file whose textures are much larger than the rest of its folder gets that folder's typical size (e.g. one 2048 px gun among 512 px weapons).
• Geometry and the rest: dedup, instancing, prune, weld, animation resampling, meshopt compression.
• Idempotent: a .threeops-cache.json manifest records each output's hash and settings, so reruns skip files it produced. Changing --cap re-runs them.
• Never worse: if the optimized file isn't lighter on the GPU or the wire, the original is kept.

Options: --cap <px> (default 2048), --images (also resize and re-encode images, same format and name), --image-cap <px>, --allow-webp, --no-ktx2, --quiet.

Guard before builds: threeops-optimize --check <dir> exits 1 unless every model under <dir> is an unchanged output of threeops-optimize with KTX2 textures. threeops fix puts it in the project's prebuild script, so npm run build (and every deploy that builds) refuses an export that didn't finish optimizing.

As a library: import { optimizeDir, optimizeFile, analyzeFile, findSceneIssues, BUDGETS } from '@threeops/optimize'. The threeops CLI (packages/cli) uses it for audits, and threeops fix vendors it into projects as vendor/threeops-optimize-<version>.tgz.

KTX2 encoding calls ktx create directly with the same settings as glTF-Transform's toktx() (verified byte-identical on real models), which keeps this package at ~50 dependencies instead of ~200.