Python scripting tutorial/de

Introduction
Python ist eine Programmiersprache, sehr einfach zu bedienen und sehr schnell zu erlernen. Sie ist quelloffen, plattformübergreifend und kann für eine Vielzahl von Aufgaben allein verwendet werden, von der Programmierung einfacher Shell Skripte bis hin zu sehr komplexen Programmen. Aber eine der am weitesten verbreiteten Anwendungen ist die Skriptsprache, da sie leicht in andere Anwendungen integriert werden kann. Genau so wird es in FreeCAD verwendet. Von der Python Konsole oder von deinen benutzerdefinierten Skripten aus kannst du FreeCAD steuern und es sehr komplexe Aktionen ausführen lassen, für die es noch kein Werkzeug für die grafische Benutzeroberfläche gibt.

Zum Beispiel aus einem Python Skript, kannst Du:
 * neue Objekte erstellen
 * bestehende Objekte ändern
 * die 3D Darstellung dieser Objekte ändern
 * die FreeCAD Schnittstelle modifizieren

Es gibt auch mehrere Möglichkeiten, Python in FreeCAD zu verwenden:
 * Aus dem FreeCAD Python Interpreter, wo du einfache Befehle wie in einer "Kommandozeile" Stilschnittstelle ausgeben kannst.
 * Aus Makros, die eine bequeme Möglichkeit darstellen, ein fehlendes Werkzeug schnell zur FreeCAD Oberfläche hinzuzufügen.
 * Aus externen Skripten, mit denen man viel komplexere Dinge programmieren kann, wie z.B. ganze Arbeitsbereiche.

In diesem Tutorial werden wir an ein paar einfachen Beispielen arbeiten, um dir den Einstieg zu erleichtern, aber es gibt auch viel mehr zu diesem Thema Dokumentation über Python Skripting auf diesem Wiki. Wenn du völlig neu in Python bist und verstehen willst, wie es funktioniert, haben wir auch eine grundlegende Einführung in Python.

"'Wichtig!' Bevor Du mit dem Python-Skripting fortfährst, gehe zum und aktiviere 2 Kästchen: Dann gehe zu  und wähle: Das erspart Dir eine Menge Ärger!
 * Interne Python-Meldungen auf Ausgabefenster umleiten
 * Interne Python-Fehlermeldungen auf Ausgabefenster umleiten
 * Ausgabefenster

Python Code schreiben
Es gibt zwei einfache Wege, Python Code in FreeCAD zu schreiben: Über die Python Konsole (verfügbar im Menü Ansicht → Paneele → Python Konsole) oder über den Makro Editor (Werkzeuge → Makros). In der Konsole schreibst Du nacheinander Python Befehle, die ausgeführt werden, wenn Du die Eingabetaste drückst, während die Makros ein komplexeres Skript aus mehreren Zeilen enthalten können, das erst bei der Ausführung des Makros ausgeführt wird.

There are two ways to write Python code in FreeCAD. In the Python console (select from the menu) or in the Macro editor (select  from the menu). In the console you write Python commands one by one, executing them by pressing, while macros can contain more complex code made up of several lines, executed only when the macro is executed.



In diesem Tutorial wirst Du 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 leeres Dokument zu erstellen:

Let's start by creating a new empty document:

Wenn Du dies in die Python Konsole eingibst, wirst Du 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 Du newDocument auswählst, sieh Dir die anderen verfügbaren Optionen an.



Nun wird unser neues Dokument erstellt. Dies ist ähnlich wie das Drücken der Schaltfläche "Neues Dokument" in der Symbolleiste. Tatsächlich tun die meisten Schaltflächen in FreeCAD nichts anderes, als ein oder zwei Zeilen Python Code auszuführen. Noch besser, Du kannst eine Option in auf "Skriptbefehle in der Python Konsole anzeigen" setzen. Dies wird in der Konsole den gesamten Python Code ausgeben, der beim Drücken von Knöpfen ausgeführt wird. Sehr nützlich, um zu lernen, wie man Aktionen in Python reproduziert.

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

