# Burr
Burr is a design-rule linter for CAD-as-code workflows.
It checks generated design data and artifacts for mechanical mistakes before
they become prints, prototypes, or expensive debugging sessions.
```txt
design file -> generated part -> burr-design-data.json -> Burr checks -> receipt
```
Burr is not a constraint solver, FEA engine, or universal CAD brain. It does not
design the part. It checks whether generated CAD violates known mechanical
rules.
## Why
Image review is useful, but not enough. A screenshot can show that something
looks suspicious; it cannot reliably prove exact hole distances, hidden
clearances, source/STEP freshness, or rule-specific pass/fail.
Burr turns design data into measurable receipts:
```txt
M3 loaded mounting hole
measured center-to-edge = 8.0 mm
required center-to-edge = 10.2 mm
result = fail by 2.2 mm
```
## Install
See [INSTALL.md](INSTALL.md) for current crates.io and uv install paths.
For local development:
```bash
cargo test
uv sync --all-packages
npm run check
```
Install the Rust CLI from crates.io:
```bash
cargo install burr
burr --version
```
Run the CLI from a local checkout:
```bash
cargo run -- --version
cargo run -- init my-part
cargo run -- check examples/linear-actuator-bad
cargo run -- check examples/linear-actuator-good
```
Run the build123d adapter examples:
```bash
uv sync --all-packages
npm run check:build123d
```
Run the optional OpenCascade STEP backend proof:
```bash
uv sync --all-packages
npm run check:ocp
```
Run the mixed-intent CAD proof:
```bash
uv sync --all-packages
npm run check:mixed-intent
```
Run the counterbore CAD proof:
```bash
uv sync --all-packages
npm run check:counterbore
```
Run the straight-slot CAD proof:
```bash
uv sync --all-packages
npm run check:slots
```
The build123d examples commit only `design.py`. `actuator.step` and
`burr-design-data.json` are generated by the example scripts and ignored by git.
Start a build123d part:
```bash
burr init my-part
cd my-part
uv run python design.py
burr check .
```
## Commands
```bash
burr --version
burr init <folder>
```
`init` creates a minimal build123d project with `design.py`, `pyproject.toml`,
and `.gitignore`. The generated project depends on `burr-build123d==0.6.0`
from PyPI.
`check` finds `burr-design-data.json`, runs freshness checks and rulepack
checks, then writes `burr-receipt.json` beside each design data file.
`stamp` computes `sha256` and `size_bytes` for declared source and generated
artifact files.
## Build123d Helper
Burr does not replace build123d. The optional helper records design data while
your normal build123d file creates geometry.
```python
from build123d import Box, BuildPart, Locations, export_step
from burr_build123d import BurrDesignData, DESIGN_DATA_FILE, m3_clearance_hole
design = BurrDesignData(
artifact_id="my-actuator",
artifact_type="actuator_mount",
process={"kind": "FDM", "material": "PETG", "nozzle_mm": 0.4},
)
design.source("design.py")
design.artifact("actuator.step")
design.part("housing", bbox_min=(-42, -16, 0), bbox_max=(42, 16, 26))
with BuildPart() as housing:
with Locations((0, 0, 13)):
Box(84, 32, 26)
m3_clearance_hole(
design,
feature_id="m3_lower_left",
part="housing",
center=(39.5, -8, 8),
axis=(1, 0, 0),
role="loaded_mount",
)
export_step(housing.part, "actuator.step")
design.write(DESIGN_DATA_FILE)
```
That one helper call cuts the hole in build123d and records the feature Burr
checks. Burr core still reads only `burr-design-data.json`, so other CAD tools
can use the same contract.
## Design Data
A lintable CAD artifact folder contains `burr-design-data.json`.
This file is the language-agnostic contract. It can be emitted by build123d,
CadQuery, OpenSCAD, JavaScript CAD, Rust CAD, Fusion scripts, or any tool that
can write JSON.
```json
{
"schema_version": "burr.design-data.v1",
"artifact_id": "linear-actuator-bad",
"artifact_version": "0.1.0",
"artifact_type": "actuator_mount",
"units": "mm",
"source": {
"path": "source.py",
"sha256": "..."
},
"artifacts": [
{
"kind": "step",
"path": "actuator.step",
"sha256": "..."
}
],
"parts": [
{
"id": "housing",
"bbox_mm": {
"min": [-42, -16, 0],
"max": [42, 16, 26]
}
}
],
"features": [
{
"id": "m3_lower_left",
"part": "housing",
"kind": "clearance_hole",
"intent": "mechanical_interface",
"fastener": "M3",
"diameter_mm": 3.4,
"center_mm": [39.5, -8, 8],
"axis": [1, 0, 0],
"role": "loaded_mount"
}
]
}
```
### Declared Feature Intent
Burr does not infer that every cylinder or hole in a STEP file is mechanically
important. A STEP file may contain vents, lightening holes, fluid passages,
cosmetic cuts, construction reliefs, bosses, fillets, and unrelated round faces.
Burr judges only features that are declared in `burr-design-data.json` and
selected by the active rulepack. Use `intent` to separate mechanical interfaces
from incidental geometry:
```txt
mechanical_interface -> judged by mechanical rulepacks
weight_reduction -> declared if useful, but not judged by actuator rules
fluid_or_air_path -> separate rules, not screw-mount rules
manufacturing_feature -> process-specific rules only
cosmetic -> normally unjudged
```
For legacy design data, missing `intent` is treated as `mechanical_interface`.
Set `intent` explicitly when a declared feature should not be judged by
mechanical rulepacks.
## Rulepacks
The included actuator mount rulepack checks loaded M3 clearance-hole edge
distance, minimum wall thickness around M3 clearance holes, whether declared M3
clearance holes exist as matching cylindrical geometry in the exported STEP, and
whether declared straight slots, counterbores, and heat-set insert pockets exist
as matching STEP cylinder/plane evidence:
```json
{
"schema_version": "burr.rulepack.v1",
"id": "actuator_mount",
"version": "0.7.0",
"rules": [
{
"id": "m3_loaded_hole_edge_distance",
"kind": "hole_edge_distance",
"applies_to": {
"kind": "clearance_hole",
"fastener": "M3",
"intent_any": ["mechanical_interface"],
"role_any": ["loaded_mount", "mount", "housing_mount"]
},
"min_center_to_edge_diameter_multiple": 3.0
},
{
"id": "m3_clearance_hole_wall_thickness",
"kind": "minimum_wall_thickness",
"applies_to": {
"kind": "clearance_hole",
"fastener": "M3",
"intent_any": ["mechanical_interface"]
},
"min_wall_thickness_mm": 2.0
},
{
"id": "m3_clearance_hole_step_presence",
"kind": "feature_presence",
"applies_to": {
"kind": "clearance_hole",
"fastener": "M3",
"intent_any": ["mechanical_interface"]
},
"artifact_kind": "step",
"diameter_tolerance_mm": 0.05,
"centerline_tolerance_mm": 0.25,
"axis_dot_min": 0.99
},
{
"id": "straight_slot_step_presence",
"kind": "feature_presence",
"applies_to": {
"kind": "straight_slot",
"intent_any": ["mechanical_interface"]
},
"artifact_kind": "step",
"width_tolerance_mm": 0.05,
"endpoint_tolerance_mm": 0.25,
"side_plane_tolerance_mm": 0.25,
"axis_dot_min": 0.99
},
{
"id": "counterbore_step_presence",
"kind": "feature_presence",
"applies_to": {
"kind": "counterbore",
"intent_any": ["mechanical_interface"]
},
"artifact_kind": "step",
"bore_diameter_tolerance_mm": 0.05,
"counterbore_diameter_tolerance_mm": 0.05,
"centerline_tolerance_mm": 0.25,
"counterbore_center_tolerance_mm": 0.5,
"shoulder_plane_tolerance_mm": 0.25,
"axis_dot_min": 0.99
},
{
"id": "heat_set_insert_pocket_step_presence",
"kind": "feature_presence",
"applies_to": {
"kind": "heat_set_insert_pocket",
"intent_any": ["mechanical_interface"]
},
"artifact_kind": "step",
"pocket_diameter_tolerance_mm": 0.05,
"centerline_tolerance_mm": 0.25,
"pocket_center_tolerance_mm": 0.5,
"bottom_plane_tolerance_mm": 0.25,
"axis_dot_min": 0.99
}
]
}
```
## Versioning
Burr has three versioned surfaces:
```txt
Burr package version -> CLI/library behavior
Design data schema version -> JSON shape Burr can read
Rulepack schema version -> rule syntax Burr can execute
```
Receipts include all three:
```json
{
"schema_version": "burr.receipt.v1",
"burr_version": "0.8.0",
"artifact_version": "0.1.0",
"rulepack_version": "0.7.0",
"compatibility": {
"design_data_schema_version": "burr.design-data.v1",
"rulepack_schema_version": "burr.rulepack.v1"
}
}
```
Unsupported design data or rulepack schemas fail lint instead of silently producing
untrustworthy receipts.
Legacy `fray-cad.json` files with schema `fray.cad.artifact.v1` are still read
for transition, but new integrations should emit `burr-design-data.json`.
## Example Result
Bad actuator:
```txt
FAIL examples/build123d-actuator/bad/burr-design-data.json -> <not written>
1 problem:
1. M3 loaded hole m3_lower_left is too close to the edge.
Measured center-to-edge: 8 mm
Required center-to-edge: 10.2 mm
Short by: 2.2 mm
Try moving the hole inward or increasing the surrounding part size.
```
Fixed actuator:
```json
{
"status": "pass",
"measured": {
"center_to_edge_mm": 12,
"wall_to_edge_mm": 10.3
},
"required": {
"center_to_edge_mm": 10.2,
"wall_to_edge_mm": 8.5
},
"margin_mm": 1.8
}
```
Thin wall fixture:
```txt
FAIL examples/build123d-wall-thickness/bad/burr-design-data.json -> <not written>
1 problem:
1. M3 clearance hole m3_alignment leaves too little wall.
Measured wall thickness: 1.2 mm
Required wall thickness: 2 mm
Short by: 0.8 mm
Try moving the hole inward or increasing part width.
```
Missing STEP feature fixture:
```txt
FAIL examples/build123d-step-presence/bad/burr-design-data.json -> <not written>
1 problem:
1. Declared clearance hole m3_claimed is missing from the STEP artifact.
Checked artifact: presence.step
Candidate cylinders found: 0
Regenerate the STEP from the same helper that emitted the design data.
```
`Candidate cylinders found` and `Candidate planes found` are not counts of
failed features. They are the STEP faces Burr considered while trying to prove
one declared feature. Extra faces are ignored unless a rulepack selects matching
declared intent and the geometry fits the declared tolerances.
## Status
Early prototype. Current checks combine design-data rules with narrow STEP
feature-presence verification for declared M3 clearance holes, declared
straight slots, declared counterbores, and declared heat-set insert pockets.
Burr does not classify all holes, slots, counterbores, or pockets in a model or
decide which features matter.
By default, the Rust CLI reads simple analytic STEP cylinder entities directly.
For stronger local verification, install the optional Python/OCP workspace and
run with:
```bash
BURR_STEP_CYLINDER_BACKEND=ocp \
BURR_OCP_STEP_CYLINDERS="uv run --package burr-ocp burr-ocp-step-cylinders" \
burr check .
```
The OCP helper extracts measured cylinder and plane candidates. Burr still owns
rule matching, diagnostics, and receipts.