FreeCAD Scripting Basics

Python scripting in FreeCAD
FreeCAD is built from scratch to be totally controlled by python scripts. Almost all parts of FreeCAD such as the interface, the scene contents, and even the representation of this content in the 3d views are accessible from the built-in python interpreter or from your own scripts. As a result, FreeCAD is probably one of the most deeply customizable engineering application available today.

In its current state however, FreeCAD has very few "native" commands to interact on your 3D objects, mainly because it is still in early stage of development, but also because the philosophy behind it is more to provide a platform for CAD development than a user-tailored application. But the ease of python scripting inside FreeCAD will probably help much to see quickly new functionality being developed by "power users", or, typically, users who know a bit of python programming, like, we hope, yourself.

If you are not familiar with python, we recommend you to search for tutorials on the internet, and have a quick look at its structure. Python is a very easy language to learn, especially because it can be run inside an interpreter, where from simple commands to complete programs can be executed on the fly, without the need to compile anything. FreeCAD has a built-in python interpreter. If you don't see the window labeled "Report view" as shown below, you can activate it under the View -> Views -> Report view to bring up the interpreter.

The interpreter
From the interpreter, you can access all your system-installed python modules, as well as the built-in FreeCAD modules, and all additional FreeCAD modules you installed later. The screenshot below shows the python interpreter:



From the interpreter, you can execute python code and browse through the available classes and function. FreeCAD provides a very handy class browser for exploration of your new FreeCAD world: When you type the name of a known class followed by a period (meaning you want to add something from that class), a class browser window opens, where you can navigate between available subclasses and methods. When you select something, an associated help text (if existing) is displayed:



So, start here by typing App. or Gui. and see what happens. Another more generic python way of exploring contents of modules and classes is to use the print dir command. For example, typing print dir will list all modules currently loaded in FreeCAD. print dir(App) will show you everything inside the App module, etc.

Another useful feature of the interpreter is the possibility to go back in command history and retrieve a line of code you already typed earlier. To navigate in command history, just use CTRL+UP or CTRL+DOWN.

By right-clicking in the interpreter window, you also have several other options, such as copy the entire history (useful to experiment something here, then make a full script of it), or insert filename with complete path.

Python Help
In the FreeCAD Help menu, you'll find an entry labeled "Python help", which will open a browser window containing a complete, realtime-generated documentation of all python modules available to the FreeCAD interpreter, including python and FreeCAD built-in modules, system-installed modules, and FreeCAD additional modules. The documentation available there depends on how much effort each module developer put in documenting his code, but usually python module have the reputation to be fairly well documented. Your FreeCAD window must stay open for this documentation system to work.

Built-in modules
Since FreeCAD is designed to be run without Graphic User Interface, almost all its functionality is separated in two groups: Core functionality, named App, and Gui functionality, named Gui. So, our two main FreeCAD built-in modules are called App and Gui. These two modules can also be accessed from scripts outside of the interpreter, by the respective names of FreeCAD and FreeCADGui.


 * In the App module, you'll find everything related to the application itself, like methods for opening or closing files, and to the documents, like setting the active document or listing their contents.


 * In the Gui module, you'll find tools for accessing and managing Gui elements, like the workbenches and their toolbars, and, more interesting, the graphical representation of all FreeCAD content.

Listing all the content of those modules is a bit counter-productive task, since they grow quite fast along FreeCAD development. But the two browsing tools provided (the class browser and the python help) should give you, at any moment, a complete and up-to-date documentation of these modules.

The App and Gui objects
As we said, in FreeCAD, everything is separated between core and representation. This includes the 3D objects too. You can access defining properties of objects (called features in FreeCAD) via the App module, and change the way they are represented on screen via the Gui module. For example, a cube has properties that define it, like width, length, height, that are stored in an App object, and representation properties, such as faces color, drawing mode, that are stored in a corresponding Gui object.

This way of doing allows a very wide range of uses, like having algorithms work only on the defining part of features, without the need to care about any visual part, or even redirect the content of the document to non-graphical application, such as lists, spreadsheets, or element analysis.

For every App object in your document, exists a corresponding Gui object. The document itself, actually, also has App and a Gui objects. This, of course, is only valid when you run FreeCAD with its full interface. In the command-line version, no GUI exists, so only App objects are availible. Note that the Gui part of objects is generated again everytime an App object is marked as "to be recomputed" (for example when one of its parameters changed), so changes you might have done directly to the Gui object might get lost.

to access the App part of something, you type: myObject = App.ActiveDocument.getObject("ObjectName") where "ObjectName is the name of your object. You can also type: myObject = App.ActiveDocument.ObjectName

to access the Gui part of the same object, you type: myViewObject = Gui.ActiveDocument.getObject("ObjectName") where "ObjectName is the name of your object. You can also type: myViewObject = App.ActiveDocument.ObjectName.ViewObject

If we have no GUI (for example we are in command line mode), the last line will return None.

The Document objects
In FreeCAD all your work resides inside Documents. A document contains your geometry and can be saved to a file. Several documents can be opened at the same time. The document, like the geometry contained inside, has App and Gui objects. App object contains your actual geometry definitions, while the Gui object contains the different views of your document. You can open several windows, each one viewing your work with a different zoom factor or point of view. These views are all part of your document's Gui object.

To access the App part the currently open (active) document, you type: myDocument = App.ActiveDocument To create a new document, type: myDocument = App.newDocument("Document Name") To access the Gui part the currently open (active) document, you type: myGuiDocument = Gui.ActiveDocument To access the current view, you type: myView = Gui.ActiveDocument.ActiveView