Staging guidelines
Learn how to enrich and beautify your models with UVs, materials, and ambient occlusion for production-ready assets.
Read time 4 minutesLast updated a day ago
Why stage your models?
The staging phase transforms a geometrically correct model into a production-ready, visually appealing asset. This optional step enriches your model with visual details that make it suitable for high-quality real-time visualization:- UVs - Texture coordinate mapping for applying materials and baked maps
- Materials - Visual appearance with textures, colors, and PBR properties
- Ambient Occlusion - Pre-baked shadowing for enhanced realism without runtime cost
Important
Staging should be performed after fixing and repairing your models, but before optimization. Follow the import guidelines to ensure models are properly repaired before enriching them with visual details.
Note
The staging phase produces your master model (LOD0) - the highest quality version of your asset that serves as the foundation for optimization and LOD generation.
1. Apply UVs
UV coordinates map 2D textures onto 3D geometry. Without proper UVs, you cannot apply materials with textures or bake lighting information.UV channels for different purposes
Real-time applications typically use two UV channels with different characteristics:UV Channel 0 - Tileable textures
Tileable textures are image patterns designed to seamlessly repeat without visible seams. They're ideal for surfaces like wood, metal, fabric, or stone where the pattern can repeat. Characteristics:- Good UV continuity (minimize visible seams)
- UV alignment and direction preserved
- Low distortion for uniform texture density
- Overlapping UVs allowed
UV Channel 1 - Baking (non-tileable)
Non-tileable textures provide one-to-one correspondence between each texel and a precise part of the mesh. Baking results like ambient occlusion, lightmaps, or unique albedo are stored here. Characteristics:- No overlapping (required for baking)
- Fit to unit square [0,1]
- Maximum use of UV space
- Padding between UV islands
- Controlled distortion
UV0: Tileable texture | UV1: Baking | |
|---|---|---|
| UV Continuity | Seams will be noticeable | Not mandatory |
| UV Distortion | Low distortion preferred | Importance-driven |
| Value range | Any | Unit square [0,1] |
| Overlaps | Allowed | Forbidden |
UV generation workflow
The typical UV pipeline consists of several steps:- Segmentation - How the model will be cut to allow UV unwrapping (UV seams)
- Unwrapping - Each island is flattened (parameterized in 2D)
- Merging (optional) - Merge multiple UV islands to reduce seams
- Alignment (optional) - Align UV islands for tileable textures
- Packing - Position UV islands within the unit square ’for baking
UV generation for CAD (BREP) models
CAD models come with intrinsic parametric surfaces that can be used to generate UVs during tessellation. Use ConformalScaledUV mode to reduce distortion:# Generate UVs during tessellationpxz.algo.tessellate( occurrences, maxSag=0.002, maxAngle=-1, maxLength=-1, uvMode=pxz.algo.UVGenerationMode.ConformalScaledUV)# Copy UV0 to UV1 for baking purposespxz.algo.copyUV( occurrences, sourceChannel=0, destinationChannel=1)# Merge UV0 islands to reduce seams for tileable materialspxz.algo.mergeUVIslandsAffine( occurrences, channel=0, allowedTransformations=pxz.algo.TransformationType.TRSOnly, usePolygonsWeights=1, rotationStep=90)# Repack UV1 for baking (no overlaps, fit to unit square)pxz.algo.repackUV( occurrences, channel=1, shareMap=False, resolution=1024, padding=2)# Normalize UV1 to maximize texture space usagepxz.algo.normalizeUV( occurrences, sourceUVChannel=1, uniform=False # Allow non-uniform scaling for baking)
Tip
For CAD models, mode adjusts parametrization to be more consistent with 3D dimensions, reducing distortion compared to mode.
ConformalScaledUVIntrinsicUV2. Apply materials
Materials define the visual appearance of your model - colors, textures, metallic properties, roughness, and more. Applying materials during staging ensures your master model (LOD0) has the final intended look.Material application workflow
A typical material application workflow involves:- Import a material library - Pre-configured materials saved as a .glb or .pxz file
- Map CAD materials to library materials - Use a CSV mapping table to replace CAD materials with library materials
- Apply materials - Programmatically assign materials based on the mapping
Example: Apply materials from CSV mapping
This example shows how to import a material library and replace CAD materials with new materials based on a CSV mapping file.- Download a pre-made material library from here or create your own by importing models with materials and saving as .pxz.
- Create a CSV file () that maps CAD material names to replacement material names:
material_mapping.csv
Then use this Python script to apply materials:CADMaterialName,MaterialNameColor #ff8000ff,MetalBrushedColor #ffff00ff,PlasticBlackColor #ffffffff,PlasticRedColor #c1c4c0ff,Glass
from pxz import *import csv# Import file root = io.importScene("path/to/cad_file.CATProduct")# Import material library from .pxz or .glb filematerial_library_path = "path/to/pixyz-materials-library/Pixyz_PBR_realistic_materials_library.pxz"root_material_library = pxz.io.importScene(material_library_path)# List all materials from the imported librarymaterial_library_map = {core.getProperty(mat, "Name"):mat for mat in scene.getMaterialsFromSubtree(root_material_library)}# Load material mapping from CSV file# CSV format: CADMaterialName,MaterialName# CADMaterialName: The name of the material from the imported CAD file# MaterialName: The name of the replacement material from the librarymaterial_mapping = {}with open("path/to/material_mapping.csv", "r") as csvfile: reader = csv.DictReader(csvfile) for row in reader: cad_material_name = row["CADMaterialName"] new_material_name = row["MaterialName"] material_mapping[cad_material_name] = new_material_name# Get all occurrences in the sceneroot = pxz.scene.getRoot()replaced_count = 0for material in material.getAllMaterials(): mat_name = core.getProperty(material, "Name") if mat_name in material_mapping: new_mat_name = material_mapping[mat_name] if new_mat_name in material_library_map: new_material = material_library_map[new_mat_name] # Replace material in the scene scene.replaceMaterial(material, new_material) print(f"Replaced material '{mat_name}' with '{new_mat_name}'") replaced_count += 1 else: print(f"Warning: Material '{new_mat_name}' not found in library.") else: print(f"No mapping found for material '{mat_name}'.")print(f"\nTotal materials replaced: {replaced_count}")
3. Bake ambient occlusion
Ambient occlusion (AO) is a shading technique that simulates soft shadows in crevices and corners where ambient light is blocked. Pre-baking AO during staging adds realistic shadowing without runtime performance cost.- Enhanced realism - Adds depth and detail with soft shadowing
- Near zero runtime cost - Pre-computed and stored in textures or vertex colors
- Complements materials - Enhances PBR materials with contact shadows
Staging workflow summary
Here's the complete staging workflow to transform a repaired model into a production-ready master asset:Generate UVs
Create UV channels for both tileable materials (UV0) and baking (UV1).
Note
UV0 allows overlapping for continuity, UV1 requires no overlapping for baking.
Apply materials
Import material libraries and assign materials to parts based on naming or mapping tables.
Note
Material application can be automated using CSV mapping files for large assemblies.
Bake ambient occlusion
Pre-compute self-shadowing and store in textures using UV1 channel.