How to Check Object Visibility in FreeCAD

Checking whether an object is visible or hidden in FreeCAD using Python requires accessing its visual representation rather than its underlying geometry data. Because FreeCAD maintains a strict separation between the document model (App) and the graphical user interface (Gui), visibility states are managed by the object's view provider. This article explains how to query the visibility state of individual or multiple FreeCAD objects programmatically using the Python console or macro environment.

Understanding the App vs. Gui Architecture

In FreeCAD, the core object containing shape and positional data is stored under the App namespace (e.g., App.ActiveDocument.Box). However, display properties—such as color, transparency, display mode, and visibility—reside within the ViewObject extension managed under the Gui namespace.

To read an object's visibility, you inspect the boolean Visibility property on its ViewObject.

Checking a Single Object's Visibility

If you already have a reference to a document object, you can directly query its ViewObject.Visibility attribute:

import FreeCAD as App

# Get the document object by its internal name
obj = App.ActiveDocument.getObject("Box")

if obj and hasattr(obj, "ViewObject") and obj.ViewObject:
    is_visible = obj.ViewObject.Visibility
    print(f"Object '{obj.Label}' is visible: {is_visible}")
else:
    print("Object does not exist or has no ViewObject.")

Alternatively, you can access the object directly through the Gui module using the object's name:

import FreeCADGui as Gui

# Access the ViewProvider directly
view_obj = Gui.ActiveDocument.getObject("Box")

if view_obj:
    print(f"Visibility: {view_obj.Visibility}")

Both approaches return True if the item is currently shown in the 3D view and False if it is hidden (for example, toggled off using the spacebar).

Checking Visibility for All Objects in a Document

To inspect every object in the active document, iterate through the document's object list:

import FreeCAD as App

doc = App.ActiveDocument

if doc:
    for obj in doc.Objects:
        if hasattr(obj, "ViewObject") and obj.ViewObject is not None:
            state = "Visible" if obj.ViewObject.Visibility else "Hidden"
            print(f"[{state}] {obj.Label} ({obj.Name})")

Checking Selected Objects

If you want to check the visibility state of only the objects currently highlighted by the user:

import FreeCADGui as Gui

selection = Gui.Selection.getSelection()

for obj in selection:
    if hasattr(obj, "ViewObject") and obj.ViewObject:
        print(f"{obj.Label} is visible: {obj.ViewObject.Visibility}")

Important Considerations for Headless Mode

The ViewObject attribute is only populated when FreeCAD is executed with a graphical interface. If your script runs in a pure headless environment (e.g., via freecadcmd or importing FreeCAD into an external Python script without FreeCADGui), obj.ViewObject will return None. Always verify that FreeCAD.GuiUp is True or that obj.ViewObject is not None before attempting to read Visibility in scripts intended for both GUI and automated command-line execution.