Erkunde die verfügbaren Möglichkeiten. Üblicherweise sind Namen, die mit einem Großbuchstaben beginnen, Attribute, sie enthalten einen Wert, während Namen, die mit einem Kleinbuchstaben beginnen, Funktionen (auch Methoden genannt) sind, sie "tun etwas". Namen, die mit einem Unterstrich beginnen, sind normalerweise für die interne Arbeit des Moduls da, und Du solltest dich nicht um sie kümmern. Lasse uns eine der Methoden verwenden, um ein neues Objekt zu unserem Dokument hinzuzufü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:

Siehst du? Jetzt ist unsere Box erschienen! Viele der Schaltflächen, mit denen in FreeCAD Objekte hinzugefügt werden, tun eigentlich 2 Dinge: das Objekt hinzufügen und neu berechnen. Wenn Du oben die Option "lich zwei Dinge: das Objekt einfügen und das Dokument neuberechnen lassen. Wenn Du oben die Option ''Zeige Skript Befehle in Pythonkonsole" eingeschaltet hast, versuche nun, eine Kugel mit der GUI Schaltfläche hinzuzufügen, Du wirst sehen, wie die beiden Zeilen Python Code nacheinander ausgeführt werden.

Nun erkunden wir die Inhalte unseres Würfels:

Du wirst sofort einige sehr interessante Dinge sehen, wie zum Beispiel:

Dadurch wird die aktuelle Höhe unseres Würfels ausgegeben. Versuchen wir nun, das zu ändern:

