Scripts/fr: Difference between revisions
(Created page with "== Vous ouvrir l'appétit ==") |
No edit summary Tag: Manual revert |
||
(84 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
<languages/> |
<languages/> |
||
{{Docnav/fr |
|||
|[[Macros/fr|Macros]] |
|||
|[[Introduction_to_Python/fr|Introduction à Python]] |
|||
}} |
|||
{{TutorialInfo/fr |
{{TutorialInfo/fr |
||
|Topic=Scripting |
|Topic=Scripting |
||
Line 11: | Line 17: | ||
== Introduction == |
== Introduction == |
||
Par script, nous entendons la création d'objets topologiques à l'aide de l'interpréteur Python de FreeCAD. FreeCAD pourrait être utilisé comme un "très bon" remplaçant d'OpenSCAD, principalement parce qu'il possède un véritable interpréteur Python, ce qui signifie qu'il dispose d'un véritable langage de programmation, presque tout ce que vous pouvez faire avec l'interface graphique est réalisable avec un script Python. |
|||
Malheureusement, les informations sur les scripts dans la documentation, et même dans ce wiki sont éparpillées et manquent d'uniformité "d'écriture" et la plupart d'entre elles sont expliquées d'une manière trop technique. |
Malheureusement, les informations sur les scripts dans la documentation, et même dans ce wiki sont éparpillées et manquent d'uniformité "d'écriture" et la plupart d'entre elles sont expliquées d'une manière trop technique. |
||
<span id="Getting_started"></span> |
|||
== Commencer == |
|||
Le premier obstacle d'une manière simple à la création de scripts est qu'il n'y a pas de moyen direct d'accéder à l'éditeur Python interne de FreeCAD via un élément de menu ou une icône dans la zone de la barre d'outils, mais sachant que FreeCAD ouvre un fichier avec un {{incode|.py }} dans l'éditeur Python interne, l'astuce la plus simple est de créer dans votre éditeur de texte préféré, puis de l'ouvrir avec la commande habituelle {{MenuCommand|Fichier → Ouvrir}}. |
|||
== Vous ouvrir l'appétit == |
|||
Pour faire les choses d'une manière polie, le fichier doit être écrit avec un certain ordre, l'éditeur Python FreeCAD a une bonne "Syntaxe Highlighting" qui manque dans de nombreux éditeurs simples comme le Notepad de Windows ou certains éditeurs Linux de base, il suffit donc d'écrire ces quelques lignes : |
|||
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}}. |
|||
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: |
|||
{{Code|code= |
{{Code|code= |
||
""" |
"""filename.py |
||
A short description of what the script does |
|||
Primo script per FreeCAD |
|||
""" |
""" |
||
}} |
}} |
||
Enregistrez-les avec un nom significatif avec l'extension {{incode|.py}} et chargez le fichier résultant dans FreeCAD, avec la commande {{MenuCommand|Fichier → Ouvrir}}. |
|||
Un exemple simple de ce qu'il est nécessaire d'avoir dans un script est présenté dans cette partie du code que vous pourriez utiliser comme modèle pour presque tous les futurs scripts: |
|||
Save them with a meaningfull name with {{incode|.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: |
|||
{{Code|code= |
{{Code|code= |
||
"""filename.py |
"""filename.py |
||
First FreeCAD Script |
|||
Here a short but significant description of what the script do |
|||
""" |
""" |
||
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 70: | Line 69: | ||
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 use to cut the parts |
|||
VEC0 = Vector(0, 0, 0) |
|||
EPS = 0.10 |
|||
EPS_C = EPS * -0.5 |
|||
}} |
}} |
||
Certaines astuces sont incorporées dans le code ci-dessus: |
|||
Some tricks are incorporated in the above code: |
|||
* {{incode|import FreeCAD}} Cette ligne importe FreeCAD dans l'interpréteur FreeCAD Python, cela peut sembler redondant, mais ce n'est pas le cas. |
|||
* {{incode|from FreeCAD import Placement, Rotation, Vector}} '''Placement''' '''Rotation''' et '''Vector''' sont largement utilisés dans l'écriture de scripts FreeCAD, les importer de cette manière vous évitera de les appeler avec {{incode|FreeCAD.Vector}} ou {{incode|FreeCAD.Placement}} au lieu de {{incode|Vector}} ou {{incode|Placement}}, cela économisera de nombreuses frappes et rendra les lignes de code beaucoup plus petites. |
|||
Commençons par un petit script qui fait un très petit travail, mais qui montre la puissance de cette approche. |
|||
* {{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 Base, Vector}} Base and Vector are widely used in FreeCAD scipting, import them in this manner will save you to invoke them with {{incode|FreeCAD.Vector}} or {{incode|FreeCAD.Base}} instead of {{incode|Base}} or {{incode|Vector}}, this will save many keystrokes and make codelines much smaller. |
|||
{{Code|code= |
|||
# Script methods |
|||
def my_box(name, len, wid, hei): |
|||
Let's start with a small script that does a very small job, but display the power of this approach. |
|||
"""Create a box.""" |
|||
obj_b = DOC.addObject("Part::Box", name) |
|||
{{Code|code= |
|||
obj_b.Length = len |
|||
def cubo(nome, lung, larg, alt): |
|||
obj_b = |
obj_b.Width = wid |
||
obj_b. |
obj_b.Height = hei |
||
obj_b.Width = larg |
|||
obj_b.Height = alt |
|||
DOC.recompute() |
DOC.recompute() |
||
Line 103: | Line 99: | ||
# objects definition |
# objects definition |
||
obj = |
obj = my_box("test_cube", 5, 5, 5) |
||
setview() |
setview() |
||
}} |
}} |
||
Ecrivez les lignes de code ci-dessus après {{incode|# Script methods}} et appuyez sur la flèche verte dans la '''Barre d'outils des macros''' |
|||
Put these lines after the "template" code and press the green arrow in the '''Macro toolbar''' |
|||
Vous verrez des choses magiques, un nouveau document est ouvert nommé "Wiki_example" et vous verrez dans la vue 3D un [[Part_Box/fr|Cube]] comme ci-dessous. |
|||
[[File:Cubo.png|thumb|center| |
[[File:Cubo.png|thumb|center|Cube de test]] |
||
<span id="Something_more"></span> |
|||
== Something more... == |
|||
== Quelque chose en plus == |
|||
Pas si surprenant ? Oui, mais il faut commencer quelque part, on peut faire la même chose avec un [[Part_Cylinder/fr|Cylindre]], ajouter ces lignes de code après la méthode {{incode|my_box()}} et avant la ligne : {{incode|# objects definition}}. |
|||
{{Code|code= |
{{Code|code= |
||
def |
def my_cyl(name, ang, rad, hei): |
||
"""Create a Cylinder.""" |
|||
obj = DOC.addObject("Part::Cylinder", nome) |
|||
obj = DOC.addObject("Part::Cylinder", name) |
|||
obj.Angle = ang |
obj.Angle = ang |
||
obj.Radius = rad |
obj.Radius = rad |
||
obj.Height = |
obj.Height = hei |
||
DOC.recompute() |
DOC.recompute() |
||
return obj |
return obj |
||
}} |
}} |
||
Même ici, rien de trop excitant. Mais veuillez noter quelques particularités: |
|||
Even here nothing too exciting. But please note some peculiarities: |
|||
* |
* L'absence de la référence habituelle à l '{{incode|App.}}, présente dans de nombreux extraits de code de documentation est délibérée. Ce code pourrait être utilisé même en invoquant FreeCAD comme module dans un interpréteur Python externe, la chose n'est pas facilement faisable avec une AppImage, mais avec un certain soin, cela pourrait être fait. De plus, dans la devise standard de Python, "mieux explicite qu'implicite", {{incode|App.}} explique de manière très "mal" d'où viennent les choses. |
||
* |
* Notez l'utilisation du nom "constant" attribué au document actif dans {{incode|DOC = FreeCAD.activeDocument()}}. activeDocument n'est pas une "constante" au sens strict, mais d'une manière "sémantique" c'est notre "Document actif", qui pour notre utilisation sera une "constante" appropriée. La convention Python d'utiliser le nom "ALL CAPS" pour "constantes", sans oublier que {{incode|DOC}} est beaucoup plus court que {{incode|FreeCAD.activeDocument()}}. |
||
* |
* Chaque méthode retourne une géométrie, cela sera clair dans la suite de la page. |
||
* |
* Géométrie n'avait pas la propriété {{incode|Placement}}, lors de l'utilisation de géométries simples pour créer une géométrie plus complexe, gérer {{incode|Placement}} est une chose délicate. |
||
Maintenant, que faire avec ces géométries? |
|||
Now what to do with this geometries? |
|||
Introduisons les opérations booléennes. Comme exemple pour démmarrer, placez ces lignes après {{incode|my_cyl}}, cela crée une méthode pour une '''Fusion''' également connue sous le nom d'opération '''Union''' : |
|||
{{Code|code= |
{{Code|code= |
||
def fuse_obj( |
def fuse_obj(name, obj_0, obj_1): |
||
"""Fuse two objects.""" |
|||
obj = DOC.addObject("Part::Fuse", nome) |
|||
obj = DOC.addObject("Part::Fuse", name) |
|||
obj.Base = obj_0 |
obj.Base = obj_0 |
||
obj.Tool = obj_1 |
obj.Tool = obj_1 |
||
Line 154: | Line 151: | ||
}} |
}} |
||
Rien d'exceptionnel ici aussi, notez cependant l'uniformité dans le codage des méthodes; Cette approche est plus linéaire que celles vues autour d'autres tutoriels sur les scripts, cette "linéarité" aide grandement à la lisibilité et aussi avec les opérations couper-copier-coller. |
|||
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. |
|||
Utilisons les géométries, supprimons les lignes sous la section de code commençant par {{incode|# objects definition}} et insérons les lignes suivantes: |
|||
{{Code|code= |
{{Code|code= |
||
# objects definition |
# objects definition |
||
obj = |
obj = my_box("test_cube", 5, 5, 5) |
||
obj1 = |
obj1 = my_cyl("test_cyl", 360, 2, 10) |
||
fuse_obj(" |
fuse_obj("Fusion", obj, obj1) |
||
setview() |
setview() |
||
}} |
}} |
||
Lancez le script avec la flèche verte et nous verrons dans la vue 3D quelque chose comme : |
|||
[[File:Cucil.png|thumb|center| |
[[File:Cucil.png|thumb|center|Cube et cylindre]] |
||
== Placement == |
== Placement == |
||
Le concept de placement est relativement complexe, voir [[Aeroplane/fr|tutoriel avion]] pour une explication plus approfondie. |
|||
Nous avons généralement besoin de placer des géométries respectueuses les unes des autres, lorsque la construction d'un objet complexe est une tâche récurrente, le moyen le plus courant est d'utiliser la propriété geometry {{incode|Placement}}. |
|||
FreeCAD |
FreeCAD offre un large choix de moyens pour définir cette propriété, l'un est plus adapté à l'autre en fonction des connaissances et du parcours de l'utilisateur, mais plus l'écriture est simple et expliquée dans le Tutoriel cité, plus il utilise une définition particulière de la partie {{incode|Rotation}} de {{incode|Placement}}, assez facile à apprendre. |
||
{{Code|code= |
{{Code|code= |
||
FreeCAD.Placement(Vector(0,0,0), FreeCAD.Rotation(10,20,30), Vector(0,0,0)) |
FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0)) |
||
}} |
}} |
||
Mais par rapport à d'autres considérations, une chose est cruciale, la géométrie '''point de référence''', c'est-à-dire le point à partir duquel l'objet est modélisé par FreeCAD, comme décrit dans ce tableau, copié de [[Placement/fr|Placement]] : |
|||
{| class="wikitable" border="1" |
{| class="wikitable" border="1" |
||
! |
!Objet!!Point de référence |
||
|- |
|||
|- align="left" |
|||
|Part.Box || |
|Part.Box ||gauche (minx), avant (miny), bas (minz) sommet |
||
|- |
|||
|- align="left" |
|||
|Part.Sphere|| |
|Part.Sphere||centre de la sphère |
||
|- |
|||
|- align="left" |
|||
|Part.Cylinder|| |
|Part.Cylinder||centre de la face inférieure |
||
|- |
|||
|- align="left" |
|||
|Part.Cone|| |
|Part.Cone||centre de la face inférieure (ou sommet si le rayon inférieur est 0) |
||
|- |
|||
|- align="left" |
|||
|Part.Torus|| |
|Part.Torus||centre du tore |
||
|- |
|||
|- align="left" |
|||
| |
|Fonctions dérivées d'esquisses||La fonction hérite de la position de l'esquisse sous-jacente. Les esquisses commencent toujours par Position = (0, 0, 0). Cette position correspond à l'origine dans l'esquisse. |
||
|} |
|} |
||
Cette information doit être gardée à l'esprit, en particulier lorsque nous devons appliquer une rotation. |
|||
Quelques exemples peuvent aider, supprimez toute la ligne après la méthode {{incode|my_cyl}} et insérez la partie de code ci-dessous : |
|||
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 {{incode|base_cyl}} method and insert the portion of code below: |
|||
{{Code|code= |
{{Code|code= |
||
def my_sphere(name, rad): |
|||
"""Create a Sphere.""" |
|||
def sfera(nome, rad): |
|||
obj = DOC.addObject("Part::Sphere", |
obj = DOC.addObject("Part::Sphere", name) |
||
obj.Radius = rad |
obj.Radius = rad |
||
DOC.recompute() |
DOC.recompute() |
||
return obj |
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( |
def mfuse_obj(name, objs): |
||
"""Fuse multiple objects.""" |
|||
obj = DOC.addObject("Part::MultiFuse", nome) |
|||
obj = DOC.addObject("Part::MultiFuse", name) |
|||
obj.Shapes = objs |
obj.Shapes = objs |
||
obj.Refine = True |
obj.Refine = True |
||
Line 231: | Line 242: | ||
return obj |
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) |
|||
def aeroplano(): |
|||
obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset) |
|||
lung_fus = 30 |
|||
diam_fus = 5 |
|||
ap_alare = lung_fus * 1.75 |
|||
larg_ali = 7.5 |
|||
spess_ali = 1.5 |
|||
alt_imp = diam_fus * 3.0 |
|||
pos_ali = (lung_fus*0.70) |
|||
off_ali = (pos_ali - (larg_ali * 0.5)) |
|||
obj3 = my_sphere("nose", fuselage_diameter) |
|||
obj1 = base_cyl('primo cilindro', 360, diam_fus, lung_fus) |
|||
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) |
|||
obj3 = sfera("naso", diam_fus) |
|||
obj3.Placement = FreeCAD.Placement(Vector(0,0,lung_fus), FreeCAD.Rotation(0,0,0), Vector(0,0,0)) |
|||
obj4 = cubo('impennaggio', spess_ali, alt_imp, larg_ali, False, 0) |
|||
obj4.Placement = FreeCAD.Placement(Vector(0,alt_imp * -1,0), FreeCAD.Rotation(0,0,0), Vector(0,0,0)) |
|||
objs = (obj1, obj2, obj3, obj4) |
objs = (obj1, obj2, obj3, obj4) |
||
obj = mfuse_obj(" |
obj = mfuse_obj("airplane", objs) |
||
obj.Placement = |
obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position)) |
||
DOC.recompute() |
DOC.recompute() |
||
Line 264: | Line 274: | ||
# objects definition |
# objects definition |
||
airplane() |
|||
aeroplano() |
|||
setview() |
setview() |
||
Line 270: | Line 280: | ||
}} |
}} |
||
Expliquons quelque chose dans le code: |
|||
* Nous avons utilisé une méthode pour définir une sphère, en utilisant la définition la plus simple, en utilisant uniquement le rayon. |
|||
* We have used a method to define a spehere, using the most easy definition, using only the radius. |
|||
* |
* Nous avons introduit une deuxième écriture pour '''Union''' ou '''Fusion''', en utilisant plusieurs objets, pas trés éloignés de l'habituel '''Part::Fuse''' qu'il utilise '''Part:Multifuse''' et n'utilise qu'une seule propriété {{incode|Shapes}}. Nous avons passé un '''tuple''' comme arguments mais il accepte aussi une '''liste'''. |
||
* Nous avons défini un objet complexe '''un avion''' mais nous l'avons fait de manière '''"paramétrique"''' en définissant certains paramètres et en dérivant d'autres paramètres, grâce à des calculs , basé sur les principaux paramètres. |
|||
* 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. |
|||
* |
* Nous avons utilisé des propriétés de placement {{incode|Placement}} dans la méthode et avant de renvoyer les géométries finales, nous avons utilisé une propriété {{incode|Rotation}} avec l'écriture ''Yaw-Pitch-Roll''. Notez le dernier {{incode|Vector(0, 0, tail_position)}} qui définit un '''centre de rotation''' de toute la géométrie. |
||
{| class="wikitable" |
{| class="wikitable" |
||
|- |
|- |
||
| [[File:Aereo.png|thumb|left| |
| [[File:Aereo.png|thumb|left|Exemple d'un avion]] || [[File:Aereo2.png|thumb|center|Rotation de l'avion]]|| |
||
[[File:Aereo-prop.png|thumb|center| |
[[File:Aereo-prop.png|thumb|center|Propriété de placement]] |
||
|} |
|} |
||
On peut facilement remarquer que la géométrie de l''''avion''' tourne autour de son "barycentre" ou "centre de gravité", que j'ai fixé au centre de l'aile, un endroit relativement "naturel", mais qui pourrait être placé n'importe où vous voulez. |
|||
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. |
|||
Le premier {{incode|Vector(0, 0, 0)}} est le vecteur de translation, non utilisé ici, mais si vous remplacez {{incode|airplane()}} par ces lignes : |
|||
{{Code|code= |
{{Code|code= |
||
obj_f = airplane() |
|||
obj_f = aeroplano() |
|||
print(obj_F.Placement) |
print(obj_F.Placement) |
||
}} |
|||
Vous verrez dans la fenêtre Rapport ce texte: |
|||
{{Code|code= |
|||
Placement [Pos=(0, -21, 21), Yaw-Pitch-Roll=(0, 0, -90)] |
|||
}} |
}} |
||
Que s'est-il passé? |
|||
You will see in the Report window this text: |
|||
FreeCAD a traduit {{incode|Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position)}} en d'autres termes notre définition {{incode|Placement}} qui spécifie trois composants, '''Translation''', '''Rotation''' et '''centre de rotation''' en valeurs "internes" de seulement deux composants, '''Translation''' et '''Rotation'''. |
|||
vous pouvez facilement visualiser la valeur de {{incode|tail_position}} en utilisant une instruction print dans la méthode {{incode|airplane()}} et voir que c'est : |
|||
{{Code|code= |
{{Code|code= |
||
tail_position = 21.0 |
|||
Placement [Pos=(0,-21,21), Yaw-Pitch-Roll=(0,0,-90)] |
|||
}} |
}} |
||
en d'autres termes, le '''centre de rotation''' de la géométrie est à {{incode|Vector(0, 0, 21)}}, mais ce centre de rotation n'est pas affiché dans l'interface graphique, il pourrait être entré comme {{incode|Placement}}, il n'a pas pu être facilement récupéré. |
|||
What has happened? |
|||
C'est le sens du mot "maladroit" que j'ai utilisé pour définir la propriété {{incode|Placement}}. |
|||
FreeCAD has translated the {{incode|Vector(0,0,0), FreeCAD.Rotation(0,0,-90), Vector(0,0,pos_ali)}} in other word 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'''. |
|||
you can easily visualize the value of {{incode|pos_ali}} using a print statement in the {{incode|aeroplano(...}} method and see that it is: |
|||
Voici l'exemple de code complet avec un docstring de script décent selon la [https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google convention de docstrings de Google] : |
|||
{{Code|code= |
{{Code|code= |
||
"""Sample code. |
|||
pos ali = 21.0 |
|||
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() |
|||
}} |
}} |
||
in other word 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. |
|||
{{Docnav/fr |
|||
This is the meaning of the word "awkward" that I've used to define {{incode|Placement}} property. |
|||
|[[Macros/fr|Macros]] |
|||
|[[Introduction_to_Python/fr|Introduction à Python]] |
|||
}} |
|||
{{Powerdocnavi{{#translation:}}}} |
{{Powerdocnavi{{#translation:}}}} |
||
[[Category:Developer Documentation{{#translation:}}]] |
[[Category:Developer Documentation{{#translation:}}]] |
||
[[Category:Python Code{{#translation:}}]] |
[[Category:Python Code{{#translation:}}]] |
||
{{clear}} |
Latest revision as of 21:10, 7 November 2023
Tutoriel |
Thème |
---|
Scripting |
Niveau |
Base |
Temps d'exécution estimé |
Auteurs |
onekk Carlo |
Version de FreeCAD |
0.19 |
Fichiers exemples |
Voir aussi |
None |
Introduction
Par script, nous entendons la création d'objets topologiques à l'aide de l'interpréteur Python de FreeCAD. FreeCAD pourrait être utilisé comme un "très bon" remplaçant d'OpenSCAD, principalement parce qu'il possède un véritable interpréteur Python, ce qui signifie qu'il dispose d'un véritable langage de programmation, presque tout ce que vous pouvez faire avec l'interface graphique est réalisable avec un script Python.
Malheureusement, les informations sur les scripts dans la documentation, et même dans ce wiki sont éparpillées et manquent d'uniformité "d'écriture" et la plupart d'entre elles sont expliquées d'une manière trop technique.
Commencer
Le premier obstacle d'une manière simple à la création de scripts est qu'il n'y a pas de moyen direct d'accéder à l'éditeur Python interne de FreeCAD via un élément de menu ou une icône dans la zone de la barre d'outils, mais sachant que FreeCAD ouvre un fichier avec un .py
dans l'éditeur Python interne, l'astuce la plus simple est de créer dans votre éditeur de texte préféré, puis de l'ouvrir avec la commande habituelle Fichier → Ouvrir.
Pour faire les choses d'une manière polie, le fichier doit être écrit avec un certain ordre, l'éditeur Python FreeCAD a une bonne "Syntaxe Highlighting" qui manque dans de nombreux éditeurs simples comme le Notepad de Windows ou certains éditeurs Linux de base, il suffit donc d'écrire ces quelques lignes :
"""filename.py
A short description of what the script does
"""
Enregistrez-les avec un nom significatif avec l'extension .py
et chargez le fichier résultant dans FreeCAD, avec la commande Fichier → Ouvrir.
Un exemple simple de ce qu'il est nécessaire d'avoir dans un script est présenté dans cette partie du code que vous pourriez utiliser comme modèle pour presque tous les futurs scripts:
"""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)
Certaines astuces sont incorporées dans le code ci-dessus:
import FreeCAD
Cette ligne importe FreeCAD dans l'interpréteur FreeCAD Python, cela peut sembler redondant, mais ce n'est pas le cas.from FreeCAD import Placement, Rotation, Vector
Placement Rotation et Vector sont largement utilisés dans l'écriture de scripts FreeCAD, les importer de cette manière vous évitera de les appeler avecFreeCAD.Vector
ouFreeCAD.Placement
au lieu deVector
ouPlacement
, cela économisera de nombreuses frappes et rendra les lignes de code beaucoup plus petites.
Commençons par un petit script qui fait un très petit travail, mais qui montre la puissance de cette approche.
# 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()
Ecrivez les lignes de code ci-dessus après # Script methods
et appuyez sur la flèche verte dans la Barre d'outils des macros
Vous verrez des choses magiques, un nouveau document est ouvert nommé "Wiki_example" et vous verrez dans la vue 3D un Cube comme ci-dessous.
Quelque chose en plus
Pas si surprenant ? Oui, mais il faut commencer quelque part, on peut faire la même chose avec un Cylindre, ajouter ces lignes de code après la méthode my_box()
et avant la ligne : # 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
Même ici, rien de trop excitant. Mais veuillez noter quelques particularités:
- L'absence de la référence habituelle à l '
App.
, présente dans de nombreux extraits de code de documentation est délibérée. Ce code pourrait être utilisé même en invoquant FreeCAD comme module dans un interpréteur Python externe, la chose n'est pas facilement faisable avec une AppImage, mais avec un certain soin, cela pourrait être fait. De plus, dans la devise standard de Python, "mieux explicite qu'implicite",App.
explique de manière très "mal" d'où viennent les choses. - Notez l'utilisation du nom "constant" attribué au document actif dans
DOC = FreeCAD.activeDocument()
. activeDocument n'est pas une "constante" au sens strict, mais d'une manière "sémantique" c'est notre "Document actif", qui pour notre utilisation sera une "constante" appropriée. La convention Python d'utiliser le nom "ALL CAPS" pour "constantes", sans oublier queDOC
est beaucoup plus court queFreeCAD.activeDocument()
. - Chaque méthode retourne une géométrie, cela sera clair dans la suite de la page.
- Géométrie n'avait pas la propriété
Placement
, lors de l'utilisation de géométries simples pour créer une géométrie plus complexe, gérerPlacement
est une chose délicate.
Maintenant, que faire avec ces géométries?
Introduisons les opérations booléennes. Comme exemple pour démmarrer, placez ces lignes après my_cyl
, cela crée une méthode pour une Fusion également connue sous le nom d'opération Union :
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
Rien d'exceptionnel ici aussi, notez cependant l'uniformité dans le codage des méthodes; Cette approche est plus linéaire que celles vues autour d'autres tutoriels sur les scripts, cette "linéarité" aide grandement à la lisibilité et aussi avec les opérations couper-copier-coller.
Utilisons les géométries, supprimons les lignes sous la section de code commençant par # objects definition
et insérons les lignes suivantes:
# objects definition
obj = my_box("test_cube", 5, 5, 5)
obj1 = my_cyl("test_cyl", 360, 2, 10)
fuse_obj("Fusion", obj, obj1)
setview()
Lancez le script avec la flèche verte et nous verrons dans la vue 3D quelque chose comme :
Placement
Le concept de placement est relativement complexe, voir tutoriel avion pour une explication plus approfondie.
Nous avons généralement besoin de placer des géométries respectueuses les unes des autres, lorsque la construction d'un objet complexe est une tâche récurrente, le moyen le plus courant est d'utiliser la propriété geometry Placement
.
FreeCAD offre un large choix de moyens pour définir cette propriété, l'un est plus adapté à l'autre en fonction des connaissances et du parcours de l'utilisateur, mais plus l'écriture est simple et expliquée dans le Tutoriel cité, plus il utilise une définition particulière de la partie Rotation
de Placement
, assez facile à apprendre.
FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0))
Mais par rapport à d'autres considérations, une chose est cruciale, la géométrie point de référence, c'est-à-dire le point à partir duquel l'objet est modélisé par FreeCAD, comme décrit dans ce tableau, copié de Placement :
Objet | Point de référence |
---|---|
Part.Box | gauche (minx), avant (miny), bas (minz) sommet |
Part.Sphere | centre de la sphère |
Part.Cylinder | centre de la face inférieure |
Part.Cone | centre de la face inférieure (ou sommet si le rayon inférieur est 0) |
Part.Torus | centre du tore |
Fonctions dérivées d'esquisses | La fonction hérite de la position de l'esquisse sous-jacente. Les esquisses commencent toujours par Position = (0, 0, 0). Cette position correspond à l'origine dans l'esquisse. |
Cette information doit être gardée à l'esprit, en particulier lorsque nous devons appliquer une rotation.
Quelques exemples peuvent aider, supprimez toute la ligne après la méthode my_cyl
et insérez la partie de code ci-dessous :
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()
Expliquons quelque chose dans le code:
- Nous avons utilisé une méthode pour définir une sphère, en utilisant la définition la plus simple, en utilisant uniquement le rayon.
- Nous avons introduit une deuxième écriture pour Union ou Fusion, en utilisant plusieurs objets, pas trés éloignés de l'habituel Part::Fuse qu'il utilise Part:Multifuse et n'utilise qu'une seule propriété
Shapes
. Nous avons passé un tuple comme arguments mais il accepte aussi une liste. - Nous avons défini un objet complexe un avion mais nous l'avons fait de manière "paramétrique" en définissant certains paramètres et en dérivant d'autres paramètres, grâce à des calculs , basé sur les principaux paramètres.
- Nous avons utilisé des propriétés de placement
Placement
dans la méthode et avant de renvoyer les géométries finales, nous avons utilisé une propriétéRotation
avec l'écriture Yaw-Pitch-Roll. Notez le dernierVector(0, 0, tail_position)
qui définit un centre de rotation de toute la géométrie.
On peut facilement remarquer que la géométrie de l'avion tourne autour de son "barycentre" ou "centre de gravité", que j'ai fixé au centre de l'aile, un endroit relativement "naturel", mais qui pourrait être placé n'importe où vous voulez.
Le premier Vector(0, 0, 0)
est le vecteur de translation, non utilisé ici, mais si vous remplacez airplane()
par ces lignes :
obj_f = airplane()
print(obj_F.Placement)
Vous verrez dans la fenêtre Rapport ce texte:
Placement [Pos=(0, -21, 21), Yaw-Pitch-Roll=(0, 0, -90)]
Que s'est-il passé?
FreeCAD a traduit Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position)
en d'autres termes notre définition Placement
qui spécifie trois composants, Translation, Rotation et centre de rotation en valeurs "internes" de seulement deux composants, Translation et Rotation.
vous pouvez facilement visualiser la valeur de tail_position
en utilisant une instruction print dans la méthode airplane()
et voir que c'est :
tail_position = 21.0
en d'autres termes, le centre de rotation de la géométrie est à Vector(0, 0, 21)
, mais ce centre de rotation n'est pas affiché dans l'interface graphique, il pourrait être entré comme Placement
, il n'a pas pu être facilement récupéré.
C'est le sens du mot "maladroit" que j'ai utilisé pour définir la propriété Placement
.
Voici l'exemple de code complet avec un docstring de script décent selon la convention de docstrings de Google :
"""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()
- Scripts FreeCAD : Python, Introduction à Python, Tutoriel sur les scripts Python, Débuter avec les scripts
- Modules : Modules intégrés, Unités, Quantity
- Ateliers : Création d'atelier, Commands Gui, Les commandes, Installer des ateliers supplémentaires
- Maillages et objets Parts : Scripts Mesh, Script de données topologiques, Conversion objet Mesh en Part, PythonOCC
- Objets paramétriques : Objets créés par script, Viewproviders (Icône personnalisée dans l'arborescence)
- Scénographie : Graphe de scène Coin (Inventor), Pivy
- Interface graphique : Création d'interface, Création d'une boite de dialogue (1, 2, 3, 4, 5), PySide, Exemples PySide débutant, intermédiaire, expérimenté
- Macros : Macros, Comment installer des macros
- Intégration : Intégrer FreeCAD, Intégration de FreeCADGui
- Autre : Expressions, Extraits de codes, Fonction - tracer une ligne, Bibliothèque mathématique vectorielle de FreeCAD (déprécié)