Scripted objects/ro

Introduction
Pe lângă tipurile obișnuite de obiecte, cum ar fi adnotările, plasele și obiectele de piese, FreeCAD oferă, de asemenea, uimitoare posibilitate de a scrie scriptul obeictelor 100% Python, numite caracteristici Python. Aceste obiecte se vor comporta exact ca orice alt obiect FreeCAD și vor fi salvate și restaurate automat la salvarea / încărcarea fișierelor.

O particularitate care trebuie înțeleasă, aceste obiecte sunt salvate în fișiere FreeCAD FcStd cu modului python json module. Acest modul transformă un obiect python în șir de caractere(test), permițându-l să fie adăugat la fișierul salvat. Odată încărcat, modulul json utilizează șirul de caracter pentru a recrea obiectul original, cu condiția ca acesta să aibă acces la codul sursă care a creat obiectul. Aceasta înseamnă că dacă salvați un astfel de obiect personalizat și îl deschideți pe o mașină unde codul python care a generat obiectul nu este prezent, obiectul nu va fi recreat. Dacă distribuiți astfel de obiecte ale altora, va trebui să distribuiți în totalitate scriptul python care a creat-o împreună.

Note: It is possible to pack python code inside a FreeCAD file using json serializing with an App::PropertyPythonObject, but that code can never directly be run, and therefore has little use for our purpose here.

Caracteristicile Python respectă aceeași regulă ca toate funcțiile FreeCAD: ele sunt separate în părți App(application) și GUI(interfață grafică). Partea de aplicație, Object App, definește geometria obiectului nostru, în timp ce partea GUI, definește modul în care obiectul va fi afișat pe ecran. Instrumentul View Provider Objet, ca oricare altă caracteristică FreeCAD, este disponibil numai când rulați FreeCAD în propriul GUI. Există mai multe proprietăți și metode disponibile pentru a construi obiectul. Proprietățile trebuie să fie oricare dintre tipurile de proprietăți predefinite oferite de FreeCAD și vor apărea în fereastra de vizualizare a proprietății, astfel încât acestea să poată fi editate de utilizator. În acest fel, obiectele FeaturePython (au toate proprietățile Python) sunt cu adevărat și în totalitate parametrice. Puteți defini proprietăți pentru Obiect și ViewObject separat.

Exemplu de bază
Următorul exemplu poate fi găsit in fișierul src/Mod/TemplatePyMod/FeaturePython.py, împreună cu alte exemple:

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.

Proprietăți disponibile
Proprietățile sunt adevăratele pietre de temelie ale obiectelor FeaturePython. Prin intermediul acestora, utilizatorul va putea să interacționeze și să vă modifice obiectul. După crearea unui nou obiect FeaturePython din documentul dvs. (obj = FreeCAD.ActiveDocument.addObject ("App :: FeaturePython", "Box")), puteți obține o listă a proprietăților disponibile prin emiterea:

Veți obține o listă cu proprietățile disponibile:


 * App::PropertyAcceleration
 * App::PropertyAngle
 * App::PropertyArea
 * App::PropertyBool
 * App::PropertyBoolList
 * App::PropertyColor
 * App::PropertyColorList
 * App::PropertyDirection
 * App::PropertyDistance
 * App::PropertyEnumeration
 * App::PropertyExpressionEngine
 * App::PropertyFile
 * App::PropertyFileIncluded
 * App::PropertyFloat
 * App::PropertyFloatConstraint
 * App::PropertyFloatList
 * App::PropertyFont
 * App::PropertyForce
 * App::PropertyFrequency
 * App::PropertyInteger
 * App::PropertyIntegerConstraint
 * App::PropertyIntegerList
 * App::PropertyIntegerSet
 * App::PropertyLength
 * App::PropertyLink
 * App::PropertyLinkChild
 * App::PropertyLinkGlobal
 * App::PropertyLinkHidden
 * App::PropertyLinkList
 * App::PropertyLinkListChild
 * App::PropertyLinkListGlobal
 * App::PropertyLinkListHidden
 * App::PropertyLinkSub
 * App::PropertyLinkSubChild
 * App::PropertyLinkSubGlobal
 * App::PropertyLinkSubHidden
 * App::PropertyLinkSubList
 * App::PropertyLinkSubListChild
 * App::PropertyLinkSubListGlobal
 * App::PropertyLinkSubListHidden
 * App::PropertyMap
 * App::PropertyMaterial
 * App::PropertyMaterialList
 * App::PropertyMatrix
 * App::PropertyPath
 * App::PropertyPercent
 * App::PropertyPersistentObject
 * App::PropertyPlacement
 * App::PropertyPlacementLink
 * App::PropertyPlacementList
 * App::PropertyPosition
 * App::PropertyPrecision
 * App::PropertyPressure
 * App::PropertyPythonObject
 * App::PropertyQuantity
 * App::PropertyQuantityConstraint
 * App::PropertySpeed
 * App::PropertyString
 * App::PropertyStringList
 * App::PropertyUUID
 * App::PropertyVacuumPermittivity
 * App::PropertyVector
 * App::PropertyVectorDistance
 * App::PropertyVectorList
 * App::PropertyVolume
 * App::PropertyXLink
 * App::PropertyXLinkList
 * App::PropertyXLinkSub
 * App::PropertyXLinkSubList
 * Mesh::PropertyCurvatureList
 * Mesh::PropertyMeshKernel
 * Mesh::PropertyNormalList
 * Part::PropertyFilletEdges
 * Part::PropertyGeometryList
 * Part::PropertyPartShape
 * Part::PropertyShapeHistory
 * Path::PropertyPath
 * Path::PropertyTool
 * Path::PropertyTooltable
 * Sketcher::PropertyConstraintList
 * Spreadsheet::PropertyColumnWidths
 * Spreadsheet::PropertyRowHeights
 * Spreadsheet::PropertySheet
 * Spreadsheet::PropertySpreadsheetQuantity
 * TechDraw::PropertyCenterLineList
 * TechDraw::PropertyCosmeticEdgeList
 * TechDraw::PropertyCosmeticVertexList
 * TechDraw::PropertyGeomFormatList

