bdbox¶

build123d development with live preview and interactive parameters

See the documentation site for full project details!

Why?¶

I discovered build123d after modeling with OpenSCAD. build123d has some great advantages over OpenSCAD:

Better geometry (STEP file export) than OpenSCAD's mesh of vertexes
Common CAD operations like chamfer and fillet are simple
build123d models are Python programs, whereas OpenSCAD uses its own modeling language

Comparatively, build123d's development experience was lacking. OpenSCAD previews a model on save or hotkey, makes exporting a model render simple, and even provides a GUI for setting toplevel variables! I started with some self-made tooling to work around these drawbacks, but having to remember how to use and maintain it resulted in me working on models less.

I built bdbox to be the missing tool I wanted: Let models just define their geometry plus optional parameters, and let bdbox handle everything else!

See more background info in the documentation!

Installation¶

Install user-wide with uv or pipx for use across all projects:

uv tool install bdbox

pipx install bdbox

Install in any environment where pip is available:

pip install bdbox

Installation in projects¶

Install in a project, such as with uv or poetry:

uv add bdbox

poetry add bdbox

bdbox detects and automatically uses virtual environments also containing bdbox.

This enables running via bdbox model.py instead of uv run bdbox model.py, for example.

Works with any build123d model¶

Use bdbox with any existing build123d script:

# mymodel.py
from build123d import Box

result = Box(10, 10, 10)

Export geometry files:

bdbox mymodel.py export           # Export STEP files to current directory
bdbox mymodel.py export output/   # Export STEP files to output/
bdbox mymodel.py export -f stl    # Export STL files to current directory

View your model using the web UI, which includes OCP CAD Viewer and an interactive parameters panel:

bdbox mymodel.py view

Module paths work too:

bdbox mypackage.mymodule view
bdbox mypackage.mymodule export

See more about actions in the documentation!

Add parameters¶

Declare typed parameters with defaults and constraints:

from bdbox import Float, Int, Params, Preset, show
from build123d import Box

class P(Params):
    width = Float(10.0, min=5, max=100)
    length = Float(20.0, min=5, max=100)
    thickness = Int(2, min=1, max=10)
    presets = (
        Preset("small", width=5.0, length=8.0),
        Preset("large", width=80.0, length=40.0, thickness=5),
    )

result = Box(P.width, P.length, P.thickness)
show(result)

Or inherit from Model for reusable, importable models:

from bdbox import Float, Int, Model, Preset
from build123d import Box

class MyModel(Model):
    width = Float(10.0, min=5, max=100)
    length = Float(20.0, min=5, max=100)
    thickness = Int(2, min=1, max=10)
    presets = (
        Preset("small", width=5.0, length=8.0),
        Preset("large", width=80.0, length=40.0, thickness=5),
    )

    def build(self):
        return Box(self.width, self.length, self.thickness)

Parameters become CLI flags automatically:

python mymodel.py                 # Run with default values
python mymodel.py view            # View with live reload and parameter panel
python mymodel.py --width 50      # Override a field value
python mymodel.py --preset large  # Apply a named preset
python mymodel.py --help          # Usage info with all parameters

Export geometry files using the built-in export action:

python mymodel.py export          # Export STEP files to current directory
python mymodel.py export -f stl   # Export STL files to current directory

See more about parameters in the documentation!

Project template¶

This project is generated and maintained with copier-python.