How FreeCAD Integrates with OpenCASCADE for B‑REP Geometry Operations

FreeCAD integrates with OpenCASCADE through a thin C++ wrapper layer centered on the TopoShape class, which translates internal data structures into OCCT TopoDS_Shape objects, invokes OpenCASCADE algorithms for Boolean operations and healing, and maps results back into FreeCAD's document model.

FreeCAD's 3‑D geometry kernel is built entirely on the OpenCASCADE Technology (OCCT) library. This integration allows FreeCAD to leverage industrial‑strength B‑REP (Boundary Representation) operations while presenting a higher‑level API to both C++ and Python developers. The architecture relies on a centralized header aggregation, a unified shape wrapper, and specialized subclasses that add error handling and progress reporting to native OCCT algorithms.

Core Wrapper Architecture: The TopoShape Class

The foundation of FreeCAD's OpenCASCADE integration is the TopoShape class, defined in src/Mod/Part/App/TopoShape.h and implemented in src/Mod/Part/App/TopoShape.cpp. This class serves as the primary container for all B‑REP data within FreeCAD.

Centralized OCCT Header Aggregation

All OpenCASCADE dependencies are collected in a single header file to ensure consistent compilation across platforms:

• src/Mod/Part/App/OpenCascadeAll.h – Aggregates every required OCCT header, including BRepBuilderAPI_MakeEdge.hxx, BRepAlgoAPI_Cut.hxx, and BRepPrimAPI_MakeBox.hxx

This centralization prevents circular dependencies and ensures that any module using B‑REP operations includes the complete OCCT API surface.

Shape Container and Cache

The TopoShape class stores three critical components:

1. The OCCT shape – A TopoDS_Shape instance representing the actual B‑REP geometry
2. History mapper – Tracks modifications during Boolean operations and filleting
3. Cache – Stores computed properties (volume, bounding box) for fast reuse without recalculating

When FreeCAD creates geometry, it follows a consistent three‑step workflow:

1. Invoke an OCCT construction class (e.g., BRepPrimAPI_MakeBox)
2. Extract the resulting TopoDS_Shape via .Shape()
3. Wrap it in a TopoShape object for storage in the document graph

Boolean Operations: The FCBRepAlgoAPI_* Layer

FreeCAD does not call OpenCASCADE Boolean classes directly. Instead, it subclasses them to add error handling, progress reporting, and Python exception translation.

Specialized Algorithm Wrappers

Located in src/Mod/Part/App/, these classes inherit from OCCT's Boolean API:

• FCBRepAlgoAPI_Cut.h/cpp – Inherits from BRepAlgoAPI_Cut for subtraction operations
• FCBRepAlgoAPI_Fuse.h/cpp – Inherits from BRepAlgoAPI_Fuse for union operations
• FCBRepAlgoAPI_Common.h/cpp – Inherits from BRepAlgoAPI_Common for intersection operations

Each wrapper implements a perform() method that executes the underlying OCCT algorithm, checks the IsDone() status, and throws Part::BooleanException if the operation fails. This translates low‑level OCCT error codes into exceptions catchable by FreeCAD's Python API.

// Example from the wrapper implementation
BRepAlgoAPI_Cut cutter(shapeA, shapeB);
cutter.Build();               // OCCT runs the Boolean
if (!cutter.IsDone())
    throw BooleanException("OpenCASCADE Boolean failed");
TopoShape result(cutter.Shape());

Shape Healing and Sewing

Before exposing geometry to users or performing Boolean operations, FreeCAD frequently runs OpenCASCADE "fix‑up" tools to ensure B‑REP validity.

Healing Operations

• BRepBuilderAPI_Sewing – Merges adjacent wires and faces into a coherent shell, exposed via TopoShape::sew()
• ShapeFix_Shape – Repairs self‑intersections, missing seams, and invalid curves, invoked through TopoShape::fixShape() in TopoShape.cpp

These utilities are included via OpenCascadeAll.h and operate directly on the internal TopoDS_Shape before re‑wrapping the result.

Mesh Generation from B‑REP

When tessellation is required for visualization or export, FreeCAD calls BRepMesh_IncrementalMesh (implemented in src/Mod/Part/App/BRepMesh.cpp). This generates a triangular mesh while preserving the original B‑REP topology. The mesh data is stored separately from the shape to maintain the parametric B‑REP's integrity.

Python API Integration

FreeCAD exposes the entire C++ wrapper layer through the Part module. Python methods like Part.makeBox() or shape.cut(other) directly invoke the C++ TopoShape and FCBRepAlgoAPI_* classes.

C++ Example: Box Construction and Boolean Cut