Când adăugați proprietăți obiectelor dvs. personalizate, aveți grijă de acestea:
 * Nu utilizați caractere "<" sau ">" în descrierile de proprietăți (care ar sparge fragmente de cod în fișierul xml.fcstd)
 * Proprietățile sunt stocate în ordine alfabetică într-un fișier .fcstd. Toate proprietățile ale căror nume vine după ”Shape” sunt așezate în ordine alfabetică . Dacă aveți o formă în proprietățile dvs., și cum orice proprietate al cărei nume vine după "Shape", se poate să aveți parte de comportamente ciudate.

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:

Tipuri de proprietăți
Implicit proprietățile pot fi actualizate. Este posibil să se facă proprietățile numai pentru citire, de exemplu în cazul în care cineva dorește să afișeze rezultatul unei metode. De asemenea, este posibilă ascunderea proprietății. Tipul de proprietate poate fi setat utilizând

unde mode este un int scurt care poate fi definit ca: 0 -- modul imolicit, read and write 1 -- read-only 2 -- hidden

EditorModes nu sunt definite la reîncărcarea fișierului FreeCAD. Acest lucru ar putea fi făcut prin funcția the __setstate__ function. Vezi http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072. Folosind setEditorMode proprietățile sunt citite numai în PropertyEditor. S-ar putea schimba încă de la Python. Pentru a le face să citească doar setarea trebuie să fie transmisă direct în interiorul funcției addProperty. A s vedea 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 32 -- Prop_NoPersist, Property won't be saved to file at all

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

Alte exemple mai complexe
Acest exemplu ne face să utilizăm Part Workbench pentru a crea un octahedron, apoi crează reprezentarea sa coin cu pivy.

Primul este însuși obiectul Document:

Apoi, avem obiectul furnizorului de vizualizare, responsabil pentru afișarea obiectului în scena 3D:

În cele din urmă, odată ce obiectul și obiectul său de vedere sunt definite, trebuie doar să le numim (clasa Octahedron și codul clasei viewprovider pot fi copiate direct în consola Python FreeCAD):

Crearea de obiecte selectabile
Dacă doriți să faceți obiectul selectabil sau cel puțin o parte a acestuia, făcând clic pe el în fereastra de vizualizare, trebuie să includeți forma geometriei sale în interiorul unui nod SoFCSelection. Dacă obiectul are o reprezentare complexă, cu widget-uri, adnotări etc., poate doriți să includeți doar o parte a acestuia într-o selecție SoFCSelecție. Tot ceea ce este un SoFCSelection este scanat constant de FreeCAD pentru a detecta selectia / preselectarea, deci ar fi bine să  nu incercați a o supraincarca cu scanări inutile. Iată un exemplu de ceea ce ați face pentru a include o self.face din exemplul de mai sus :

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:

Lucrul cu forme simple
Dacă obiectul dvs. parametric emite doar o formă simplă, nu este necesar să utilizați un obiect furnizor de vizualizare(view provider object). Forma va fi afișată utilizând reprezentarea standard a formelor din FreeCAD:

Același cod utilizând 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:

Part Design scripted objects
When making scripted objects in Part Design the process is similar to the scripted objects discussed above, but with a few additional considerations. We must handle 2 shape properties, one for the shape we see in the 3D view and another for the shape used by the pattern tools, such as polar pattern features. The object shapes also needs to be fused to any existing material already in the Body (or cut from it in the case of Subtractive features). And we must account for the placement and attachment of our objects a little bit differently.

Part Design scripted solid object features should be based on either PartDesign::FeaturePython, PartDesign::FeatureAdditivePython, or PartDesign::FeatureSubtractivePython rather than Part::FeaturePython. Only the Additive and Subtractive variants can be used in pattern features, and if based on Part::FeaturePython when the user drops the object into a Part Design Body it becomes a BaseFeature rather than being treated by the Body as a native Part Design object. Note: all of these are expected to be solids, so if you are making a non-solid feature it should be based on Part::FeaturePython or else the next feature in the tree will attempt to fuse to as a solid and it will fail.

Here is a simple example of making a Tube primitive, similar to the Tube primitive in Part Workbench except this one will be a Part Design solid feature object. For this we will 2 separate files: pdtube.FCMacro and pdtube.py. The .FCMacro file will be executed by the user to create the object. The .py file will hold the class definitions, imported by the .FCMacro. The reason for doing it this way is to maintain the parametric nature of the object after restarting FreeCAD and opening a document containing one of our Tubes.

First, the class definition file:

And now the macro file to create the object:



Informație suplimentară
Există câteva subiecte foarte interesante pe forum despre obiectele script:

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?

În plus față de exemplele prezentate aici puteți să vă aruncați o privire în codul sursă FreeCAD  src/Mod/TemplatePyMod/FeaturePython.py for more examples.