# Animating an LDraw model This guide shows the **different steps required** in order to animate an LDraw model. Some of them to be performed by the user, but most of them by the agent itself. We will **illustrate** this process by **animating an example car.** The actual process is **iterative** in nature, where **self-corrections** are done by the agent in **feedback loops**, taking into account both **analytical** and **visual aspects**, as shown on this diagram: ```mermaid flowchart LR s1["1. Annotate
annotated car.mpd"] --> s2["2. Convert
IDs + model.glb"] s2 --> s3["3. Plan
plan.json"] s3 --> s4["4. Animate
ai-animated.blend"] s4 --> s5["5. Verify
checks + stills"] s5 -. "fix limits" .-> s3 ``` | Step | Action | Output | | ---- | -------- | ------------------------------------------ | | 1 | Annotate | Annotated `car.mpd` | | 2 | Convert | `plan.json` (draft), annotated `model.glb` | | 3 | Plan | `plan.json` (ready) | | 4 | Animate | `ai-animated.blend` | | 5 | Verify | Final `.blend` + notes | ## Preliminars We will assume that this process will be carried out on **Visual Studio Code**, with the **current repo project open** and also **a new chat session with the agent**. We will need **an LDraw model to start with**, the one that will be **given to an agent** through the chat session. **Two options** here: 1. **Give your own:** the agent will annotate and refine it in order to make it easier to analyze. 2. **Select a pre-annotated one:** run the following to open the model **selector app**, and click **"Copy prompt"** for the model you choose. 3. ```sh python3 model-selector/serve.py ``` Paste the copied **prompt** in the **chat session**, adding extra instructions after it if needed: ``` Animate the following model: some/path/car.mpd (your extra instructions if needed) ``` > [!IMPORTANT] > It is **highly recommended** to provide this initial prompt with the agent set to **Plan mode** **The example car** we will be animating is this one: Sample car --- ## Step 1: Annotate This step will be carried out **only if the provided model is unnanotated.** **The agent** will turn the **source code** of parts into a tree of **described assemblies**, also keeping the pre-existing ones. It will: 1. Run [ldraw-annotator-nova](https://github.com/anteloc/ldraw-annotator-nova) to get **every part's name and colour** from a parts database 2. ... and then it will add those to the model's `.mpd` source as **comments**: `0 // Plate 2 x 10 (black)`. 3. The agent **reads the enriched .mpd sources** and **infers (reverse-engineers) the mechanisms present.** 4. The file is rewritten as a **tree of submodels**, being the **main** one the **root** for the tree. See [docs/annotation.md](docs/annotation.md) for details. ### Before and after **Before:** Four basic submodels, only names but **no real descriptions.** Every submodel that makes the car is one **flat list** of parts: ```mermaid flowchart TD main["106 - main.ldr
“main”"] car["106 - car.ldr
“car”
45 loose parts"] wheel["106 - wheel assembly.ldr
“wheel assembly”
2 parts"] fig["106 - Minifig.ldr
“Minifig”
10 parts"] main --> car main --> fig car -->|×5| wheel ``` **After:** A **refined version** for the former tree, this time with detailed descriptions. These **new submodels**, smaller and also better described, encode the **hierarchy** and semantics **found** by the agent: ```mermaid flowchart TD main["106 - main.ldr
Complete model: blue UNICEF car
with a smiling driver minifig"] car["106 - car.ldr
Blue UNICEF car on a black chassis,
with four grey wheels and a spare"] chassis["106 - chassis.ldr
Black chassis: plates, car base, mudguards,
steering wheel, red rear lights
19 parts"] wheels["106 - wheels.ldr
Wheel set: four wheels and a spare
on wheel-pin plates
2 parts"] wheel["106 - wheel assembly.ldr
Light grey rim with black tyre
2 parts"] body["106 - cabin-body.ldr
Blue body with UNICEF logo panels
10 parts"] front["106 - front-end.ldr
Headlight bricks, yellow lights,
black grille
8 parts"] doors["106 - doors.ldr
Pair of blue hinged doors
2 parts"] roof["106 - hinged-roof.ldr
Clear windscreen and blue hinged roof
4 parts"] fig["106 - Minifig.ldr
Driver minifig: brown hair,
smiling head, blue torso
10 parts"] main --> car main --> fig car --> chassis car --> wheels car --> body wheels -->|×5| wheel body --> front body --> doors body --> roof classDef new fill:#d9f2e3,stroke:#2e7d4f,color:#123 class chassis,wheels,body,front,doors,roof new ``` **Source code** comparison: ``` Before After 0 FILE 106 - car.ldr 0 FILE 106 - chassis.ldr 0 car 0 Black car chassis: long plates and car base with mudguards, … 0 Name: 106 - car.ldr 0 Name: 106 - chassis.ldr … … 1 0 0 0 0 1 0 0 0 1 0 0 0 1 3832.dat 0 // Plate 2 x 10 (black) 1 0 0 0 0 1 0 0 0 1 0 0 0 1 3832.dat ``` --- ## Step 2: Convert **The agent** will give every part on the model an **ID**, lists **how** the **pieces connect**, and then convert: `car.mpd -> model.glb` For the conversion bit, it will use this tool: [mpd2glb](https://github.com/anteloc/mpd2glb) See: [docs/discovery-and-blender.md](docs/discovery-and-blender.md) ### IDs An **ID** is a **part's path** through the model's tree, that is both **unique** and also **encodes where every part is**, in hierarchical terms. **Examples:** ``` 0 106 - car.ldr line 0 of the main model 0/1 106 - cabin-body.ldr line 1 of car.ldr 0/1/10 106 - hinged-roof.ldr line 10 of cabin-body.ldr 0/1/10/2 4213.dat line 2 of hinged-roof.ldr: the roof ``` ### IDs in Blender The converter ([mpd2glb](https://github.com/anteloc/mpd2glb)) **maps** the **model's tree IDs** from **source code** to the **glTF 3D nodes representing parts and submodels**. For that, it will add nodes metadata into glTF `extras`, which Blender imports as **Custom Properties**. With this, **any Blender object** can be **traced back to the exact source line** by the **agent's scripts.** **Example:** The car's roof Custom Properties, available under Blender's **Object Properties → Custom Properties**: ``` fileName 4213.dat description Hinge Car Roof 4 x 4 colorCode 1 mecha_id 0/1/10/2 mecha_section 106 - main.ldr mecha_source b247a29a… (SHA-256 of car.mpd) ``` --- ## Step 3: Plan At this stage, the agent (usually!) **lists** the mechanisms it found, and **asks** what you want. Typical questions are: - Which mechanisms to animate? (For the car: roof, doors, wheels.) - One animation of the whole model, or each mechanism on its own? - For big models: hide the bodywork? Leave out hoses and cables? Then, the agent **applies** (again) its own **toolset** and **decides**, for each mechanism, which pieces would move, around which point and axis, how far, and what drives them, and records it in `plan.json`. This is where the agent **infers how mechanisms would work** for this particular model. **Nothing** in `car.mpd` says **"the roof opens"**: the agent **infers it from a roof, a roof holder and the hinge between them.** See [docs/motion-plan.md](docs/motion-plan.md) for more details. ### How agents work out a plan Strategies used across the [samples](GALLERY.md): 1. **Read the tree and descriptions.** Submodels named `doors`, `hinged-roof` or `wheels` are the first candidates. 2. **Read the connection evidence.** Hinges, shared axles and gear meshes give positions and axes. Scans can miss things: in [42110](samples/42110.md), some gears were hidden from the first scan. 3. **Ask you for the scope**, as above. 4. **Work on a copy when the source falls short.** Extract one mechanism, split parts stored as one piece, add missing parts. Your original is never changed. ([42043 crane](samples/42043-crane.md), [3625](samples/3625.md), [42083](samples/42083-mechanisms.md)) 5. **Compare with a reference.** Use a hand-made rig or an official set with the same parts. ([42000](samples/42000.md), [movables](samples/movables.md), [plants](samples/plants.md)) 6. **Do the maths.** Gear ratios, rod lengths, every gear combination. ([42000](samples/42000.md), [42110](samples/42110.md)) ### Look inside: x-ray boards Mechanisms are usually **hidden inside** models. Because of that, very often, **mechanisms cannot be visually inspected when looking at the whole model**, which would leave the agent with **no visual feedback.** Which made me **vibe-code** this [ldraw-xray](https://github.com/anteloc/ldraw-xray) tool, a thin wrapper around [LeoCAD](https://github.com/leozide/leocad), that (amazingly!) **renders a mechanism even if hidden inside a model:** **Example:** the car's roof and axis ![X-ray board of the car's roof](img/xray-roof.png) *Coloured: the moving piece. Ghosted: the rest of the car. Green rod: the hinge axis (drawn in, not a LEGO part). Panels 3 to 5: the roof at 0°, 40° and 75°.* --- ## Step 4: Animate An here's the last step! **The agent** builds the plan in **Blender**, by means of generating **Blender scripts** that will carry out the job. Those scripts will add a pivot per moving body, a slider per control, and the requested animation. The end result will be saved as `ai-animated.blend`. Process would be as follows: ```mermaid flowchart LR plan["plan.json
roof → 0/1/10/2"] --> script["rig"] glb["Blender object 4213.dat
mecha_id = 0/1/10/2"] --> script script --> rig["PIV_car_roof driven by
slider roof on CTRL_car"] rig --> blend["ai-animated.blend"] ``` ---