# 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:
---
## 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

*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"]
```
---