Python scripting tutorial/de

Python ist eine Programmiersprache, die schnell zu erlernen und leicht zu verwenden ist. Sie ist quelloffen, plattformunabhängig und kann für viele Zwecke genutzt werden, vom Programmieren von einfachen Shell-Scripts bis zu sehr komplexer Software. Eine seiner am weitesten verbreiteten Anwendungen ist jedoch als Skriptsprache, weil sie besonders einfach in andere Programme integriert werden kann. Und genauso wird sie auch in FreeCAD verwendet. Über die Python-Konsole oder mit selbtgemachten Skripten kann man in FreeCAD arbeiten und dabei sehr komplexe Vorgänge ausführen, für die es bisher keine über die Benutzeroberfläche erreichbaren Werkzeuge gibt.

Beispielsweise kann man mit Python-Skripten:
 * neue Objekte erzeugen
 * vorhandene Objekte modifizieren
 * die 3D-Darstellung der Objekte verändern
 * die Benutzeroberfläche von FreeCAD anpassen

Es gibt zudem mehrere Möglichkeiten, um Python innerhalb von FreeCAD zu verwenden:
 * Mit dem FreeCAD python interpreter können einfache Befehle erstellt werden
 * Mit Macros, die eine bequeme Möglichkeit bieten, fehlende Werkzeuge in die Benutzeroberfläche zu integrieren
 * Mit externen Skripten, die für komplexere Problemstellungen genutzt werden können (z.B. Einfügen von neuen Arbeitsbereichen)

In diesem Tutorial werden wir zum Einstieg ins Thema einige Beispiele behandeln, aber es ist noch viel mehr zum Thema python scripting in diesem Wiki verfügbar. Wenn Sie keinerlei Vorerfahrung mit Python besitzen, aber wissen möchten wie es funktioniert, dann bieten wir Ihnen auch eine Einführung in Python.

Wichtig! Bevor Sie mit dem Python scripting loslegen, sollten Sie noch zwei Ankreuzfelder im Menü (ganz unten) aktivieren: Gehen Sie dann ins Menü und klicken Sie auf Ausgabefenster. Dies wird Ihnen eine Menge Ärger ersparen.
 * Interne Python-Meldungen auf Ausgabefenster umleiten
 * Interne Python-Fehlermeldungen auf Ausgabefenster umleiten

Python-Code schreiben
Es gibt zwei einfache Wege, um Python-Programmcode in FreeCAD zu schreiben: Über die Python-Konsole (Menü: ) oder über den Makro-Editor (Menü: ). In der Konsole werden die Python-Befehle zeilenweise nacheinander eingegeben und mit der Eingabetaste ausgeführt, wohingegen Makros komplexere Skripte enthalten können, die viele Zeilen lang sind und beim Ausführen des Makros nacheinander ausgeführt werden.



In diesem Tutorial werden Sie beide Methoden kennenlernen, also entweder durch Kopieren/Einfügen von einzelnen Zeilen in die Python-Konsole und drücken der oder alternativ durch Kopieren/Einfügen des gesamten Programmcodes in ein neues Makro-Fenster.

Erkunden von FreeCAD
Wir beginnen damit, ein neues und leeres Dokument zu erstellen:

Wenn Sie dies in die Python-Konsole eingeben, werden Sie bemerken, dass nach dem Eintippen von FreeCAD. ein neues Fenster erscheint, dass eine Autovervollständigung des gesuchten Befehls anbietet. Vorteilhaft ist dabei auch, dass jeder angebotene Befehl eine Kurzinfo über die Funktion des Befehls anzeigt, sobald man den Mauszeiger darüber stehen lässt. Dies macht es umso einfacher, die verschiedenen Möglichkeiten des Programms zu erkunden. Bevor Sie newDocument auswählen, sollten Sie sich auch die anderen verfügbaren Optionen ansehen.



Nach dem Drücken der Eingabetaste wird ein neues Dokument erzeugt. Dies ist vergleichbar mit dem Drücken der Schaltfläche Neues Dokument erstellen in der Werkzeugleiste. Tatsächlich wird beim Drücken von Schaltflächen in FreeCAD meistens lediglich ein Python-Code ausgeführt. Noch besser ist es, wenn man im Menü die Option Skript-Befehle in Pythonkonsole anzeigen aktiviert. Dadurch wird beim Drücken von Schaltflächen der dazugehörige Python-Code in der Konsole angezeigt, was das Erlernen der Python-Befehle erleichtert.

Kehren wir nun zu unserem Dokument zurück. Schauen wir uns an, was wir damit machen können:

Erkunden Sie die verfügbaren Möglichkeiten. Namen, die mit einem Großbuchstaben beginnen, bezeichnen üblicherweise Attribute (Variablen bzw. Eigenschaften), während Namen, die mit Kleinbuchstaben beginnen, meistens aufrufbaren Funktionen (so genannte "Methoden") kennzeichnen. Hingegen beziehen sich Namen, die mit einem Unterstrich beginnen, auf die interne Programmierung des Moduls und sind im Normalfall nicht für die Verwendung durch den Benutzer gedacht. Wir werden nun eine der verfügbaren Methoden nutzen, um ein neues Objekt in under Dokument einzufügen:

