Python scripting tutorial/it

Python è un linguaggio di programmazione, molto semplice da usare e molto veloce da imparare.

E' open-source, multi-piattaforma, e può essere usato da solo per una vasta gamma di cose, sia per semplici script che per programmi molto complessi.

Uno dei suoi usi più frequenti è sicuramente come linguaggio di script poiché è facile da incorporare in altre applicazioni. Questo è esattamente il modo in cui viene utilizzato all'interno di FreeCAD.

Dalla console di Python, o tramite script personali, è possibile pilotare FreeCAD e fargli eseguire azioni molto complesse per le quali non esiste ancora lo strumento per l'interfaccia grafica utente.

Ad esempio, tramite uno script Python, è possibile:
 * creare nuovi oggetti
 * modificare gli oggetti esistenti
 * modificare la rappresentazione 3D degli oggetti
 * modificare l'interfaccia di FreeCAD

Ci sono anche altri modi per utilizzare Python in FreeCAD:
 * Tramite l'Interprete di Python in FreeCAD, dove è possibile inviare semplici comandi come si fa in una interfaccia di tipo "linea di comando"
 * Tramite le Macro, che sono un modo pratico per aggiungere rapidamente all'interfaccia di FreeCAD uno strumento mancante
 * Tramite degli script esterni, che possono essere utilizzati per programmare le cose molto complesse, ad esempio, creare completi Ambienti di lavoro.

In questo tutorial, lavoreremo su un paio di esempi semplici per consentirte a tutti di iniziare, ma in questo wiki è disponibile anche molta altra documentazione sugli script Python.

Per chi non conosce ancora Python, ma è interessato a capire come funziona, c'è anche una Introduzione a Python per una formazione di base.

Important! Before proceeding with Python scripting, go to Edit->Prefences->General->Output window and check 2 boxes: Then go to View->Views and check: This will save you a lot of aggravation!
 * Redirect internal Python output to report view
 * Redirect internal Python errors to report view
 * Report view

Scrivere un codice Python
In FreeCAD, ci sono due modi semplici per scrivere un codice Python: Tramite la console di Python (disponibile con Visualizza → Viste → Console Python) oppure tramite l'editor delle Macro (Strumenti → Macro).

Nella console, si scrivono i comandi Python uno per uno (riga per riga), e questi vengono eseguiti quando si preme Invio, mentre le macro possono contenere uno script più complesso fatto di diverse righe, e i comandi vengono eseguiti solo quando viene eseguita la macro.



In questo tutorial si utilizzeranno entrambi i metodi, sia il copia/incolla di ogni riga, una per una, nella console Python seguito da dopo ogni riga, sia il copia/incolla dell'intero codice in una nuova finestra Macro.

Esplorare FreeCAD
Iniziamo creando un nuovo documento vuoto:

Quando si digita questo nella console Python di FreeCAD si nota che, non appena si digita "FreeCAD", si apre una finestra che consente di autocompletare rapidamente il resto della riga.

In più, ogni voce dell'elenco di completamento automatico possiede un testo di aiuto che la descrive. Questo rende molto facile esplorare le funzionalità disponibili.

Prima di scegliere "newDocument", date un'occhiata alle altre opzioni disponibili.



Ora verrà creato il nostro nuovo documento. Questo equivale alla pressione sul pulsante "nuovo documento" della barra degli strumenti.

In effetti, la maggior parte dei pulsanti di FreeCAD non fa altro che eseguire una o due righe di codice Python.

Meglio ancora, in Modifica → Preferenze → Generale → Macro è possibile attivare l'opzione "mostra lo script dei comandi nella console Python". Questo visualizzerà nella console tutto il codice Python che viene eseguito quando si premono i vari pulsanti. E' molto utile per imparare a riprodurre le azioni in codice Python.

Ora torniamo al nostro documento. Vediamo cosa possiamo fare con esso:

Esploriamo le opzioni disponibili.

Di solito i nomi che iniziano con la lettera maiuscola sono attributi e contengono un valore, mentre i nomi che iniziano con la lettera minuscola sono funzioni (chiamate anche metodi) e "fanno qualcosa".

I nomi che iniziano con un carattere di sottolineatura di solito sono lì per il funzionamento interno del modulo e non dobbiamo preoccuparci di loro.

Usiamo ora uno dei metodi per aggiungere un nuovo oggetto al nostro documento:

Non succede nulla. Perché? Perché FreeCAD è pensato per realizzare lavori molto complessi.

In futuro, lavorerà con centinaia di oggetti complessi, tutti dipendenti l'uno dall'altro.

Apportare una piccola modifica da qualche parte potrebbe avere un grande impatto, potrebbe essere necessario ricalcolare l'intero documento, operazione che potrebbe richiedere molto tempo ... Per questo motivo, quasi nessun comando aggiorna la scena automaticamente. È necessario farlo manualmente:

Visto? Ora il box è apparso! Molti dei pulsanti che aggiungono oggetti in FreeCAD in realtà fanno 2 cose: aggiungere l'oggetto, e ricalcolare.