#include "TopoShape.h"
#include <BRepPrimAPI_MakeBox.hxx>
#include <BRepOffsetAPI_MakeOffset.hxx>
#include <FCBRepAlgoAPI_Cut.h>

int main()
{
    // 1. Build a solid box using OCCT primitives
    BRepPrimAPI_MakeBox mkBox(gp_Pnt(0,0,0), 10, 10, 10);
    Part::TopoShape box(mkBox.Shape());

    // 2. Offset the box faces outward by 1.0
    BRepOffsetAPI_MakeOffset offsetMaker(box.getShape());
    offsetMaker.Perform(1.0);
    Part::TopoShape offsetBox(offsetMaker.Shape());

    // 3. Build a cylinder for cutting
    BRepPrimAPI_MakeCylinder mkCyl(gp_Ax2(gp_Pnt(5,5,0), gp::DZ()), 3.0, 20.0);
    Part::TopoShape cyl(mkCyl.Shape());

    // 4. Boolean cut using the FreeCAD wrapper
    Part::FCBRepAlgoAPI_Cut cutter(offsetBox, cyl);
    cutter.Build();
    if (!cutter.IsDone())
        throw Part::BooleanException("Cut failed");

    Part::TopoShape result(cutter.Shape());
    return 0;
}

Python Equivalent

import FreeCAD as App
import Part

# Create primitives

box = Part.makeBox(10, 10, 10)
cyl = Part.makeCylinder(3, 20, App.Vector(5, 5, 0), App.Vector(0, 0, 1))

# Offset and Boolean operations

offset = box.makeOffset3D(1.0)
result = offset.cut(cyl)

# Export the final B-REP

Part.export([result], "cut_result.step")

Both workflows demonstrate the same pattern: create OCCT primitives → modify via OCCT algorithms → execute Boolean via FCBRepAlgoAPI_* → return TopoShape.

Summary

• TopoShape is the central wrapper class that encapsulates OCCT's TopoDS_Shape and provides caching, history tracking, and healing methods.
• OpenCascadeAll.h aggregates all OCCT headers used by FreeCAD, ensuring consistent access to B‑REP construction and Boolean classes.
• FCBRepAlgoAPI_* wrappers subclass OCCT Boolean algorithms to add error handling, progress reporting, and Python exception translation.
• FreeCAD invokes OpenCASCADE healing tools (ShapeFix_Shape, BRepBuilderAPI_Sewing) automatically to ensure valid B‑REP topology before operations.
• The Python Part module exposes these C++ wrappers directly, allowing scripted access to industrial‑grade B‑REP operations.

Frequently Asked Questions

What is the purpose of the TopoShape class in FreeCAD?

The TopoShape class acts as the primary bridge between FreeCAD's document structure and OpenCASCADE's geometry kernel. It stores a TopoDS_Shape object, tracks modification history during Boolean operations, and caches geometric properties to avoid expensive recalculations. All B‑REP creation, modification, and query functions in FreeCAD ultimately operate on TopoShape instances defined in src/Mod/Part/App/TopoShape.h.

Why does FreeCAD use FCBRepAlgoAPI_* classes instead of calling OpenCASCADE directly?

FreeCAD subclasses OpenCASCADE Boolean algorithms (like BRepAlgoAPI_Cut) into FCBRepAlgoAPI_Cut and similar classes to add three critical capabilities: error checking via IsDone() status validation, translation of OCCT errors into FreeCAD's BooleanException for Python compatibility, and integration with FreeCAD's progress reporting system. These wrappers are located in src/Mod/Part/App/FCBRepAlgoAPI_Cut.h and corresponding implementation files.

How does FreeCAD handle invalid geometry from OpenCASCADE operations?

Before performing Boolean operations or exporting, FreeCAD invokes OpenCASCADE healing algorithms through methods like TopoShape::fixShape() and TopoShape::sew(). These use ShapeFix_Shape to repair self‑intersections and BRepBuilderAPI_Sewing to merge disconnected faces. If healing fails, the FCBRepAlgoAPI_* wrappers throw Part::BooleanException, which propagates to the Python console as a catchable error.

Can FreeCAD use geometry kernels other than OpenCASCADE?

While FreeCAD's core Part and PartDesign workbenches are tightly coupled to OpenCASCADE through the TopoShape architecture, the modular design allows alternative kernels in theory. However, all standard B‑REP operations—creation, Boolean logic, filleting, and meshing—currently require the OCCT integration layer centered on TopoShape and the FCBRepAlgoAPI_* wrappers. Changing kernels would require reimplementing these specific wrapper classes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}