The Problem

Generative 3D modeling typically outputs static meshes that are hard to edit. MeshCoder addresses this by generating Blender Python scripts from point clouds, producing editable, programmatic 3D geometry. This shifts 3D reconstruction from fixed outputs to code that can be modified, re-parameterized, and re-executed.

What This Does

MeshCoder is a multimodal LLM pipeline: it takes a 3D point cloud (npz format) and produces a Blender script that reconstructs the object. The core logic lives in src/llama_recipes/custom_models/ — a modified Llama-3.2-1B with custom attention modules (cross_attn/, point_cross_attn/) and a DINOv2 vision backbone for point feature extraction. The recipes/ folder contains inference, finetuning, and benchmark examples.

The training pipeline (in src/llama_recipes/finetuning_shape2code.py and train_utils_shape2code.py) uses LoRA adapters and a shape tokenizer to map point clouds to code tokens. The pretrained checkpoint and 100K paired object-code dataset are hosted on Hugging Face.

How It Is Wired

Execution starts at main in recipes/code_llama/code_completion_example.py, which reaches 118 functions. For the core shape-to-code path, the entry is recipes/inference/local_inference/inference_shape2code.py, which loads the LoRA adapter and shape tokenizer, then calls the model via model.generate (traced path: main -> inference).

The highest fan-in modules are the custom model files:

  • src/llama_recipes/custom_models/modeling_llama.py — 51 functions, 14 classes, called from 3 files, imports 10 modules. This is the Llama core; changes here ripple through everything.
  • src/llama_recipes/blender_scripts/bpy_lib.py — 54 functions, called from 9 files. It owns mesh generation primitives (delete_all, recalculate_normals, get_faces).
  • src/llama_recipes/custom_models/modeling_llama_3_2.py — 49 functions, 16 classes, the Llama-3.2 variant.

The internal call graph shows 524 resolved edges. array is called from 23 places, solidify from 13, and permute from 9 — these are the widest blast radius functions. The module graph has no circular dependencies, which is good for maintainability. The code touches the outside world through 13 model inference calls, 7 network calls, 7 database operations, and 24 file I/O operations. The wiring for side effects (e.g., which function writes to disk) has not been fully mapped for this repository.

How To Use It

Setup (from README, tested with Python 3.10, PyTorch 2.4.1, CUDA 11.8):

git clone https://github.com/moses-y/MeshCoder
cd MeshCoder
conda install pytorch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 pytorch-cuda=11.8 -c pytorch -c nvidia -y
pip install bpy==4.0.0
pip install -e .

Configuration: Download pretrained models from Hugging Face. Place config.yaml, shape_tokenizer.pt, adapter_config.json, adapter_model.safetensors into MeshCoder/llama-3-models/object_to_code_model/, and the base Llama-3.2-1B into MeshCoder/llama-3-models/Llama3.2-1B.

Running inference: Use recipes/inference/local_inference/inference_shape2code.py with an npz point cloud file. The README documents this but the exact CLI flags are not fully specified in the repo — you'll need to check the script's argument parser.

Real-World Use

A product design team captures a physical object via photogrammetry, exports a point cloud, and runs MeshCoder to get a Blender script. They then edit the generated code to adjust dimensions, change topology, or create variations — all without re-scanning. The code output is the deliverable, not the mesh.

Code Health & Issues

Static analysis found 50 issues (21 high, 26 medium, 3 low) across 9 kinds. Key findings:

  • High — Duplicated code blocks: 1,293 repeated 6-line blocks across 45 files, notably in recipes/benchmarks/inference_throughput/ (Azure/vLLM benchmark scripts). Extract shared helpers.
  • High — Oversized files: bpy_lib.py (1,685 lines), modeling_llama.py, modeling_llama_3_2.py. Splitting by responsibility is warranted.
  • High — Deep nesting: 28 instances of 10-level indentation in recipes/code_llama/ examples.
  • Medium — File handles without context managers: 6 cases in blender_scripts/code_to_mesh.py, datasets/alpaca_dataset.py, datasets/oss_io_utils.py.
  • Medium — Broad exception handling: 8 cases in bpy_lib.py, point_projection.py, craftsman_utils/base.py.
  • Low — TODO/FIXME markers: 20 total across modeling_llama.py, modeling_llama_3_2.py, cross_attn/attention.py.

SDLC observations: no CI/CD pipeline, no lockfile (non-reproducible builds), only 1 test file against 122 source files (ratio 0.008), and a 11.9MB PDF committed to the repo. A license is present; no committed secrets found.

The Bottom Line

MeshCoder is a technically interesting research codebase with a novel approach — code-as-output for 3D modeling. The core model code is dense but well-structured (no circular dependencies). The practical gaps are reproducibility (no lockfile, no CI) and maintainability (large files, heavy duplication). Use it for research and prototyping; production deployment would require hardening the build and test pipeline first.