Product Assets

CustomForge needs a 3D model with UV coordinates and a named Mesh that receives the live design texture

UV data is normally stored inside the model rather than supplied as a separate .uv file

Supported model files

The current release loads

• Binary GLTF files with the .glb extension
• JSON GLTF files with the .gltf extension and their referenced resources

GLB is usually the easiest format to deploy because geometry, materials, and other model data can be delivered in one file

The current loader expects a model that standard Three.js GLTFLoader can open without additional compression decoders

Model contract

Your product should satisfy all of these requirements

Requirement	Why it matters
Valid UV coordinates	They map the rectangular design canvas onto the 3D surface
A named customizable Mesh	surfaceMesh uses this name to find the target surface
Target material in the first slot	The live canvas texture is assigned to the first material slot
Browser-readable GLB or GLTF	The current loader does not configure extra compression decoders
CORS-enabled remote URL	Browser security must allow the application to fetch the model

The default Mesh name is PrintArea

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

Separate printable overlay

For products with handles, interiors, bases, seams, or other non-printable areas, use a dedicated decal Mesh instead of applying the design to the complete product body

The bundled model follows this structure

cup_decal_small_margins.glb
|-- MugBody    Complete cup, including the body, interior, base, and handle
`-- PrintArea  Thin overlay covering only the printable outer surface

MugBody keeps its original material and never receives user artwork. PrintArea has its own UV layout and receives the live design texture through its first material slot. This keeps the handle and other excluded surfaces out of the editor without deleting UV regions from the complete cup

Keep the overlay close enough to the product surface to avoid a visible gap. CustomForge applies a small polygon offset to the bundled PrintArea to reduce z-fighting

UV coordinates and textures

Think of UV coordinates as the model's map into a flat image

• U is the horizontal texture coordinate
• V is the vertical texture coordinate
• The 2D CustomForge canvas is the texture image being updated
• The 3D model geometry uses its stored UVs to sample that image

The optional textureUrl is a base visual layer beneath editable text and images

It does not provide or replace UV coordinates

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

Use textureFlipY when the design appears vertically inverted on the model

Base texture and design background

These resources have different lifecycles

Resource	Configuration	Saved in Design JSON
Product base texture	product.textureUrl	No
Editable design background	Image object with role: 'background'	Yes

A base texture belongs to the product, while a design background belongs to the user's editable design

Preparing a model

Blender is a common free tool for this workflow

1. Create or import the complete product geometry
2. Create a close-fitting overlay that contains only the printable surface
3. Mark seams and unwrap the overlay
4. Give the overlay a stable name such as PrintArea
5. Assign the customizable material as its first material slot
6. Inspect the UV layout for overlap, orientation, and print margins
7. Export the complete product and overlay together as an uncompressed GLB or GLTF
8. Host the file with the correct CORS response headers

Other DCC tools such as Maya, 3ds Max, Cinema 4D, or Substance 3D can be used as long as the exported model follows the same contract

CORS requirements

Models, base textures, uploaded remote images, preset assets, and remote fonts must allow the web application's origin

For public resources, a typical response includes

Access-Control-Allow-Origin: *

Use a restricted origin instead when the assets should only be consumed by your own application

An image that loads without proper CORS permission can taint the Canvas and prevent PNG export

Preflight checklist

• The model opens in a standard GLTF viewer
• The target Mesh name matches surfaceMesh exactly
• Non-printable geometry is excluded from the target Mesh
• The target surface has usable, non-overlapping UVs where required
• The editable material is in the first material slot
• The design is not upside down, or textureFlipY corrects it
• Every remote asset returns the required CORS headers
• The editor aspect ratio matches the UV layout you prepared