Every command-line tool in the pipeline, grouped by what you are trying to do. One
script, one job: nothing here is imported by image_to_3dlab/, and anything worth
reusing was pulled out as a module-level function so it can be tested without Blender
or a GPU.
Each summary below is the script's own first line. tests/test_scripts_registry.py
fails if a script is missing from this file or if a summary has drifted from the
docstring, so a new script is not finished until it is listed here.
Most tools print their real documentation with --help; the docstring at the top of
each file explains why it exists, which is usually the part you need.
Run a backend end to end, or re-run part of one without paying for the whole thing again.
For the staged fitted metarig → proxy weights → reference pose → tunable gait → standing transition workflow, start with the quadruped pipeline guide. It includes commands, parameter definitions, failure checks, and an LLM-assisted tuning checklist. Manual fitting and visual weight/deformation review remain required.
For prop sheets (many props from one image in one run, then split and finished into game-ready LODs), start with the prop sheet guide.
| Script | What it does |
|---|---|
blender_quadruped_pipeline.py |
Bind, capture and animate fitted Rigify quadrupeds with tunable profiles and audit reports. |
quadruped_gait.py |
Gait curves for the Rigify basic quadruped metarig, as pure functions. |
blender_quadruped_walk.py |
Author a natural walk, trot or scamper on any Rigify basic-quadruped rig. |
bootstrap_macos.sh |
Create the project virtualenv and install the SF3D backend and its native dependencies (needs Python 3.10/3.11 and Homebrew's libomp). |
bootstrap_trellis_macos.sh |
Clone and install the shivampkumar/trellis-mac port, with the Metal acceleration backends when Xcode's Metal compiler is present and a slower CPU bake fallback when it is not. |
bootstrap_trellis_space_macos.py |
Bootstrap TRELLIS.2 on macOS from Microsoft's pinned Space source. |
bootstrap_trellis_cuda.py |
Install TRELLIS.2 for Linux with an NVIDIA card: Microsoft's own code, built for CUDA. |
bootstrap_hunyuan_cuda.py |
Install Hunyuan3D-2.1 for Linux with an NVIDIA card: Tencent's own code, built for CUDA. |
bootstrap_hunyuan_rocm.py |
Install Hunyuan3D-2.1 for Linux with an AMD card: Tencent's own code, built with HIP. |
bootstrap_trellis_rocm.py |
Install TRELLIS.2 for Linux with an AMD card: Microsoft's own code, built with HIP. |
bootstrap_sf3d.py |
Install Stable Fast 3D: its code and compiled extensions, then its gated weights. |
patch_sf3d_linux.py |
Let Stable Fast 3D compile its GPU texture baker on an AMD card. |
bootstrap_sf3d_rocm.py |
Install Stable Fast 3D for Linux with an AMD card: its own venv, built with HIP. |
bootstrap_front_back.py |
Install Front + back: the two downloads that build a model from a front and a back picture. |
bootstrap_pixal3d.py |
Install Pixal3D (raven38/pixal3d.cpp): a trellis-cli build plus its Q8_0 weights. |
bootstrap_blender.py |
Install Blender 4.2 LTS for Finish on Linux, from blender.org. |
bootstrap_gltfpack.py |
Install gltfpack for split props, from meshoptimizer's GitHub release. |
bootstrap_hunyuan_xiong.py |
Set up Hunyuan3D-MLX (Xiong, full pipeline): both Python environments, then the weights. |
bootstrap_matte.py |
Install BiRefNet-lite, the background remover every backend uses once it is present. |
bootstrap_upscaler.py |
Install Real-ESRGAN x4plus, the 4x upscaler Hero face uses on the head crop. |
bootstrap_qwen_image.py |
Install the text-to-image route: a stable-diffusion.cpp binary and Qwen-Image weights. |
pixal3d_generate.py |
End-to-end Pixal3D generation: image -> textured GLB, on a Mac, NVIDIA or AMD. |
hero_route.py |
Build a hero character: a full-body model with a high-detail head grafted on, as one GLB. |
hero_blender.py |
Join a grafted head and body into one object, or render a check sheet, in a background Blender. |
upscale_esrgan.py |
Upscale a picture 4x with Real-ESRGAN, then resize it to a square of SIZE pixels. |
make_back_view.py |
Draw the back of a subject from its front picture, for a front + back 3D build. |
trellis_space_generate.py |
Full image -> GLB generation through the CLEAN trellis-space-mac port on Apple Silicon. |
trellis_cuda_generate.py |
Full image -> GLB generation through Microsoft's own TRELLIS.2 on an NVIDIA card. |
trellis_rocm_generate.py |
Full image -> GLB generation through Microsoft's own TRELLIS.2 on an AMD card. |
trellis_route.py |
What differs between the TRELLIS.2 routes, in one place, so the two cannot drift. |
hunyuan_cuda_generate.py |
Full image -> textured GLB through Tencent's own Hunyuan3D-2.1 on an NVIDIA card. |
hunyuan_rocm_generate.py |
Full image -> textured GLB through Tencent's own Hunyuan3D-2.1 on an AMD card. |
hunyuan_mlx_generate.py |
End-to-end Hunyuan3D-MLX generation: image -> textured GLB. |
hunyuan_mlx_xiong_generate.py |
End-to-end, single-repo Hunyuan3D-MLX generation: image -> textured GLB. |
hunyuan_shape_octree_test.py |
Shape-only generation at a given octree_resolution, with visible progress. |
trellis_stage3.py |
Resample only TRELLIS.2's Stage-3 material field on a cached shape latent. |
trellis_rebake.py |
Re-bake a GLB from a cached decode, without re-sampling or loading the model. |
export_decode_highpoly.py |
Export a cached decode as a high-poly PLY, to bake detail from. |
runpod_trellis2_cuda_probe.py |
Run a frozen-shape TRELLIS.2 Stage-3 material probe on CUDA. |
trellis-cuda.txt |
In locks/. Every package but PyTorch for the NVIDIA TRELLIS.2 route, pinned; regenerate with lock_nvidia_routes.py. |
hunyuan-cuda.txt |
In locks/. Every package but PyTorch for the NVIDIA Hunyuan3D-2.1 route, pinned; regenerate with lock_nvidia_routes.py. |
lock_nvidia_routes.py |
Regenerate the NVIDIA routes' lock files (scripts/locks/*.txt) with uv. |
pod_smoke_test.py |
Run the NVIDIA one-shot on a fresh RunPod pod, through the viewer's own web API. |
runpod_trellis2_cuda_requirements.txt |
Pinned CUDA 13 wheels from the RunPod control run; bootstrap_trellis_cuda.py installs them on compute-capability 12.0 cards. |
A generation run costs 15-20 minutes. These cost seconds and are worth it first.
| Script | What it does |
|---|---|
classify_trellis_input.py |
Advisory TinyCLIP check for TRELLIS-hostile flat/vector-style inputs. |
soften_markings.py |
Reduce the contrast of flat painted markings in a conditioning image. |
check_trellis_space_attention.py |
Cheap MPS integration gate for TRELLIS sparse self/cross attention. |
check_trellis_space_dino.py |
Capture the exact preprocessed image and DINO conditioning tensor. |
audit_model_weights.py |
Find model weights stored twice, and optionally reclaim the duplicates. |
Everything here operates on a GLB or a cached decode and is headless.
| Script | What it does |
|---|---|
repair_decode.py |
Repair winding on a cached decode, before to_glb ever sees it. |
fix_winding.py |
Make a generated mesh's faces point outward. |
mesh_weld.py |
Weld vertices that share coordinates exactly, and drop the faces that collapse. |
mesh_health.py |
Measure the structural health of a generated mesh, and optionally repair it. |
fill_holes.py |
Close small holes in a generated mesh, leaving large openings alone. |
remove_loose_parts.py |
Delete disconnected junk from a generated mesh, keeping the texture intact. |
visibility_cull.py |
Pure helpers for visibility-based face culling: keep only what is seen from outside. |
remesh_to_target.py |
Decimate a mesh to a target face count via fast_simplification, with timing. |
crop_mesh.py |
Cut a region out of a mesh at full density, so it can be judged by eye. |
The asset's surface, as opposed to its shape.
| Script | What it does |
|---|---|
paint_eyes.py |
Repaint a generated head's eyes into a dedicated high-resolution patch. |
colour_match_albedo.py |
Grade a generated GLB's albedo toward the colour of its source concept art. |
lift_lightness.py |
Brighten a GLB's albedo without shifting its colour. |
surface_detail.py |
Give a generated asset a surface: normal relief and roughness variation. |
attach_normal_map.py |
Attach a baked normal map to a GLB's material. |
restore_pbr_material.py |
Re-attach the metallicRoughness map that --material-mode matte orphaned. |
fix_glb_opaque_material.py |
Make an existing TRELLIS GLB opaque and single-sided without rebaking it. |
compress_glb_textures.py |
Re-encode a GLB's textures, without touching its geometry. |
retopo_repaint.py |
Finish a generated asset: retopologise, repaint, bake detail, compress. |
finish_props.py |
Finish every prop from a prop sheet: LODs re-baked from the original, then compressed. |
living_organic_material.py |
Apply a reproducible living-organic material recipe to an existing GLB. |
project_labels.py |
Project a 2D image onto a generated mesh as per-vertex colours. |
project_markings.py |
Paint the source image's markings back onto a generated mesh's texture. |
feature_mask.py |
Build a UV-space mask for one feature of a mesh, from a point in 3D. |
bake_stiffness.py |
Bake foliage stiffness into a GLB as vertex colours, for engine-side wind. |
classify_thickness.py |
Separate solid body from thin foliage by measuring local thickness. |
Numbers and renders to decide whether a change helped. Read docs/ before trusting an old one.
| Script | What it does |
|---|---|
compare_to_source.py |
Put a generated asset next to the image it was generated from. |
mark_asset.py |
Record a human verdict on a generated asset, so winners stay findable. |
ribbon_metric.py |
Measure how torn a generated mesh is, and gate post-processing on it. |
tear_provenance.py |
Ask of every large tear: could the input view see it?. |
glb_forensics.py |
Dump what a GLB actually contains, so a reference asset can be diffed against ours. |
mesh_checkpoint_forensics.py |
Measure exact-position topology in an o_voxel .pt geometry checkpoint. |
replay_cleanup_checkpoints.py |
Replay o_voxel cleanup on an exact mesh checkpoint, saving every substage. |
diagnose_remesh_kernel.py |
Isolate why Metal narrow-band DC remeshing emits a wireframe instead of a surface. |
measure_bvh_on_surface.py |
Check MtlBVH on an invariant that scales with the real production mesh. |
measure_bvh_precision.py |
Measure how accurate MtlBVH's unsigned_distance actually is, against exact ground truth. |
xatlas_timing_probe.py |
Time xatlas.parametrize in isolation, to characterize its face-count scaling. |
These talk to a running Blender over the execute_code socket on port 9876 unless they say headless.
| Script | What it does |
|---|---|
blender_stage.py |
Put assets side by side in the RUNNING Blender, lit, textured and ready to look at. |
blender_stage_bake.py |
Render a full frame sequence of a named Action at the locked dungeon-stage camera angle. |
blender_render_asset.py |
Import a GLB into the local Blender MCP scene and render cardinal previews. |
blender_turntable.py |
Render a seamlessly looping 360-degree turntable of a GLB via the Blender MCP scene. |
blender_light_orbit.py |
Render a GLB under an orbiting key light, holding the camera still. |
blender_lineup_sweep.py |
Render a camera sweep past a line-up of assets, headless. |
blender_orbit_camera.py |
Point an orbit camera at a target and (optionally) render. |
blender_inspect.py |
Inspect a Blender scene or an unopened .blend file's contents. |
blender_pick_pixel.py |
Raycast one render pixel into the asset currently staged in live Blender. |
blender_import_character.py |
Append a rigged character (armature + skinned mesh) into the currently live Blender scene, cleaned up and positioned. |
blender_wind_demo.py |
Animate labelled foliage with shader-style wind and render it to MP4. |
blender_agent.py |
Let a local LLM stage a scene in the running Blender, by calling a small set of tools. |
Heavier edits that need Blender's own operators rather than trimesh.
| Script | What it does |
|---|---|
blender_fix_normals.py |
Recalculate outward-facing normals on a generated mesh and re-export it. |
blender_solidify.py |
Give a generated mesh's zero-thickness sheets real thickness, headless. |
blender_solidify_bake.py |
Voxel-remesh a mesh into a closed surface and bake its albedo back on. |
blender_voxel_remesh.py |
Rebuild one closed skin from the decode, using Blender's voxel remesh. |
blender_shrinkwrap.py |
Pull a clean remeshed surface back onto the original decode. |
blender_visibility_cull.py |
Delete every face never seen from outside the mesh, headless. |
blender_retopo_bake.py |
Quad-retopologise a generated mesh and transfer its texture onto the clean topology. |
blender_split_props.py |
Split a multi-prop GLB into one upright, named object per prop, headless. |
blender_reunwrap_bake.py |
Re-unwrap a generated mesh into coherent UV islands and re-bake its texture, headless. |
blender_split_regions.py |
Split a generated mesh into per-region material slots, each with its own texture. |
blender_bake_ao.py |
Bake an ambient-occlusion map from an asset's own geometry, headless. |
blender_bake_normals.py |
Bake TRELLIS' discarded high-poly detail into a normal map for the low-poly mesh. |
blender_bake_detail.py |
Bake the original's surface detail onto a finished mesh: normal map + metallic-roughness. |
The *_pose.py files are pure curve maths with no bpy, which is why they have tests.
| Script | What it does |
|---|---|
blender_joint_markers.py |
Spawn named joint markers on a mesh in Blender, and read their placed positions back. |
blender_build_rig.py |
Build a quadruped armature from placed joint markers and bind the mesh to it. |
blender_voxel_weights.py |
Weight a generated mesh via a watertight voxel proxy, then transfer the result back. |
blender_voxel_weights_code.py |
The Blender-side program for blender_voxel_weights.py. |
blender_rebind.py |
Apply browser fit-joint corrections to an opened prepared Blender scene. |
blender_bind_rig.py |
Generate a Rigify rig and bind a mesh to it through a watertight voxel proxy, headless. |
blender_rebind_weights.py |
Voxel-proxy weight transfer used by the headless rig rebind worker. |
blender_export_rig_binding.py |
Prepare an open Blender metarig scene and export its browser rig sidecar. |
rignet_infer.py |
Run vendored RigNet inference on one of our own generated meshes. |
arm_clearance.py |
Keep a retargeted character's arms out of its own body. |
bootstrap_autorig.py |
Install the auto-rigger: SkinTokens (VAST-AI, MIT), which gives a humanoid mesh a skeleton and skin weights. |
pack_kimodo_clip.py |
Shrink a Kimodo motion clip to what kimodo_retarget.py reads, about 12x smaller. |
clean_skin_weights.py |
Drop skin weights that come from bones far away in the skeleton, then rebalance. |
kimodo_retarget.py |
Play a Kimodo text-to-motion clip on a SkinTokens-rigged humanoid and export an animated GLB. |
rig_check.py |
Say whether a rigged GLB fits the preset moves (a humanoid), read without Blender. |
attack_pose.py |
Pose curves for a quadruped slam attack, as pure functions. |
rigify_walk_pose.py |
Pose curves for a quadruped trot on a Rigify-generated rig, as pure functions. |
blender_walk_cycle.py |
Author a looping quadruped gait cycle on the rigged fox in the live Blender scene. |
blender_rigify_walk_cycle.py |
Author a trot cycle on the Rigify-generated 'rig' armature in the live Blender scene. |
blender_idle_cycle.py |
Author a looping idle for the rigged fox. |
blender_attack_cycle.py |
Author a slam-attack clip on a rigged quadruped in the live Blender scene. |
Numbers about the project itself, not about any asset.
| Script | What it does |
|---|---|
discord_release_card.py |
Post a GitHub release to Discord as a tidy card instead of a bare link. |
discord_pr_card.py |
Post a GitHub pull request to Discord as a tidy card, like the release cards. |
repo_traffic.py |
Save a repo's GitHub traffic and its one-line install counts into one CSV, a row per day. |
vendor/ is git-ignored, so every fix to someone else's checkout lives here as a re-appliable patch script. Each one asserts its anchor and is idempotent; re-running after a bootstrap is the intended workflow.
| Script | What it does |
|---|---|
patch_trellis_space_core.py |
Apply the minimal inference-preserving Mac patch to a Microsoft Space tree. |
patch_trellis_metal_backends.py |
Replay proven image-to-3dlab fixes over pinned Pedro Metal backends. |
patch_trellis_face_cap.py |
Lift the hard 200,000-face cap in the Mac port's generate.py. |
patch_trellis_highpoly.py |
Export TRELLIS' full-resolution mesh before it is simplified away. |
patch_trellis_quality.py |
Expose the quality controls TRELLIS already has and the Mac port never passes. |
patch_trellis_multiview.py |
Teach the vendored TRELLIS.2 to condition on several views of one subject. |
patch_trellis_enable_cleanup.py |
Re-enable the decode-time mesh cleanup that mps_compat.py turns into no-ops. |
patch_trellis_dump_decode.py |
Teach generate.py to cache the decoded mesh, so baking can be re-run without sampling. |
patch_pixal3d_rembg.py |
Stop Pixal3D loading BRIA RMBG-2.0, before it ever downloads it. |
patch_pixal3d_model_subset.py |
Let Pixal3D load only the checkpoints a run actually needs. |
patch_pixal3d_low_vram.py |
Make Pixal3D's low-VRAM mode reachable, via PIXAL3D_LOW_VRAM=1. |
patch_pixal3d_dump_continue.py |
Let Pixal3D save its clean-up input and still write the model, via PIXAL3D_DUMP_CONTINUE=1. |
patch_pixal3d_msvc.py |
Let Pixal3D's uv_bake.cpp build with MSVC (Windows): make one lambda-read constant static. |
patch_pixal3d_steps.py |
Let Pixal3D (pixal3d.cpp) run fewer sampling steps, via PIXAL3D_STEPS=N. |
patch_pixal3d_shape_reuse.py |
Let Pixal3D save a run's shape and later repaint it from new pictures, via PIXAL3D_SAVE_SHAPE / PIXAL3D_LOAD_SHAPE. |
patch_skintokens_portable.py |
Let SkinTokens (the auto-rigger) run on an Apple Silicon Mac, and on NVIDIA without flash-attn. |
patch_hunyuan_rocm.py |
Make Tencent's Hunyuan3D-2.1 survive on an AMD card, without touching what NVIDIA runs. |
photo_paint.py |
Paint a finished model with the real pixels of its source photos, where they can see. |
patch_trellis_no_bria.py |
Disable TRELLIS' configured background model for license-controlled runs. |
patch_trellis_cuda_no_bria.py |
Stop the NVIDIA TRELLIS.2 checkout loading BRIA RMBG-2.0, before it ever downloads it. |
patch_trellis_rocm.py |
Make TRELLIS.2 run on an AMD card: an attention backend, and a build that compiles. |
patch_trellis_mlx_attention.py |
Add an mlx sparse-attention backend to a vendored TRELLIS.2 checkout. |
render_glb_comparison.py |
Render several GLBs from one fixed camera and lay them out as a comparison image. |
patch_ovoxel_pack_options.py |
Let o_voxel.postprocess.to_glb forward xatlas packing options. |
patch_ovoxel_opaque_material.py |
Match the official TRELLIS GLB's opaque, single-sided material flags. |
patch_ovoxel_weld_before_simplify.py |
Weld coincident vertices before every simplify() in o_voxel's to_glb. |
patch_ovoxel_skip_spurious_fill.py |
Use the measured-safe cleanup order for Metal remesh output. |
patch_ovoxel_remesh_checkpoints.py |
Add opt-in exact geometry checkpoints to o_voxel's remesh branch. |
patch_metal_hashmap_miss.py |
Fix the unchecked hashmap miss in the Metal dual-contouring kernel. |
patch_mtlbvh_production_traversal.py |
Apply the production-scale MtlBVH traversal and dispatch-lifetime fixes. |
patch_rignet_macos_compat.py |
Make the vendored RigNet checkout run inference on macOS / Apple Silicon. |
rebuild_metallib.sh |
Recompile and install cumesh's Metal shader library after patching a .metal source, without rebuilding the Obj-C++ extension. |
rebuild_mtlbvh_metallib.sh |
Recompile and install only MtlBVH's Metal shader library after editing bvh.metal. |
rebuild_mtlbvh_native.sh |
Rebuild, install and ad-hoc sign MtlBVH's native extension. Stop every Python worker first: overwriting a loaded Mach-O image makes macOS kill them. |