FreeCAD Scripting Basics/it

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.

Allo stato attuale, FreeCAD ha però pochissimi comandi "nativi" per interagire con gli oggetti 3D, soprattutto perché è ancora all'inizio dello sviluppo, ma anche perché i suoi programmatori intendono fornire una piattaforma base per lo sviluppo del CAD piuttosto che un'applicazione per un uso specifico.

La facilità d'uso degli script Python all'interno di FreeCAD permette di conoscere velocemente le nuove funzionalità in fase di sviluppo come "utenti esperti", cioè come utenti che conoscono un po' di programmazione Python.

Python è uno dei più popolari linguaggi interpretati, e poiché è generalmente considerato facile da imparare, anche voi potrete produrre presto vostri script all'interno di FreeCAD come "utenti esperti".

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 → Vista → 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 qualcosaltro 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 la combinazione di tasti oppure.

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.

Aiuti di Python
Nel menu Aiuto di FreeCAD, trovate una voce denominata Moduli Python, essa apre una finestra del browser contenente una documentazione completa, generata in tempo reale, di tutti i moduli Python a disposizione dell'interprete di FreeCAD, compreso Python e i moduli interni di FreeCAD, i moduli installati dal sistema e i moduli aggiuntivi di FreeCAD.

La documentazione disponibile dipende dalla fatica che lo sviluppatore del modulo ha fatto per documentare il proprio codice. I moduli Python hanno la reputazione di essere in genere abbastanza ben documentati. La finestra di FreeCAD deve rimanere aperta perchè questo sistema di documentazione funzioni.

Moduli incorporati (Built-in)
Dato che FreeCAD è stato progettato per essere eseguito senza una interfaccia grafica (GUI), quasi tutte le sue funzionalità sono divise in due parti: la funzionalità di base, denominata App, e la funzionalità grafica, denominata Gui. Per questo motivo i due principali moduli incorporati nel nostro FreeCAD sono chiamati App e Gui. Questi due moduli sono accessibili, rispettivamente con il nome "FreeCAD" e "FreeCADGui", anche tramite script eseguiti al di fuori dell'interprete.


 * 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 tutto il contenuto di tali moduli è un lavoro un po' controproducente, in quanto essi crescono molto velocemente seguendo lo sviluppo di FreeCAD.

I due strumenti di esplorazione disponibili (il browser delle classi e l'aiuto di Python) dovrebbero dare, in qualsiasi momento, una completa e aggiornata documentazione di questi moduli.

Gli oggetti App e gli oggetti GUI
Come abbiamo detto, in FreeCAD, tutto viene separato tra nucleo e rappresentazione. Ciò vale anche per gli oggetti 3D.

È possibile accedere alla definizione delle proprietà degli oggetti (chiamate funzioni in FreeCAD) tramite il modulo App, e cambiare il modo in cui gli oggetti vengono riprodotti sullo schermo tramite il modulo Gui.

Ad esempio, un parallelepipedo ha delle proprietà che lo definiscono, (cioè larghezza, lunghezza e altezza) che vengono memorizzate in un oggetto App e delle proprietà di rappresentazione, (come il colore delle facce, la modalità di disegno) che sono memorizzate 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.

Nel documento, per ogni oggetto App, esiste un corrispondente oggetto Gui. Infatti lo stesso documento possiede sia oggetti App che oggetti Gui.

Questo, naturalmente, è valido solo quando si esegue FreeCAD completo di interfaccia grafica. Nella versione riga di comando, senza interfaccia grafica, sono quindi disponibili solo gli oggetti App.

Ricordare che la parte Gui degli oggetti viene rigenerata ogni volta che un oggetto App viene indicato "da ricalcolare" (ad esempio quando cambia uno dei suoi parametri), in quanto le modifiche fatte direttamente all'oggetto Gui potrebbero perdersi.

Per accedere alla parte App di qualcosa, si digita: dove "ObjectName" è il nome del vostro oggetto.

Inoltre è possibile digitare: To access the Gui part of the same object, you type: where "ObjectName" is the name of your object. You can also type: If we have no GUI (for example we are in command-line mode), the last line will return 'None'.

The Document objects
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. 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 point of view. These views are all part of your document's Gui object.

To access the App part the currently open (active) document, you type: To create a new document, type: To access the Gui part the currently open (active) document, you type: To access the current view, you type:

Using additional modules
The FreeCAD and FreeCADGui modules are solely responsibles for creating and managing objects in the FreeCAD document. They don't actually do anything such as creating or modifying geometry. That is because that geometry can be of several types, and so it is managed by additional modules, each responsible for managing a certain geometry type. For example, the Part Module uses the OpenCascade kernel, and therefore is able to create and manipulate B-rep type geometry, which is what OpenCascade is built for. The Mesh Module is able to build and modify mesh objects. That way, FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types could be added easily in the future.

Creating objects
Each module has its own way to treat its 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: will list you all the possible objects you can create. For example, let's create a mesh (treated by the mesh module) and a part (treated by the part module): The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with dir(myMesh) and dir(myPart). Except for one, myMesh has a "Mesh" property and "Part" has a "Shape" property. That is where the Mesh and Part data are stored. For example, let's create a Part cube and store it in our myPart object: You could try storing the cube inside the Mesh property of the myMesh object, it will return an error complaining of the wrong type. That is because those properties are made to store only a certain type. In the myMesh's Mesh property, you can only save stuff created with the Mesh module. Note that most modules also have a shortcut to add their geometry to the document:

Modifying objects
Modifying an object is done the same way: Now let's change the shape by a bigger one:

Querying objects
You can always look at the type of an object like this: or know if an object is derived from one of the basic ones (Part Feature, Mesh Feature, etc): Now you can really start playing with FreeCAD! To look at what you can do with the Part Module, read the Part scripting page, or the Mesh Scripting page for working with the Mesh Module. Note that, although the Part and Mesh modules are the most complete and widely used, other modules such as the Draft Module also have scripting APIs that can be useful to you. For a complete list of each modules and their available tools, visit the Category:API section.