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.

## 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
MITThis server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues