FreeCAD Python: Query Faces, Edges, and Vertices

This guide explains how to inspect and query a 3D model's topological elements—faces, edges, and vertices—using FreeCAD’s built-in Python console and the Part module. By accessing the boundary representation (B-Rep) stored within an object's Shape property, you can extract geometric properties such as coordinates, lengths, surface areas, and sub-element relationships for automated modeling and analysis.

Accessing an Object's Shape

Every solid object in FreeCAD stores its geometric definition in its Shape attribute. Before querying sub-elements, access the active document and retrieve the target object:

import FreeCAD as App

# Get the active document
doc = App.ActiveDocument

# Retrieve a specific object by its label or name
obj = doc.getObject("Box")

# Access the top-level shape
shape = obj.Shape

Querying Vertices

Vertices represent 0D points in 3D space. You can access the list of all vertices in a shape using shape.Vertexes:

# Total count of vertices
print(f"Total vertices: {len(shape.Vertexes)}")

# Iterate through vertices and print coordinates
for i, v in enumerate(shape.Vertexes):
    point = v.Point
    print(f"Vertex {i}: X={point.x:.2f}, Y={point.y:.2f}, Z={point.z:.2f}")

Key properties of a Vertex:

  • v.Point: Returns the Base.Vector representing the 3D coordinates.
  • v.X, v.Y, v.Z: Direct access to individual axis coordinates.

Querying Edges

Edges represent 1D curves or segments bounded by vertices. Access them using shape.Edges:

# Total count of edges
print(f"Total edges: {len(shape.Edges)}")

# Inspect edge geometry
for i, edge in enumerate(shape.Edges):
    length = edge.Length
    curve_type = edge.Curve
    is_closed = edge.isClosed()
    print(f"Edge {i}: Length={length:.2f}, Closed={is_closed}, Type={type(curve_type).__name__}")

Key properties and methods of an Edge:

  • edge.Length: Returns the scalar length of the edge.
  • edge.Vertexes: Returns the vertices bounding the edge (usually start and end points).
  • edge.Curve: Returns the underlying mathematical curve object (e.g., Line, Circle, BSplineCurve).

Querying Faces

Faces represent 2D bounded surfaces. Access them using shape.Faces:

# Total count of faces
print(f"Total faces: {len(shape.Faces)}")

# Inspect face properties
for i, face in enumerate(shape.Faces):
    area = face.Area
    surface_type = face.Surface
    center_of_mass = face.CenterOfMass
    print(f"Face {i}: Area={area:.2f}, Center={center_of_mass}, Surface={type(surface_type).__name__}")

Key properties and methods of a Face:

  • face.Area: Returns the surface area.
  • face.CenterOfMass: Returns the Base.Vector of the face's centroid.
  • face.Surface: Returns the underlying mathematical surface (e.g., Plane, Cylinder, Toroid).
  • face.normalAt(u, v): Returns the normal vector at the specified UV parameter coordinates.

Traversing Hierarchical Relationships

FreeCAD allows topological navigation across levels. You can query sub-elements directly from parent elements:

# Select the first face of the shape
first_face = shape.Faces[0]

# Retrieve all edges belonging to this specific face
face_edges = first_face.Edges

# Retrieve all vertices belonging to this specific face
face_vertices = first_face.Vertexes

print(f"The selected face contains {len(face_edges)} edges and {len(face_vertices)} vertices.")

Similarly, you can retrieve the bounding vertices of a single edge:

first_edge = shape.Edges[0]
start_vertex = first_edge.Vertexes[0]
end_vertex = first_edge.Vertexes[-1]

print(f"Edge Start: {start_vertex.Point}, Edge End: {end_vertex.Point}")