Wenn Sie den Würfel mit der Maus auswählen, dann sehen Sie in der Combo-Ansicht in der Registerkarte "Daten" ebenfalls diese Höhe. Alle Eigenschaften eines FreeCAD-Objektes, die dort erscheinen (und außerdem in der Registerkarte "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).

FreeCAD has been designed so that it can also be used without its user interface, as a command-line application. Almost every object in FreeCAD therefore consists of two parts: an, its "geometry" component, and a , its "visual" component. When you work in command-line mode, the geometry part is present, but the visual part is disabled.

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 Registerkarten "Daten" und "Ansicht" in der Combo-Ansicht. Das viewobject eines Objektes kann wie folgt angesprochen werden:

Damit lassen sich auch die Eigenschaften der Registerkarte "Ansicht" ändern:

Wenn Sie FreeCAD starten, dann lädt die Python-Konsole automatisch die beiden Module FreeCAD und FreeCADGui (die in der Konsole auch über ihre Abkürzungen App und Gui angesprochen werden können). Sie enthalten allerlei allgemeine Funktionen zum Arbeiten mit Dokumenten und Objekten. Um unser Konzept zu illustrieren, beachten Sie, dass sowohl FreeCAD als auch FreeCADGui ein Attribut namens ActiveDocument enthalten, das das momentan geöffnete Dokument angibt. Dabei sind FreeCAD.ActiveDocument and FreeCADGui.ActiveDocument jedoch nicht dasselbe Objekt. Sie sind stattdessen zwei Komponenten eines FreeCAD-Dokumentes, die verschiedene Attribute und Methoden enthalten. Beispielsweise enthält nur FreeCADGui.ActiveDocument eine Eigenschaft namens ActiveView, die die momentan geöffnete 3D-Ansicht beschreibt.

Module
Nun fragst du dich sicher, was außer "Part::Box" kann ich noch tun ? Die FreeCAD Basisanwendung ist mehr oder weniger ein leerer Behälter. Ohne seine Module kann es kaum mehr tun, als neue, leere Dokumente erstellen. Die wahre Stärke von FreeCAD liegt in seinen zuverlässigen Modulen. Jedes von ihnen fügt nicht nur neue Arbeitsbereiche zur Benutzeroberfläche hinzu, sondern auch neue Python Befehle und neue Objekttypen. Als Ergebnis können mehrere unterschiedliche oder sogar völlig inkompatible Objekttypen in einem Dokument koexistieren. Die wichtigsten Module in FreeCAD, die wir in diesem Tutorial betrachten werden, sind Part, Netz, Skizzierer und Entwurf.

The true power of FreeCAD lies in its faithful modules. The FreeCAD base application is more or less an empty container. Without its modules it can do little more than create new, empty documents. Each module not only adds new workbenches to the interface, but also new Python commands and new object types. As a result several different, and 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 and Draft.

Skizzierer und Entwurf verwenden beide das Part Modul, um ihre Geometrie zu erzeugen und handzuhaben, die BRep ist, während Netz völlig unabhängig ist und seine eigenen Objekte handhabt. Mehr dazu weiter unten.

Du kannst alle verfügbaren Basisobjekttypen für das aktuelle Dokument folgendermaßen prüfen:

Die verschiedenen FreeCAD Module werden, obwohl sie ihre Objekttypen zu FreeCAD hinzugefügt haben, nicht automatisch in die Python Konsole geladen. Dies soll einen sehr langsamen Start vermeiden. Die Module werden nur dann geladen, wenn Du sie benötigst. Zum Beispiel, um zu erkunden, was sich innerhalb des Part Moduls befindet:

Aber wir werden weiter unten mehr über das Part Modul sprechen.

Netz
Polygonnetze (engl. Meshes) sind eine sehr einfache Art von 3D Objekten, die z.B. von Sketchup (Software), Blender (Software) oder 3ds Max verwendet werden. Sie werden gebildet aus 3 Elementen: Punkte (auch Knoten genannt), Linien (auch Kanten genannt) und Flächen. In vielen Anwendungen, einschließlich FreeCAD, können Flächen nur 3 Eckpunkte haben. Natürlich hindert Dich nichts daran, eine größere ebene Fläche aus mehreren nebeneinander liegenden Dreiecken zu haben.

Polygonnetze sind einfach, aber weil sie einfach sind, kannst Du leicht Millionen von ihnen in einem einzigen Dokument haben. Allerdings sind sie in FreeCAD weniger nützlich und meist vorhanden, so dass Du Objekte in Netzformaten (.stl, .obj) aus anderen Anwendungen importieren kannst. Das Netzmodul wurde auch im ersten Monat des FreeCAD Lebens ausgiebig als Haupttestmodul verwendet.

Netzobjekte und FreeCAD Objekte sind unterschiedliche Dinge. Du kannst das FreeCAD Objekt als einen Behälter für ein Netzobjekt betrachten (und wie wir unten sehen werden, auch für Part Objekte). Um also ein Netz Objekt zu FreeCAD hinzuzufügen, müssen wir zuerst ein FreeCAD Objekt und ein Mesh Objekt erstellen und dann das Netz Objekt zum FreeCAD Objekt hinzufügen:

Dies ist ein Standardbeispiel, das die createSphere Methode verwendet, um automatisch eine Kugel zu erstellen, aber Du kannst auch benutzerdefinierte Netze von Grund auf neu erstellen, indem Du ihre Knoten und Flächen definierst.

Lies mehr über Netz Skripten...

Part
Das Part Arbeitsbereich ist das leistungsfähigste Modul im gesamten FreeCAD. Es erlaubt Dir BRep Objekte zu erstellen und zu verändern. Diese Art von Objekten kann, im Gegensatz zu Netzen, eine Vielzahl von Komponenten haben. Brep steht für Begrenzungsflächenmodell (engl.: Boundary Representation), was bedeutet, dass Brep Objekte durch ihre Oberflächen definiert werden; diese Oberflächen umschließen und definieren ein Innenvolumen. Eine Oberfläche kann eine Vielzahl von Dingen sein, wie z.B. ebene Flächen oder sehr komplexe NURBS Oberflächen.

The Part Module is the most powerful module in the whole of FreeCAD. It allows you to create and manipulate BRep objects. BRep stands for "Boundary Representation". A BRep object is defined by surfaces that enclose and define an inner volume. Unlike meshes, BRep objects can have a wide variety of components from planar faces to very complex NURBS surfaces.

Das Part-Modul basiert auf der leistungsstarken OpenCasCade Bibliothek, die es ermöglicht, eine Vielzahl von komplexen Operationen auf diesen Objekten einfach durchzuführen, wie z.B. boolesche Operationen, Filetierung, Ausformungen, usw.

Das Part-Modul arbeitet auf dieselbe Weise wie das Netz Modul: Man erzeugt ein FreeCAD Objekt, ein Part Objekt, danach fügt man das Part Objekt zum FreeCAD Objekt hinzu:

Das Part Modul (wie das Netz Modul) hat auch ein Tastaturkürzel, das automatisch ein FreeCAD Objekt erstellt und eine Form hinzufügt, so dass du die letzten drei Zeilen oben verkürzen kannst auf:

Beim erforschen der Inhalt von myshape, wirst Du viele interessante Unterkomponenten wie Flächen, Kanten, Knoten, Festkörper und Schalen, und eine weite Bandbreite von Geometrieoperationen wie Schnitt (Subtraktion), Gemein (Schnittpunkt) oder Verschmelzung (Vereinigung) bemerken. Die Topologisches Daten Skripten Seite erklärt all das im Detail.

Lies mehr über Part Skripten...

Entwurf
FreeCAD bietet noch viele weitere Module, wie Skizzierer und Entwurf, die ebenfalls Teilobjekte erzeugen. Diese Module fügen zusätzliche Parameter zu den erzeugten Objekten hinzu oder implementieren sogar eine völlig neue Art und Weise, die Teilegeometrie in ihnen zu handhaben. Unser obiges Box Beispiel ist ein perfektes Beispiel für ein parametrisches Objekt. Alles was Du zur Definition der Box benötigst, ist die Angabe der Parameter Höhe, Breite und Länge. Basierend auf diesen Parametern berechnet das Objekt automatisch seine Teileform. FreeCAD erlaubt es Dir Erzeuge solche Objekte in Python.

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

Das Entwurfsmodul fügt parametrische 2D Objekttypen (die alle Part Objekte sind) wie Linien und Kreise hinzu und bietet auch einige grundlegende Funktionen, die nicht nur auf Entwurfsobjekte, sondern auf jedes Part Objekt wirken. Um zu erkunden, was verfügbar ist, mache einfach:

Benutzeroberfläche
Die Benutzeroberfläche von FreeCAD ist mit Qt, einer leistungsstarken grafischen Schnittstellensystem, erstellt worden, das für das Zeichnen und die Handhabung aller Bedienelemente, Menüs, Werkzeugleisten und Schaltflächen rund um die 3D Ansicht verantwortlich ist. Qt stellt ein Modul, PySide, zur Verfügung, welches Python erlaubt, auf die Qt Schnittstellen wie FreeCAD zuzugreifen und zu verändern. Lass uns versuchen, mit der Qt Schnittstelle zu tüfteln und einen einfachen Dialog zu erzeugen:

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

Beachte, dass der erscheinende Dialog das FreeCAD Symbol in seiner Werkzeugleiste hat, was bedeutet, dass Qt weiß, dass der Auftrag aus der FreeCAD Anwendung heraus erteilt wurde. Wir können daher leicht jeden Teil der FreeCAD Schnittstelle direkt manipulieren.

Qt ist ein sehr mächtiges Schnittstellensystem, das es dir erlaubt, sehr komplexe Dinge zu tun. Es hat auch einige einfach zu benutzende Werkzeuge wie den Qt Designer, mit dem du Dialoge grafisch entwerfen kannst und sie dann mit ein paar Zeilen Python Code zur FreeCAD Oberfläche hinzufügen kannst.

Erfahre hier mehr über PySide...

Makros
Nun, da Du ein gutes Verständnis der Grundlagen hast, wo werden wir unsere Python Skripte aufbewahren und wie werden wir sie einfach von FreeCAD aus starten? Dafür gibt es einen einfachen Mechanismus, genannt Makros. Ein Makro ist einfach ein Python Skript, das zu einer Werkzeugleiste hinzugefügt und per Mausklick gestartet werden kann. FreeCAD bietet dir einen einfachen Texteditor (Makro → Makros → Erstellen), in dem du Skripte schreiben oder einfügen kannst. Sobald das Skript fertig ist, verwende Werkzeuge → Anpassung → Makros, um eine Schaltfläche dafür zu definieren, die zu den Symbolleisten hinzugefügt werden kann.

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 inside FreeCAD? There is an easy mechanism for that, called Macros. A macro is a Python script that can be added to a toolbar and launched via a mouse click. FreeCAD provides you with a simple text editor where you can write or paste scripts. Once the script is done, use to define a button for it that can be added to toolbars.

Jetztbist Du bereit für eine vertiefte FreeCAD Skripterstellung. Gehe weiter zum Verteiler für Erfahrene Anwender!