https://github.com/smkent/bdbox
A live development environment for build123d models
https://github.com/smkent/bdbox
3d 3d-models build123d cad python step stl
Last synced: about 1 month ago
JSON representation
A live development environment for build123d models
- Host: GitHub
- URL: https://github.com/smkent/bdbox
- Owner: smkent
- License: lgpl-3.0
- Created: 2026-04-04T17:58:50.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-05T06:40:54.000Z (about 1 month ago)
- Last Synced: 2026-05-05T07:31:02.062Z (about 1 month ago)
- Topics: 3d, 3d-models, build123d, cad, python, step, stl
- Language: Python
- Homepage: https://smkent.github.io/bdbox/
- Size: 559 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# bdbox
**[build123d][build123d]** development with live preview and
interactive parameters
[](https://github.com/smkent/bdbox/blob/main/LICENSE)
[](https://pypi.org/project/bdbox/)
[](https://pypi.org/project/bdbox/)
[](https://github.com/smkent/bdbox/actions/workflows/ci.yaml)
[](https://codecov.io/gh/smkent/bdbox)
[](https://renovatebot.com)
[](https://github.com/smkent/bdbox)
![Screenshot][docs-screenshot-ui]
**[See the documentation site for full project details!][docs]**
## Why?
I discovered [build123d][build123d] after modeling with [OpenSCAD][openscad].
build123d has some [great advantages][build123d-vs-openscad] over OpenSCAD:
* Better geometry ([STEP][step] file export) than OpenSCAD's
[mesh of vertexes][openscad-csg]
* Common CAD operations like [**`chamfer`**][build123d-chamfer] and
[**`fillet`**][build123d-fillet] are simple
* [build123d models are Python programs][build123d-pypi], whereas
[OpenSCAD uses its own modeling language][openscad-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][openscad-customizer]!
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!][docs-background]**
## Installation
Install user-wide with [`uv`][uv-tool] or [`pipx`][pipx] for use across all
projects:
```sh
uv tool install bdbox
```
```sh
pipx install bdbox
```
Install in any environment where `pip` is available:
```sh
pip install bdbox
```
### Installation in projects
Install in a project, such as with [`uv`][uv] or [`poetry`][poetry]:
```sh
uv add bdbox
```
```sh
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:
```python
# mymodel.py
from build123d import Box
result = Box(10, 10, 10)
```
Export geometry files:
```sh
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][ocp_vscode]
and an [interactive parameters panel][docs-panel]:
```sh
bdbox mymodel.py view
```
Module paths work too:
```sh
bdbox mypackage.mymodule view
bdbox mypackage.mymodule export
```
**[See more about actions in the documentation!][docs-actions]**
## Add parameters
Declare typed parameters with defaults and constraints:
```python
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:
```python
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:
```sh
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:
```sh
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!][docs-parameters]**
## Project template
This project is generated and maintained with [copier-python][copier-python].
[build123d-chamfer]: https://build123d.readthedocs.io/en/stable/direct_api_reference.html#topology.Mixin3D.chamfer
[build123d-fillet]: https://build123d.readthedocs.io/en/stable/direct_api_reference.html#topology.Mixin3D.fillet
[build123d-pypi]: https://pypi.org/project/build123d/
[build123d-vs-openscad]: https://build123d.readthedocs.io/en/stable/OpenSCAD.html
[build123d]: https://build123d.readthedocs.io
[copier-python]: https://smkent.github.io/copier-python
[docs-actions]: https://smkent.github.io/bdbox/actions/
[docs-background]: https://smkent.github.io/bdbox/background/
[docs-panel]: https://smkent.github.io/bdbox/parameters/panel/
[docs-parameters]: https://smkent.github.io/bdbox/parameters/
[docs-screenshot-ui]: https://smkent.github.io/bdbox/bdbox-ui.png
[docs]: https://smkent.github.io/bdbox/
[ocp_vscode]: https://github.com/bernhard-42/vscode-ocp-cad-viewer
[openscad-csg]: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/CSG_Modelling
[openscad-customizer]: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Customizer
[openscad-language]: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual#The_OpenSCAD_Language_Reference
[openscad]: https://openscad.org/
[pipx]: https://pipx.pypa.io
[poetry]: https://python-poetry.org/
[step]: https://en.wikipedia.org/wiki/ISO_10303-21
[uv-tool]: https://docs.astral.sh/uv/guides/tools/
[uv]: https://docs.astral.sh/uv/