Script di base per FreeCAD
Script Python in FreeCAD
FreeCAD è stato costruito fin dall'inizio per essere totalmente controllato tramite gli script Python.
Quasi tutte le parti di FreeCAD, come ad esempio l'interfaccia oppure i contenuti della scena, compresa la rappresentazione di quanto contenuto nelle viste 3D, sono accessibili tramite l'interprete Python incorporato o tramite script personali.
Per questo, FreeCAD risulta probabilmente una delle applicazioni ingegneristiche più profondamente personalizzabili oggi disponibili.
Se non conoscete ancora Python, vi consigliamo di cercare qualche tutorial su internet e di dare un rapido sguardo alla sua struttura.
Python è un linguaggio molto facile da imparare, soprattutto perché può essere eseguito all'interno di un interprete, dove sia i comandi semplici come i programmi completi, possono essere eseguiti "al volo", cioè senza bisogno di compilare nulla.
FreeCAD incorpora un interprete Python. Se non vedete la finestra denominata "Console Python" della figura successiva, potete attivarla con Visualizza → Pannelli → Console Python e mostrare l'interprete.
L'interprete
Tramite l'interprete, è possibile accedere a tutti i moduli Python installati nel sistema, come pure ai moduli incorporati in FreeCAD e a tutti i moduli aggiuntivi di FreeCAD installati successivamente.
La schermata seguente mostra l'interprete Python di FreeCAD:
Tramite l'interprete è possibile eseguire del codice Python e sfogliare le classi e le funzioni disponibili.
FreeCAD fornisce un browser delle classi molto utile per esplorare il nuovo mondo di FreeCAD.
Quando si digita il nome di una classe nota seguita da un punto (.) (il che significa che si intende completare aggiungendo qualcos'altro alla classe), si apre la finestra del browser delle classi, dove si può navigare tra le sottoclassi e i metodi disponibili.
Quando si seleziona una voce, viene visualizzato il testo di aiuto associato (se esiste):
Per verificare questo, iniziate a digitare App.
oppure Gui.
e osservate cosa succede.
Generalmente, in Python, per esplorare il contenuto dei moduli e delle classi si utilizza il comando print(dir())
.
Ad esempio, digitando print(dir())
si ottiene l'elenco di tutti i moduli attualmente caricati in FreeCAD e con print(dir(App))
si mostra tutto ciò che è contenuto all'interno del modulo App, ecc..
Inoltre l'interprete ricorda i codici che vengono digitati. Questa altra utile caratteristica dell'interprete permette di esplorare all'indietro i comandi digitati e di recuperare, attraverso la cronologia, una riga di codice scritta in precedenza.
Per navigare nella cronologia dei comandi, basta usare i tasti Freccia sù oppure Freccia giù.
Cliccando col tasto destro nella finestra dell'interprete, si rendono disponibili diverse altre opzioni, quali, ad esempio, copiare lo storico (l'intera cronologia, cosa utile quando si desidera sperimentare qualcosa prima di utilizzarla in uno script) oppure inserire un nome di un file con il suo percorso completo.
Help di Python
Nel menu Help di FreeCAD, troverai una voce denominata Automatic python modules documentation, che aprirà una finestra del browser contenente una documentazione completa e generata in tempo reale di tutti i moduli Python disponibili per l'interprete di FreeCAD, inclusi i moduli integrati di Python e FreeCAD, i moduli installati dal sistema e i moduli aggiuntivi di FreeCAD. La documentazione lì disponibile dipende da quanto sforzo ogni sviluppatore di moduli ha fatto per documentare il suo codice, ma i moduli Python hanno la reputazione di essere abbastanza ben documentati. La finestra di FreeCAD deve rimanere aperta affinché questo sistema di documentazione funzioni.
Moduli incorporati
Poiché FreeCAD è progettato in modo da poter essere eseguito anche senza un'interfaccia utente grafica (GUI), quasi tutte le sue funzionalità sono separate in due gruppi: funzionalità principale, denominata App
, e funzionalità GUI, denominata Gui
. È possibile accedere a questi due moduli anche da script esterni all'interprete, rispettivamente con i nomi FreeCAD
e FreeCADGui
.
- Nel modulo
App
, si trova tutto ciò che riguarda l'applicazione stessa, cioè i metodi per l'apertura o la chiusura di file e documenti, oppure l'impostazione del documento attivo o la visualizzazione dei contenuti.
- Nel modulo
Gui
, si trovano gli strumenti per accedere e gestire gli elementi dell'interfaccia grafica (GUI), cioè gli ambienti di lavoro e le loro barre degli strumenti e, più interessante, la rappresentazione grafica di tutti i contenuti di FreeCAD.
Elencare il contenuto di questi moduli non è molto utile perché crescono abbastanza velocemente con lo sviluppo di FreeCAD. Ma i due strumenti di navigazione forniti (il browser di classe e la guida di Python) dovrebbero fornire una documentazione completa e aggiornata in qualsiasi momento.
Gli oggetti App e GUI
Come già accennato, in FreeCAD tutto è separato in core e representation. Ciò include gli oggetti 3D. Puoi accedere alle proprietà di definizione degli oggetti (chiamate funzionalità in FreeCAD) tramite il modulo App
e modificare il modo in cui sono rappresentate sullo schermo tramite il modulo Gui
. Ad esempio, un cubo ha proprietà che lo definiscono (come larghezza, lunghezza, altezza) che sono archiviate in un oggetto App
e proprietà di rappresentazione (come il colore delle facce, la modalità di disegno) che sono archiviate in un corrispondente oggetto Gui
.
Questo modo di fare le cose consente una vasta gamma di operazioni, come gli algoritmi che funzionano solo sulla parte di definizione delle caratteristiche, senza la necessità di prendersi cura di nessuna parte visiva, e consente anche di reindirizzare il contenuto del documento a applicazioni non-grafiche, quali, ad esempio, elenchi, fogli di calcolo, o analisi degli elementi.
Per ogni oggetto App
nel tuo documento, esiste un oggetto Gui
corrispondente. Infatti il documento stesso ha sia un oggetto App
che un oggetto Gui
. Questo, ovviamente, si applica solo quando esegui FreeCAD con la sua interfaccia completa. Nella versione da riga di comando non esiste una GUI, quindi sono disponibili solo oggetti App
. Nota che la parte Gui
degli oggetti viene rigenerata ogni volta che un oggetto App
viene contrassegnato come 'da ricalcolare' (ad esempio quando uno dei suoi parametri cambia), quindi qualsiasi modifica fatta direttamente all'oggetto Gui
potrebbe andare persa.
Per accedere alla parte App di qualcosa, si digita:
myObject = App.ActiveDocument.getObject("ObjectName")
dove "ObjectName" è il nome del vostro oggetto.
Inoltre è possibile digitare:
myObject = App.ActiveDocument.ObjectName
Per accedere alla parte Gui dello stesso oggetto, si digita:
myViewObject = Gui.ActiveDocument.getObject("ObjectName")
dove "ObjectName" è il nome del vostro oggetto.
Inoltre è possibile digitare:
myViewObject = App.ActiveDocument.ObjectName.ViewObject
Se non abbiamo GUI (ad esempio, siamo in modalità riga di comando), l'ultima riga non restituirà nulla.
Gli oggetti del documento
In FreeCAD tutto il vostro lavoro si trova all'interno dei documenti.
Un documento contiene la geometria e può essere salvato in un file. Si possono avere simultaneamente più documenti aperti.
Il documento, come la geometria contenuta all'interno, ha oggetti App e oggetti Gui. L'oggetto App contiene le definizioni della geometria reale, mentre l'oggetto Gui contiene i diversi punti di vista del documento.
È possibile aprire più finestre, ognuna delle quali visualizza il lavoro con un fattore di zoom o un punto di vista diverso. Questi punti di vista fanno tutti parte dell'oggetto Gui del documento.
In FreeCAD all your work resides inside documents. A document contains your geometry and can be saved to a file. Several documents can be opened at the same time. The document, like the geometry contained inside, has App
and Gui
objects. The App
object contains your actual geometry definitions, while the Gui
object contains the different views of your document. You can open several windows, each one viewing your work with a different zoom factor or from a different direction. These views are all part of your document's Gui
object.
Per accedere alla parte App del documento attualmente aperto (attivo), si digita:
myDocument = App.ActiveDocument
Per creare un nuovo documento, si digita:
myDocument = App.newDocument("Document Name")
Per accedere alla parte Gui del documento attualmente aperto (attivo), si digita:
myGuiDocument = Gui.ActiveDocument
Per accedere alla vista corrente, si digita:
myView = Gui.ActiveDocument.ActiveView
Utilizzo di moduli aggiuntivi
I moduli FreeCAD e FreeCADGui sono responsabili esclusivamente della creazione e della gestione degli oggetti nel documento di FreeCAD.
Essi in realtà non fanno nulla che riguardi la creazione o la modifica della geometria.
Ciò è dovuto al fatto che la geometria può essere di diversi tipi, e quindi la sua gestione è affidata ai moduli aggiuntivi, ognuno di essi ha il compito di gestire uno specifico tipo di geometria.
Il modulo Parte utilizza il kernel OpenCascade, e quindi è in grado di creare e manipolare geometrie di tipo B-rep, che è appunto il tipo di geometria costruito da OpenCascade.
Il modulo Mesh è in grado di costruire e modificare gli oggetti mesh.
In questo modo, FreeCAD è in grado di gestire un'ampia gamma di tipi di oggetti che possono coesistere nello stesso documento, e nuovi tipi potrebbero essere aggiunti facilmente in futuro.
The FreeCAD
and FreeCADGui
modules are only responsible for creating and managing objects in the FreeCAD document. They don't actually do anything more such as creating or modifying geometry. This is because that geometry can be of several types, and therefore requires additional modules, each responsible for managing a certain geometry type. For example, the Part Workbench, using the OpenCascade kernel, is able to create and manipulate BRep type geometry. Whereas the Mesh Workbench is able to build and modify mesh objects. In this manner FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types can easily be added in the future.
Creare degli oggetti
Ogni modulo tratta la propria geometria in un modo specifico, però in genere tutti i moduli possono creare degli oggetti nel documento.
Il documento FreeCAD è anche a conoscenza dei tipi di oggetti fornibili dai moduli e il seguente comando:
Each module has its own way of dealing with geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules:
FreeCAD.ActiveDocument.supportedTypes()
mostra tutti gli oggetti che si possono creare.
Come esempio, proviamo a creare un oggetto mesh (trattato dal modulo Mesh) e un oggetto parte (trattato dal modulo Part):
myMesh = FreeCAD.ActiveDocument.addObject("Mesh::Feature", "myMeshName")
myPart = FreeCAD.ActiveDocument.addObject("Part::Feature", "myPartName")
Il primo parametro è il tipo di oggetto, il secondo il nome dell'oggetto. I nostri due oggetti appaiono quasi come la stessa cosa.
Al momento, essi non contengono ancora la geometria, e se li ispezioniamo con dir(myMesh) e con dir(myPart) la maggior parte delle loro proprietà sono le stesse. L'unica differenza è che myMesh ha una proprietà "Mesh" e "Part" ha una proprietà "Shape". È qui che i dati Mesh e Parte vengono memorizzati.
Come esempio, creiamo un cubo di tipo Parte e poi lo archiviamo nel nostro oggetto myPart:
import Part
cube = Part.makeBox(2, 2, 2)
myPart.Shape = cube
Se provate a memorizzare il cubo all'interno della proprietà Mesh dell'oggetto myMesh, vi verrà restituito un messaggio di "errore di tipo". Questo perché le proprietà sono fatte in modo da memorizzare solo uno specifico tipo. Nelle proprietà Mesh di myMesh, è possibile salvare solo elementi creati con il modulo Mesh.
Notare che la maggior parte dei moduli hanno anche un collegamento per aggiungere la loro geometria al documento:
import Part
cube = Part.makeBox(2, 2, 2)
Part.show(cube)
Modificare gli oggetti
La modifica di un oggetto si esegue nello stesso modo:
Modifying an object is done in the same way:
import Part
cube = Part.makeBox(2, 2, 2)
myPart.Shape = cube
Ora cambiamo la sua forma in una più grande:
biggercube = Part.makeBox(5, 5, 5)
myPart.Shape = biggercube
Interrogare gli oggetti
È sempre possibile sapere di che tipo è un oggetto con:
You can always look at the type of an object like this:
myObj = FreeCAD.ActiveDocument.getObject("myObjectName")
print(myObj.TypeId)
o sapere se un oggetto è derivato da uno di quelli base (struttura di Parte, struttura di Mesh, etc) con:
print(myObj.isDerivedFrom("Part::Feature"))
Ora si può davvero iniziare a divertirsi con FreeCAD! Per vedere ciò che si può fare con il Modulo Parte, leggere la pagina Script per ambiente Parte, o la pagina Script per ambiente Mesh per lavorare con il Modulo Mesh.
Notare che, oltre ai moduli Parte e Mesh che sono i più completi e sono molto utilizzati, anche altri moduli come il Modulo Draft hanno script API che possono servirvi.
Per un elenco completo di tutti i moduli e gli strumenti disponibili, consultare la sezione Category:API/it.
- FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics
- Modules: Builtin modules, Units, Quantity
- Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
- Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC
- Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
- Scenegraph: Coin (Inventor) scenegraph, Pivy
- Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Embedding: Embedding FreeCAD, Embedding FreeCADGui
- Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)
- Hubs: User hub, Power users hub, Developer hub