Scripted objects/it

Introduzione
Oltre ai tipi di oggetti standard, come le Annotazioni, gli oggetti Mesh e gli oggetti Parte, FreeCAD offre anche la straordinaria possibilità di costruire al 100% oggetti parametrici in script di Python, chiamati Python Features (Caratteristiche Python). Questi oggetti si comportano esattamente come un qualsiasi altro oggetto di FreeCAD, e sono salvati e ripristinati automaticamente con salva/apri il file.

Una particolarità deve essere compresa: per motivi di sicurezza, i file di FreeCAD non contengono mai alcun codice incorporato. Il codice Python che scrivi per creare oggetti parametrici non viene mai salvato all'interno di un file. Ciò significa che se apri un file contenente tale oggetto su un'altra macchina, e quel codice Python non è disponibile su quella macchina, l'oggetto non verrà completamente ricreato. Se distribuisci tali oggetti ad altri, dovrai distribuire anche il tuo script Python, ad esempio come Macro.

Nota: è possibile impacchettare il codice Python all'interno di un file FreeCAD utilizzando la serializzazione json con un App::PropertyPythonObject, ma quel codice non può mai essere eseguito direttamente, e quindi ha poca utilità per il nostro scopo qui.

Le Python Features seguono le stesse regole di tutte le altre funzionalità di FreeCAD: sono divise in una parte App e una parte GUI. La parte App, cioè il Document Object (oggetto del documento), definisce la geometria dell'oggetto, mentre la sua parte grafica, cioè il View Provider Object (fornitore della vista dell'oggetto), definisce come l'oggetto viene disegnato sullo schermo. Il View Provider Object, come qualsiasi altro elemento di FreeCAD, è disponibile solo quando si esegue FreeCAD nella sua GUI (interfaccia grafica). Per costruire il proprio oggetto, sono disponibili diversi metodi e proprietà. La Proprietà deve essere una qualsiasi dei tipi di proprietà predefinite che FreeCAD mette a disposizione. Le proprietà disponibili sono quelle che appaiono nella finestra di visualizzazione delle proprietà per consentire all'utente di modificarle. Con questa procedura, gli oggetti FeaturePython sono realmente e totalmente parametrici. E' possibile definire separatamente le proprietà per l'oggetto e per la sua ViewObject (rappresentazione).



Esempio di base
L'esempio seguente si trova nel file src/Mod/TemplatePyMod/FeaturePython.py, con molti altri esempi:



Cose da notare
Se il tuo oggetto si basa sul ricalcolo non appena viene creato, devi farlo manualmente nella funzione poiché non viene chiamato automaticamente. Questo esempio non lo richiede, perché il metodo della classe  ha lo stesso effetto della funzione, ma gli esempi seguenti si basano sull'essere ricalcolati prima che qualsiasi cosa venga visualizzata nella vista 3D. Negli esempi, questo viene fatto manualmente con, ma in scenari più complessi devi decidere dove ricalcolare l'intero documento o l'oggetto FeaturePython.

Questo esempio produce una serie di analisi dello stack di eccezioni nella finestra di visualizzazione del report. Questo perché il metodo della classe  viene chiamato ogni volta che viene aggiunta una proprietà in. Quando viene aggiunta la prima, le proprietà Width e Height non esistono ancora e quindi il tentativo di accedervi fallisce.

Una spiegazione di e  è nel thread del forum obj.Proxy.Type è un dizionario, non una stringa.



Metodi disponibili
Vedi Metodi FeaturePython per i riferimenti completi.



