FreeCAD Scripting Basics: Difference between revisions

From FreeCAD Documentation
(→‎Python scripting in FreeCAD: python → Python)
(Added: Category:Developer Documentation.)
(49 intermediate revisions by 15 users not shown)
Line 1: Line 1:
<languages/>
== Python scripting in FreeCAD ==
<translate>


<!--T:41-->
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.
{{Docnav
|[[Python_scripting_tutorial|Python scripting tutorial]]
|[[Topological_data_scripting|Topological data scripting]]
}}


</translate>
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.
{{TOCright}}
<translate>


==Python scripting in FreeCAD== <!--T:1-->
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.


<!--T:44-->
===The interpreter===
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 applications available today.


<!--T:3-->
If you are not familiar with Python, we recommend you 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 simple commands, right up 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 '''Python console''' as shown below, you can activate it under the {{MenuCommand|View → Panels → Python console}}.

===The interpreter=== <!--T:4-->

<!--T:45-->
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 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:


<!--T:5-->
[[Image:screenshot_pythoninterpreter.jpg|The FreeCAD Python interpreter]]
[[Image:screenshot_pythoninterpreter.jpg|The FreeCAD Python interpreter]]


<!--T:6-->
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:
From the interpreter, you can execute Python code and browse through the available classes and functions. FreeCAD provides a very handy class browser for exploration of the 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 it exists) is displayed:


<!--T:7-->
[[Image:screenshot_classbrowser.jpg|The FreeCAD class browser]]
[[Image:screenshot_classbrowser.jpg|The FreeCAD class browser]]


<!--T:8-->
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.
So, start here by typing {{incode|App.}} or {{incode|Gui.}} and see what happens. Another more generic Python way of exploring the content of modules and classes is to use the {{incode|print(dir())}} command. For example, typing {{incode|print(dir())}} will list all modules currently loaded in FreeCAD. {{incode|print(dir(App))}} will show you everything inside the App module, etc.


<!--T:9-->
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.
Another useful feature of the interpreter is the possibility to go back through the command history and retrieve a line of code that you already typed earlier. To navigate through the command history, just use {{KEY|Up arrow}} or {{KEY|Down arrow}}.


<!--T:10-->
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.
By right-clicking in the interpreter window, you also have several other options, such as copy the entire history (useful when you want to experiment with things before making a full script of them), or insert a filename with complete path.


