Access FreeCAD Document Objects Using Python API

Interacting with FreeCAD programmatically allows you to automate 3D modeling workflows, modify parametric features, and extract design data. This guide demonstrates how to access open documents, retrieve specific document objects using their internal names or labels, inspect and modify their properties, and properly update the document using the FreeCAD Python API.

Accessing the Document

Before you can access individual objects, you must reference the containing document. The primary module used is FreeCAD (often accessible via App inside the FreeCAD Python console).

To target the currently active document:

import FreeCAD

doc = FreeCAD.ActiveDocument

To target a specific document by its internal name:

doc = FreeCAD.getDocument("Unnamed")

If you are running a script outside the interactive GUI, you can open an existing file:

doc = FreeCAD.openDocument("/path/to/your/file.FCStd")

Retrieving Objects from the Document

Once you have a reference to the document, you can access its objects using several methods depending on whether you know the object's internal name, user-facing label, or want to process all objects.

1. By Internal Name

Every object in FreeCAD has a unique, internal Name property (e.g., Box, Cylinder001). You can retrieve it using getObject() or direct document attribute access:

# Using getObject()
obj = doc.getObject("Box")

# Direct attribute access
obj = doc.Box

2. By User Label

Users frequently change the object's Label in the tree view, which can differ from its internal Name. Multiple objects can share the same label. Use getObjectsByLabel() to find objects by their displayed name:

# Returns a list of matching objects
matching_objects = doc.getObjectsByLabel("Base Plate")

if matching_objects:
    obj = matching_objects[0]

3. Listing All Objects

To iterate over every object contained in the document, access the Objects list attribute:

for obj in doc.Objects:
    print(f"Name: {obj.Name}, Label: {obj.Label}, Type: {obj.TypeId}")

Filtering Objects by Type

In complex assemblies or models, you may only want to interact with specific types of features, such as solid shapes:

# Check if the object is derived from Part::Feature
part_objects = [obj for obj in doc.Objects if obj.isDerivedFrom("Part::Feature")]

for part in part_objects:
    print(f"Volume of {part.Label}: {part.Shape.Volume}")

Inspecting and Modifying Object Properties

FreeCAD objects expose properties dynamically based on their underlying feature type.

Reading and Writing Properties

To view and adjust parameters such as dimensions, placements, or colors:

# Accessing dimensions
box = doc.getObject("Box")
print("Current Length:", box.Length)

# Modifying dimensions
box.Length = 50.0
box.Width = 30.0
box.Height = 15.0

# Modifying placement
box.Placement.Base = FreeCAD.Vector(10, 0, 0)

Inspecting Available Properties

To programmatically inspect which properties an object supports:

# List all property names supported by the object
print(box.PropertiesList)

# Get the type of a specific property
print(box.getTypeOfProperty("Length"))

Recomputing the Document

After modifying properties of document objects, FreeCAD requires a recomputation step to update the geometry and dependency tree:

doc.recompute()

If changes affect visual representation in the GUI, you can optionally refresh the view:

if FreeCAD.Gui:
    import FreeCADGui
    FreeCADGui.updateGui()