FreeCAD Scripting Basics

From FreeCAD Documentation
Jump to: navigation, search
This page is a translated version of the page FreeCAD Scripting Basics and the translation is 98% complete.

Outdated translations are marked like this.
Other languages:
čeština • ‎Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎italiano • ‎polski • ‎português • ‎română • ‎русский • ‎svenska • ‎Türkçe • ‎中文(中国大陆)‎

Python scripting in FreeCAD

FreeCAD ist von Grund auf von Python-Skripten gesteuert. Fast alle Teile von FreeCAD wie die Schnittstelle, der Szene-Inhalt, und sogar die Darstellung dieser Inhalte in den 3D-Ansichten sind vom eingebauten Python-Interpreter oder mittels Ihrer eigenen Skripte zugänglich. Infolgedessen ist FreeCAD wahrscheinlich eine der am weitesten anpassbaren Technikanwendungen auf dem Markt.

In seinem aktuellen Zustand hat jedoch FreeCAD sehr wenige "native" Befehle, um auf Ihre 3D-Objekten zu interagieren, vor allem, weil es ist immer noch im frühen Stadium der Entwicklung ist, sondern auch weil die Philosophie dahinter mehr ist, um eine Plattform für die CAD-Entwicklung zur Verfügung zu stellen, als eine spezifische Gebrauch-Anwendung. Aber die Leichtigkeit des Python-Scripting innerhalb FreeCAD ist ein schneller Weg, um neue Funktionalität durch "Power User" zu entwickeln, Benutzer, die typischerweise ein bisschen Python-Programmierung kennen. Python ist eine der populärsten Interpreter-Sprachen, und weil es im allgemeinen als leicht zu erlernen angesehen wird, können auch Sie schon bald Ihre eigenen FreeCAD "Power User"-Skripte erstelen.

Wenn Sie nicht mit Python vertraut sind, empfehlen wir Ihnen, nach Tutorien im Internet zu suchen, um so einen kurzen Blick auf seine Struktur zu bekommen. Python ist eine sehr einfache Sprache zu lernen, vor allem, weil es innerhalb eines Interpreters ausgeführt werden kann, wobei von einfachen Befehlen bis zu vollständigen Programmen alles dynamisch ausgeführt werden kann. Wenn Sie das Fenster mit der Aufschrift "Report-Ansicht", wie unten dargestellt nicht sehen, können Sie es unter Ansicht → Paneele → Berichtsansicht aktivieren, um den Interpreter anzeigen zu lassen.

Der Interpreter

Über den Interpreter, können Sie auf alle Ihre systeminstallierten Python-Module zugreifen, sowie die eingebaute FreeCAD Module und alle zusätzlichen Module, die Sie später installiert haben. Der folgende Screenshot zeigt den Python-Interpreter:

The FreeCAD Python interpreter

Im Interpreter kann man Python-Code ausführen und die verfügbaren Klassen und Funktion durchsuchen. FreeCAD stellt einen sehr handlichen Klassenbrowser für die Erforschung Ihrer neuen FreeCAD Welt zur Verfügung: Wenn Sie den Namen einer bekannten Klasse gefolgt von einem Punkt tippen (das heißt, Sie wollen etwas von dieser Klasse hinzufügen), öffnet sich ein Klassenbrowser-Fenster, wo Sie zwischen verfügbaren Unterklassen und Methoden navigieren können. Wenn Sie etwas auswählen, wird ein verbundener Hilfstext(falls bestehend) gezeigt:

The FreeCAD class browser

Als Anfang tippen wir '"App."' oder '"Gui."' ein und sehen was passiert. Ein weiterer Python-üblicher Weg zur Erkundung der Inhalte der Module und Klassen ist es, den verwenden. print dir() -Befehl zu nutzen. Zum Beispiel, das Schreiben von print dir() wird alle in FreeCAD zurzeit geladenen Module auflisten. print dir(App) wird Ihnen alles innerhalb des App Moduls anzeigen, usw.

Eine weitere nützliche Funktion des Interpreters ist die Möglichkeit, zurück zu gehen in Kommando-History und eine Zeile des Codes wiederzubekommen, den Sie bereits früher tippten. Um in der zu navigieren, benutzen Sie einfach STRG + HOCH oder STRG + RUNTER.

Mit der rechten Maustaste in der Interpreter-Fenster haben Sie auch einige andere Optionen, wie z. B. Kopie der gesamten Geschichte (nützlich, um hier etwas experimentieren, dann machen Sie eine vollständige Skript davon), oder fügen Sie Dateinamen mit dem ganzen Pfad ein.

Python Hilfe

Im FreeCAD-Hilfsmenü finden Sie einen Eintrag mit der Bezeichnung "Python-Hilfe", der ein Browser-Fenster mit einem vollständigen Überblick in Echtzeit generierter Dokumentation aller Python-Module, die im FreeCAD Interpreter zur Verfügung stehen, einschließlich der Python- und FreeCAD eingebauten Module, systeminstallierten Module, und FreeCAD's zusätzlicher Module. Die vorhandenen Dokumentation hängt davon ab, wie viel Aufwand jeder Modul-Entwickler bei der Dokumentation seines Code einsetzt, aber in der Regel haben Python-Module einen Ruf als ziemlich gut dokumentiert. Damit dieses Dokumentationssystem funktioniert, muss Ihr FreeCAD Fenster offen sein.

Eingebaute Module

Da FreeCAD dafür entworfen ist, ohne Graphische Benutzerschnittstelle geführt zu werden, wird fast seine ganze Funktionalität in zwei Gruppen getrennt: Kernfunktionalität, genannt App, und Gui Funktionalität, genannt Gui. Also sind unsere beiden wichtigsten eingebauten FreeCAD Module die, namens App und GUI. Auf diese zwei Module kann auch von Scripten außerhalb des Interpreters, durch die jeweiligen Namen von FreeCAD und FreeCADGui zugegriffen werden.

  • Im App-Modul, finden Sie alles im Zusammenhang mit der Anwendung selbst, wie Methoden zum Öffnen oder Schließen von Dateien, und zu den Dokumenten, wie z.B. die Einstellung des aktiven Dokuments oder wie sie ihre Inhalte auflisten.
  • Im GUI-Modul, werden Sie Werkzeuge für den Zugriff und das Management GUI-Elemente zu finden, wie die Arbeitsbereiche und ihre Symbolleisten, und, noch interessanter, die grafische Darstellung aller Inhalte in FreeCAD.

Die Auflistung des ganzen Inhalts jener Module ist eine kontraproduktive Aufgabe, da sie ziemlich schnell entlang der FreeCAD Entwicklung wachsen. Aber die zwei zur Verfügung gestellten Browsing-Tools(der Klassenbrowser und die Python-Hilfe) sollten Ihnen, jederzeit, eine komplette und aktuelle Dokumentation dieser Module geben.

Die App und GUI-Objekte

Wie gesagt, in FreeCAD, wird alles zwischen Kern und Darstellung getrennt. Dazu gehören auch die 3D-Objekte. Sie können auf die Definition von Eigenschaften von Objekten (so genannte Features in FreeCAD) über das App Modul zugreifen, und die Art ändern, wie sie auf dem Schirm über das Gui Modul dargestellt werden. Zum Beispiel hat ein Würfel Eigenschaften, um ihn zu definieren, wie Breite, Länge, Höhe, die in einem App-Objekt gespeichert sind, und Darstellung-Eigenschaften, wie Flächen-Farbe, Zeichnen-Modus, die in einem entsprechenden GUI-Objekt gespeichert sind.

Diese Handlungsweise ermöglicht eine sehr breite Palette von Anwendungen, wie mit Algorithmen nur aem Teil der Definition von Features zu arbeiten, ohne die Notwendigkeit, sich um den visuellen Teil kümmern zu müssen, oder sogar den Inhalt des Dokumentes zu nichtgraphischen Anwendung, wie Listen, Spreadsheets, oder Element-Analysen umzuleiten.

Für jedes App-Objekt in Ihrem Dokument, existiert ein entsprechendes GUI-Objekt. Das Dokument selbst hat tatsächlich auch App, und ein GUI-Objekt. Dies ist natürlich nur dann gültig, wenn Sie FreeCAD mit seiner vollen Schnittstelle starten. In der Kommandozeilen-Version besteht keine GUI, so dass nur App-Objekte verfügbar sind. Beachten Sie, dass der GUI-Teil der Objekte jedemal neu generiert wird, sobald ein ein App-Objekt markiert wird als "neu zu berechnen"(Zum Beispiel, wenn sich einer ihrer Parameter ändert), so dass Änderungen, die Sie direkt am GUI-Objekt vorgenommen haben, verloren gehen können.

Um auf den App Teil von etwas zuzugreifen, tippen Sie:

myObject = App.ActiveDocument.getObject("ObjectName")

wobei "ObjectName" der Name Ihres Objektes ist. Sie können auch eingeben:

myObject = App.ActiveDocument.ObjectName

Um den GUI-Teil des gleichen Objekts zuzugreifen, geben Sie ein:

myViewObject = Gui.ActiveDocument.getObject("ObjectName")

wobei "ObjectName" der Name Ihres Objektes ist. Sie können auch eingeben:

myViewObject = App.ActiveDocument.ObjectName.ViewObject

Wenn wir kein GUI (zum Beispiel sind wir im Kommandozeilen-Modus) haben, wird die letzte Zeile None zurückgeben.

Die Dokument-Objekte

In FreeCAD wird Ihre gesamte Arbeit in Dokumenten hinterlegt. Ein Dokument enthält Ihre Geometrie und kann zu einer Datei gespeichert werden. Es können auch mehrere Dokumente zur gleichen Zeit geöffnet werden. Das Dokument, wie auch die darin enthalten Geometrie, hat App und GUI-Objekte. App-Objekt enthält Ihre tatsächliche Geometrie Definitionen, während dasdie GUI-Objekt die verschiedenen Ansichten von Ihrem Dokument enthält. Sie können mehrere Fenster öffnen, jedes, um Ihre Arbeit mit einem anderen Zoomfaktor oder Ansicht zu betrachten. Diese Ansichten sind alle Teil des GUI-Objekts Ihres Dokuments.

Für den Zugriff auf den App-Teil des aktuell geöffneten (aktiv) Dokuments, schreiben Sie:

myDocument = App.ActiveDocument

Um ein neues Dokument zu erstellen, eingeben:

myDocument = App.newDocument("Document Name")

Für den Zugriff auf den GUI-Teil des aktuell geöffneten (aktiv) Dokuments, geben Sie ein:

myGuiDocument = Gui.ActiveDocument

Um auf die gegenwärtige Ansicht zuzugreifen, tippen Sie:

myView = Gui.ActiveDocument.ActiveView

Das Verwenden zusätzlicher Module

Die FreeCAD und FreeCADGui Module sind ausschließlich Verantwortlich für das Erstellen und Verwalten von Objekten in einem FreeCAD Dokument. Sie haben nichts zu tun, mit dem Erstellen oder Ändern von Geometrie. Das liegt daran, dass die Geometrie aus mehreren Typen bestehen kann, somit werden sie durch zusätzliche Module verwaltet, jeweils zuständig für die Verwaltung eines bestimmten Geometrie-Typs. Zum Beispiel, Part Modul verwendet den OpenCascade Kern, und kann daher die Erstellung und Bearbeitung von B-rep Geometrien behandeln, wofür OpenCascade entwickelt wurde. Das Mesh-Modul ist in der Lage, Mesh-Objekte zu erzeugen und zu modifizieren. Auf diese Weise ist FreeCAD in der Lage, eine Vielzahl von Objekttypen, die alle im selben Dokument koexistieren können, zu handhaben, und neue Arten könnten in der Zukunft leicht hinzugefügt werden.

Erzeugen von Objekten

Jedes Modul hat seine eigene Art und Weise seiner Geometrie zu behandeln, aber eines können sie in der Regel alle, neue Objekte im Dokument erzeugen. Aber das FreeCAD Dokument ist sich auch der verfügbaren, durch die Module zur Verfügung gestellten Objektarten bewusst:

FreeCAD.ActiveDocument.supportedTypes()

listet Ihnen alle möglichen Objekte, die Sie erstellen können. Zum Beispiel, erstellen wir ein Mesh (behandelt durch das Mesh-Modul) und einen Teil (behandelt durch das Part-Modul):

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

Das erste Argument ist die Objektart, das zweite der Name desObjekts. Unsere beiden Objekte sehen fast gleich aus: Sie enthalten noch keine Geometrie, und die meisten ihrer Eigenschaften sind die selben, wenn Sie sie mit dir (myMesh) und dir (myPart) untersuchen. Bis auf eines, myMesh hat eine "Mesh"-Eigenschaft und "Part" hat eine "Shape"-Eigenschaft(Gestalt). Das ist, wo die Mesh-und Part-Daten gespeichert sind. Zum Beispiel erstellen wir ein Teil Würfel und speichern Sie es in unserem MyPart Objekt:

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

Falls Sie versuchen, den Würfel innerhalb der Mesh-Eigenschaft des Objekts myMesh zu speichern, wird ein Fehler gemeldet, da es sich um den falschen Typ handelt. Das passiert, weil die Eigenschaften so vorgegeben sind, das sie nur einen bestimmten Typ speichern. In der "myMesh"-Mesh-Eigenschaft können Sie nur speichern, was mit dem Mesh-Modul erstellt wurde. Beachten Sie, dass die meisten Module auch eine Verknüpfung haben, über die sie ihre Geometrie zum Dokument hinzufügen:

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

Ändern von Objekten

Ändern eines Objekts geschiet auf dieselbe Weise:

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

Wollen jetzt wir die Form in eine größere ändern:

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

Abfragen von Objekten

Sie können jederzeit den Typ eines Objekts wie folgt ermitteln:

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

der feststellen, ob ein Objekt von einer der Grunformen abgeleitet wurde(Part Feature, Mesh Feature, etc):

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

Jetzt können Sie wirklich anfangen, mit FreeCAD zu spielen! Um herauszufinden, was Sie mit dem Part Modul tun können, Lesen Sie die Part scripting-Seite, oder die Mesh Skripting in FreeCAD-Seite für die Arbeit mit dem Mesh-Modul. Beachten Sie, dass, obwohl das Teil- und Mesh-Modul die vollständigsten und am weitesten verbreitetet sind, haben andere Module wie das Draft-Modul auch scripting-APIs, die für Sie nützlich sein können. Eine vollständige Liste der einzelnen Module und ihrer verfügbaren Tools finden Sie im Category:API-Abschnitt.