Scripted objects/de

Introduction
Außer den Standardobjektarten wie Anmerkungen, Mesh-und Teile-Objekten, bietet FreeCAD auch die erstaunliche Möglichkeit an, 100%ige python Skript Objekte zu erstellen, genannt Python Funktionen Diese Objekte verhalten sich genau so wie jedes andere Objekt in FreeCAD und werden automatisch in Dateien gespeichert und wiederhergestellt, wenn speichern/laden ausgeführt wird.

Eine Besonderheit muss verstanden werden, jene Gegenstände werden in FreeCAD FcStd Dateien gespeichert mit python's cPickle-modul. Das Modul bildet aus einem Python-Objekt einen String, der dann einer gespeicherten Datei hinzugefügt werden kann. Beim Dateiöffnen, verwendet das cPickle Modul diese Zeichenfolge, um das ursprüngliche Objekt neu zu erstellen, vorausgesetzt, es hat den Zugriff auf den Quellcode, welcher das Objekt erstellt hat. Dies bedeutet, dass wenn Sie ein solches benutzerdefiniertes Objekt speichern und öffnen es auf einer Maschine, wo der Python-Code, der das Objekt erzeugt hat, ist nicht vorhanden, wird das Objekt nicht neu erstellt werden.

Python-Features folgen der gleichen Regeln wie alle FreeCAD Features: sie werden in App und GUI Teile getrennt. Der App Teil, das Document Object, definiert die Geometrie unseres Objektes, während der GUI-Teil, das View-Objekt, definiert, wie das Objekt auf dem Bildschirm gezeichnet wird. Das View-Objekt, ist wie jedes andere FreeCAD Feature nur verfügbar, wenn Sie FreeCAD in seiner eigenen GUI ausführen. Es gibt mehrere Eigenschaften und Methoden, die verfügbar sind, um Ihr Objekt zu erstellen. Eigenschaften muss von einem der in FreeCAD vordefinierten Typen sein, um im Eigenschafts-View-Fenster zu erscheinen, wo sie vom Benutzer editiert werden können.

Auf diese Weise sind FeaturePython-Objekte wirklich und völlig parametrisch. Sie können die Eigenschaften für den Gegenstand und sein ViewObjekt getrennt definieren.

Grundlegendes Beispiel
Das folgende Beispiel kann in der src/Mod/TemplatePyMod/FeaturePython.py-Datei gefunden werden, zusammen mit einigen anderen Beispielen:

Things to note
If your object relies on being recomputed as soon as it is created, you must do this manually in the function as it is not called automatically. This example does not require it because the method of the  class has the same effect as the  function, but the examples below rely on being recomputed before anything is displayed in the 3D view. In the examples, this is done manually with but in more complex scenarios you need to decide where to recompute either the whole document or the FeaturePython object.

This example produces a number of exception stack traces in the report view window. This is because the method of the  class is called each time a property is added in. When the first one is added, the Width and Height properties don't exist yet and so the attempt to access them fails.

An explanation of and  is in the forum thread obj.Proxy.Type is a dict, not a string.

Verfügbare Eigenschaften
Eigenschaften sind die wahren Bausteine von FeaturePython-Gegenständen. Durch ist der Benutzer im Stande, mit einem Objekt zu interagieren und es zu ändern. Nach dem Erstellen eines neuen FeaturePython-Objekts in Ihrem Dokument( a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), können eine Liste der verfügbaren Eigenschaften bekommen, indem Sie folgendes eingeben:

Sie werden eine Liste von verfügbaren Eigenschaften bekommen mit:

Beim Hinzufügen von Eigenschaften zu benutzerdefinierten Objekte, achten Sie bitte auf folgendes:


 * Verwenden Sie keine Zeichen "<" oder ">" in den Eigenschaftes-Beschreibungen (das würde den XML-Teil in der .Fcstd-Datei zerbrechen)
 * Eigenschaften werden alphabetisch in einer .fcstd Datei gespeichert. Wenn Sie eine Form("Shape") in Ihren Eigenschaften haben, wird jede Eigenschaft, deren Name in alphabetischen Reihenfolge nach "Shape" kommt, auch nach der Form geladen, was zu seltsamen Verhaltensweisen führen kann.

A complete list of property attributes can be seen in the PropertyStandard C++ header file. For instance, if you want to allow the user to enter only a limited range of values (e.g. using PropertyIntegerConstraint), in Python you will assign a tuple containing not only the property value, but also the lower and upper limit as well as the stepsize, as below:

Andere komplexere Beispiele
Dieses Beispiel macht von Part Module Gebrauch, um ein Oktaeder zu schaffen, erstellt dann seine coin-Darstellung mit pivy. Zuerst erstellen wir das Document-Objekt selbst:

wobei der mode als short int gesetzt werden kann als: 0 -- Standardmodus, Lesen und Schreiben 1 -- Nur-Lesen 2 -- Versteckt

The EditorModes are not set at FreeCAD file reload. This could to be done by the __setstate__ function. See http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072. By using the setEditorMode the properties are only read only in PropertyEditor. They could still be changed from python. To really make them read only the setting has to be passed directly inside the addProperty function. See http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 for an example.

Using the direct setting in the addProperty function, you also have more possibilities. In particular, an interesting one is mark a property as an output property. This way FreeCAD won't mark the feature as touched when changing it (so no need to recompute).

Example of output property (see also https://forum.freecadweb.org/viewtopic.php?t=24928):

The property types that can be set at last parameter of the addProperty function are: 0 -- Prop_None, No special property type 1 -- Prop_ReadOnly, Property is read-only in the editor 2 -- Prop_Transient, Property won't be saved to file 4 -- Prop_Hidden, Property won't appear in the editor 8 -- Prop_Output, Modified property doesn't touch its parent container 16 -- Prop_NoRecompute, Modified property doesn't touch its container for recompute

You can find these different property types defined in the source code C++ header for PropertyContainer

Andere komplexere Beispiele
Dieses Beispiel macht von Part Module Gebrauch, um ein Oktaeder zu schaffen, erstellt dann seine coin-Darstellung mit pivy. Zuerst erstellen wir das Document-Objekt selbst:

Dann haben wir das Darstellungs-Objekt,

verantwortlich für die Ansicht des Objekts in der 3D-Szene:

Schließlich, sobald unser Objekt und sein Darstellungs-Objekt definiert sind, müssen wir sie nur noch aufrufen:

Objekte wählbar machen
Wollen Sie Ihr Objekt wählbar machen, oder zumindest ein Teil davon, indem Sie im Editor darauf klicken, müssen Sie seine coin-Geometrie in einen SoFCSelection-Knoten enibinden. Verfügt Ihr Objekt über komplexe Darstellung, mit Widgets, Anmerkungen, etc., möchten Sie vielleicht nur einen Teil davon in einem SoFCSelection einschliessen. Alles, was ein SoFCSelection ist, wird ständig durch FreeCAD gescannt, um eine Auswahl/Vorwahl zu entdecken, der Sinn dabei ist, zu versuchen, es nicht mit unnötigen Abtastungen zu überlasten. Folgendes würden Sie tun, um einen self.face vom Beispiel oben einzuschließen:

Once the parts of the scenegraph that are to be selectable are inside SoFCSelection nodes, you then need to provide two methods to handle the selection path. The selection path can take the form of a string giving the names of each element in the path, or of an array of scenegraph objects. The two methods you provide are, which converts from a string path to an array of scenegraph objects, and , which takes an element which has been clicked on in the scenegraph and returns its string name (note, not its string path).

Here is the molecule example above, adapted to make the elements of the molecule selectable:

Arbeiten mit einfachen Formen
Erstellen Sie einfach einen SoFCSelection Knoten, dann fügen Sie Ihre Geometrie-Knoten dazu hinzu, dann fügen Sie alles zu Ihrem Hauptknoten hinzu, anstatt Ihre Geometrie-Knoten direkt einzufügen. Die Form wird mittels der FreeCAD Standard-Form-Darstellung angezeigt:

Gleicher Code unter Verwendung von ViewProviderLine

Scenegraph Structure
You may have noticed that the examples above construct their scenegraphs in slightly different ways. Some use while others use.

Each feature in a FreeCAD document is based the following scenegraph structure:

The displays only one of its children, depending on which display mode is selection in FreeCAD.

The examples which use are constructing their scenegraphs solely out of coin3d scenegraph elements. Under the covers, adds a new child to the ; the name of that node will match the display mode it was passed.

The examples which use also construct part of their geometry using functions from the Part workbench, such as. This constructs the different display mode scenegraphs under the ; when we later come to add coin3d elements to the scenegraph, we need to add them to the existing display mode scenegraphs using rather than creating a new child of the.

When using to add geometry to the scenegraph, each display mode should have its own node which is passed to ; don't reuse the same node for this. Doing so will confuse the selection mechanism. It's okay if each display mode's node has the same geometry nodes added below it, just the root of each display mode needs to be distinct.

Here is the above molecule example, adapted to be drawn only with Coin3D scenegraph objects instead of using objects from the Part workbench:

Weitere Informationen
Es gibt ein paar sehr interessante Forumeinträge zu geskripteten Objekten:

Additional pages:
 * Scripted objects saving attributes
 * Scripted objects migration
 * Scripted objects with attachment
 * Viewproviders

Interesting forum threads about scripted objects:
 * Python object attributes lost at load
 * New FeaturePython is grey
 * Explanation on __getstate__ and __setstate__, official documentation
 * Eigenmode frequency always 0?
 * how to implement python feature's setEdit properly?

In addition to the examples presented here have a look at FreeCAD source code src/Mod/TemplatePyMod/FeaturePython.py for more examples.