Add Custom Properties with Python in FreeCAD

Custom parameter properties in FreeCAD allow you to attach user-defined variables—such as dimensions, strings, integers, or booleans—to any document object, making your parametric designs significantly more flexible. By leveraging FreeCAD’s built-in Python API, you can programmatically inject these properties into existing parts or scripted objects using the addProperty() method. This article explains how to select an object, define a new property type, organize it within FreeCAD's Property View, and update its values using Python.

The addProperty() Method

To add a custom property, you call the addProperty() method on an existing document object. The basic syntax is:

obj.addProperty(type, name, group, doc_string)
  • type: The internal C++ data type (e.g., "App::PropertyLength", "App::PropertyString").
  • name: The programmatic identifier for the property (must not contain spaces).
  • group: The section header under which the property appears in the FreeCAD Data tab.
  • doc_string: The tooltip description displayed when hovering over the property in the GUI.

Step-by-Step Implementation

Open the Python Console inside FreeCAD (View > Panels > Python console) and run the following commands:

1. Retrieve the Object

First, select an object in your tree view or target an object by its label from the active document:

import FreeCAD as App

# Get the active document
doc = App.ActiveDocument

# Target an existing object by its internal name (e.g., "Box")
obj = doc.getObject("Box")

2. Add the Property

Next, declare the custom property on the object:

# Add a custom dimensional length property
obj.addProperty("App::PropertyLength", "CustomOffset", "Custom Parameters", "Defines the custom offset distance")

3. Assign a Value

Once added, the property behaves like any native attribute. You can set its value directly:

# Set the value (for PropertyLength, numerical values default to millimeters)
obj.CustomOffset = 25.4

# Recompute the document to update changes
doc.recompute()

Common Property Types

FreeCAD provides various property types under the App:: namespace:

  • App::PropertyLength: Used for linear measurements (automatically handles unit conversions).
  • App::PropertyAngle: Used for angular parameters (converts degrees and radians).
  • App::PropertyFloat: A standard floating-point number without units.
  • App::PropertyInteger: A whole integer value.
  • App::PropertyString: Text strings.
  • App::PropertyBool: True/False checkboxes.
  • App::PropertyEnumeration: A dropdown list of predefined string choices.

Example: Adding an Enumeration (Dropdown)

To create a dropdown selection:

obj.addProperty("App::PropertyEnumeration", "Mode", "Custom Parameters", "Operational mode")
obj.Mode = ["Draft", "Standard", "Precision"]
obj.Mode = "Standard"
doc.recompute()

Removing a Custom Property

If you need to delete a dynamic property added via Python, use the removeProperty() method:

obj.removeProperty("CustomOffset")
doc.recompute()

Note: Native C++ properties built into the object's base definition cannot be removed with this method; it only applies to dynamically added custom properties.