High-Precision 3D Web Optimize#

将高精度 GLB/GLTF 模型优化为适合 Web 3D 与数字孪生平台交付的轻量化资产，重点是 保护 UV、保护材质与贴图表现、降低文件体积与浏览器渲染压力，并输出可直接接入的 LOD 结果。

Do this by default#

1. 先判断模型是否属于高精度交付资产，是否存在高面数、高贴图成本或不规则拓扑风险。
2. 默认保持 workflow UV-safe。
3. 优先做 geometry / texture optimization，再考虑 retopo。
4. 生成 optimized.glb、 lod0.glb、 lod1.glb、 lod2.glb 和 manifest.json。
5. 在 Three.js 或 Babylon.js 中验证加载结果。

Recommended workflow#

1. 检查 model origin、UV risk、topology risk

2. 清理 invalid / dirty geometry

3. 选择纹理压缩格式：

   • WebP（默认）：浏览器原生支持、工具链简单、适合大多数 Web 场景
   • KTX2：GPU 原生纹理、零 CPU 解码开销、适合重度 3D 场景（大量模型同屏、移动端 GPU 受限、需要 Mipmap 精确控制）

4. 执行 UV-safe simplification

5. 压缩 textures and geometry（按 slot 分层选择编码策略与质量参数）

6. 生成 lod0、 lod1、 lod2（按 LOD 级别对不同 slot 差异化分辨率与编码）

7. 写出 manifest.json（含纹理格式、KTX2 参数、slot 级别压缩映射）

8. 验证 browser loading、Draco 解码、KTX2 解码（如适用）与 LOD switching

9. 根据结果给出 tuning advice

Treat as high-precision optimization candidates when you see#

• messy UVs / UV 混乱
• noisy surfaces / 表面噪声重
• baked-looking shadows / 带明显烘焙阴影
• irregular topology / 拓扑不规则
• unusually high polygon count / 面数异常高
• abnormally large .glb size / 文件体积异常大
• high texture resolution or heavy material stacks / 高分辨率贴图或重材质栈

Avoid by default#

• Voxel Remesh
• Quad Remesh
• destructive re-topology that reuses original textures without rebake
• workflows likely to break UV alignment
• 无 Bake 的破坏性重拓扑复材质流程

Default outputs#

text

output/
└─ model-name/
   ├─ model-name.optimized.glb
   ├─ model-name.lod0.glb
   ├─ model-name.lod1.glb
   ├─ model-name.lod2.glb
   └─ manifest.json

Default parameters#

json

{
  "lod0": 1.0,
  "lod1": 0.55,
  "lod2": 0.25,
  "textureSize": 2048,
  "geometryCompression": "draco",
  "textureCompression": "webp",
  "ktx2Options": {
    "etc1sQuality": 128,
    "uastcQuality": 2,
    "mipmapMode": "generate",
    "supercompression": "zstd"
  },
  "textureSlotGroups": {
    "normal": { "ktx2Mode": "uastc", "colorSpace": "linear", "webpQuality": 90 },
    "orm": { "ktx2Mode": "uastc", "colorSpace": "linear", "webpQuality": 90 },
    "baseColor": { "ktx2Mode": "etc1s", "colorSpace": "srgb", "webpQuality": 80 },
    "emissive": { "ktx2Mode": "etc1s", "colorSpace": "srgb", "webpQuality": 75 }
  },
  "lodSlotTextureSizes": {
    "lod0": { "baseColor": 2048, "normal": 2048, "orm": 1024, "emissive": 2048 },
    "lod1": { "baseColor": 1024, "normal": 1024, "orm": 512,  "emissive": 1024 },
    "lod2": { "baseColor": 512,  "normal": 256,  "orm": 256,  "emissive": 512  }
  }
}

• textureCompression： "webp" | "ktx2"，默认 "webp"。
• ktx2Options：仅在 textureCompression === "ktx2" 时生效。
• textureSlotGroups：定义每个纹理 slot 的编码策略（KTX2 模式 / 色空间 / WebP 质量）。
• lodSlotTextureSizes：LOD 级别 × slot 的差异化分辨率映射，远景 slot 可更激进降级。

