Preparing the latest guides, releases, and feature request updates.
Loading guides
Preparing the right Knowledge Base content for this platform.
Prepare FBX models and environment maps | Chamevo Support Center
Prepare FBX models and environment maps
Create custom 3D models for Chamevo products, including FBX export, environment map setup, config.json structure, and mesh naming conventions.
Updated April 28, 20265 min read
If your product has a unique shape that prebuilt models do not cover, you can create a custom 3D model. This guide covers the file requirements, mesh naming conventions, config.json structure, and upload process.
Before you start
You need a 3D modeling tool that exports FBX files: Blender (free), Cinema 4D, 3ds Max, or Maya.
You need an HDR environment map file for realistic lighting. Free HDR maps are available from sites like Poly Haven.
Basic knowledge of 3D modeling: creating meshes, assigning materials, and exporting files.
Model folder structure
Each 3D model lives in its own folder. The folder must contain exactly three files:
A product with front and back views would have two meshes: custom (front) and custom_1 (back). The customer's design from each canvas view is applied as a texture to the matching mesh.
All other meshes in the model (the product body, handle, base, etc.) can have any name. Only meshes named custom, custom_1, custom_2, etc. receive design textures.
Material setup
Assign a material named custom to the custom mesh. The 3D engine replaces this material's texture with the canvas content.
Non-printable meshes use standard materials. Set their color, metalness, and roughness in the 3D tool — these properties carry over to the web preview.
For color-linkable parts (parts the customer can recolor), give each part a distinct mesh name. You will reference these names in the Color Link 3D Layer element setting.
UV mapping
UV mapping determines how the 2D design texture wraps onto the 3D surface. The custom mesh must have clean UV mapping:
The UV should fill the 0–1 UV space as completely as possible.
Avoid UV overlap — overlapping UVs cause the design to appear in multiple places.
Orient the UV so the design appears right-side-up on the model.
Test the UV by applying a checkerboard texture in your 3D tool. If the squares are uniform and oriented correctly, the UV is good.
Polygon count
Keep the model lightweight for web delivery:
Product type
Recommended polygon count
Simple shapes (mugs, phone cases, bottles)
5,000–15,000 polygons
Medium complexity (shoes, bags)
15,000–40,000 polygons
Detailed products (multi-part items)
40,000–80,000 polygons
Higher polygon counts produce smoother surfaces but increase file size and load time. For web use, aim for the lowest polygon count that still looks smooth.
Step 2: Export as FBX
Export the model from your 3D tool as FBX binary format:
Blender export settings:
Select all meshes.
Go to File → Export → FBX (.fbx).
Set the following:
Path Mode: Copy (embed textures if any).
Apply Modifiers: enabled.
Forward: -Z Forward (or match your scene orientation).
Up: Y Up.
Export as model.fbx.
General export guidelines for any tool:
Export geometry and materials only. Do not include cameras, lights, or armatures unless needed.
Embed textures if the model has baked textures on non-printable parts.
Use binary FBX format (not ASCII). Binary is smaller and loads faster.
Step 3: Prepare the environment map
The environment map provides realistic lighting and reflections. It is an HDR (High Dynamic Range) image that wraps around the scene as a spherical light source.
Create your own in Blender by rendering a scene to an HDR equirectangular image.
Requirements:
Format: .hdr (Radiance HDR).
Resolution: 1024 × 512 or 2048 × 1024 is sufficient. Higher resolutions increase file size without visible benefit at typical product preview sizes.
Name the file exactly environment_map.hdr.
Choose an environment that matches your product context. A neutral studio environment works for most products. An outdoor environment adds natural lighting but may not suit all product types.
Step 4: Create config.json
The config.json file defines the model's identity and rendering properties.
Base color of non-printable surfaces as a decimal integer. 16777215 = white (#FFFFFF). Use a hex-to-decimal converter
ambient_Light_color
number
No
Ambient light color as a decimal integer. 16777215 = white
print_padding
number
No
Padding around the printed design on the mesh (in UV units). 0 = no padding
only_exportable
boolean
No
If true, the model is used only for print-ready export visualization, not customer-facing preview
customMaterialLayers
object
No
Maps mesh names to normal map filenames for added surface detail. Example: { "body": "body_normal.png" }
Print area and aspect ratio
The print_area width and height define the texture resolution applied to the printable mesh. More importantly, their aspect ratio must match the canvas print area aspect ratio in your product.
If your canvas print area is 900 × 600 pixels (3:2), set print_area to any 3:2 ratio — like { "width": 900, "height": 600 } or { "width": 1200, "height": 800 }. Higher values produce sharper textures but use more GPU memory.
Material color format
Colors are specified as decimal integers, not hex strings. Common values:
Color
Hex
Decimal
White
#FFFFFF
16777215
Black
#000000
0
Light gray
#CCCCCC
13421772
Red
#FF0000
16711680
To convert: in JavaScript, parseInt('CCCCCC', 16) returns 13421772.
Normal maps (optional)
Normal maps add surface detail (texture, bumps, grain) to model meshes without adding polygons. If your product has a textured surface (like fabric weave or leather grain), add normal map images to the model folder and reference them in customMaterialLayers:
Each key is a mesh name in the FBX model. The value is the filename of the normal map image in the same model folder. Normal maps should be PNG format, square, and power-of-two resolution (512 × 512, 1024 × 1024).
Step 5: Upload the model
Option A: FTP upload
Connect to your server via FTP or SFTP.
Navigate to wp-content/uploads/chamevo/3d_models/.
Create a new folder matching your model's id value (for example, my-product).
Upload all three files (model.fbx, environment_map.hdr, config.json) into that folder.
Option B: Manual ZIP install
Create a ZIP file containing your model folder (the folder itself, not just the files).
The ZIP structure should be: my-product/model.fbx, my-product/environment_map.hdr, my-product/config.json.
Host the ZIP at a publicly accessible URL.
Use the 3D Models Manager install flow, which downloads and extracts the ZIP to the correct directory.
After uploading, the model appears in the 3D Preview Model dropdown when editing products in Chamevo → Products.
Check your setup
Go to Chamevo → Products, open a product, and select your custom model from the 3D Preview Model dropdown. Save.
Open the product page on the frontend.
Verify the 3D model loads and displays correctly.
Add a design element (text or image) and check that it appears on the model surface.
Rotate the model to verify the design is positioned correctly and not stretched.
Troubleshooting
Model does not appear in the dropdown
Verify the folder is in wp-content/uploads/chamevo/3d_models/.
Verify config.json exists and is valid JSON (no trailing commas, proper quoting).
Verify the id field in config.json matches the folder name exactly.
Design appears stretched or skewed
The print area aspect ratio in config.json does not match the canvas print area. Adjust either the config.json print_area values or the canvas printing box dimensions so the ratios match.
Design appears upside down or rotated
The UV mapping on the custom mesh is oriented incorrectly. Open the model in your 3D tool, adjust the UV rotation, and re-export.
Model loads but looks dark or unrealistic
Check that environment_map.hdr is a valid HDR file and not corrupted.
Adjust base_material_metalness and base_material_roughness in config.json. A metalness of 0.0–0.3 and roughness of 0.5–0.9 works for most non-metallic products.
Try a different HDR environment map.
Console error: "Failed to load model"
The FBX file may be corrupt or in ASCII format. Re-export as binary FBX.
The file path may be incorrect. Check that the model folder URL is accessible in the browser.