Proprietà disponibili
Le proprietà sono i veri e propri mattoni per la costruzione degli oggetti FeaturePython. Attraverso di esse, l'utente è in grado di interagire e modificare l'oggetto. Dopo aver creato un nuovo oggetto FeaturePython nel documento (obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box")), è possibile ottenere un elenco delle proprietà disponibili digitando:

Si ottiene un elenco di proprietà disponibili, che sono descritte in modo più approfondito nella pagina FeaturePython Custom Properties:


 * 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

Quando si aggiungono delle proprietà agli oggetti personalizzati, stare attenti a questo:
 * Non utilizzare i caratteri "<" o ">" nelle descrizioni delle proprietà (questo spezza le parti xml nel file .fcstd)
 * Le proprietà sono memorizzate in ordine alfabetico nel file .fcstd. Se si dispone di una forma (Shape) nelle proprietà, qualsiasi proprietà il cui nome, in ordine alfabetico, viene dopo "Shape", verrà caricato DOPO la forma (Shape), e questo può causare strani comportamenti.

Un elenco completo degli attributi delle proprietà può essere visualizzato nel file PropertyStandard C++ header. Ad esempio, se vuoi consentire all'utente di inserire solo un intervallo limitato di valori (ad es. Usando PropertyIntegerConstraint), in Python assegnerai una tupla contenente non solo il valore della proprietà, ma anche il limite inferiore e superiore, nonché la dimensione del passo, come sotto:



Tipi di proprietà
Di default, le proprietà possono essere aggiornate. È possibile creare delle proprietà di sola lettura, per esempio nel caso si vuole mostrare il risultato di un metodo. È anche possibile nascondere una proprietà. Il tipo di proprietà può essere impostata usando

dove mode è un indice che può essere impostato: 0 -- default mode, lettura e scrittura 1 -- solo lettura 2 -- nascosto

Gli EditorModes non sono fissati nel file reload di FreeCAD. Questo può essere fatto dalla funzione __setstate__. Vedere http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072. Usando setEditorMode le proprietà sono in sola lettura soltanto in PropertyEditor. Esse possono ancora essere modificate da un comando Python. Per renderle davvero in sola lettura le impostazioni devono essere passate direttamente all'interno della funzione addProperty. Per un esempio, vedere http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709.

Utilizzando l'impostazione diretta nella funzione addProperty, si hanno anche più possibilità. In particolare, è interessante contrassegnare una proprietà come proprietà di output. In questo modo FreeCAD non contrassegnerà l'elemento come variato durante la modifica (quindi non è necessario ricalcolare).

Esempio di proprietà di output (vedi anche https://forum.freecadweb.org/viewtopic.php?t=24928):

I tipi di proprietà che possono essere impostati all'ultimo parametro della funzione addProperty sono: 0 -- Prop_None, nessun tipo di proprietà speciale 1 -- Prop_ReadOnly, la proprietà è di sola lettura nell'editor 2 -- Prop_Transient, la proprietà non verrà salvata nel file 4 -- Prop_Hidden, la proprietà non apparirà nell'editor 8 -- Prop_Output, la proprietà modificata non tocca il suo contenitore principale 16 -- Prop_NoRecompute, la proprietà modificata non tocca il suo contenitore per il ricalcolo 32 -- Prop_NoPersist, la proprietà non verrà affatto salvata nel file

È possibile trovare questi diversi tipi di proprietà definiti nell'intestazione del codice sorgente C++ per PropertyContainer.



Un altro esempio più complesso
In questo esempio si utilizza il Modulo Part per creare un ottaedro, quindi si crea la sua rappresentazione Coin con Pivy.

Prima si crea l'oggetto del documento:

In seguito si crea il fornitore della vista dell'oggetto (view provider object), responsabile di mostrare l'oggetto nella scena 3D:

Infine, dopo che l'oggetto e il suo visualizzatore sono definiti, basta solo chiamarli (La classe Octahedron e il codice della classe viewprovider possono essere copiati direttamente nella console Python di FreeCAD)::



Rendere gli oggetti selezionabili
Se volete rendere il vostro oggetto selezionabile, o almeno una parte di esso, facendo clic su di esso nella finestra, è necessario includere la sua geometria Coin all'interno di un nodo SoFCSelection. Se l'oggetto ha una rappresentazione complessa, con widget, annotazioni, etc, si potrebbe voler includere solo una parte di esso in un SoFCSelection. Tutto quello che compone un SoFCSelection viene costantemente analizzato da FreeCAD per rilevare selezioni/preselezioni, quindi non ha senso sovraccaricarlo con delle scansioni non necessarie.

Una volta che le parti dello scenegraph, che devono essere selezionabili, si trovano all'interno dei nodi SoFCSelection, è necessario fornire due metodi per gestire il percorso di selezione. Il percorso di selezione può assumere la forma di una stringa che fornisce i nomi di ciascun elemento nel percorso o di un array di oggetti scenegraph. I due metodi che fornisci sono, che converte da un percorso stringa in un array di oggetti scenegraph, e , che prende un elemento su cui è stato fatto clic nello scenegraph e restituisce il suo nome di stringa (nota, non il suo percorso di stringa).

Ecco l'esempio della molecola sopra, adattato per rendere selezionabili gli elementi della molecola:



Lavorare con forme semplici
Se l'oggetto parametrico produce semplicemente una forma, non è necessario utilizzare un fornitore di vista dell'oggetto (view provider object). La forma viene visualizzata utilizzando la rappresentazione della forma standard di FreeCAD:

Lo stesso codice con l'uso di ViewProviderLine



Struttura di Scenegraph
Potresti aver notato che gli esempi sopra costruiscono i loro scenegraphs in modi leggermente diversi. Alcuni usano mentre altri usano.

Ogni caratteristica in un documento di FreeCAD si basa sulla seguente struttura di scenegraph:

mostra solo uno dei suoi figli, a seconda della modalità di visualizzazione selezionata in FreeCAD.

Gli esempi che utilizzano stanno costruendo i loro scenegraph esclusivamente dagli elementi dello scenegraph di coin3d. Dietro le quinte, aggiunge un nuovo figlio a ; il nome di quel nodo corrisponderà alla modalità di visualizzazione, che è stata passata.

Gli esempi che utilizzano costruiscono anche parte della loro geometria utilizzando le funzioni dell'ambiente Part, come. Questo costruisce i diversi scenegraph della modalità di visualizzazione sotto ; quando in seguito arriveremo ad aggiungere elementi coin3d allo scenegraph, dobbiamo aggiungerli agli scenegraph della modalità di visualizzazione esistenti usando piuttosto che creare un nuovo figlio di.

Quando si utilizza per aggiungere geometria allo scenegraph, ogni modalità di visualizzazione dovrebbe avere il proprio nodo che viene passato a ; non riutilizzare lo stesso nodo per questo. Ciò confonderà il meccanismo di selezione. Va bene se il nodo di ciascuna modalità di visualizzazione ha gli stessi nodi geometrici aggiunti sotto di esso, solo la radice di ciascuna modalità di visualizzazione deve essere distinta.

Ecco l'esempio della molecola sopra, adattato per essere disegnato solo con oggetti scenegraph Coin3D invece di utilizzare oggetti dall'ambiente Part:



Oggetti con script di Part Design
Quando si creano oggetti con script in Part Design, il processo è simile agli oggetti con script discussi sopra, ma con alcune considerazioni aggiuntive. Dobbiamo gestire 2 proprietà della forma, una per la forma, che vediamo nella vista 3D e un'altra per la forma utilizzata dagli strumenti del modello, come le caratteristiche del modello polare. Le forme dell'oggetto devono anche essere fuse con qualsiasi materiale esistente già nel Corpo (o tagliate da esso nel caso di funzioni sottrattive). E dobbiamo tenere conto della collocazione e dell'attaccamento dei nostri oggetti in modo un po' diverso.

Le feature di oggetti solidi con script di Part Design devono essere basate su PartDesign::FeaturePython, PartDesign::FeatureAdditivePython o PartDesign::FeatureSubtractivePython piuttosto che su Part::FeaturePython. Solo le varianti Additive e Subtractive possono essere utilizzate nelle feature di ripetizione e, se basate su Part::FeaturePython, quando l'utente rilascia l'oggetto in un Body di Part Design, diventa una BaseFeature invece di essere trattato dal Body come un oggetto di Part Design nativo. Nota: tutti questi dovrebbero essere solidi, quindi se stai creando una caratteristica non solida dovrebbe essere basata su Part::FeaturePython altrimenti la caratteristica successiva nell'albero tenterà di fondersi come un solido e fallirà.

Di seguito è riportato un semplice esempio di creazione di una primitiva Tube, simile alla primitiva Tube nell'ambiente Part, tranne per il fatto che questa sarà un oggetto feature solido di Part Design. Per questo useremo 2 file separati: pdtube.FCMacro e pdtube.py. Il file .FCMacro verrà eseguito dall'utente per creare l'oggetto. Il file .py conterrà le definizioni delle classi, importate da .FCMacro. Il motivo per farlo in questo modo è mantenere la natura parametrica dell'oggetto dopo aver riavviato FreeCAD e aperto un documento contenente uno dei nostri tubi.

Innanzitutto, il file di definizione della classe:

E ora il file macro per creare l'oggetto:



Ulteriori informazioni
Pagine aggiuntive:
 * Oggetti creati con script che salvano gli attributi
 * Migrazione di oggetti creati con script
 * Oggetti creati da script con parti associate
 * Viewprovider

Interessanti thread del forum sugli oggetti con script:


 * 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?

Oltre agli esempi presentati qui dare un'occhiata al codice sorgente di FreeCAD src/Mod/TemplatePyMod/FeaturePython.py per ulteriori esempi.