Skip to main content
Glama
cad-blender-bridge

cad-blender-bridge

by DECRUX9812
README.md
# cad-blender-bridge

An agentic bridge between **natural-language CAD parameters**, **[build123d](https://github.com/gumyr/build123d)**
(the OpenCascade B-Rep kernel) and **headless Blender (`bpy`)** — with an
**[MCP](https://modelcontextprotocol.io)** server so any MCP-capable agent can drive the whole loop.

Ask an agent for *"a planetary gearbox, module 1.5, 16-tooth sun, three 8-tooth planets, 10 mm thick"*
and get back a **true multi-part B-Rep assembly**, verified `.step` / `.stl` exports, a manifold-checked
mesh, and a studio render — not a picture of gears.

![verification render](assets/verify_sample.png)

## Architecture

```
natural-language parameters (via MCP tool call)
        │
        ▼
┌─────────────────────────────────────────────────────────┐
│ build123d / OpenCascade B-Rep kernel                    │
│  • involute tooth profiles (20° pressure angle)         │
│  • sun + planets (PolarLocations, mesh-phased) + ring   │
│  • Mode.SUBTRACT bores, Z-axis edge fillets             │
│  • assertions: is_valid, volume > 0, exact bbox,        │
│    pairwise interference ≤ 0.1 ppm of volume            │
└─────────────────────────────────────────────────────────┘
        │  out/planetary_assembly.step  (B-Rep, CAD interchange)
        │  out/planetary_assembly.stl   (tessellated mesh)
        │  out/manifest.json            (build + verification manifest)
        ▼
┌─────────────────────────────────────────────────────────┐
│ headless Blender (blender --background --python …)      │
│  • STL import (wm.stl_import, legacy fallback)          │
│  • bmesh integrity: non-manifold edges, zero-area faces │
│  • Cycles studio render (EEVEE fallback): metallic      │
│    Principled BSDF, key + fill AREA lights,             │
│    orthographic isometric camera → 1024×1024 PNG        │
│  • out/verification_report.json                         │
└─────────────────────────────────────────────────────────┘
        ▲
        │  FastMCP("cad-blender-bridge") — stdio MCP server
        │  tools: build_parametric_gearbox,
        │         verify_and_render_blender,
        │         inspect_step_manifest
```

The gearbox is mechanically real: the ring tooth count is derived as
`sun_teeth + 2·planet_teeth`, the planetary assembly condition
`(sun_teeth + ring_teeth) % planet_count == 0` is enforced, planets are
rotationally phased so sun/planet/ring teeth mesh tooth-into-space, and a
pairwise boolean intersection check proves no parts overlap.

## Installation

Requires Python ≥ 3.11. Blender ≥ 4.x is optional (only needed for the
verification/render stage).

```bash
git clone https://github.com/DECRUX9812/cad-blender-bridge.git
cd cad-blender-bridge
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## CLI usage

```bash
python -m cad_blender_bridge.generator \
    --module 1.5 --sun-teeth 16 --planet-teeth 8 --planet-count 3 \
    --thickness 10 --clearance 0.2 --out-dir out
```

Writes `out/planetary_assembly.step`, `out/planetary_assembly.stl` and
`out/manifest.json`, and prints the manifest:

```json
{
  "status": "ok",
  "step_path": "out/planetary_assembly.step",
  "stl_path": "out/planetary_assembly.stl",
  "volume_mm3": 12345.678,
  "is_valid_brep": true,
  "bbox_mm": {"x": 80.0, "y": 80.0, "z": 10.0},
  "params": {"module": 1.5, "sun_teeth": 16, "...": "..."}
}
```

Invalid parameter combinations (e.g. planets that cannot all mesh) raise
`ValueError` before any geometry is built.

## Headless Blender verification + render

```bash
blender --background --python src/cad_blender_bridge/verify_render.py -- \
    --input out/planetary_assembly.stl \
    --out out/verify.png \
    --report out/verification_report.json
```

The report contains `non_manifold_edges`, `zero_area_faces`, `manifold_pass`,
`dimensions_mm`, mesh counts and the renderer used. The render is a 1024×1024
orthographic isometric studio shot (Cycles CPU, EEVEE fallback).

## MCP server

```bash
python -m cad_blender_bridge.mcp_server   # stdio transport
```

Tools exposed:

| Tool | What it does |
|---|---|
| `build_parametric_gearbox(module, sun_teeth, planet_teeth, planet_count, thickness, clearance_mm)` | Builds + verifies the B-Rep assembly, exports STEP/STL, returns the JSON manifest |
| `verify_and_render_blender(stl_path, render_out, blender_bin)` | Runs headless Blender mesh inspection + studio render, returns the JSON report (clear error if Blender is not in PATH) |
| `inspect_step_manifest(manifest_path)` | Returns the latest build manifest plus a tolerance-check summary |

### MCP client configuration

```json
{
  "mcpServers": {
    "cad-blender-bridge": {
      "command": "/path/to/cad-blender-bridge/.venv/bin/python",
      "args": ["-m", "cad_blender_bridge.mcp_server"],
      "cwd": "/path/to/cad-blender-bridge"
    }
  }
}
```

Then ask your agent: *"Build a module-2 planetary gearbox with a 20-tooth sun
and four 10-tooth planets, verify it in Blender, and show me the render."*

## Tests

```bash
pytest
```

The suite generates real geometry into `tmp_path`, asserts non-empty STEP/STL
exports, `is_valid_brep is True`, zero interference, and that increasing the
module increases the assembly volume.

## License

MIT