AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

freecad-scripts

Expert skill for writing FreeCAD Python scripts, macros, and automation. Use when asked to create FreeCAD models, parametric objects, Part/Mesh/Sketcher scripts, workbench tools, GUI dialogs with PySide, Coin3D scenegraph manipulation, or any FreeCAD Python API task. Covers FreeCAD scripting basics, geometry creation, FeaturePython objects, interface tools, and macro development.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--freecad-scripts at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 6

references/parametric-objects.md

FreeCAD Parametric Objects

Reference guide for creating FeaturePython objects, scripted objects, properties, view providers, and serialization.

Official Wiki References

FeaturePython Object — Complete Template

import FreeCAD
import Part

class MyParametricObject:
    """Proxy class for a custom parametric object."""

    def __init__(self, obj):
        """Initialize and add properties."""
        obj.Proxy = self
        self.Type = "MyParametricObject"

        # Add custom properties
        obj.addProperty("App::PropertyLength", "Length", "Dimensions",
                         "The length of the object").Length = 10.0
        obj.addProperty("App::PropertyLength", "Width", "Dimensions",
                         "The width of the object").Width = 10.0
        obj.addProperty("App::PropertyLength", "Height", "Dimensions",
                         "The height of the object").Height = 5.0
        obj.addProperty("App::PropertyBool", "Chamfered", "Options",
                         "Apply chamfer to edges").Chamfered = False
        obj.addProperty("App::PropertyLength", "ChamferSize", "Options",
                         "Size of chamfer").ChamferSize = 1.0

    def execute(self, obj):
        """Called when the document is recomputed. Build the shape here."""
        shape = Part.makeBox(obj.Length, obj.Width, obj.Height)
        if obj.Chamfered and obj.ChamferSize > 0:
            shape = shape.makeChamfer(obj.ChamferSize, shape.Edges)
        obj.Shape = shape

    def onChanged(self, obj, prop):
        """Called when any property changes."""
        if prop == "Chamfered":
            # Show/hide ChamferSize based on Chamfered toggle
            if obj.Chamfered:
                obj.setPropertyStatus("ChamferSize", "-Hidden")
            else:
                obj.setPropertyStatus("ChamferSize", "Hidden")

    def onDocumentRestored(self, obj):
        """Called when the document is loaded. Re-initialize if needed."""
        self.Type = "MyParametricObject"

    def __getstate__(self):
        """Serialize the proxy (for saving .FCStd)."""
        return {"Type": self.Type}

    def __setstate__(self, state):
        """Deserialize the proxy (for loading .FCStd)."""
        if state:
            self.Type = state.get("Type", "MyParametricObject")

ViewProvider — Complete Template

import FreeCADGui
from pivy import coin

class ViewProviderMyObject:
    """Controls how the object appears in the 3D view and tree."""

    def __init__(self, vobj):
        vobj.Proxy = self
        # Add view properties if needed
        # vobj.addProperty("App::PropertyColor", "Color", "Display", "Object color")

    def attach(self, vobj):
        """Called when the view provider is attached to the view object."""
        self.Object = vobj.Object
        self.standard = coin.SoGroup()
        vobj.addDisplayMode(self.standard, "Standard")

    def getDisplayModes(self, vobj):
        """Return available display modes."""
        return ["Standard"]

    def getDefaultDisplayMode(self):
        """Return the default display mode."""
        return "Standard"

    def setDisplayMode(self, mode):
        return mode

    def getIcon(self):
        """Return the icon path for the tree view."""
        return ":/icons/Part_Box.svg"
        # Or return an XPM string, or path to a .svg/.png file

    def updateData(self, obj, prop):
        """Called when the model object's data changes."""
        pass

    def onChanged(self, vobj, prop):
        """Called when a view property changes."""
        pass

    def doubleClicked(self, vobj):
        """Called on double-click in the tree."""
        # Open a task panel, for example
        return True

    def setupContextMenu(self, vobj, menu):
        """Add items to the right-click context menu."""
        action = menu.addAction("My Action")
        action.triggered.connect(lambda: self._myAction(vobj))

    def _myAction(self, vobj):
        FreeCAD.Console.PrintMessage("Context menu action triggered\n")

    def claimChildren(self):
        """Return list of child objects to show in tree hierarchy."""
        # return [self.Object.BaseFeature] if hasattr(self.Object, "BaseFeature") else []
        return []

    def __getstate__(self):
        return None

    def __setstate__(self, state):
        return None

Creating the Object

def makeMyObject(name="MyObject"):
    """Factory function to create the parametric object."""
    doc = FreeCAD.ActiveDocument
    if doc is None:
        doc = FreeCAD.newDocument()

    obj = doc.addObject("Part::FeaturePython", name)
    MyParametricObject(obj)

    if FreeCAD.GuiUp:
        ViewProviderMyObject(obj.ViewObject)

    doc.recompute()
    return obj

