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)

python model.py --hollow        # Set to True
python model.py --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.                            │
│   • view     View model geometry.                      │
│   • export   Export geometry to a STEP or STL file.    │
╰────────────────────────────────────────────────────────╯

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 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