Scripted objects/de

Einführung
Neben den Standard Objekttypen wie Anmerkungen, Netze und Teileobjekte bietet FreeCAD auch die erstaunliche Möglichkeit, 100% python geschriebene Objekte zu erstellen, die als Python Funktionen bezeichnet werden. Diese Objekte verhalten sich genau wie jedes andere FreeCAD Objekt und werden beim Speichern/Laden von Dateien automatisch gespeichert und wiederhergestellt.

Eine Besonderheit muss verstanden werden, diese Objekte werden in FreeCAD FcStd Dateien mit dem Python Modul json gespeichert. Dieses Modul wandelt ein Python Objekt in eine Zeichenkette um, so dass es der gespeicherten Datei hinzugefügt werden kann. Beim Laden verwendet das json Modul diese Zeichenfolge, um das ursprüngliche Objekt wieder zu erzeugen, vorausgesetzt, es hat Zugriff auf den Quellcode, der das Objekt erzeugt hat. Das heißt, wenn Sie ein solches benutzerdefiniertes Objekt speichern und es auf einem Rechner öffnen, auf dem der Python Code, der das Objekt erzeugt hat, nicht vorhanden ist, wird das Objekt nicht neu erstellt. Wenn Sie solche Objekte an andere verteilen, müssen Sie das Python Skript, das das Objekt erzeugt hat, zusammen verteilen.

Python Funktionen folgen der gleichen Regel wie alle FreeCAD Funktionen: Sie sind in App- und einen GUI Teile getrennt. Der App-Teil, das Dokument-Objekt, definiert die Geometrie unseres Objekts, während sein GUI-Teil, das View-Provider-Objekt, definiert, wie das Objekt auf dem Bildschirm gezeichnet wird. Das Ansichtsprovider-Objekt ist, wie jede andere FreeCAD-Funktion, nur verfügbar, wenn Sie FreeCAD in seiner eigenen GUI ausführen. Es stehen mehrere Eigenschaften und Methoden zur Verfügung, um Ihr Objekt zu erstellen. Die Eigenschaften müssen zu einem der vordefinierten Eigenschaftstypen gehören, die FreeCAD anbietet, und werden im Eigenschaften-Ansichtsfenster angezeigt, damit sie vom Benutzer bearbeitet werden können. Auf diese Weise sind FeaturePython Objekte wirklich und vollständig parametrisch. Sie können Eigenschaften für das Objekt und sein Ansichtsobjekt getrennt definieren.

Tip: In früheren Versionen haben wir das Python Modul cPickle verwendet. Dieses Modul führt jedoch willkürlichen Code aus und verursacht damit ein Sicherheitsproblem. Daher sind wir zu Pythons json Modul übergegangen.

Grundlegendes Beispiel
Das folgende Beispiel ist zusammen mit einigen anderen Beispielen in der src/Mod/TemplatePyMod/FeaturePython.py Datei zu finden:

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.

Available methods
See FeaturePython methods for the complete reference.

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.