# Usage
obj = makeMyObject("ChamferedBlock")
obj.Length = 20.0
obj.Chamfered = True
FreeCAD.ActiveDocument.recompute()

Complete Property Type Reference

Numeric Properties

| Type | Python | Notes | |---|---|---| | App::PropertyInteger | int | Standard integer | | App::PropertyFloat | float | Standard float | | App::PropertyLength | float | Length with units (mm) | | App::PropertyDistance | float | Distance (can be negative) | | App::PropertyAngle | float | Angle in degrees | | App::PropertyArea | float | Area with units | | App::PropertyVolume | float | Volume with units | | App::PropertySpeed | float | Speed with units | | App::PropertyAcceleration | float | Acceleration | | App::PropertyForce | float | Force | | App::PropertyPressure | float | Pressure | | App::PropertyPercent | int | 0-100 integer | | App::PropertyQuantity | Quantity | Generic unit-aware value | | App::PropertyIntegerConstraint | (val,min,max,step) | Bounded integer | | App::PropertyFloatConstraint | (val,min,max,step) | Bounded float |

String/Path Properties

| Type | Python | Notes | |---|---|---| | App::PropertyString | str | Text string | | App::PropertyFont | str | Font name | | App::PropertyFile | str | File path | | App::PropertyFileIncluded | str | Embedded file | | App::PropertyPath | str | Directory path |

Boolean and Enumeration

| Type | Python | Notes | |---|---|---| | App::PropertyBool | bool | True/False | | App::PropertyEnumeration | list/str | Dropdown; set list then value |

# Enumeration usage
obj.addProperty("App::PropertyEnumeration", "Style", "Options", "Style choice")
obj.Style = ["Solid", "Wireframe", "Points"]  # set choices FIRST
obj.Style = "Solid"                              # then set value

Geometric Properties

| Type | Python | Notes | |---|---|---| | App::PropertyVector | FreeCAD.Vector | 3D vector | | App::PropertyVectorList | [Vector,...] | List of vectors | | App::PropertyPlacement | Placement | Position + rotation | | App::PropertyMatrix | Matrix | 4x4 matrix | | App::PropertyVectorDistance | Vector | Vector with units | | App::PropertyPosition | Vector | Position with units | | App::PropertyDirection | Vector | Direction vector |

Link Properties

| Type | Python | Notes | |---|---|---| | App::PropertyLink | obj ref | Link to one object | | App::PropertyLinkList | [obj,...] | Link to multiple objects | | App::PropertyLinkSub | (obj, [subs]) | Link with sub-elements | | App::PropertyLinkSubList | [(obj,[subs]),...] | Multiple link+subs | | App::PropertyLinkChild | obj ref | Claimed child link | | App::PropertyLinkListChild | [obj,...] | Multiple claimed children |

Shape and Material

| Type | Python | Notes | |---|---|---| | Part::PropertyPartShape | Part.Shape | Full shape | | App::PropertyColor | (r,g,b) | Color (0.0-1.0) | | App::PropertyColorList | [(r,g,b),...] | Color per element | | App::PropertyMaterial | Material | Material definition |

Container Properties

| Type | Python | Notes | |---|---|---| | App::PropertyPythonObject | any | Serializable Python object | | App::PropertyIntegerList | [int,...] | List of integers | | App::PropertyFloatList | [float,...] | List of floats | | App::PropertyStringList | [str,...] | List of strings | | App::PropertyBoolList | [bool,...] | List of booleans | | App::PropertyMap | {str:str} | String dictionary |

Object Dependency Tracking

# InList: objects that reference this object
obj.InList          # [objects referencing obj]
obj.InListRecursive # all ancestors

# OutList: objects this object references
obj.OutList         # [objects obj references]
obj.OutListRecursive # all descendants

Migration Between Versions

class MyParametricObject:
    # ... existing code ...

    def onDocumentRestored(self, obj):
        """Handle version migration when document loads."""
        # Add properties that didn't exist in older versions
        if not hasattr(obj, "NewProp"):
            obj.addProperty("App::PropertyFloat", "NewProp", "Group", "Tip")
            obj.NewProp = default_value

        # Rename properties (copy value, remove old)
        if hasattr(obj, "OldPropName"):
            if not hasattr(obj, "NewPropName"):
                obj.addProperty("App::PropertyFloat", "NewPropName", "Group", "Tip")
                obj.NewPropName = obj.OldPropName
            obj.removeProperty("OldPropName")

Attachment Support

import Part

class MyAttachableObject:
    def __init__(self, obj):
        obj.Proxy = self
        obj.addExtension("Part::AttachExtensionPython")

    def execute(self, obj):
        # The attachment sets the Placement automatically
        if not obj.MapPathParameter:
            obj.positionBySupport()
        # Build your shape at the origin; Placement handles positioning
        obj.Shape = Part.makeBox(10, 10, 10)