Scripts/it

Work in progress -- need some revision

Introduzione
Per Scripting si intende l'uso dell'interprete Python interno di FreeCAD per generare oggetti. FreeCAD può essere usato come "ottimo" sostituto di OpenSCAD, perché possiede un vero e proprio interprete Python, con il pieno supporto per tutti i costrutti di un linguaggio di programmazione, quasi tutto quello che si può realizzare con l'interfaccia grafica è possibile realizzarlo anche attraverso uno script Python.

Le informazioni sullo scripting sono però sparse nella documentazione di FreeCAD, non c'è una uniformità di "scritture" e alcune cose sono spiegate in maniera complicata per chi comincia.

Primo assaggio
Purtroppo non esiste un modo per attivare direttamente con un comando di menù od un'icona nella barra degli strumenti, l'editor Python interno a FreeCAD, sapendo però che FreeCAD apre un file con estensione nell'editor Python interno, il trucco più semplice è quello di creare un file usando il proprio editor di testo preferito, poi aprirlo in FreeCAD con.

Per fare le cose con un minimo di stile, lo script deve essere scritto con un certo ordine. L'editor di FreeCAD possiede una decente "evidenziazione di sintassi" che manca a molti editor come Windows Notepad o altri editor di Linux di base, per cominciare basta scrivere queste poche righe:

Salvatele con un nome significativo e con estensione e caricate il file prodotto in FreeCAD, con il comando File -Apri.

Un esempio mimale ma che contiene tutto quanto necessario per uno script è mostrato in questa porzione di codice, che potete tranquillamente usare come modello per quasi ogni vostro futuro script:

Nel code qui sopra sono presenti alcuni trucchi:


 * Questa linea serve per importare FreeCAD all'interno dell'interprete Python, può sembrare superfluo, ma non lo è.
 * Base e Vector sono molto usati negli script in FreeCAD, importando questi due metodi in questo modo vi evita di scrivere oppure  al posto di   oppure, vi risparmiano quindi molto lavoro di battitura e rendono il codice più compatto.

Cominciamo con un piccolo script che un piccolo lavoro, ma dimostra la potenza di questo approccio.

Mettetelo dopo il codice di esempio e premete la freccia verde della Barra di strumenti Macro

You will see some magic things, a new document is open named "Pippo" (Italian name of Goofy) and you will see in the 3d view a cube, like the one in the image below.



Something more...
Not too amazing? Yes, but we have to start somewhere, we can do the same thing with a Cylinder, add these lines of code after the method and before the line.

Even here nothing too exciting. But please note some peculiarities:


 * The absence of the usual reference to the, present in many Documentation code snippets, is deliberate, this code could be used even invoking FreeCAD as a module in an external Python, the thing is not easily doable with an AppImage, but with some care it could be done. Plus in the standard Python motto that "better explicit than implicit"  is explaining in a very "poor" way where the things are from.
 * note the use of the "constant" name assigned to the active Document in = ; active Document is not a "constant" in a strict sense, but in a "semantical"  way is our "active Document", that for our use is a proper "constant" so the Python convention to use the  "ALL CAPS" name for "constants", not to mention that  is much shorten than.
 * every method returns a geometry, this became clear in the continuation of the page.
 * geometry didn't have the property, when using the simple geometries to make more complex geometry, managing  is a ankward thing.

Now what to do with this geometries?

Let's introduce boolean operations. As a starter example put these lines after, this create a method for a Fusion also know as Union operation:

Nothing exceptional also here, note however the uniformity in method coding; This approach is more linear that those seen around other tutorial on scripting, this "linearity" help greatly in readability and also with cut-copy-paste operations.

Let's use the geometries, delete lines below the code section starting with, and insert the following lines:

Launch the script with the green arrow and we will see in the 3D view something like:



Placement
Placement Concept is relatively complex, see Aeroplane Tutorial for a more deep explanation.

We usually are in need of placing geometries respect each other, when building complex object this is a recurring task, the most common way is to use the geometry property.

FreeCAD offer a wide choice of ways to set this property, one is more tailored to another depending the knowledge and the background of the user, but the more plain writing is explained in the cited Tutorial, it use a peculiar definition of the portion of, quite easy to learn.

But over other consideration, one thing is crucial, geometry reference point, in other word the point from which the object is modeled by FreeCAD, as described in this table, copied from Placement:

This information has to be keep in mind especially when we have to apply a rotation.

Some examples may help, delete all the line after method and insert the portion of code below:

Let's explain something in the code:


 * We have used a method to define a spehere, using the most easy definition, using only the radius.
 * We have introduced a second writing for the 'Union or Fusion, using multiple objects, not more distant from the usual Part::Fuse it uses Part:Multifuse and use only one property, we have passed a tuple as arguments, but it accepts also a list.
 * We have defined a complex object aeroplano (italian word for aeroplane), but we have done it in a "parametric" way, defining some parameters and deriving other parameters, through some calculation, based on the main parameters.
 * We have used some Placement poperties around in the method and before returning the final geometries we have used a  property with the Yaw-Pitch-Roll, writing. Note the last, that define a center of rotation of the whole geometry.

It can be easily noted that aeroplano geometry rotate around his "barycenter" or "center of gravity", that I've fixed at wing center, a place that is relatively "natural", but could be placed wherever you want.

The first  is the Translation vector, not used here, but if you substitute  with these lines to the code

You will se in the Report window this text:

What has happened?

FreeCAD has translated the in other word our  definition that specifies three components, Translation, Rotation and center of rotation in the "internal" values of only two components, Translation and Rotation'.

you can easily visualize the value of using a print statement in the  method and see that it is:

in other word the rotation center of the geometry is at, but this rotation center is not shown in the GUI, it could be entered as a value, it could not be easily retrieved.

This is the meaning of the word "ankward" that I've used to define property.