Texturing Pipeline

Overview

Generate photo-realistic texture atlases for 3D meshes in Metashape. Covers UV mapping, texture generation, color calibration, and quality optimization. This skill is used AFTER mesh building and BEFORE export.

When to Use

• After mesh is built and cleaned, ready for texturing
• When choosing texture settings for a specific output (game engine, web viewer, print)
• When texture quality is poor (blurry, seams, ghosting, color shifts)
• When re-texturing after mesh edits

Prerequisites

• Mesh exists in chunk (get_model_stats() should return data)
• Cameras aligned with good reprojection error (<1.0 px)
• Mesh cleaned of artifacts (run clean_model first)

Standard Texture Pipeline

Step 1: Build UV Map

build_uv(
    mapping_mode="generic",
    texture_size=8192
)

UV mapping modes:

For road corridors: generic is the right choice. The geometry is too complex (walls, overhangs, road surface) for orthophoto modes.

Step 2: Build Texture Atlas

build_texture(
    blending_mode="natural",
    texture_size=8192,
    ghosting_filter=True
)

You may also pass anti_aliasing, or if you are baking from another model (e.g. you decimated a high‑res mesh and want to reuse its texture) include source_model_key=<int>, transfer_texture=True, and source_data="model". When using a source model the blending mode must be "mosaic" to avoid assertion errors in Metashape 2.3+.

Step 3: (Optional) Color Calibration

If colors look inconsistent across the mesh:

calibrate_colors(
    source_data="model"
)

Run this BEFORE build_texture for best results. Color calibration normalizes brightness/color across cameras — critical for long corridors captured over varying lighting conditions.

Blending Modes — When to Use What

This is the most important texture decision. Each mode produces dramatically different results.

Default: always use "natural" unless the user explicitly requests otherwise.

Natural (Default)

build_texture(blending_mode="natural", ...)

• How it works: Blends multiple camera contributions with smooth falloff at seams
• Result: Smooth color transitions, no visible seams. Clean, seamless textures.
• Best for: Everything — walls, road corridors, objects, terrain, organic surfaces
• Why default: Produces the most professional-looking result without color seams or patchwork artifacts

Mosaic (User-requested only)

build_texture(blending_mode="mosaic", ...)

• How it works: Each face gets texture from the single best camera (closest, most perpendicular)
• Result: Sharpest possible detail per-patch, but visible seams between patches
• Downside: Color/exposure seams between patches. Requires very consistent exposure across all cameras.
• When to use: Only when the user specifically requests maximum sharpness and accepts seam artifacts

Average

build_texture(blending_mode="average", ...)

• How it works: Arithmetic mean of all camera contributions per texel
• Result: Very smooth but noticeably blurry. Reduces noise but loses detail.
• Downside: Blurriest option. Not recommended for most use cases.
• Best for: Noisy datasets, very low-res cameras, preview textures

Max / Min

• max: Brightest camera value per texel. Useful for detecting features.
• min: Darkest camera value. Rarely useful.

Texture Size Selection

VRAM budget reality:

• 4096x4096 × 4 channels = ~64 MB per tile
• 8192x8192 × 4 channels = ~256 MB per tile
• 16384x16384 × 4 channels = ~1 GB per tile

For 80 tiles at 8192: ~20 GB texture memory. Most game engines stream/LOD this, but it's worth knowing.

Ghosting Filter

build_texture(ghosting_filter=True, ...)

What it does: Detects and removes texture contributions from cameras that captured moving objects (vehicles, pedestrians, shadows).

Always enable for road corridors. Vehicles and pedestrians appear in multiple camera views at different positions — without ghosting filter, they create blurred/duplicated artifacts on the road surface.

When to disable: Static indoor scenes, objects on turntables, anything without moving elements.

Re-Texturing After Mesh Edits

If the mesh was modified (decimated, cleaned, split) after initial texturing:

# UV map may be invalid after mesh changes — rebuild
build_uv(mapping_mode="generic", texture_size=8192)
build_texture(blending_mode="natural", texture_size=8192, ghosting_filter=True)

If only small edits were made and UV is still valid:

# Just rebuild texture, keep existing UV
build_texture(blending_mode="natural", texture_size=8192, ghosting_filter=True)

Diagnosing Texture Problems

Pro tip: if you ever need to bake a texture from a previous chunk or model (for example, transferring a high‑res atlas onto a decimated mesh) use the source_model_key/transfer_texture parameters described above.

Blurry texture

Visible seams

Ghosting / double images

Color shifts / banding

Texture for Tiled Export

When exporting tiles for Blender/game engine, each tile gets its own texture atlas. For consistent look:

1. Run calibrate_colors ONCE on the full mesh
2. Build UV + texture on the full mesh
3. Export tiles individually — each tile carries its portion of the atlas

Or, if tiling is done in Blender:

1. Export untextured mesh tiles (PLY with vertex colors)
2. Process in Blender (cleanup, classification)
3. Re-import cleaned tiles into Metashape
4. Re-texture with the cleaned geometry

The handoff-coordinator agent manages this round-trip.

Common Settings Combinations

Road corridor (driving simulator)

calibrate_colors(source_data="model")
build_uv(mapping_mode="generic", texture_size=8192)
build_texture(blending_mode="natural", texture_size=8192, ghosting_filter=True)

Aerial terrain (orthomosaic alternative)

build_uv(mapping_mode="adaptive_orthophoto", texture_size=8192)
build_texture(blending_mode="natural", texture_size=8192, ghosting_filter=False)

Detailed object (statue, artifact)

build_uv(mapping_mode="generic", texture_size=16384)
build_texture(blending_mode="natural", texture_size=16384, ghosting_filter=False)

Quick preview

build_uv(mapping_mode="generic", texture_size=4096)
build_texture(blending_mode="natural", texture_size=4096, ghosting_filter=False)