Es passiert zunächst einmal nichts. Warum? Weil FreeCAD für das große Ganze gedacht ist. Eines Tages wird es mit hunderten von komplexen Objekten arbeiten, die alle voneinander abhängen. Eine geringfügige Änderung an einer Stelle könnte eine große Veränderung an einer anderen Stelle bewirken, sodass das gesamte Dokument aufwendig neu berechnet werden muss. Aus diesem Grund aktualisiert kaum ein Befehl die Ansicht automatisch. Es muss manuell durchgeführt werden:

Nun erscheint unser Würfel. Viele der Schaltflächen für Objekte in FreeCAD tun eigentlich zwei Dinge: das Objekt einfügen und das Dokument neuberechnen lassen. Wenn Sie oben die Option Skript-Befehle in Pythonkonsole anzeigen aktiviert haben, dann können Sie dies nun leicht überprüfen, indem Sie die Schaltfläche für eine Kugel anklicken und sich anschließend die Ausgabekonsole ansehen, in der die beiden Befehle erscheinen sollten.

Was ist mit der "Part::Box", könnten Sie sich nun fragen? Woher kann ich wissen, welche anderen Objekte eingefügt werden können? Dies funktioniert mit folgendem Befehl:

Nun erkunden wir die Inhalte unseres Würfels:

Man sieht sofort einige interessante Dinge, wie z.B.:

Dieser Befehl zeigt die aktuelle Höhe des Würfels an. Versuchen wir nun, diesen Wert zu ändern:

Wenn Sie den Würfel mit der Maus auswählen, dann sehen Sie in der Combo-Ansicht im Reiter "Daten" ebenfalls diese Höhe. Alle Eigenschaften eines FreeCAD-Objektes, die dort erscheinen (und außerdem im Reiter "Ansicht", später mehr dazu), können direkt über die Python-Konsole durch Angabe des Namens gelesen und geändert werden, genauso wie wir es mit der Höhe getan haben. Versuchen Sie die anderen Maße des Würfels auf diesem Wege zu ändern!

Vektoren und Platzierungen
Vektoren sind ein fester Bestandteil jeder 3D-Anwendung. Ein Vektor ist dabei eine Liste von Zahlen (x,y,z), die einen Ort im dreidimensionalen Raum beschreiben. Mit Vektoren sind verschiedene mathematische Operationen möglich, wie z.B. Addition, Subtraktion, Projektion (Skalarprodukt) und vieles mehr. In FreeCAD funktionieren Vektoren wie folgt:

Ein wichtiges Merkmal von Objekten in FreeCAD ist ihr Ort. Jedes Objekt besitzt Attribute, die seinen Ort (Base) und seine Ausrichtung (Rotation) angeben. Diese Attribute lassen sich leicht ändern, um beispielsweise das Objekt zu bewegen:

Bevor wir weitermachen können, müssen Sie erst noch einige wichtige Konzepte verstehen.

App und GUI
FreeCAD wurde von Anfang an als Kommandozeilen-Anwendung konzipiert, d.h. ohne notwendige Benutzeroberfläche. Als Folge davon ist fast alles zwischen einer "geometrischen" Komponente und einer "visuellen" Komponente aufgeteilt. Wenn man im Kommandozeilenmodus arbeitet, dann ist der geometrische Teil vorhanden, aber der visuelle Teil deaktiviert. Fast jedes Objekt in FreeCAD besteht deshalb aus zwei Teilen, einem Object und einem ViewObject (Objektansicht).

Um dieses Konzept besser zu verstehen, sollten Sie sich das Würfel-Objekt genauer ansehen. Seine geometrischen Eigenschaften (Maße, Ort, usw.) sind im object gespeichert, während seine visuellen Eigenschaften (Farbe, Liniendicke, usw.) im viewobject enthalten sind. Diese Aufteilung entspricht den beiden Reitern "Data" und "View" in der Combo-Ansicht. Das viewobject eines Objektes kann wie folgt angesprochen werden:

Now you can also change the properties of the "View" tab:

When you start FreeCAD, the python console already loads 2 base modules: FreeCAD and FreeCADGui (which can also be accessed by their shortcuts App and Gui). They contain all kinds of generic functionality to work with documents and their objects. To illustrate our concept, see that both FreeCAD and FreeCADGui contain an ActiveDocument attribute, which is the currently opened document. FreeCAD.ActiveDocument and FreeCADGui.ActiveDocument are not the same object. They are the two components of a FreeCAD document, and they contain different attributes and methods. For example, FreeCADGui.ActiveDocument contains ActiveView, which is the currently opened 3D view

Modules
Now, you must be wondering, what, other than "Part::Box", can I do? The FreeCAD base application is more or less an empty container. Without its modules, it can do little more than create new, empty documents. The true power of FreeCAD is in its faithful modules. Each of them adds not only new workbenches to the interface, but also new python commands and new object types. As a result, several different or even totally incompatible object types can coexist in the same document. The most important modules in FreeCAD, that we'll look at in this tutorial, are Part, Mesh, Sketcher or Draft.

