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

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

Default parameters

{
  "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:

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

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

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 常见坑

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 建议。