Build123d/CadQuery Workbench for FreeCAD

A FreeCAD workbench that provides integration with build123d and CadQuery, allowing you to write parametric CAD models using Python and visualize them directly in FreeCAD.

Features

• Run build123d and CadQuery scripts directly in FreeCAD
• Built-in script editor with Python syntax highlighting
• Shape conversion between OCP/build123d/CadQuery and FreeCAD Part objects
• Example scripts to get started quickly
• File import support for .py files containing CAD code

Installation

Prerequisites

1. FreeCAD 0.21+ or FreeCAD 1.0+ (recommended)
2. build123d and/or CadQuery Python packages

Installing the Workbench

1. Clone or download this repository
2. Copy/symlink the folder to your FreeCAD Mod directory:
   • Linux: ~/.local/share/FreeCAD/Mod/ or ~/.FreeCAD/Mod/
   • Windows: %APPDATA%\FreeCAD\Mod\
   • macOS: ~/Library/Application Support/FreeCAD/Mod/

# Linux example
cd ~/.local/share/FreeCAD/Mod/
ln -s /path/to/freecad-build123d .

Installing build123d and CadQuery

The recommended approach is to use FreeCAD's Python environment or ensure build123d/CadQuery are installed in a compatible Python environment.

Option 1: Using FreeCAD's bundled Python (recommended for AppImage/portable)

# Find FreeCAD's Python
/path/to/FreeCAD/bin/python -m pip install build123d cadquery

Option 2: System Python with FreeCAD access

If your FreeCAD is built against system Python:

pip install build123d cadquery

Usage

Activating the Workbench

1. Start FreeCAD
2. Go to View → Workbench → Build123d/CadQuery

Running a Script

1. Click Run Script in the toolbar or use Build123d → Run Script
2. Select a Python file containing build123d or CadQuery code
3. The shapes will appear in the FreeCAD document

Using the Built-in Editor

1. Click Open Editor to open the script editor panel
2. Write your build123d or CadQuery code
3. Press Ctrl+Enter or click Run to execute

Script Output

Your script should expose shapes to display in one of these ways:

# Method 1: Set the 'result' variable
result = my_shape

# Method 2: Set 'results' for multiple shapes
results = [shape1, shape2, shape3]

# Method 3: Use show_object() (CadQuery style)
show_object(my_shape, name="My Part")

# Method 4: Use show() (build123d style)
show(my_shape)

Examples

build123d Example

from build123d import *

# Create a box with filleted edges
with BuildPart() as part:
    Box(50, 30, 20)
    fillet(part.edges(), radius=3)

result = part.part

CadQuery Example

import cadquery as cq

# Create a box with a hole
result = (
    cq.Workplane("XY")
    .box(50, 30, 20)
    .faces(">Z")
    .workplane()
    .hole(10)
)

Complex Example

from build123d import *

with BuildPart() as bracket:
    # Base plate
    Box(100, 60, 5)
    
    # Vertical wall
    with Locations((0, 25, 15)):
        Box(100, 10, 30)
    
    # Mounting holes
    with Locations((0, 0, 5)):
        with GridLocations(80, 40, 2, 2):
            Hole(radius=3, depth=5)
    
    # Fillet the edges
    fillet(bracket.edges().filter_by(Axis.Z), radius=5)

result = bracket.part

Architecture

freecad-build123d/
├── Init.py                 # FreeCAD startup script (console mode)
├── InitGui.py              # FreeCAD GUI initialization
├── b123d_cq_workbench/     # Main package
│   ├── __init__.py
│   ├── commands.py         # FreeCAD commands
│   ├── converter.py        # Shape conversion utilities
│   ├── editor.py           # Built-in script editor
│   ├── importer.py         # File import handler
│   └── script_runner.py    # Script execution engine
├── resources/
│   └── icons/              # SVG icons
└── examples/               # Example scripts

API Reference

Converter Module

from b123d_cq_workbench.converter import (
    to_fc_shape,        # Convert any supported shape to FreeCAD
    add_to_document,    # Add a shape to a FreeCAD document
)

# Convert a build123d shape
fc_shape = to_fc_shape(build123d_part)

# Add to document with custom name and color
obj = add_to_document(my_shape, name="MyPart", color=(0.5, 0.5, 1.0))

Script Runner Module

from b123d_cq_workbench.script_runner import (
    run_script_file,    # Run a script from file
    run_script_string,  # Run a script from string
)

# Run a script file
run_script_file("/path/to/my_script.py")

# Run inline script
run_script_string('''
from build123d import *
result = Box(10, 20, 30)
''', name="MyScript")

Related Projects

• build123d - Python CAD modeling library
• CadQuery - Python parametric CAD scripting
• ocp-freecad-cam - FreeCAD CAM for OCP shapes
• OCP - Python bindings for OpenCASCADE

License

This project is licensed under the GNU Lesser General Public License v2.1 or later (LGPL-2.1+).

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Acknowledgments

• The FreeCAD development team
• The build123d and CadQuery communities
• Inspiration from freecad-cadquery2-workbench and ocp-freecad-cam projects