Sketcher and Draft both use the Part module to create and handle their geometry, which are BRep while Mesh is totally independent, and handles its own objects. More about that below.

You can check all the available base object types for the current document like this:

The different FreeCAD modules, although they added their object types to FreeCAD, are not automatically loaded in the python console. This is to avoid having a very slow startup. Modules are loaded only when you need them. So, for example, to explore what's inside the Part module:

But we'll talk more about the Part module below.

By now, you know a bit more about the different modules of FreeCAD: The core modules (FreeCAD, FreeCADGui), and the workbenches modules (Part, Mesh, Sketcher). The other important modules are the 3d scene module (pivy) and the interface module (pyside), we'll talk about them too below.

Now it's time to explore a bit deeper the important ones, which are the workbench modules.

Mesh
Meshes are a very simple kind of 3D objects, used for example by Sketchup, Blender or 3D studio Max. They are composed of 3 elements: points (also called vertices), lines (also called edges) and faces. In many applications, FreeCAD included, faces can have only 3 vertices. But of course nothing prevents you from having a bigger plane face made of several coplanar triangles.

Meshes are simple, this can be a bad thing, but for many applications such as those mentioned above, it turns to be an advantage, because they are so simple that you can easily have millions of them in a single document. In FreeCAD, though, they have less use, and are mostly there so you can import objects in mesh formats (.stl, .obj) from other applications. It was also used extensively as the main test module in the first month of FreeCAD's life.

Mesh objects and FreeCAD objects are different things. You can see the FreeCAD object as a container for a Mesh object (like, we'll see below, for Part objects too). So in order to add a mesh object to FreeCAD, we must first create a FreeCAD object and a Mesh object, then add the Mesh object to the FreeCAD object:

This is a standard example, that uses the createSphere method to automatically create a sphere, but you can very well create custom meshes from scratch, by defining their vertices and faces.

Read more about mesh scripting...

Part
The Part Module is the most powerful module of the whole FreeCAD. It allows to create and manipulate BRep objects. This kind of object, unlike meshes, can have a wide variety of components. To resume a bit, Brep means Boundary Representation. which means that they are defined by their surfaces, which enclose and define an inner volume. These surface can be a variety of things, such as plane faces or very complex NURBS surfaces. They also carry the concept of volume.

The Part module is based on the powerful OpenCasCade library, which allows a wide range of complex operations to be easily performed on those objects, such as boolean operations, filleting, lofts, etc...

The Part module works the same way as the Mesh module: You create a FreeCAD object, a Part object, then add the Part object to the FreeCAD object:

The Part module (like the Mesh module) also has a shortcut that automatically creates a FreeCAD object and add a shape to it, so you can skip the 3 last lines above:

By exploring the contents of myshape, you will notice many interesting available subcomponents such as Faces, Edges, Vertexes, Solids or Shells, and a wide range of geometry operations such as cut (subtraction), common (intersection) or fuse (union). The Topological data scripting page explains all that in detail.

Read more about part scripting...

Draft
FreeCAD features many more modules, such as Sketcher or Draft, which also create Part objects, but add parameters to it, or even carry a whole new way to handle the Part geometry in them. Our box example above, is a perfect example of parametric object. All you need, to define the box, is to specify a couple of parameters, such as height, width and length. Based on those, the object will automatically calculate its Part shape. FreeCAD allows you to create such objects in python.

The Draft Module adds a couple of 2D parametric objects types (which are all Part objects) such as lines and circles, and also provides some generic functions that work not only on Draft-made objects, but on any Part object. To explore what is available, simply do:

Interface
The FreeCAD user interface is made with Qt, a powerful graphical interface system, responsible for drawing and handling all the controls, menus, toolbars, buttons around the 3D view. Qt provides a module, called PySide, which allows python to access and modify Qt interfaces, such as FreeCAD. Let's try to fiddle with the Qt interface and produce a simple dialog:

See that the dialog that appears has the FreeCAD icon in its toolbar, meaning that Qt knows that the order has been issued from inside the FreeCAD application. We can therefore easily directly manipulate any part of the FreeCAD interface.

Qt is a very powerful interface system, that allows you to do very complex things, but also has a couple of very easy-to use tools such as the Qt Designer with which you can design dialogs graphically and then add them to the FreeCAD interface with a couple of lines of python.

Read more about PySide here...

Macros
Now that you have a good understanding of the basics, where are we going to keep our python scripts, and how are we going to launch them easily from FreeCAD? There is an easy mechanism for that, called Macros. A macro is simply a python script, that can then be added to a toolbar and be launched from a simple mouse click. FreeCAD provides you with a simple text editor (Macro -> Macros -> Create) where you can write or paste scripts. Once it is done, the Tools -> Customize -> Macros allow you to define a button for it, that can be added to toolbars.

Now you are ready for more in-depth FreeCAD scripting. Head on to the Power users hub!