<!--T:46-->
===Python Help===
[[#top|top]]


===Python Help=== <!--T:11-->
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.


<!--T:47-->
==Built-in modules==
In the FreeCAD {{MenuCommand|Help}} menu, you'll find an entry labeled {{MenuCommand|Automatic python modules documentation}}, 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 into documenting his code, but Python modules have a reputation for being fairly well documented. Your FreeCAD window must stay open for this documentation system to work.
The entry {{MenuCommand|Python scripting documentation}} will give you a quick link to the [[Power_users_hub|Power users hub]] wiki section.


<!--T:48-->
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.
[[#top|top]]


==Built-in modules== <!--T:12-->
* 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.


<!--T:49-->
* 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.
Since FreeCAD is designed so that it can also be run without a Graphical User Interface (GUI), almost all its functionality is separated into two groups: Core functionality, named {{incode|App}}, and GUI functionality, named {{incode|Gui}}. These two modules can also be accessed from scripts outside of the interpreter, by the names {{incode|FreeCAD}} and {{incode|FreeCADGui}} respectively.


<!--T:13-->
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.
* In the {{incode|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.


<!--T:14-->
===The App and Gui objects===
* In the {{incode|Gui}} module, you'll find tools for accessing and managing Gui elements, like the workbenches and their toolbars, and, more interestingly, the graphical representation of all FreeCAD content.


<!--T:15-->
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.
Listing the content of these modules is not very useful because they grow quite fast as FreeCAD develops. But the two browsing tools provided (the class browser and the Python help) should give you complete and up-to-date documentation at any moment.


<!--T:50-->
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.
[[#top|top]]


===The App and Gui objects=== <!--T:16-->
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.


<!--T:51-->
to access the App part of something, you type:
As already mentioned, in FreeCAD everything is separated into core and representation. This includes the 3D objects. You can access defining properties of objects (called features in FreeCAD) via the {{incode|App}} module, and change the way they are represented on screen via the {{incode|Gui}} module. For example, a cube has properties that define it (like width, length, height) that are stored in an {{incode|App}} object, and representation properties (like faces color, drawing mode) that are stored in a corresponding {{incode|Gui}} object.
myObject = App.ActiveDocument.getObject("ObjectName")
where "ObjectName is the name of your object. You can also type:
myObject = App.ActiveDocument.ObjectName


<!--T:17-->
to access the Gui part of the same object, you type:
This way of doing things allows a very wide range of uses, like having algorithms work only on the definition 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.
myViewObject = Gui.ActiveDocument.getObject("ObjectName")
where "ObjectName is the name of your object. You can also type:
myViewObject = App.ActiveDocument.ObjectName.ViewObject


<!--T:18-->
If we have no GUI (for example we are in command line mode), the last line will return None.
For every {{incode|App}} object in your document, there exists a corresponding {{incode|Gui}} object. In fact the document itself has both an {{incode|App}} and a {{incode|Gui}} object. This, of course, only applies when you run FreeCAD with its full interface. In the command-line version no GUI exists, so only {{incode|App}} objects are available. Note that the {{incode|Gui}} part of objects is re-generated every time an {{incode|App}} object is marked as 'to be recomputed' (for example when one of its parameters changes), so any changes made directly to the {{incode|Gui}} object may be lost.


<!--T:19-->
=== The Document objects ===
To access the {{incode|App}} part of something, you type:


</translate>
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.
{{Code|code=
myObject = App.ActiveDocument.getObject("ObjectName")
}}
<translate>


<!--T:20-->
To access the App part the currently open (active) document, you type:
where {{incode|"ObjectName"}} is the name of your object. You can also type:
myDocument = App.ActiveDocument

</translate>
{{Code|code=
myObject = App.ActiveDocument.ObjectName
}}
<translate>

<!--T:21-->
To access the {{incode|Gui}} part of the same object, you type:

</translate>
{{Code|code=
myViewObject = Gui.ActiveDocument.getObject("ObjectName")
}}
<translate>

<!--T:22-->
where {{incode|"ObjectName"}} is the name of your object. You can also type:

</translate>
{{Code|code=
myViewObject = App.ActiveDocument.ObjectName.ViewObject
}}
<translate>

<!--T:23-->
If you are in command-line mode and have no GUI, the last line will return {{incode|None}}.

<!--T:52-->
[[#top|top]]

===The Document objects=== <!--T:24-->

<!--T:53-->
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 {{incode|App}} and {{incode|Gui}} objects. The {{incode|App}} object contains your actual geometry definitions, while the {{incode|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 from a different direction. These views are all part of your document's {{incode|Gui}} object.

<!--T:25-->
To access the {{incode|App}} part of the currently open (active) document, you type:

</translate>
{{Code|code=
myDocument = App.ActiveDocument
}}
<translate>

<!--T:26-->
To create a new document, type:
To create a new document, type:

myDocument = App.newDocument("Document Name")
</translate>
To access the Gui part the currently open (active) document, you type:
{{Code|code=
myGuiDocument = Gui.ActiveDocument
myDocument = App.newDocument("Document Name")
}}
<translate>

<!--T:27-->
To access the {{incode|Gui}} part of the currently open (active) document, you type:

</translate>
{{Code|code=
myGuiDocument = Gui.ActiveDocument
}}
<translate>

<!--T:28-->
To access the current view, you type:
To access the current view, you type:
myView = Gui.ActiveDocument.ActiveView


</translate>
== Using additional modules ==
{{Code|code=
myView = Gui.ActiveDocument.ActiveView
}}
<translate>


<!--T:54-->
The FreeCAD and FreeCADGui modules are solely responsibles for creating and managing objects in the FreeCAD document. They don't actually do anything such as creating or modifying geometry. That is because that geometry can be of several types, and so it is managed by additional modules, each responsible for managing a certain geometry type. For example, the [[Part Module]] uses the OpenCascade kernel, and therefore is able to create and manipulate BRep-type geometry, which is what OpenCascade is built for. The [[Mesh Module]] is able to build and modify mesh objects. That way, FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types could be added easily in the future.
[[#top|top]]


==Using additional modules== <!--T:29-->
=== Creating objects ===


<!--T:55-->
Each module has its own way to treat its geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules:
The {{incode|FreeCAD}} and {{incode|FreeCADGui}} modules are only responsible for creating and managing objects in the FreeCAD document. They don't actually do anything more such as creating or modifying geometry. This is because that geometry can be of several types, and therefore requires additional modules, each responsible for managing a certain geometry type. For example, the [[Part Module|Part Module]], using the OpenCascade kernel, is able to create and manipulate [http://en.wikipedia.org/wiki/Boundary_representation BRep] type geometry. Whereas the [[Mesh Module|Mesh Module]] is able to build and modify mesh objects. In this manner FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types can easily be added in the future.


<!--T:56-->
FreeCAD.ActiveDocument.supportedTypes()
[[#top|top]]


===Creating objects=== <!--T:30-->
will list you all the possible objects you can create. For example, let's create a mesh (treated by the mesh module) and a part (treated by the part module):


<!--T:57-->
myMesh = FreeCAD.ActiveDocument.addObject("Mesh::Feature","myMeshName")
Each module has its own way of dealing with geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules:
myPart = FreeCAD.ActiveDocument.addObject("Part::Feature","myPartName")


</translate>
The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with dir(myMesh) and dir(myPart). Except for one, myMesh has a "Mesh" property and "Part" has a "Shape" property. That is where the Mesh and Part data are stored. For example, let's create a Part cube and store it in our myPart object:
{{Code|code=
FreeCAD.ActiveDocument.supportedTypes()
}}
<translate>


<!--T:31-->
import Part
will list all possible objects you can create. For example, let's create a mesh (handled by the {{incode|Mesh}} module) and a part (handled by the {{incode|Part}} module):
cube = Part.makeBox(2,2,2)
myPart.Shape = cube


</translate>
You could try storing the cube inside the Mesh property of the myMesh object, it will return an error complaining of the wrong type. That is because those properties are made to store only a certain type. In the myMesh's Mesh property, you can only save stuff created with the Mesh module. Note that most modules also have a shortcut to add their geometry to the document:
{{Code|code=
myMesh = FreeCAD.ActiveDocument.addObject("Mesh::Feature", "myMeshName")
myPart = FreeCAD.ActiveDocument.addObject("Part::Feature", "myPartName")
}}
<translate>


<!--T:32-->
import Part
The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with {{incode|dir(myMesh)}} and {{incode|dir(myPart)}}. Except for one thing, {{incode|myMesh}} has a {{incode|Mesh}} property and {{incode|myPart}} has a {{incode|Shape}} property. That is where the Mesh and Part data are stored. For example, let's create a {{incode|Part}} cube and store it in our {{incode|myPart}} object:
cube = Part.makeBox(2,2,2)
Part.show(cube)


</translate>
=== Modifying objects ===
{{Code|code=
import Part
cube = Part.makeBox(2, 2, 2)
myPart.Shape = cube
}}
<translate>


<!--T:33-->
Modifying an object is done the same way:
You could try storing the cube inside the {{incode|Mesh}} property of the {{incode|myMesh}} object, but it will return an error. That is because each properties is made to store only a certain type. In a {{incode|Mesh}} property, you can only save stuff created with the {{incode|Mesh}} module. Note that most modules also have a shortcut to add their geometry to the document:


</translate>
import Part
{{Code|code=
cube = Part.makeBox(2,2,2)
import Part
myPart.Shape = cube
cube = Part.makeBox(2, 2, 2)
Part.show(cube)
}}
<translate>


<!--T:58-->
[[#top|top]]

===Modifying objects=== <!--T:34-->

<!--T:59-->
Modifying an object is done in the same way:

</translate>
{{Code|code=
import Part
cube = Part.makeBox(2, 2, 2)
myPart.Shape = cube
}}
<translate>

<!--T:35-->
Now let's change the shape by a bigger one:
Now let's change the shape by a bigger one:


</translate>
biggercube = Part.makeBox(5,5,5)
{{Code|code=
myPart.Shape = biggercube
biggercube = Part.makeBox(5, 5, 5)
myPart.Shape = biggercube
}}
<translate>

<!--T:60-->
[[#top|top]]


=== Querying objects ===
===Querying objects=== <!--T:36-->


<!--T:61-->
You can always look at the type of an object like this:
You can always look at the type of an object like this:


</translate>
myObj = FreeCAD.ActiveDocument.getObject("myObjectName")
{{Code|code=
print myObj.Type
myObj = FreeCAD.ActiveDocument.getObject("myObjectName")
print(myObj.TypeId)
}}
<translate>


<!--T:37-->
or know if an object is derived from one of the basic ones (Part Feature, Mesh Feature, etc):
or check if an object is derived from one of the basic ones (Part Feature, Mesh Feature, etc):


</translate>
print myObj.isDerivedFrom("Part::Feature")
{{Code|code=
print(myObj.isDerivedFrom("Part::Feature"))
}}
<translate>


<!--T:38-->
Now you can really start playing with FreeCAD! To look at what you can do with the [[Part Module]], read the [[Topological data scripting|Part scripting]] page, or the [[Mesh Scripting]] page for working with the [[Mesh Module]]. Note that, although the Part and Mesh modules are the most complete and widely used, other modules such as the [[Draft Module]] also have [[Draft API|scripting]] APIs that can be useful to you. For a complete list of each modules and their available tools, visit the [[:Category:API]] section.
Now you can really start playing with FreeCAD! For a complete list of available modules and their tools, visit the [[:Category:API|Category:API]] section.


<!--T:62-->
{{docnav|Introduction to python|Mesh Scripting}}
[[#top|top]]


<!--T:39-->
{{languages | {{es|FreeCAD Scripting Basics/es}} {{se|FreeCAD Scripting Basics/se}} {{ru|FreeCAD Scripting Basics/ru}} }}
{{Docnav
|[[Python_scripting_tutorial|Python scripting tutorial]]
|[[Topological_data_scripting|Topological data scripting]]
}}


</translate>
[[Category:Poweruser Documentation]]
{{Powerdocnavi{{#translation:}}}}
[[Category:Developer Documentation{{#translation:}}]]
[[Category:Python Code{{#translation:}}]]
{{clear}}

Revision as of 12:20, 3 June 2020

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 applications available today.

If you are not familiar with Python, we recommend you 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 simple commands, right up 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 Python console as shown below, you can activate it under the View → Panels → Python console.

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:

The FreeCAD Python interpreter

From the interpreter, you can execute Python code and browse through the available classes and functions. FreeCAD provides a very handy class browser for exploration of the 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 it exists) is displayed:

The FreeCAD class browser

So, start here by typing App. or Gui. and see what happens. Another more generic Python way of exploring the content 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 through the command history and retrieve a line of code that you already typed earlier. To navigate through the command history, just use Up arrow or Down arrow.

By right-clicking in the interpreter window, you also have several other options, such as copy the entire history (useful when you want to experiment with things before making a full script of them), or insert a filename with complete path.

top

Python Help

In the FreeCAD Help menu, you'll find an entry labeled Automatic python modules documentation, 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 into documenting his code, but Python modules have a reputation for being fairly well documented. Your FreeCAD window must stay open for this documentation system to work. The entry Python scripting documentation will give you a quick link to the Power users hub wiki section.

top

Built-in modules

Since FreeCAD is designed so that it can also be run without a Graphical User Interface (GUI), almost all its functionality is separated into two groups: Core functionality, named App, and GUI functionality, named Gui. These two modules can also be accessed from scripts outside of the interpreter, by the names FreeCAD and FreeCADGui respectively.

  • 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 interestingly, the graphical representation of all FreeCAD content.

Listing the content of these modules is not very useful because they grow quite fast as FreeCAD develops. But the two browsing tools provided (the class browser and the Python help) should give you complete and up-to-date documentation at any moment.

top

The App and Gui objects

As already mentioned, in FreeCAD everything is separated into core and representation. This includes the 3D objects. 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 (like faces color, drawing mode) that are stored in a corresponding Gui object.

This way of doing things allows a very wide range of uses, like having algorithms work only on the definition 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, there exists a corresponding Gui object. In fact the document itself has both an App and a Gui object. This, of course, only applies when you run FreeCAD with its full interface. In the command-line version no GUI exists, so only App objects are available. Note that the Gui part of objects is re-generated every time an App object is marked as 'to be recomputed' (for example when one of its parameters changes), so any changes made directly to the Gui object may be 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 you are in command-line mode and have no GUI, the last line will return None.

top

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. The 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 from a different direction. These views are all part of your document's Gui object.

To access the App part of 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 of the currently open (active) document, you type:

myGuiDocument = Gui.ActiveDocument

To access the current view, you type:

myView = Gui.ActiveDocument.ActiveView

top

Using additional modules

The FreeCAD and FreeCADGui modules are only responsible for creating and managing objects in the FreeCAD document. They don't actually do anything more such as creating or modifying geometry. This is because that geometry can be of several types, and therefore requires additional modules, each responsible for managing a certain geometry type. For example, the Part Module, using the OpenCascade kernel, is able to create and manipulate BRep type geometry. Whereas the Mesh Module is able to build and modify mesh objects. In this manner FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types can easily be added in the future.

top

Creating objects

Each module has its own way of dealing with geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules:

FreeCAD.ActiveDocument.supportedTypes()

will list all possible objects you can create. For example, let's create a mesh (handled by the Mesh module) and a part (handled by the Part module):

myMesh = FreeCAD.ActiveDocument.addObject("Mesh::Feature", "myMeshName")
myPart = FreeCAD.ActiveDocument.addObject("Part::Feature", "myPartName")

The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with dir(myMesh) and dir(myPart). Except for one thing, myMesh has a Mesh property and myPart has a Shape property. That is where the Mesh and Part data are stored. For example, let's create a Part cube and store it in our myPart object:

import Part
cube = Part.makeBox(2, 2, 2)
myPart.Shape = cube

You could try storing the cube inside the Mesh property of the myMesh object, but it will return an error. That is because each properties is made to store only a certain type. In a Mesh property, you can only save stuff created with the Mesh module. Note that most modules also have a shortcut to add their geometry to the document:

import Part
cube = Part.makeBox(2, 2, 2)
Part.show(cube)

top

Modifying objects

Modifying an object is done in the same way:

import Part
cube = Part.makeBox(2, 2, 2)
myPart.Shape = cube

Now let's change the shape by a bigger one:

biggercube = Part.makeBox(5, 5, 5)
myPart.Shape = biggercube

top

Querying objects

You can always look at the type of an object like this:

myObj = FreeCAD.ActiveDocument.getObject("myObjectName")
print(myObj.TypeId)

or check if an object is derived from one of the basic ones (Part Feature, Mesh Feature, etc):

print(myObj.isDerivedFrom("Part::Feature"))

Now you can really start playing with FreeCAD! For a complete list of available modules and their tools, visit the Category:API section.

top