---

name: mesh-extraction description: "Plan, run, and validate Neuralangelo isosurface mesh extraction from trained checkpoints with safe resolution, block size, texturing, filtering, bounds, and PLY checks." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Neuralangelo Mesh Extraction

Use this sub-skill when a trained Neuralangelo checkpoint already exists and the task is to extract, tune, or validate an isosurface mesh. It covers the repository's mesh extraction CLI, config/checkpoint/output relationships, marching-cubes resolution planning, block-wise GPU memory tradeoffs, transforms.json bounds handling, texturing, largest-connected-component filtering, and PLY sanity checks.

Do not use this sub-skill to prepare images/COLMAP/transforms data or to create checkpoints. Route data conversion, camera poses, transforms.json creation, and bounding-sphere adjustment to data-preparation. Route training, config generation, checkpoint selection, resume behavior, and training-time quality issues to training-and-configs.

Evidence basis

This operating guidance is distilled from the repository's isosurface extraction guidance, data-processing notes for transforms.json and bounding-sphere adjustment, training/config entry points, Neuralangelo base/custom configs, mesh extraction implementation, mesh utilities, dataset coordinate normalization, and verified import/help checks for the relevant Python modules and CLIs. Runtime instructions point to bundled skill helpers; execution still requires a user's target Neuralangelo project root because the project code owns the actual model implementation.

Load-bearing facts

• Mesh extraction delegates to the target Neuralangelo project root's extraction entry point against a training config and checkpoint; use the root bundled wrapper when invoking it from this skill.
• The config must resolve cfg.data.root/transforms.json; the script reads sphere_center, sphere_radius, and optionally aabb_range from that JSON.
• The checkpoint is loaded with optimizer/scheduler state disabled, then the model is placed in eval mode and coarse-to-fine SDF levels are set from the checkpoint evaluation iteration.
• --resolution controls global marching-cubes sample spacing (2 / resolution); it mainly affects detail, runtime, and output size.
• --block_res controls the per-block lattice size; it mainly affects peak GPU memory and block count, not the target detail.
• --textured exports vertex colors by evaluating the RGB head at mesh vertices; it is slower and uses more memory.
• --keep_lcc filters each extracted block to its largest connected component before final concatenation; it can suppress floating noise but can also remove thin or disconnected structures.
• The final PLY is exported by the master process in world coordinates after multiplying vertices by sphere_radius and adding sphere_center.

Standard workflow

1. Confirm the checkpoint/config pair:
   • Prefer the config.yaml saved next to the training logs for the checkpoint.
   • Confirm data.root in the config points to the intended scene data root.
   • Confirm that data root contains a transforms.json with camera frames plus sphere_center and sphere_radius.
2. Plan resolution and memory:
   • Start with a smoke extraction at low resolution before a production-quality run.
   • Reduce block_res first for CUDA out-of-memory; reduce resolution when final mesh size/runtime is too large or the scene only needs coarse geometry.
   • Disable --textured until geometry is acceptable.
3. Run extraction:
   • Single process: use python ... --single_gpu.
   • Multi-GPU: use torchrun --nproc_per_node=<N> without --single_gpu.
   • Always make --output_file include a parent directory, because the bundled extractor creates the parent directory before export.
4. Validate the result:
   • Check console counts for nonzero vertices/faces and, when textured, colors.
   • Run the bundled scripts/validate_mesh_file.py on the produced PLY.
   • Inspect whether the mesh is cropped, shifted, hollow, noisy, or missing thin structures before treating it as a final reconstruction.

Command template

CONFIG=logs/<group>/<name>/config.yaml
CHECKPOINT=logs/<group>/<name>/<checkpoint>.pt
OUTPUT=mesh_outputs/<scene>_r2048_b128.ply
RESOLUTION=2048
BLOCK_RES=128
GPUS=1

python ../../scripts/run_neuralangelo_entrypoint.py \
  --project-root <neuralangelo-root> \
  --entrypoint extract-mesh -- \
  --config=${CONFIG} \
  --checkpoint=${CHECKPOINT} \
  --output_file=${OUTPUT} \
  --resolution=${RESOLUTION} \
  --block_res=${BLOCK_RES}

Add --textured only after geometry looks reasonable. Add --keep_lcc only when removing floating components is worth the risk of losing thin or disconnected geometry.

Bundled helpers

• scripts/plan_mesh_extraction.py performs a safe, static preflight of config/checkpoint/output/transforms paths, estimates normalized lattice dimensions and block counts, and can print a ready-to-run extraction command. It does not import or execute Neuralangelo.
• scripts/validate_mesh_file.py performs basic PLY header validation with the Python standard library and can optionally load the mesh with trimesh when installed.

Reference map

• references/workflows.md — preflight, command recipes, resolution/block planning, texturing/LCC guidance, validation workflow, and usability case ideas.
• references/mesh-api-and-outputs.md — extractor CLI flags, internal data flow, transforms.json coordinate handling, output PLY semantics, and bundled helper contracts.
• references/troubleshooting.md — symptoms, likely causes, recovery steps, and escalation/reroute guidance.