FreeCAD App Module vs Gui Module Differences Explained

FreeCAD operates on a strictly decoupled architecture that separates underlying engineering data from its visual representation. This article explains the fundamental differences between FreeCAD’s App module and Gui module, detailing their respective roles within the software's Model-View-Controller (MVC) design, their operational dependencies, and when to use each in Python scripting and workbench development.

Core Architectural Distinction

FreeCAD is built using a dual-layer architecture where the data model and the user interface are completely isolated from one another.

  • App (The Model): Represents the data, geometry engine, and business logic. It handles parametric objects, geometric definitions, calculation trees, and document structures. It operates entirely independently of any user interface.
  • Gui (The View and Controller): Represents the presentation layer and user interaction. It manages the graphical interface, handles 3D rendering (using Coin3D), and processes user input via the Qt framework.

The App Module (FreeCAD / App)

The App module, typically accessed in Python via import FreeCAD or import App, contains the non-graphical core of the software.

Key characteristics include:

  • Headless Execution: The App module has no dependencies on display servers (like X11, Wayland, or Windows GDI) or GUI libraries like Qt. It can run in pure command-line environments, automated continuous integration (CI) pipelines, Docker containers, and web backends.
  • Document and Geometry Management: It creates and controls App::Document and App::DocumentObject instances. All mathematical modeling, shape generation via the Open CASCADE Technology (OCCT) kernel, and object properties (such as length, radius, and placement) are defined and calculated here.
  • Persistence: Saving and loading the actual geometric and parametric data of .FCStd files is coordinated through the App module.

The Gui Module (FreeCADGui / Gui)

The Gui module, accessed in Python via import FreeCADGui or import Gui, attaches to the App module when FreeCAD runs in visual desktop mode.

Key characteristics include:

  • Display Requirement: The Gui module depends directly on Qt for interface rendering and Coin3D for scene graph and 3D Open Inventor rendering. It cannot be initialized in a strictly headless environment without a virtual framebuffer.
  • Visual Representation: For almost every object created in the App module, the Gui module creates an associated ViewProvider. The ViewProvider handles how the object looks in the 3D viewport, including its color, transparency, line width, draw style, and visibility.
  • User Interaction: The Gui module handles user events such as mouse clicks, object selections, camera movements, workbench switching, task panels, and custom dialog windows.

Object Coupling: DocumentObject vs. ViewProvider

The relationship between the two modules is best observed in how objects exist within a FreeCAD session:

  1. App::DocumentObject: Created via App.ActiveDocument.addObject(...). This object stores parameters (such as Length = 10mm) and computes the resulting topological shape. It knows nothing about screen color or rendering nodes.
  2. Gui::ViewProvider: Accessed via Gui.ActiveDocument.getObject(...). This object listens to changes in the App::DocumentObject and updates the 3D scene graph accordingly. Changing a display color via obj.ViewObject.ShapeColor = (1.0, 0.0, 0.0) manipulates the Gui layer, leaving the underlying geometry unaltered.

Practical Guidelines for Developers

  • Use the App module when: Writing automation scripts, generating parametric geometry programmatically, processing batch conversions, running simulations, or building standalone command-line tools. Modifying geometry exclusively through App makes scripts portable and executable without a desktop interface.
  • Use the Gui module when: Creating interactive workbenches, capturing user selections from the 3D viewport, prompting users with dialogs, adjusting viewports/cameras, or modifying visual attributes like highlighting and transparency.