Suppress UI Redraws in FreeCAD Batch Processing

Executing heavy automated modeling or batch operations in FreeCAD can cause severe performance bottlenecks if the graphical interface redraws after every change. This article explains how to temporarily disable user interface updates in FreeCAD using Python, defer document recalculations, and run scripts in headless mode to maximize processing speed.

Method 1: Disable Qt Window Updates

FreeCAD’s user interface is built on Qt. You can directly disable painting events on the main application window through Python using FreeCAD's built-in Qt binding. Always wrap your processing loop inside a try...finally block to ensure that interface updates are re-enabled even if an error terminates the script prematurely.

import FreeCADGui

main_window = FreeCADGui.getMainWindow()

# Disable all UI repaints
main_window.setUpdatesEnabled(False)

try:
    # Run heavy batch processing loop here
    for i in range(1000):
        # Perform geometry generation or modification
        pass
finally:
    # Re-enable repaints and force an update
    main_window.setUpdatesEnabled(True)
    main_window.update()

Method 2: Defer Document Recomputes

A common cause of automatic viewport and tree view redraws is calling doc.recompute() inside a loop. Each recompute forces FreeCAD to update dependencies, visual representations, and 3D Coin3D scenegraphs.

To prevent unnecessary overhead:

  1. Add or modify all geometry, properties, and constraints inside your loop without calling recompute().
  2. Call doc.recompute() a single time outside the loop after all batch items are processed.
import FreeCAD as App

doc = App.ActiveDocument

# Avoid doc.recompute() inside the loop
for i in range(1000):
    box = doc.addObject("Part::Box", f"Box_{i}")
    box.Length = 10
    box.Width = 10
    box.Height = 10

# Recompute once at the end
doc.recompute()

Method 3: Run Scripts in Headless Mode

If the batch process does not require user interaction, the most efficient approach is to bypass the graphical user interface entirely:

  • Command-line executable: Run your script using freecadcmd (on Linux/macOS) or FreeCADCmd.exe (on Windows) instead of the standard FreeCAD binary:

    freecadcmd my_batch_script.py

  • Python module import: When using FreeCAD as a library in standard Python scripts, import only the core module FreeCAD (often aliased as App). Avoid importing FreeCADGui. Without the GUI module initialized, FreeCAD operates entirely in memory with zero rendering overhead.