产品资源

CustomForge 需要一个包含 UV 坐标的三维模型，以及一个用于接收实时设计纹理的命名 Mesh

UV 数据通常保存在模型内部，而不是作为单独的 .uv 文件提供

支持的模型文件

当前版本可以加载

扩展名为 .glb 的二进制 GLTF 文件
扩展名为 .gltf 的 JSON GLTF 文件及其引用资源

GLB 通常更适合部署，因为几何体、材质和其他模型数据可以通过一个文件交付

当前加载器要求模型能够由标准 Three.js GLTFLoader 直接打开，不依赖额外的压缩解码器

模型契约

商品模型应满足以下全部要求

要求	原因
有效的 UV 坐标	将矩形设计画布映射到三维表面
命名的可定制 Mesh	`surfaceMesh` 通过名称查找目标表面
目标材质位于第一个材质槽	实时 Canvas 纹理会赋给第一个材质槽
浏览器可读取的 GLB 或 GLTF	当前加载器不会配置额外的压缩解码器
允许跨域访问的远程地址	浏览器安全策略必须允许应用获取模型

默认 Mesh 名称为 PrintArea

product: {
  modelUrl: 'https://cdn.example.com/product.glb',
  surfaceMesh: 'PrintArea',
}

独立可打印贴花层

商品包含把手、内壁、底部、接缝或其他不可打印区域时，建议使用独立贴花 Mesh，不要让完整商品主体直接接收用户设计

随包模型采用以下结构

text

cup_decal_small_margins.glb
|-- MugBody    完整杯子，包含杯身、杯内、杯底和把手
`-- PrintArea  只覆盖可打印外表面的薄贴花层

MugBody 保留原始材质，不接收用户设计。PrintArea 拥有独立 UV，并通过第一个材质槽接收实时设计纹理。这样无需从完整杯子删除 UV 区域，也能把把手和其他不可打印表面排除在编辑器之外

贴花层应尽量贴近商品表面，避免出现可见间隙。CustomForge 会对随包 PrintArea 使用轻微的 polygon offset 来减少 z-fighting

UV 坐标与纹理

可以把 UV 坐标理解为模型指向一张平面图片的地图

U 是纹理的横向坐标
V 是纹理的纵向坐标
CustomForge 二维画布就是不断更新的纹理图片
三维模型几何体通过内部 UV 对这张图片取样

可选的 textureUrl 是位于可编辑文字和图片下方的商品基础视觉图层

它不能提供或替代 UV 坐标

product: {
  modelUrl: 'https://cdn.example.com/product.glb',
  textureUrl: 'https://cdn.example.com/base-texture.png',
  surfaceMesh: 'PrintArea',
  textureFlipY: true,
}

设计内容在模型上垂直颠倒时可以使用 textureFlipY

基础纹理与设计背景

这两种资源拥有不同的生命周期

资源	配置位置	是否保存到 Design JSON
商品基础纹理	`product.textureUrl`	否
可编辑设计背景	`role: 'background'` 的图片对象	是

基础纹理属于商品，设计背景属于用户可编辑的设计

制作模型

Blender 是这个工作流中常见的免费工具

创建或导入完整商品几何体
创建一个只包含可打印表面的贴合覆盖层
标记接缝并展开覆盖层的 UV
为覆盖层设置稳定名称，例如 PrintArea
将可定制材质放在第一个材质槽
检查 UV 布局的重叠、方向和印刷边距
将完整商品与贴花层一起导出为未压缩的 GLB 或 GLTF
使用正确的 CORS 响应头托管文件

也可以使用 Maya、3ds Max、Cinema 4D 或 Substance 3D，只要最终导出的模型符合相同契约

CORS 要求

模型、基础纹理、远程图片、预设素材和远程字体都必须允许网页应用所在来源访问

公开资源通常包含以下响应头

http

Access-Control-Allow-Origin: *

资源只允许自己的应用使用时，应改为具体的来源地址

缺少正确 CORS 权限的图片可能污染 Canvas 并导致 PNG 导出失败

上线前检查

模型可以在标准 GLTF 查看器中打开
目标 Mesh 名称与 surfaceMesh 完全一致
不可打印几何体未包含在目标 Mesh 中
目标表面在需要的位置具有可用且不重叠的 UV
可编辑材质位于第一个材质槽
设计方向正确，或 textureFlipY 能够完成修正
所有远程资源都返回所需 CORS 响应头
编辑器宽高比与制作的 UV 布局一致

产品资源 ​

支持的模型文件 ​

模型契约 ​

独立可打印贴花层 ​

UV 坐标与纹理 ​

基础纹理与设计背景 ​

制作模型 ​

CORS 要求 ​

上线前检查 ​