Scripts: Difference between revisions
m (→Posizionamento) |
No edit summary |
||
(90 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
<languages/> |
|||
<translate> |
|||
<!--T:42--> |
|||
== Introduzione allo Scripting == |
|||
{{Docnav |
|||
|[[Macros|Macros]] |
|||
|[[Introduction_to_Python|Introduction to Python]] |
|||
}} |
|||
<!--T:1--> |
|||
Per Scripting intendiamo l'uso dell'interprete Python interno di FreeCAD per generare oggetti, FreeCAD può essere usato come "ottimo" sostituto di OpenSCAD, anche 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 attraverso un programma Python. |
|||
{{TutorialInfo |
|||
|Topic=Scripting |
|||
|Level=Base |
|||
|Time= |
|||
|Author=onekk Carlo |
|||
|FCVersion=0.19 |
|||
|Files= |
|||
}} |
|||
== Introduction == <!--T:2--> |
|||
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. |
|||
<!--T:3--> |
|||
With Scripting we mean create topological objects using FreeCAD's Python interpreter. FreeCAD could be used as a "very good" replacement of OpenSCAD, mainly because it has a real Python interpreter, that means that it has a real programming language on board, almost everything you could do with the GUI, is doable with a Python Script. |
|||
<!--T:4--> |
|||
== Primo assaggio == |
|||
Sadly information about scripting in the documentation, and even in this wiki are scattered around and lacks of "writing" uniformity and most of them are explained in a too technical manner. |
|||
== Getting started == <!--T:5--> |
|||
Purtroppo non esiste un modo per attivare l'editor di Python interno, però c'è un trucco, FreeCAD apre un file con estensione '''.py''' nell'editor interno di Python, niente di più semplice che creare un file con il vostro editor di testo preferito, poi aprirlo con FreeCAD. |
|||
<!--T:6--> |
|||
Il modo più semplice è quello di battere queste poche righe: |
|||
The first obstacle in an easy way to scripting is that there is no direct way to access the FreeCAD internal Python editor through a menu item or a icon on the toolbar area, but knowing that FreeCAD opens a file with a {{incode|.py}} extension in the internal Python editor, the most simple trick is create in your favorite text editor and then open it with the usual command {{MenuCommand|File → Open}}. |
|||
<!--T:7--> |
|||
<nowiki> |
|||
To make the things in a polite way, the file has to be written with some order, FreeCAD Python editor have a good "Syntax Highlighting" that lacks in many simple editors like Windows Notepad or some basic Linux editors, so it is sufficient to write these few lines: |
|||
"""script.py |
|||
</translate> |
|||
Primo script per FreeCAD |
|||
{{Code|code= |
|||
"""filename.py |
|||
A short description of what the script does |
|||
""" |
""" |
||
}} |
|||
</nowiki> |
|||
<translate> |
|||
<!--T:8--> |
|||
Salvarlo e caricarlo in FreeCAD. |
|||
Save them with a meaningfull name with {{incode|.py}} extension and load the resulting file in FreeCAD, with the said {{MenuCommand|File → Open}} command. |
|||
<!--T:9--> |
|||
A minimal example of what is necessary to have in a script is shown in this portion of code that you could be use as a template for almost any future script: |
|||
</translate> |
|||
Il minimo indispensabile per lavorare in modo proficuo con FreeCAD è scrivere queste righe, che potete tranquillamente usare come modello: |
|||
{{Code|code= |
|||
"""filename.py |
|||
First FreeCAD Script |
|||
<nowiki> |
|||
"""nome del file.py |
|||
Descrizione di quello che fa lo script |
|||
""" |
""" |
||
import FreeCAD |
import FreeCAD |
||
from FreeCAD import |
from FreeCAD import Placement, Rotation, Vector |
||
import Part |
|||
from math import pi, sin, cos |
|||
DOC = FreeCAD.activeDocument() |
DOC = FreeCAD.activeDocument() |
||
DOC_NAME = " |
DOC_NAME = "Wiki_Example" |
||
# Helpers methods |
|||
def clear_doc(): |
def clear_doc(): |
||
"""Clear activeDocument deleting all the objects.""" |
|||
""" |
|||
Clear the active document deleting all the objects |
|||
""" |
|||
for obj in DOC.Objects: |
for obj in DOC.Objects: |
||
DOC.removeObject(obj.Name) |
DOC.removeObject(obj.Name) |
||
def setview(): |
def setview(): |
||
"""Rearrange View""" |
"""Rearrange View.""" |
||
FreeCAD.Gui.SendMsgToActiveView("ViewFit") |
FreeCAD.Gui.SendMsgToActiveView("ViewFit") |
||
FreeCAD.Gui.activeDocument().activeView().viewAxometric() |
FreeCAD.Gui.activeDocument().activeView().viewAxometric() |
||
if DOC is None: |
if DOC is None: |
||
Line 59: | Line 80: | ||
FreeCAD.setActiveDocument(DOC_NAME) |
FreeCAD.setActiveDocument(DOC_NAME) |
||
DOC = FreeCAD.activeDocument() |
DOC = FreeCAD.activeDocument() |
||
else: |
else: |
||
clear_doc() |
clear_doc() |
||
ROT0 = Rotation(0, 0, 0) |
|||
# EPS= tolerance to uset to cut the parts |
|||
VEC0 = Vector(0, 0, 0) |
|||
EPS = 0.10 |
|||
}} |
|||
EPS_C = EPS * -0.5 |
|||
<translate> |
|||
<!--T:10--> |
|||
Some tricks are incorporated in the above code: |
|||
<!--T:11--> |
|||
</nowiki> |
|||
* {{incode|import FreeCAD}} This line import FreeCAD in the FreeCAD Python interpreter, it may seem a redundant thing, but it isn't. |
|||
* {{incode|from FreeCAD import Placement, Rotation, Vector}} '''Placement''' '''Rotation''' and '''Vector''' are widely used in FreeCAD scripting, import them in this manner will save you to invoke them with {{incode|FreeCAD.Vector}} or {{incode|FreeCAD.Placement}} instead of {{incode|Vector}} or {{incode|Placement}}, this will save many keystrokes and make codelines much smaller. |
|||
<!--T:12--> |
|||
Alcuni trucchi sono incorporati in questo codice: |
|||
Let's start with a small script that does a very small job, but display the power of this approach. |
|||
</translate> |
|||
{{Code|code= |
|||
# Script methods |
|||
def my_box(name, len, wid, hei): |
|||
* <nowiki>import FreeCAD</nowiki> Questo serve per importare FreeCAD all'interno dell'interprete Python, può sembrare superfluo, ma non lo è |
|||
"""Create a box.""" |
|||
* <nowiki>from FreeCAD import Base, Vector</nowiki> Base e Vector sono molto usati, vi risparmiano molto test da battere se non fate dovete scrivere ad esempio <nowiki>FreeCAD.Vector</nowiki> ogni volta che usate un '''Vettore''' |
|||
obj_b = DOC.addObject("Part::Box", name) |
|||
obj_b.Length = len |
|||
obj_b.Width = wid |
|||
obj_b.Height = hei |
|||
DOC.recompute() |
|||
return obj_b |
|||
Partiamo con un piccolo script che fa poco, ma illustra la potenza di questo approccio. |
|||
# objects definition |
|||
obj = my_box("test_cube", 5, 5, 5) |
|||
<nowiki> |
|||
def cubo(nome, lung, larg, alt): |
|||
setview() |
|||
obj_b = DOC.addObject("Part::Box", nome) |
|||
}} |
|||
obj_b.Length = lung |
|||
<translate> |
|||
obj_b.Width = larg |
|||
obj_b.Height = alt |
|||
<!--T:13--> |
|||
Write above lines of code after {{incode|# Script methods}} and press the green arrow in the '''Macro toolbar''' |
|||
<!--T:14--> |
|||
You will see some magic things, a new document is open named "Wiki_example" and you will see in the 3d view a [[Part_Box|Cube]], like the one in the image below. |
|||
<!--T:44--> |
|||
[[File:Cubo.png|thumb|center|Test cube]] |
|||
== Something more == <!--T:15--> |
|||
<!--T:16--> |
|||
Not that amazing? Yes, but we have to start somewhere, we can do the same thing with a [[Part_Cylinder|Cylinder]], add these lines of code after the {{incode|my_box()}} method and before the line: {{incode|# objects definition}}. |
|||
</translate> |
|||
{{Code|code= |
|||
def my_cyl(name, ang, rad, hei): |
|||
"""Create a Cylinder.""" |
|||
obj = DOC.addObject("Part::Cylinder", name) |
|||
obj.Angle = ang |
|||
obj.Radius = rad |
|||
obj.Height = hei |
|||
DOC.recompute() |
DOC.recompute() |
||
return |
return obj |
||
}} |
|||
<translate> |
|||
<!--T:17--> |
|||
Even here nothing too exciting. But please note some peculiarities: |
|||
<!--T:18--> |
|||
* The absence of the usual reference to the {{incode|App.}}, present in many Documentation code snippets, is deliberate, this code could be used even invoking FreeCAD as a module in an external Python interpreter, 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" {{incode|App.}} 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 {{incode|DOC = FreeCAD.activeDocument()}}; activeDocument 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 {{incode|DOC}} is much shorten than {{incode|FreeCAD.activeDocument()}}. |
|||
* Every method returns a geometry, this will be clear in the continuation of the page. |
|||
* Geometry didn't have the {{incode|Placement}} property, when using the simple geometries to make more complex geometry, managing {{incode|Placement}} is a awkward thing. |
|||
<!--T:19--> |
|||
Now what to do with this geometries? |
|||
<!--T:20--> |
|||
Let's introduce boolean operations. As a starter example put these lines after {{incode|my_cyl}}, this create a method for a '''Fusion''' also know as '''Union''' operation: |
|||
</translate> |
|||
{{Code|code= |
|||
def fuse_obj(name, obj_0, obj_1): |
|||
"""Fuse two objects.""" |
|||
obj = DOC.addObject("Part::Fuse", name) |
|||
obj.Base = obj_0 |
|||
obj.Tool = obj_1 |
|||
obj.Refine = True |
|||
DOC.recompute() |
|||
return obj |
|||
}} |
|||
<translate> |
|||
<!--T:21--> |
|||
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. |
|||
<!--T:22--> |
|||
Let's use the geometries, delete lines below the code section starting with {{incode|# objects definition}}, and insert the following lines: |
|||
</translate> |
|||
{{Code|code= |
|||
# objects definition |
|||
obj = my_box("test_cube", 5, 5, 5) |
|||
obj1 = my_cyl("test_cyl", 360, 2, 10) |
|||
fuse_obj("Fusion", obj, obj1) |
|||
setview() |
setview() |
||
}} |
|||
<translate> |
|||
<!--T:23--> |
|||
</nowiki> |
|||
Launch the script with the green arrow and we will see in the 3D view something like: |
|||
<!--T:45--> |
|||
[[File:Cucil.png|thumb|center|Cube and cylinder]] |
|||
== Placement == <!--T:24--> |
|||
Mettetelo dopo il primo codice e premete la freccia della '''Barra di strumenti Macro''' |
|||
<!--T:25--> |
|||
e vedrete che si apre un nuovo file chiamato '''Pippo''' e si visualizza un cubo nella '''Vista 3D''', |
|||
Placement Concept is relatively complex, see [[Aeroplane|Aeroplane Tutorial]] for a more deep explanation. |
|||
<!--T:26--> |
|||
[[File:Cubo.png|thumb|center|Cubo di prova]] |
|||
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 {{incode|Placement}} property. |
|||
<!--T:27--> |
|||
== Qualcosa in più == |
|||
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 {{incode|Rotation}} portion of {{incode|Placement}}, quite easy to learn. |
|||
</translate> |
|||
Niente di eccezionale, quanto ci si può aspettare da un cubo, la stessa cosa possiamo fare con un cilindro, aggiugenete queste linee dopo il metodo che crea il cubo e prima della riga '''obj = cubo('''... |
|||
{{Code|code= |
|||
FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0)) |
|||
}} |
|||
<translate> |
|||
<!--T:28--> |
|||
<nowiki> |
|||
But over other consideration, one thing is crucial, geometry '''reference point''', in other words the point from which the object is modeled by FreeCAD, as described in this table, copied from [[Placement|Placement]]: |
|||
def base_cyl(nome, ang, rad, alt ): |
|||
obj = DOC.addObject("Part::Cylinder", nome) |
|||
<!--T:29--> |
|||
obj.Angle = ang |
|||
{| class="wikitable" border="1" |
|||
!Object!!Reference Point |
|||
|- |
|||
|Part.Box ||left (minx), front (miny), bottom (minz) vertex |
|||
|- |
|||
|Part.Sphere||center of the sphere |
|||
|- |
|||
|Part.Cylinder||center of the bottom face |
|||
|- |
|||
|Part.Cone||center of bottom face (or apex if bottom radius is 0) |
|||
|- |
|||
|Part.Torus||center of the torus |
|||
|- |
|||
|Features derived from Sketches||the Feature inherits the Position of the underlying Sketch. Sketches always start with Position = (0, 0, 0). This position corresponds to the origin in the sketch. |
|||
|} |
|||
<!--T:30--> |
|||
This information has to be kept in mind especially when we have to apply a rotation. |
|||
<!--T:31--> |
|||
Some examples may help, delete all the line after {{incode|my_cyl}} method and insert the portion of code below: |
|||
</translate> |
|||
{{Code|code= |
|||
def my_sphere(name, rad): |
|||
"""Create a Sphere.""" |
|||
obj = DOC.addObject("Part::Sphere", name) |
|||
obj.Radius = rad |
obj.Radius = rad |
||
obj.Height = alt |
|||
DOC.recompute() |
DOC.recompute() |
||
return obj |
return obj |
||
def my_box2(name, len, wid, hei, cent=False, off_z=0): |
|||
</nowiki> |
|||
"""Create a box with an optional z offset.""" |
|||
obj_b = DOC.addObject("Part::Box", name) |
|||
obj_b.Length = len |
|||
obj_b.Width = wid |
|||
obj_b.Height = hei |
|||
if cent is True: |
|||
pos = Vector(len * -0.5, wid * -0.5, off_z) |
|||
else: |
|||
pos = Vector(0, 0, off_z) |
|||
obj_b.Placement = Placement(pos, ROT0, VEC0) |
|||
Anche qui nulla di eccezionale, notiamo alcune nella costruzione del codice: |
|||
DOC.recompute() |
|||
* L'assenza dei riferimenti usuali in molta documentazione ad '''App.''', è pienamente voluto, in futuro si potrà riusare il codice per accedere a FreeCAD dall'esterno di FreeCAD, e sarà necessario importare FreeCAD come un normale modulo Python, con alcune accortezze. La scelta è volut anche nel solco degli standard di Python per cui è meglio sapere sempre da dove arrivano le cose, ovviamente App è poco significativo. |
|||
* La definizione all'inizio di una "costante" DOC, per contenere '''FreeCAD.activeDocument()''', ovviamente il nome "costante" è solo considerando dal punto di vista semantico il nostro "documento attivo", da qui l'uso della convenzione del nome "TUTTO MAIUSCOLO" per le "costanti". |
|||
* ogni metodo ritorna un geometriao, questo diventerà importante fra poco. |
|||
* la creazione della geometria non comporta la proprietà '''Placement''', se si utilizzano geometrie semplici per creare geometrie più complesse, la gestione della proprietà '''Placement''' è una cosa delicata. |
|||
return obj_b |
|||
Ora dobbiamo pur farci qualcosa con questi oggetti, be introduciamo le operazioni booleane, un esempio di metodo che compie un'operazione di '''Unione''' è questo: |
|||
def mfuse_obj(name, objs): |
|||
<nowiki> |
|||
"""Fuse multiple objects.""" |
|||
def fuse_obj(nome, obj_0, obj_1): |
|||
obj = DOC.addObject("Part:: |
obj = DOC.addObject("Part::MultiFuse", name) |
||
obj. |
obj.Shapes = objs |
||
obj.Tool = obj_1 |
|||
obj.Refine = True |
obj.Refine = True |
||
DOC.recompute() |
DOC.recompute() |
||
return obj |
return obj |
||
</nowiki> |
|||
def airplane(): |
|||
"""Create an airplane shaped solid.""" |
|||
fuselage_length = 30 |
|||
fuselage_diameter = 5 |
|||
wing_span = fuselage_length * 1.75 |
|||
wing_width = 7.5 |
|||
wing_thickness = 1.5 |
|||
tail_height = fuselage_diameter * 3.0 |
|||
tail_position = fuselage_length * 0.70 |
|||
tail_offset = tail_position - (wing_width * 0.5) |
|||
obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length) |
|||
anche qui nulla di eccezionale, notate però l'uso di molta uniformità nel codice, aiuta molto quando si vuole fare copia e incolla nella creazioni complesse. |
|||
obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset) |
|||
Inseriamo dopo il metodo '''base_cyl''' le righe sopra e modifichiamo quelle sotto in modo da leggere: |
|||
obj3 = my_sphere("nose", fuselage_diameter) |
|||
<nowiki> |
|||
obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0) |
|||
obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0) |
|||
# definizione oggetti |
|||
obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0) |
|||
objs = (obj1, obj2, obj3, obj4) |
|||
obj = mfuse_obj("airplane", objs) |
|||
obj1 = base_cyl('primo cilindro', 360,2,10) |
|||
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position)) |
|||
DOC.recompute() |
|||
fuse_obj("Fusione", obj, obj1) |
|||
</nowiki> |
|||
return obj |
|||
Lanciamo con il tasto freccia della '''barra strumenti macro''' e otteniamo: |
|||
# objects definition |
|||
[[File:Cucil.png|thumb|center|cubo e cilindro]] |
|||
airplane() |
|||
== Posizionamento == |
|||
setview() |
|||
Il concetto è relativamente complesso, vedere [[Aeroplane|Aeroplane tutorial]] per una trattazione più sistematica. |
|||
}} |
|||
<translate> |
|||
<!--T:32--> |
|||
Let's explain something in the code: |
|||
<!--T:33--> |
|||
* We have used a method to define a sphere, 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'''. We only use one property {{incode|Shapes}}. We have passed a '''tuple''' as arguments, but it accepts also a '''list'''. |
|||
* We have defined a complex object '''airplane''', 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 {{incode|Placement}} poperties around in the method and before returning the final geometries we have used a {{incode|Rotation}} property with the ''Yaw-Pitch-Roll'' writing. Note the last {{incode|Vector(0, 0, tail_position)}}, that define a '''center of rotation''' of the whole geometry. |
|||
<!--T:46--> |
|||
{| class="wikitable" |
|||
|- |
|||
| [[File:Aereo.png|thumb|left|Airplane example]] || [[File:Aereo2.png|thumb|center|Airplane rotated]]|| |
|||
[[File:Aereo-prop.png|thumb|center|Placement property]] |
|||
|} |
|||
<!--T:34--> |
|||
It can be easily noted that '''airplane''' 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. |
|||
<!--T:35--> |
|||
The first {{incode|Vector(0, 0, 0)}} is the Translation vector, not used here, but if you substitute {{incode|airplane()}} with these lines: |
|||
</translate> |
|||
{{Code|code= |
|||
obj_f = airplane() |
|||
print(obj_F.Placement) |
|||
}} |
|||
<translate> |
|||
<!--T:36--> |
|||
You will see in the Report window this text: |
|||
</translate> |
|||
{{Code|code= |
|||
Placement [Pos=(0, -21, 21), Yaw-Pitch-Roll=(0, 0, -90)] |
|||
}} |
|||
<translate> |
|||
<!--T:37--> |
|||
What has happened? |
|||
<!--T:38--> |
|||
FreeCAD has translated the {{incode|Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position)}} in other words our {{incode|Placement}} definition that specifies three components, '''Translation''', '''Rotation''' and '''center of rotation''' in the "internal" values of only two components, '''Translation''' and '''Rotation'''. |
|||
<!--T:39--> |
|||
you can easily visualize the value of {{incode|tail_position}} using a print statement in the {{incode|airplane()}} method and see that it is: |
|||
</translate> |
|||
{{Code|code= |
|||
tail_position = 21.0 |
|||
}} |
|||
<translate> |
|||
<!--T:40--> |
|||
in other words the '''rotation center''' of the geometry is at {{incode|Vector(0, 0, 21)}}, but this rotation center is not shown in the GUI, it could be entered as a {{incode|Placement}} value, it could not be easily retrieved. |
|||
<!--T:41--> |
|||
This is the meaning of the word "awkward" that I've used to define {{incode|Placement}} property. |
|||
<!--T:47--> |
|||
This is the complete code example with a decent script docstring following [https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google Google docstrings convention]: |
|||
<!--T:48--> |
|||
{{Code|code= |
|||
"""Sample code. |
|||
<!--T:49--> |
|||
Filename: |
|||
airplane.py |
|||
<!--T:50--> |
|||
Author: |
|||
Dormeletti Carlo (onekk) |
|||
<!--T:51--> |
|||
Version: |
|||
1.0 |
|||
<!--T:52--> |
|||
License: |
|||
Creative Commons Attribution 3.0 |
|||
<!--T:53--> |
|||
Summary: |
|||
This code is a sample code written for FreeCAD Wiki page. |
|||
It create and airplane shaped solid made using standard "Part WB" built in shapes. |
|||
<!--T:54--> |
|||
""" |
|||
<!--T:55--> |
|||
import FreeCAD |
|||
from FreeCAD import Placement, Rotation, Vector |
|||
<!--T:56--> |
|||
DOC = FreeCAD.activeDocument() |
|||
DOC_NAME = "Wiki_Example" |
|||
<!--T:57--> |
|||
# Helpers methods |
|||
<!--T:58--> |
|||
def clear_doc(): |
|||
"""Clear activeDocument deleting all the objects.""" |
|||
for obj in DOC.Objects: |
|||
DOC.removeObject(obj.Name) |
|||
<!--T:59--> |
|||
def setview(): |
|||
"""Rearrange View.""" |
|||
FreeCAD.Gui.SendMsgToActiveView("ViewFit") |
|||
FreeCAD.Gui.activeDocument().activeView().viewAxometric() |
|||
<!--T:60--> |
|||
if DOC is None: |
|||
FreeCAD.newDocument(DOC_NAME) |
|||
FreeCAD.setActiveDocument(DOC_NAME) |
|||
DOC = FreeCAD.activeDocument() |
|||
else: |
|||
clear_doc() |
|||
<!--T:61--> |
|||
ROT0 = Rotation(0, 0, 0) |
|||
VEC0 = Vector(0, 0, 0) |
|||
<!--T:62--> |
|||
# Script methods |
|||
<!--T:63--> |
|||
def my_cyl(name, ang, rad, hei): |
|||
"""Create a Cylinder.""" |
|||
obj = DOC.addObject("Part::Cylinder", name) |
|||
obj.Angle = ang |
|||
obj.Radius = rad |
|||
obj.Height = hei |
|||
<!--T:64--> |
|||
DOC.recompute() |
|||
<!--T:65--> |
|||
return obj |
|||
<!--T:66--> |
|||
def my_sphere(name, rad): |
|||
"""Create a Sphere.""" |
|||
obj = DOC.addObject("Part::Sphere", name) |
|||
obj.Radius = rad |
|||
<!--T:67--> |
|||
DOC.recompute() |
|||
<!--T:68--> |
|||
return obj |
|||
<!--T:69--> |
|||
def my_box2(name, len, wid, hei, cent=False, off_z=0): |
|||
"""Create a box with an optional z offset.""" |
|||
obj_b = DOC.addObject("Part::Box", name) |
|||
obj_b.Length = len |
|||
obj_b.Width = wid |
|||
obj_b.Height = hei |
|||
<!--T:70--> |
|||
if cent is True: |
|||
pos = Vector(len * -0.5, wid * -0.5, off_z) |
|||
else: |
|||
pos = Vector(0, 0, off_z) |
|||
<!--T:71--> |
|||
obj_b.Placement = Placement(pos, ROT0, VEC0) |
|||
<!--T:72--> |
|||
DOC.recompute() |
|||
<!--T:73--> |
|||
return obj_b |
|||
<!--T:74--> |
|||
def mfuse_obj(name, objs): |
|||
"""Fuse multiple objects.""" |
|||
obj = DOC.addObject("Part::MultiFuse", name) |
|||
obj.Shapes = objs |
|||
obj.Refine = True |
|||
DOC.recompute() |
|||
<!--T:75--> |
|||
return obj |
|||
<!--T:76--> |
|||
def airplane(): |
|||
"""Create an airplane shaped solid.""" |
|||
fuselage_length = 30 |
|||
fuselage_diameter = 5 |
|||
wing_span = fuselage_length * 1.75 |
|||
wing_width = 7.5 |
|||
wing_thickness = 1.5 |
|||
tail_height = fuselage_diameter * 3.0 |
|||
tail_position = fuselage_length * 0.70 |
|||
tail_offset = tail_position - (wing_width * 0.5) |
|||
<!--T:77--> |
|||
obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length) |
|||
<!--T:78--> |
|||
obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset) |
|||
<!--T:79--> |
|||
obj3 = my_sphere("nose", fuselage_diameter) |
|||
obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0) |
|||
<!--T:80--> |
|||
obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0) |
|||
obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0) |
|||
<!--T:81--> |
|||
objs = (obj1, obj2, obj3, obj4) |
|||
<!--T:82--> |
|||
obj = mfuse_obj("airplane", objs) |
|||
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position)) |
|||
<!--T:83--> |
|||
DOC.recompute() |
|||
<!--T:84--> |
|||
return obj |
|||
<!--T:85--> |
|||
# objects definition |
|||
<!--T:86--> |
|||
airplane() |
|||
<!--T:87--> |
|||
setview() |
|||
}} |
|||
<!--T:43--> |
|||
{{Docnav |
|||
|[[Macros|Macros]] |
|||
|[[Introduction_to_Python|Introduction to Python]] |
|||
}} |
|||
</translate> |
|||
'''Alla prossima!''' |
|||
{{Powerdocnavi{{#translation:}}}} |
|||
[[Category:Developer Documentation{{#translation:}}]] |
|||
[[Category:Python Code{{#translation:}}]] |
Latest revision as of 22:20, 6 November 2023
Tutorial |
Topic |
---|
Scripting |
Level |
Base |
Time to complete |
Authors |
onekk Carlo |
FreeCAD version |
0.19 |
Example files |
See also |
None |
Introduction
With Scripting we mean create topological objects using FreeCAD's Python interpreter. FreeCAD could be used as a "very good" replacement of OpenSCAD, mainly because it has a real Python interpreter, that means that it has a real programming language on board, almost everything you could do with the GUI, is doable with a Python Script.
Sadly information about scripting in the documentation, and even in this wiki are scattered around and lacks of "writing" uniformity and most of them are explained in a too technical manner.
Getting started
The first obstacle in an easy way to scripting is that there is no direct way to access the FreeCAD internal Python editor through a menu item or a icon on the toolbar area, but knowing that FreeCAD opens a file with a .py
extension in the internal Python editor, the most simple trick is create in your favorite text editor and then open it with the usual command File → Open.
To make the things in a polite way, the file has to be written with some order, FreeCAD Python editor have a good "Syntax Highlighting" that lacks in many simple editors like Windows Notepad or some basic Linux editors, so it is sufficient to write these few lines:
"""filename.py
A short description of what the script does
"""
Save them with a meaningfull name with .py
extension and load the resulting file in FreeCAD, with the said File → Open command.
A minimal example of what is necessary to have in a script is shown in this portion of code that you could be use as a template for almost any future script:
"""filename.py
First FreeCAD Script
"""
import FreeCAD
from FreeCAD import Placement, Rotation, Vector
DOC = FreeCAD.activeDocument()
DOC_NAME = "Wiki_Example"
# Helpers methods
def clear_doc():
"""Clear activeDocument deleting all the objects."""
for obj in DOC.Objects:
DOC.removeObject(obj.Name)
def setview():
"""Rearrange View."""
FreeCAD.Gui.SendMsgToActiveView("ViewFit")
FreeCAD.Gui.activeDocument().activeView().viewAxometric()
if DOC is None:
FreeCAD.newDocument(DOC_NAME)
FreeCAD.setActiveDocument(DOC_NAME)
DOC = FreeCAD.activeDocument()
else:
clear_doc()
ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)
Some tricks are incorporated in the above code:
import FreeCAD
This line import FreeCAD in the FreeCAD Python interpreter, it may seem a redundant thing, but it isn't.from FreeCAD import Placement, Rotation, Vector
Placement Rotation and Vector are widely used in FreeCAD scripting, import them in this manner will save you to invoke them withFreeCAD.Vector
orFreeCAD.Placement
instead ofVector
orPlacement
, this will save many keystrokes and make codelines much smaller.
Let's start with a small script that does a very small job, but display the power of this approach.
# Script methods
def my_box(name, len, wid, hei):
"""Create a box."""
obj_b = DOC.addObject("Part::Box", name)
obj_b.Length = len
obj_b.Width = wid
obj_b.Height = hei
DOC.recompute()
return obj_b
# objects definition
obj = my_box("test_cube", 5, 5, 5)
setview()
Write above lines of code after # Script methods
and press the green arrow in the Macro toolbar
You will see some magic things, a new document is open named "Wiki_example" and you will see in the 3d view a Cube, like the one in the image below.
Something more
Not that amazing? Yes, but we have to start somewhere, we can do the same thing with a Cylinder, add these lines of code after the my_box()
method and before the line: # objects definition
.
def my_cyl(name, ang, rad, hei):
"""Create a Cylinder."""
obj = DOC.addObject("Part::Cylinder", name)
obj.Angle = ang
obj.Radius = rad
obj.Height = hei
DOC.recompute()
return obj
Even here nothing too exciting. But please note some peculiarities:
- The absence of the usual reference to the
App.
, present in many Documentation code snippets, is deliberate, this code could be used even invoking FreeCAD as a module in an external Python interpreter, 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"App.
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
DOC = FreeCAD.activeDocument()
; activeDocument 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 thatDOC
is much shorten thanFreeCAD.activeDocument()
. - Every method returns a geometry, this will be clear in the continuation of the page.
- Geometry didn't have the
Placement
property, when using the simple geometries to make more complex geometry, managingPlacement
is a awkward thing.
Now what to do with this geometries?
Let's introduce boolean operations. As a starter example put these lines after my_cyl
, this create a method for a Fusion also know as Union operation:
def fuse_obj(name, obj_0, obj_1):
"""Fuse two objects."""
obj = DOC.addObject("Part::Fuse", name)
obj.Base = obj_0
obj.Tool = obj_1
obj.Refine = True
DOC.recompute()
return obj
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 # objects definition
, and insert the following lines:
# objects definition
obj = my_box("test_cube", 5, 5, 5)
obj1 = my_cyl("test_cyl", 360, 2, 10)
fuse_obj("Fusion", obj, obj1)
setview()
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 Placement
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 Rotation
portion of Placement
, quite easy to learn.
FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0))
But over other consideration, one thing is crucial, geometry reference point, in other words the point from which the object is modeled by FreeCAD, as described in this table, copied from Placement:
Object | Reference Point |
---|---|
Part.Box | left (minx), front (miny), bottom (minz) vertex |
Part.Sphere | center of the sphere |
Part.Cylinder | center of the bottom face |
Part.Cone | center of bottom face (or apex if bottom radius is 0) |
Part.Torus | center of the torus |
Features derived from Sketches | the Feature inherits the Position of the underlying Sketch. Sketches always start with Position = (0, 0, 0). This position corresponds to the origin in the sketch. |
This information has to be kept in mind especially when we have to apply a rotation.
Some examples may help, delete all the line after my_cyl
method and insert the portion of code below:
def my_sphere(name, rad):
"""Create a Sphere."""
obj = DOC.addObject("Part::Sphere", name)
obj.Radius = rad
DOC.recompute()
return obj
def my_box2(name, len, wid, hei, cent=False, off_z=0):
"""Create a box with an optional z offset."""
obj_b = DOC.addObject("Part::Box", name)
obj_b.Length = len
obj_b.Width = wid
obj_b.Height = hei
if cent is True:
pos = Vector(len * -0.5, wid * -0.5, off_z)
else:
pos = Vector(0, 0, off_z)
obj_b.Placement = Placement(pos, ROT0, VEC0)
DOC.recompute()
return obj_b
def mfuse_obj(name, objs):
"""Fuse multiple objects."""
obj = DOC.addObject("Part::MultiFuse", name)
obj.Shapes = objs
obj.Refine = True
DOC.recompute()
return obj
def airplane():
"""Create an airplane shaped solid."""
fuselage_length = 30
fuselage_diameter = 5
wing_span = fuselage_length * 1.75
wing_width = 7.5
wing_thickness = 1.5
tail_height = fuselage_diameter * 3.0
tail_position = fuselage_length * 0.70
tail_offset = tail_position - (wing_width * 0.5)
obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)
obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)
obj3 = my_sphere("nose", fuselage_diameter)
obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)
obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)
objs = (obj1, obj2, obj3, obj4)
obj = mfuse_obj("airplane", objs)
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))
DOC.recompute()
return obj
# objects definition
airplane()
setview()
Let's explain something in the code:
- We have used a method to define a sphere, 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. We only use one property
Shapes
. We have passed a tuple as arguments, but it accepts also a list. - We have defined a complex object airplane, 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
Placement
poperties around in the method and before returning the final geometries we have used aRotation
property with the Yaw-Pitch-Roll writing. Note the lastVector(0, 0, tail_position)
, that define a center of rotation of the whole geometry.
It can be easily noted that airplane 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 Vector(0, 0, 0)
is the Translation vector, not used here, but if you substitute airplane()
with these lines:
obj_f = airplane()
print(obj_F.Placement)
You will see in the Report window this text:
Placement [Pos=(0, -21, 21), Yaw-Pitch-Roll=(0, 0, -90)]
What has happened?
FreeCAD has translated the Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position)
in other words our Placement
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 tail_position
using a print statement in the airplane()
method and see that it is:
tail_position = 21.0
in other words the rotation center of the geometry is at Vector(0, 0, 21)
, but this rotation center is not shown in the GUI, it could be entered as a Placement
value, it could not be easily retrieved.
This is the meaning of the word "awkward" that I've used to define Placement
property.
This is the complete code example with a decent script docstring following Google docstrings convention:
"""Sample code.
Filename:
airplane.py
Author:
Dormeletti Carlo (onekk)
Version:
1.0
License:
Creative Commons Attribution 3.0
Summary:
This code is a sample code written for FreeCAD Wiki page.
It create and airplane shaped solid made using standard "Part WB" built in shapes.
"""
import FreeCAD
from FreeCAD import Placement, Rotation, Vector
DOC = FreeCAD.activeDocument()
DOC_NAME = "Wiki_Example"
# Helpers methods
def clear_doc():
"""Clear activeDocument deleting all the objects."""
for obj in DOC.Objects:
DOC.removeObject(obj.Name)
def setview():
"""Rearrange View."""
FreeCAD.Gui.SendMsgToActiveView("ViewFit")
FreeCAD.Gui.activeDocument().activeView().viewAxometric()
if DOC is None:
FreeCAD.newDocument(DOC_NAME)
FreeCAD.setActiveDocument(DOC_NAME)
DOC = FreeCAD.activeDocument()
else:
clear_doc()
ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)
# Script methods
def my_cyl(name, ang, rad, hei):
"""Create a Cylinder."""
obj = DOC.addObject("Part::Cylinder", name)
obj.Angle = ang
obj.Radius = rad
obj.Height = hei
DOC.recompute()
return obj
def my_sphere(name, rad):
"""Create a Sphere."""
obj = DOC.addObject("Part::Sphere", name)
obj.Radius = rad
DOC.recompute()
return obj
def my_box2(name, len, wid, hei, cent=False, off_z=0):
"""Create a box with an optional z offset."""
obj_b = DOC.addObject("Part::Box", name)
obj_b.Length = len
obj_b.Width = wid
obj_b.Height = hei
if cent is True:
pos = Vector(len * -0.5, wid * -0.5, off_z)
else:
pos = Vector(0, 0, off_z)
obj_b.Placement = Placement(pos, ROT0, VEC0)
DOC.recompute()
return obj_b
def mfuse_obj(name, objs):
"""Fuse multiple objects."""
obj = DOC.addObject("Part::MultiFuse", name)
obj.Shapes = objs
obj.Refine = True
DOC.recompute()
return obj
def airplane():
"""Create an airplane shaped solid."""
fuselage_length = 30
fuselage_diameter = 5
wing_span = fuselage_length * 1.75
wing_width = 7.5
wing_thickness = 1.5
tail_height = fuselage_diameter * 3.0
tail_position = fuselage_length * 0.70
tail_offset = tail_position - (wing_width * 0.5)
obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)
obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)
obj3 = my_sphere("nose", fuselage_diameter)
obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)
obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)
objs = (obj1, obj2, obj3, obj4)
obj = mfuse_obj("airplane", objs)
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))
DOC.recompute()
return obj
# objects definition
airplane()
setview()
- 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