Se l'opzione "mostra lo script dei comandi nella console Python" di cui sopra è attivata, provate ad aggiungere una sfera con il pulsante della GUI e vedrete le due righe di codice python che vengono eseguite una dopo l'altra.

E oltre a "Part :: Box"? Come posso sapere quali altri tipi di oggetti possono essere aggiunti? Sono tutti qui:

Ora esploriamo le caratteristiche del nostro box:

Si possono vedere subito un paio di cose molto interessanti quali:

Questo comando stampa l'altezza corrente del nostro box. Ora proviamo a cambiarla:

Se selezionamo il box con il mouse, nella scheda "Dati", del pannello delle proprietà, ora appare il valore della nostra proprietà "Altezza".

Tutte le proprietà di un oggetto di FreeCAD che appaiono quì (e anche nella scheda "Vista", di cui parleremo più avanti), sono anche accessibili direttamente tramite Python, tramite i loro nomi, come abbiamo fatto con la proprietà "Altezza".

Provate a cambiare le altre dimensioni del box.

Vettori e posizionamenti
I vettori sono un concetto fondamentale in qualsiasi applicazione 3D. Si tratta di un elenco di 3 numeri (x, y, z) che descrivono un punto o una posizione nello spazio 3D.

Con i vettori si possono eseguire diverse operazioni, ad esempio, sommarli, sottrarli, proiettarli e molto altro.

In FreeCAD, con i vettori si lavora in questo modo:

Un'altra caratteristica comune degli oggetti FreeCAD è la loro collocazione nello spazio, (accessibile dalla scheda Vista combinata → Proprietà → Dati → Placement,, oppure tramite il menu  Modifica → Posizionamento...).

Ogni oggetto possiede alcuni attributi di posizionamento, che contengono la posizione (Base) e l'orientamento (Rotation) dell'oggetto. Questi attributi si manipolano facilmente, ad esempio, per spostare il nostro oggetto:

Prima di continuare, si devono vedere un paio di concetti importanti.

App e Gui
FreeCAD è stato inizialmente creato per lavorare come applicazione a riga di comando, senza la sua attuale interfaccia utente. Di conseguenza, quasi tutto viene separato in una componente "geometria" e una componente "vista".

Quando si lavora in modalità riga di comando, la parte geometria è presente, ma tutta la parte di visualizzazione è semplicemente disabilitata. Quindi, in FreeCAD, quasi tutti gli oggetti si compongono di due parti, una parte Object e una parte ViewObject.

Per illustrare il concetto, consideriamo il nostro oggetto cubo, le proprietà geometriche del cubo, come ad esempio le sue dimensioni, posizione, ecc .. sono memorizzate in Object, mentre le sue proprietà di visualizzazione, come il suo colore, spessore della linea, ecc .. sono memorizzati in ViewObject. Ciò corrisponde alle schede "Dati" e "Vista" nella finestra delle proprietà.

Alla parte ViewObject di un oggetto si accede in questo modo:

Ora è anche possibile modificare le proprietà della scheda "Vista":

Quando si avvia FreeCAD, la console python carica 2 moduli base: FreeCAD e FreeCADGui (a cui si può accedere anche dai collegamenti App e Gui). Essi contengono tutti i tipi di funzionalità generiche per lavorare con i documenti ed i loro oggetti.

Per illustrare questo concetto: notare che FreeCAD e FreeCADGui contengono entrambi un attributo ActiveDocument, che è il documento attualmente aperto.

FreeCAD.ActiveDocument e FreeCADGui.ActiveDocument non sono la stessa cosa. Essi sono i due componenti di un documento FreeCAD, e contengono attributi e metodi diversi. Ad esempio, FreeCADGui.ActiveDocument contiene ActiveView che è la vista 3D attualmente attiva.

Moduli
Ora vi starete sicuramente chiedendo che cosa si possa ancora fare con "Part:: Box".

L'applicazione di base di FreeCAD è più o meno un contenitore vuoto. Senza i suoi moduli, può fare poco più che creare nuovi documenti vuoti. La vera potenza di FreeCAD è nei suoi affidabili moduli.

Ogni modulo non solo aggiunge all'interfaccia nuovi ambienti di lavoro, ma aggiunge anche nuovi comandi Python e nuovi tipi di oggetti. Di conseguenza, nello stesso documento possono coesistere diversi tipi di oggetti, compresi anche oggetti totalmente incompatibili.

I moduli principali di FreeCAD, che vederemo in questo tutorial, sono Parte, Mesh, Schizzo e Draft.

I moduli Schizzo e Draft utilizzano entrambi il modulo Parte per creare e gestire le loro geometrie, che sono geometrie B-Rep, mentre il modulo Mesh è totalmente indipendente, e gestisce autonomamente i propri oggetti. In seguito saranno fornite ulteriori informazioni.

È possibile sapere quali tipi di oggetti di base sono disponibili per il documento corrente in questo modo:

I diversi moduli di FreeCAD, anche se hanno aggiunto a FreeCAD i loro tipi di oggetti, non sono caricati automaticamente nella console Python. Questo per evitare di avere un avvio molto lento. I moduli vengono caricati solo quando servono. Quindi, per esempio, per esplorare l'interno del modulo Parte:

Ma parleremo più avanti del modulo Parte.

Ora, si conosce qualcosa in più sui diversi moduli di FreeCAD: I moduli principali (FreeCAD, FreeCADGui) e i moduli degli ambienti di lavoro (Parte, Mesh, Schizzo). Gli altri moduli importanti sono il modulo della scena 3D (pivy) e il modulo dell'interfaccia (PyQt), in seguito parleremo anche di loro.

Ora è il momento di esplorare un po' in profondità i moduli più importanti, cioè quelli degli ambienti di lavoro.

Mesh
I Mesh sono un tipo molto semplice di oggetti 3D, utilizzati ad esempio da Sketchup, Blender o 3D studio Max. Essi sono composti da 3 elementi: i punti (chiamati anche vertici), le linee (chiamate anche bordi) e le facce. In molte applicazioni, inclusa FreeCAD, le facce possono avere solo tre vertici. Ma naturalmente nulla impedisce di avere una faccia piana più grande composta da diverse facce triangolari complanari.

Meshes are simple, this can be a bad thing, but for many applications such as those above, it turns to be an advantage, because they are so simple that you can easily have millions of them in a single document. In FreeCAD, though, they have less use, and are mostly there so you can import objects in mesh formats (.stl, .obj) from other applications. It was also extensively used as the main test module in the first month of life of FreeCAD.

Mesh objects and FreeCAD objects are different things. You can see the FreeCAD object as a container for a Mesh object (like, we'll see below, for Part objects too). So in order to add a mesh object to FreeCAD, we must first create a FreeCAD object and a Mesh object, then add the Mesh object to the FreeCAD object:

This is a standard example, that uses the createSphere method to automatically create a sphere, but you can very well create custom meshes from scratch, by defining their vertices and faces.

Read more about mesh scripting...

Part
The Part Module is the most powerful module of the whole FreeCAD. It allows to create and manipulate BRep objects. This kind of object, unlike meshes, can have a wide variety of components. To resume a bit, Brep means Boundary Representation. which means that they are defined by their surfaces, which enclose and define an inner volume. These surface can be a variety of things, such as plane faces or very complex NURBS surfaces. They also carry the concept of volume.

The Part module is based on the powerful OpenCasCade library, which allows a wide range of complex operations to be easily performed on those objects, such as boolean operations, filleting, lofts, etc...

The Part module works the same way as the Mesh module: You create a FreeCAD object, a Part object, then add the Part object to the FreeCAD object:

The Part module (like the Mesh module) also has a shortcut that automatically creates a FreeCAD object and add a shape to it, so you can skip the 3 last lines above:

By exploring the contents of myshape, you will notice many interesting available subcomponents such as Faces, Edges, Vertexes, Solids or Shells, and a wide range of geometry operations such as cut (subtraction), common (intersection) or fuse (union). The Topological data scripting page explains all that in detail.

Read more about part scripting...

Draft
FreeCAD features many more modules, such as Sketcher or Draft, which also create Part objects, but add parameters to it, or even carry a whole new way to handle the Part geometry in them. Our box example above, is a perfect example of parametric object. All you need, to define the box, is to specify a couple of parameters, such as height, width and length. Based on those, the object will automatically calculate its Part shape. FreeCAD allows you to create such objects in python.

The Draft Module adds a couple of 2D parametric objects types (which are all Part objects) such as lines and circles, and also provides some generic functions that work not only on Draft-made objects, but on any Part object. To explore what is available, simply do:

Interface
The FreeCAD user interface is made with Qt, a powerful graphical interface system, responsible for drawing and handling all the controls, menus, toolbars, buttons around the 3D view. Qt provides a module, called PyQt, which allows python to access and modify Qt interfaces, such as FreeCAD. Let's try to fiddle with the Qt interface and produce a simple dialog:

See that the dialog that appears has the FreeCAD icon in its toolbar, meaning that Qt knows that the order has been issued from inside the FreeCAD application. We can therefore easily directly manipulate any part of the FreeCAD interface.

Qt is a very powerful interface system, that allows you to do very complex things, but also has a couple of very easy-to use tools such as the Qt Designer with which you can design dialogs graphically and then add them to the FreeCAD interface with a couple of lines of python.

Read more about pyqt here...

Macros
Now that you have a good understanding of the basics, where are we going to keep our python scripts, and how are we going to launch them easily from FreeCAD? There is an easy mechanism for that, called Macros. A macro is simply a python script, that can then be added to a toolbar and be launched from a simple mouse click. FreeCAD provides you with a simple text editor (Macro -> Macros -> Create) where you can write or paste scripts. Once it is done, the Tools -> Customize -> Macros allow you to define a button for it, that can be added to toolbars.

Now you are ready for more in-depth FreeCAD scripting. Head on to the Power users hub!