Command Line Interface (CLI)¶

build123d models with bdbox are Python programs. When run directly, command line arguments are processed using tyro. Geometry is collected automatically after a model finishes running. No entry point or argument parsing code is needed.

Invocation modes¶

See the Actions documentation for full details, including the view and export actions and use of the bdbox runner.

Field flags¶

Each parameter becomes a --field-name flag. Underscores in field names are converted to hyphens. For example, a value for:

wall_thickness = Float(3.0)

can be overridden with the option --wall-thickness.

Boolean fields¶

Boolean fields are represented as a pair of --flag / --no-flag options:

--hollow, --no-hollow  (default: False)

bdbox model.py --hollow     # Set to True
bdbox model.py --no-hollow  # Set to False

bdbox mypackage.mymodule --hollow     # Set to True
bdbox mypackage.mymodule --no-hollow  # Set to False

python model.py --hollow     # Set to True
python model.py --no-hollow  # Set to False

python -m mypackage.mymodule --hollow     # Set to True
python -m mypackage.mymodule --no-hollow  # Set to False

Help output¶

--help lists every field with its type, description, and default value, plus available presets and actions:

usage: MyBox [-h] [OPTIONS] [{run,view,export}]

╭─ options ──────────────────────────────────────────────╮
│ -h, --help             show this help message and exit │
│ --preset {None,small,large}                            │
│                        (default: None)                 │
│ --width 5 <= FLOAT <= 100                              │
│                        (default: 10.0)                 │
│ --thickness 1 <= FLOAT <= 10                           │
│                        (default: 3.0)                  │
╰────────────────────────────────────────────────────────╯
╭─ subcommands ──────────────────────────────────────────╮
│ (default: run)                                         │
│   • run      Run the model.                            │
│   • export   Export geometry to a STEP or STL file.    │
│   • view     View model geometry.                      │
│   • version  Show bdbox version and exit               │
╰────────────────────────────────────────────────────────╯

Automatic execution¶

Params: Subclassing Params provides the CLI and resolves parameter values.

Model: Defining exactly one Model subclass in a model program enables the model to be built without calling the run method. For more control over program execution, run may be called manually. If multiple subclasses are defined, a warning is printed and run must be manually called on the desired class.

from bdbox import Params, show
from build123d import Box

class P(Params):
    size = Float(10.0, min=5.0, max=20.0)

# Parameter values are now accessible on P
cube = Box(P.size, P.size, P.size)

from bdbox import Model
from build123d import Box

class MyBox(Model):
    size = Float(10.0, min=5.0, max=20.0)

    def build(self):
        # Parameter values are accessible on the current instance
        return Box(self.size, self.size, self.size)

Geometry collection¶

Params: One or more calls to [show][bdbox.geometry.geometry.show] accumulate geometry in call order. If show is never called (and Params is subclassed within the invoked script), bdbox scans the program's global variables for build123d.Shape instances on completion.

Model: Geometry must be returned from the build method.

from bdbox import Params, show
from build123d import Box

class P(Params):
    size = Float(10.0, min=5.0, max=20.0)

cube = Box(P.size, P.size, P.size)
show(cube)  # optional

from bdbox import Model
from build123d import Box

class MyBox(Model):
    size = Float(10.0, min=5.0, max=20.0)

    def build(self):
        return Box(self.size, self.size, self.size)

MyModel.run()  # optional, as only one Model subclass is defined