Slot-Based Texture Compression / Slot 分纹理层级压缩#

Applying identical compression to all textures either bloats size (over-preserving unimportant slots) or over-compresses critical slots. Slot-based logic differentiates by texture semantics:

SlotKTX2 ModeColor SpaceWebP QualityNotesNormalUASTCLinear90Normal maps are precision-sensitive; block artifacts cause lighting jitterORMUASTCLinear90Data textures; channel precision affects material appearanceBaseColorETC1SsRGB80Color textures tolerate compression; high ratio preferredEmissiveETC1SsRGB75Usually small area; can compress more aggressively

LOD × Slot resolution / LOD × Slot 分辨率映射：

LODBaseColorNormalORMEmissivelod02048204810242048lod1102410245121024lod2512256256512

Front-end loaders can read slotCompressionMap from manifest.json to make per-slot lazy-loading decisions.

API Constraint / API 约束#

gltf-transform textureCompress does not support switching ETC1S/UASTC per texture in a single call. The current implementation works around this by grouping textures via the slots parameter and calling textureCompress separately per group. Once gltf-transform adds a mode parameter, per-texture encoding can be controlled more precisely.

Suggested targets#

MetricRecommended valueSingle model size< 10 MBMobile single model size< 5 MBSingle model triangle budget< 100kMain scene total triangle budget< 2MFirst screen load time< 3 s

Troubleshooting#

Material looks blurry / 材质变糊#

• raise textureSize，如 1024 -> 2048
• reduce texture compression strength
• preserve more geometry in lod0

Model is still too large / 模型仍然太大#

• reduce texture size
• make lod1 and lod2 more aggressive
• confirm Draco or Meshopt is enabled
• split the asset for lazy loading if needed

Model deforms after simplification / 模型变形或破面#

• use a higher simplify ratio
• clean non-manifold or broken triangles first
• keep lod0 closer to original geometry

KTX2 Pitfalls / KTX2 常见坑#

IssueCauseFixNormal map rendering jitterETC1S block artifacts destroy normal precisionForce UASTC encoding for Normal texturesBaseColor color shiftWrong color space label (Linear treated as sRGB or vice versa)Mark BaseColor/Emissive as sRGB; Normal/ORM/AO as LinearLarger file size than expectedUASTC without supercompressionEnable Zstd supercompression ( ktx2Options.supercompression: "zstd")Black screen after loadingKTX2Loader.detectSupport(renderer) not calledPass renderer when creating the loaderHDR environment map blown outColor gamut truncation losing brightnessUse UASTC + Zstd encoding with HDR pipelineMipmap flickeringPoor implicit mipmap quality from encoderPre-generate mipmaps ( mipmapMode: "generate") and control filter mode

Escalate only when explicitly requested#

仅当用户明确需要以下目标时，才切换到 Retopo + UV + Bake：

• editable low-poly assets / 可编辑低模
• clean topology / 干净拓扑
• game-engine editing / 游戏引擎深度编辑
• re-texturing workflows / 重新贴材质流程

要明确提醒：这是重制流程，不是简单压缩，成本显著更高。

References#

• references/optimize-glb.mjs: automation template for batch optimization, LOD generation, and manifest output；适合自动化处理与批量生成结果。
• references/threejs-load-lod.js: Three.js loading example for DRACO + LOD integration；适合前端接入与加载代码生成。
• references/package-template.json: minimal Node project template for running the optimization flow；适合初始化最小可运行工程。

Response template#

1. Decision / 判断：说明该任务应继续走 UV-safe optimization，还是升级到 Retopo + UV + Bake。
2. Actions / 已执行项：列出 cleanup、simplification、texture compression、LOD generation、manifest output、load validation。
3. Results / 结果：说明体积变化、几何压缩结果、LOD 输出和 Web loading status。
4. Risks / 风险：指出 blur、deformation、decode-path issues、loading bottlenecks 等问题。
5. Next step / 下一步：给出 tuning、splitting、lazy loading 或 engine integration 建议。