Understanding the FreeCAD Placement Class

The FreeCAD Placement class is a core geometric construct used to define the exact position and orientation of an object within 3D space. It serves as the primary mechanism for executing rigid body transformations, allowing components to be translated and rotated without altering their underlying geometry or shape definitions. Understanding this class is fundamental for manipulating parts, managing assembly hierarchies, and scripting automated modeling tasks within the FreeCAD Python API.

Core Components of a Placement

A Placement object is composed of two primary geometric entities:

  1. Base (Vector): Defines the spatial position of the object along the X, Y, and Z Cartesian axes. It represents the translation offset from the global origin (0, 0, 0) or from a parent coordinate system.
  2. Rotation (Quaternion): Defines the orientation of the object. While represented internally as a quaternion to avoid gimbal lock, it can be defined or manipulated using Euler angles (Yaw, Pitch, Roll) or an axis-and-angle pair.

By binding translation and rotation into a single unified object, FreeCAD simplifies spatial calculations and ensures consistency across different modeling workbenches.

The Purpose and Role in FreeCAD

The primary objective of the Placement class is to decouple an object's geometric definition from its location in the 3D scene.

  • Rigid Body Transformations: Modifying a shape's vertices directly to move it is computationally expensive and destructive. Instead, FreeCAD keeps the original geometric shape intact and applies the Placement transformation matrix dynamically during rendering and export.
  • Assembly and Hierarchical Positioning: In complex models, such as those inside the PartDesign Workbench or third-party assembly workbenches, objects often exist within sub-coordinate systems. A child object's placement can be computed relative to its parent container by chaining placement properties.
  • Non-Destructive Modeling: Because the placement does not alter internal topological dimensions (such as edge lengths or surface areas), users can reposition, orient, and animate parts reversibly at any stage of the modeling pipeline.

Mathematical Representation and Matrix Conversion

Under the hood, a Placement represents a 4x4 affine transformation matrix limited to rigid motion (it does not include shear or non-uniform scaling). FreeCAD allows seamless conversion between a placement and a matrix:

  • Matrix Transformation: Calling Placement.toMatrix() outputs the corresponding 4x4 transformation matrix.
  • Composition: Multiple transformations can be chained together by multiplying placements (e.g., Placement3 = Placement1.multiply(Placement2)), enabling complex multi-axis rotations and offsets in localized reference frames.

Usage in Python Scripting

In Python, the Placement class is part of the FreeCAD base module (App.Placement). It can be initialized empty, via an existing matrix, or by explicitly passing a vector and a rotation:

import FreeCAD as App

# Define translation and rotation
position = App.Vector(10, 0, 5)
rotation = App.Rotation(App.Vector(0, 0, 1), 45)  # 45 degrees around Z-axis

# Create the Placement object
placement = App.Placement(position, rotation)

# Assign to an existing object
obj = App.ActiveDocument.ActiveObject
obj.Placement = placement
App.ActiveDocument.recompute()

The Placement class provides a predictable, performant, and standardized method to navigate and position objects, making it one of the foundational building blocks of the FreeCAD architecture.