Lesson 3. Creating 3D Objects: Parametric Box

📘 Tutorial: Creating Addons for FreeCAD

Lesson Goal: Learn to create solid bodies (boxes, cylinders) via Python, understand the FreeCAD document structure, and create an addon that builds a parametric part.

---

🧱 Part 1. How is a document structured in FreeCAD?

Before creating objects, it’s important to understand the data hierarchy in FreeCAD:

Document (document)
└── Object (object)
    └── Shape (geometry)

• Document — is an open file (.FCStd). Everything you create is within the document.
• Object — is a parametric object: box, cylinder, sketch, etc.
• Shape — is a geometric body (B-Rep) that can be visualized.

💡 You always work in the context of the active document.

How to get the current document?

doc = FreeCAD.ActiveDocument

If there’s no document, create a new one:

doc = FreeCAD.newDocument("MyDesign")

---

📦 Part 2. Creating a Box via Python

The simplest 3D object in FreeCAD is Part::Box.

Code example:

doc = FreeCAD.ActiveDocument or FreeCAD.newDocument()
box = doc.addObject("Part::Box", "MyBox")
box.Length = 20.0
box.Width = 10.0
box.Height = 5.0
doc.recompute()

What happens here?

1. doc.addObject("Part::Box", "MyBox")
   → creates a new Box type object named "MyBox"
2. The object has parametric properties: Length, Width, Height
3. doc.recompute()
   → rebuilds the model (mandatory after changing parameters!)

🔸 All dimensions are in millimeters (by default in FreeCAD).

---

🛠 Part 3. Addon: “Parametric Box”

Now let’s create an addon that builds a box with specified dimensions.

Step 1. Create a folder

.../Mod/ParamBoxAddon/

Step 2. File InitGui.py

# InitGui.py
import FreeCADGui
from ParamBoxAddon.param_box_workbench import ParamBoxWorkbench

FreeCADGui.addWorkbench(ParamBoxWorkbench())

Step 3. File param_box_workbench.py

# param_box_workbench.py
import FreeCAD, FreeCADGui

class CreateBoxCommand:
    def GetResources(self):
        return {
            "MenuText": "Create Box",
            "ToolTip": "Create a parametric box with default size"
        }

    def Activated(self):
        # Get or create a document
        doc = FreeCAD.ActiveDocument
        if not doc:
            doc = FreeCAD.newDocument("BoxDesign")

        # Create Box object
        box = doc.addObject("Part::Box", "MyParamBox")
        box.Length = 30.0
        box.Width = 20.0
        box.Height = 10.0

        # Recompute is mandatory!
        doc.recompute()

        # Optional: focus on the object
        FreeCADGui.Selection.clearSelection()
        FreeCADGui.Selection.addSelection(box)

    def IsActive(self):
        return True


class ParamBoxWorkbench(FreeCADGui.Workbench):
    MenuText = "Parametric Box"
    ToolTip = "Create a simple parametric box"

    def Initialize(self):
        self.list = ["CreateBoxCommand"]
        self.appendToolbar("Box Tools", self.list)
        self.appendMenu("ParamBox", self.list)

    def GetClassName(self):
        return "Gui::PythonWorkbench"


FreeCADGui.addCommand("CreateBoxCommand", CreateBoxCommand())

---

▶️ Step 4. Checking the Operation

1. Save the files
2. Restart FreeCAD
3. Select the «Parametric Box» workbench
4. Click the «Create Box» button

✅ A gray cuboid should appear in the 3D window.

Check for parametricity!

1. In the project tree (Model), double-click on MyParamBox
2. In the Data panel, change, for example, Length to 50
3. Press Enter → the model will automatically update!

This is parametric modeling.

---

🔍 Part 4. Other Basic Objects

You can create more than just boxes. Here are a few examples:

Cylinder

cyl = doc.addObject("Part::Cylinder", "MyCylinder")
cyl.Radius = 10.0
cyl.Height = 25.0

Sphere

sphere = doc.addObject("Part::Sphere", "MySphere")
sphere.Radius = 15.0

Cone

cone = doc.addObject("Part::Cone", "MyCone")
cone.Radius1 = 10.0  # bottom radius
cone.Radius2 = 5.0   # top radius
cone.Height = 20.0

💡 All these objects are in the Part module, which is built into FreeCAD.

---

🧪 Practical Task

1. Modify the addon so that it creates a cylinder instead of a box.
2. Make sure that when creating an object, it gets a unique name (e.g., Box_1, Box_2…) if an object with that name already exists.
3. Add a second command — «Create Cylinder» — to the same workbench.

Hint for unique name:

base_name = "MyBox"
index = 1
name = base_name
while name in doc.Objects:
    name = f"{base_name}_{index}"
    index += 1
box = doc.addObject("Part::Box", name)

---

💡 Debugging Tips

• Always call doc.recompute() after changing parameters
• Use FreeCAD.Console.PrintMessage("Text\n") for debugging (messages will appear in Report View)
• Check if the document exists before working with it

---

▶️ What’s next?

In Lesson 4 we will:

• Learn to create a graphical user interface (GUI) with input fields
• Create a window where the user enters length, width, and height
• And by clicking a button — a box with these parameters is built

This will already be a real tool, not just a demonstration!