Use retopo.setup_surface to create a real, editable mesh surface from a source object. The result is ordinary mesh data with no modifier stack dependency — vertex and face data can be edited directly in Blender's standard mesh tools.
Use retopo.project to snap retopo vertices onto the source mesh surface via nearest-point projection. The projection writes directly to vertex coordinates; no Shrinkwrap modifier is applied. Use retopo.transfer_layers to copy vertex groups and color attributes from source to target by nearest-vertex mapping.
Use retopo.validate to check topology quality against maxDeviation and maxPoleValence thresholds. When thresholds are exceeded, the result enters a 'handover' state with an explicit handover: true flag and descriptive issues — this means human editing is required, not that the automatic result is acceptable.
Honesty about automatic results. Voxel remesh and Quadriflow produce automatic topology. These are not professional hand-retopology and must not be described or presented as such. Any result from retopo.setup_surface + retopo.project is a starting point that requires human review and editing for production use.
Save/reopen preservation. Mesh data created by retopo commands is standard Blender mesh data. It survives save/reopen cycles including vertex groups, color attributes, and vertex positions. Validate after reopening to confirm data integrity.
When to Use
Use when a high-density source mesh requires an editable low-poly starting point, surface projection, data layer transfer, and threshold acceptance.
Prerequisites
- Specify the source mesh, target face count or density, maximum deviation, maximum pole valence, and the data layers to transfer.
- Make clear that automatic results are only a starting point; production character topology still requires manual editing and review.
Workflow
Step 1. Inspect the source mesh transforms, normals, and topology, and create an independent editable target surface. Step 2. Project the target vertices onto the source surface and record the actual deviation. Step 3. Transfer the declared vertex groups and color attributes by nearest vertex. Step 4. Run threshold validation; when limits are exceeded, set handover instead of faking a pass. Step 5. Save, reopen, and recheck vertices, faces, data layers, and position integrity.
Validation
Report the source/target objects, vertex and face counts, maximum/average deviation, pole statistics, transferred layers, handover status, and reopen results.
Rules and Capability Boundaries (Inapplicable Scenarios)
Voxel Remesh and Quadriflow are not professional manual retopo; projection results do not automatically satisfy deformation flow, UVs, or production quality.
Gotchas
- Deviation out of range: locate the area and hand it over for manual editing; do not repeatedly auto-retopologize and hope for the best.
- Missing data layers: verify the source layer names and mapping ranges.
- Inconsistent on reopen: stop delivery and review the sequence from the pre-save snapshot.