Python scripting tutorial/fr

= Python_scripting_tutorial/fr =

Python est un langage de programmation très simple à utiliser et très facile à apprendre. Il est open-source, multi-plateforme, et peut être utilisé pour un large éventail d'applications, de la programmation de simples scripts sur console à des programmes très complexes. Mais l'une de ses utilisations les plus répandues est comme langage de script, car il est facilement à intégrable dans d'autres applications. C'est exactement de cette manière qu'il est utilisée dans FreeCAD. A partir de la console python, ou à partir de vos propres scripts, vous pouvez programmer FreeCAD, et lui faire exécuter des commandes très complexes pour lesquelles il n'y a pas encore d'outils disponibles dans l'interface graphique. Par exemple, à partir d'un script python, vous pouvez: Il y a aussi d'autres manières d'utiliser Python dans FreeCad: Dans ce tutoriel, nous allons apprendre à créer facilement des scripts très simples, mais il y a beaucoup plus de documentation sur les scripts Python sur ce wiki. Si vous êtes débutant en Python et que vous voulez comprendre comment il fonctionne, nous avons également un petit tutoriel d'introduction à Python.
 * créer de nouveaux objets
 * modifier les objets existants
 * modifier la représentation 3D de ces objets
 * modifier l'interface de FreeCAD
 * Avec l' interpréteur Python inclus Dans FreeCAD, où vous pouvez exécuter de simples commandes, du style "ligne de commande".
 * Avec des macros, qui sont des moyen simples et efficaces pour ajouter rapidement un outil manquant à l'interface de FreeCAD.
 * A partir de scripts externes, qui peuvent être utilisés pour programmer des choses beaucoup plus complexes, comme par exemple des boîtes à outils.

Ecrire du code Python
Il y a deux manière d'écrire du code python dans FreeCAD: à partir de la console python, dans la barre de menus, cliquez sur Affichage--> Vues--> Console Python ou de l'éditeur de macros Outils--> Macros. Dans console Python, vous écrivez les lignes de code Python, une par une, elles seront exécutées lorsque vous appuyez sur la touche. Et dans l'éditeur de macros, les macros peuvent contenir un script plus complexe fait de plusieurs lignes de code, ici, ce code sera exécuté uniquement lorsque vous cliquerez sur (triangle vert).



Dans ce tutoriel, vous pouvez travailler avec deux méthodes, soit par copier/coller chaque ligne par ligne dans la console python puis valider avec à chaque ligne (Affichage--> Vues--> Console Python), ou par copier/coller l'intégralité du code dans une nouvelle fenêtre macro (Outils--> Macros).

Exploration de FreeCAD
Commençons par créer un nouveau document:

doc = FreeCAD.newDocument

Si vous collez ce code dans la console Python de FreeCAD, vous remarquerez que dès que vous tapez (au clavier) "FreeCAD." (Attention à la casse Freecad est différent de FreeCAD), à l'instant ou vous entrez le "." une petite fenêtre apparaît instantanément avec une liste de saisie, vous permettant de sélectionner rapidement le reste de votre ligne, avec une cerise sur le gâteau, le passage de la souris sur chaque entrée de la liste d'auto-complétion affiche une info-bulle qui vous informe sur son utilisation. Cela rend très pratique l'exploration des fonctionnalités disponibles. Avant de choisir "NewDocument", nous jetons un regard sur les autres options disponibles.



Maintenant, notre nouveau document est créé. Le même résultat est obtenu en cliquant sur "Fichier-->Nouveau" ou, sur la barre d'outils cliquez sur "Créer un nouveau document vide". En fait, la plupart des boutons dans FreeCAD ne font rien d’autre qu'exécuter une ou deux lignes de code Python. Encore mieux, vous pouvez définir une option dans "Edit--> Préférences--> Général--> Macro" et cocher "montrer les commandes de script dans la console python". Ce qui permet d'afficher dans la console toutes les commandes Python des boutons cliqués, commandes exécutées etc. Cette opportunité est très utile pour apprendre et reproduire les fonctions et les macros utilisées elle peut aussi de cette manière constituer un historique des commandes. Maintenant revenons à notre document, et voyons ce que nous pouvons faire avec lui:

doc.

Explorons les options disponibles. En règle générale, Nous allons utiliser une des méthodes suivantes pour ajouter un nouvel objet à notre document:
 * les noms qui commencent par une Majuscule sont des attributs, ils contiennent une valeur,
 * les noms qui commencent par une minuscule sont des fonctions (également appelés méthodes), ils font quelque chose,
 * les noms qui commencent et finissent par un double __soulignement__ servent généralement pour le fonctionnement interne du module, et vous ne devriez pas vous soucier d'eux.

box = doc.addObject("Part::Box","myBox")

Rien ne se passe! Pourquoi? Parce que FreeCAD est conçu pour de gros projets. Plus tard, il travaillera avec des centaines d'objets complexes, tous dépendants les uns des autres. Faire une petite modification dans un objet pourra avoir des conséquences importantes sur l'ensemble du document, vous devrez peut-être le redéfinir, ce qui pourrait prendre beaucoup de temps. Pour cette raison, peux de commandes mettront de manière automatique le projet à jour. Vous devrez le faire manuellement:

doc.recompute

Vu? Maintenant, notre boîte est apparue! La plupart des boutons qui ajoutent des objets dans FreeCAD font 2 choses: ajouter l'objet, et recalculer. Si vous avez activé l'option "Montrer les commandes du script dans la console Python", essayez d'ajouter une sphère avec le bouton GUI, vous verrez s'afficher les deux lignes de code Python en cours d'exécution l'une après l'autre. Mais que deviens notre "Partie :: Box" vous demandez-vous? Et, comment peut-on savoir quels autres types d'objets peuvent être ajoutés? Tout est ici:

doc.supportedTypes

Maintenant, nous allons explorer le contenu de notre "box". Tapez:

box.

Nous voyons immédiatement des choses intéressantes comme:

box.Height

Ceci affichera la hauteur courante de notre "box". Maintenant, nous allons essayer de changer cette valeur, Tapez:

box.Height = 5

Si vous sélectionnez votre box avec la souris, vous verrez que dans le panneau de propriétés, dans l'onglet "Données", la propriété "Height" apparaît. Toutes les propriétés d'un objet qui se trouve dans FreeCAD se trouvent là (mais aussi dans le menu "Affichage-->Vues-->Affichage des propriétés", nous verrons cela plus tard), et sont directement accessibles par la console Python aussi, par leurs noms, comme nous l'avons fait avec la propriété "Height". Essayez de modifier les autres valeurs de votre box.

Vecteurs et Positions
Les vecteurs sont un concept tout à fait fondamental dans n'importe quelle application 3D. Il s'agit de 3 nombres représentés par (x, y et z), décrivant un point ou une position précise dans l'espace 3D. Un grand nombre de choses peuvent être faites avec ces vecteurs, tels que, additions, soustractions, projections et bien plus encore. Dans les vecteurs, FreeCAD travaille de cette façon:

myvec = FreeCAD.Vector(2,0,0) myvec myvec.x myvec.y othervec = FreeCAD.Vector(0,3,0) sumvec = myvec.add(othervec)

Une autre caractéristique commune des objets dans FreeCAD est leurs emplacements. Chaque objet, possède des attributs d'emplacement qui contiennent, la position (base) et l'orientation (rotation) de l'objet. Ils sont faciles à manipuler. Par exemple pour déplacer notre objet:

box.PLacement. box.Placement.Base box.Placement.Base = sumvec otherpla = FreeCAD.Placement box.Placement = otherpla

Avant d'aller plus loin, vous devez comprendre quelques concepts importants.

App and Gui
Au départ, FreeCAD a été conçu de manière à travailler comme une application en ligne de commande, sans interface utilisateur. Par conséquent, presque tout est séparé entre une composante "geometrie" et une composante "visuelle". Lorsque vous travaillez en mode ligne de commande, la partie geometry est présente, mais toute la partie View est tout simplement désactivée. Presque n'importe quel objet dans FreeCAD est donc composé de deux parties, un Object et un ViewObject. Pour illustrer ce concept, voyons notre objet box, les propriétés géométriques du box, comme ses dimensions, sa position, etc .. sont stockés dans l'Object, tandis que ses propriétés visuelles, telles que sa couleur, l'épaisseur de la ligne, etc .. sont stockées dans ViewObject. Tout ces paramètres sont visibles (et modifiables) dans la fenêtre Propriété--> onglets "Vue" et "Données". La commande ViewObject est accessible comme ceci:

vo = box.ViewObject

Vous pouvez également modifier les propriétés de l'onglet "Vue":

vo.Transparency = 80 vo.hide vo.show

Lorsque vous démarrez FreeCAD, la console python charge 2 modules de base: FreeCAD et FreeCADGui (qui peuvent également êtres consultés par leurs raccourcis App et Gui). Ils contiennent toutes sortes de fonctionnalités génériques pour travailler avec des documents et leurs objets. Pour illustrer notre concept, observez que FreeCAD et FreeCADGui contiennent un attribut ActiveDocument, qui est le document courant. FreeCAD.ActiveDocument et FreeCADGui.ActiveDocument ne sont pas le même objet. Ce sont, les deux composantes d'un document FreeCAD, et, ils contiennent des attributs et des méthodes différentes. Par exemple, FreeCADGui.ActiveDocument contient ActiveView, qui est la vue 3D actuellement ouverte.

Les modules
Maintenant, vous devez sûrement vous demander, que puis-je faire d'autre avec "Part::Box"? D'origine l'application, FreeCAD n'est qu'un conteneur plus ou moins vide. Sans ses modules, FreeCAD ne peut guère faire plus que de créer de nouveaux documents vides. La véritable puissance de FreeCAD réside dans ses modules. Chaque module ajoute non seulement de nouveaux outils à l'interface, mais, aussi de nouvelles commandes Python et de nouveaux types d'objets. Par conséquent, plusieurs types d'objets différents, voire totalement incompatibles entre eux peuvent parfaitement coexister dans le même document. Les modules les plus importants dans FreeCAD, que nous allons voir dans ce tutoriel, sont Part Module (Atelier Pièce), Mesh Module (Atelier Maillage), Sketcher Workbench (Atelier Sketcher (Esquisse)) ou Draft Module (Planche à dessin). Atelier Sketcher (Esquisse) et Draft Module (Planche à dessin) utilisent tous les deux Part Module (Atelier Pièce) pour créer et gérer leurs objets, qui sont représentés par les bords (B-Rep). Alors que Mesh Module (Atelier Maillage) est totalement indépendant et gère ses propres objets. Nous en saurons plus tout à l'heure. Vous pouvez en savoir plus sur tous les types d'objets disponibles dans le document courant comme ceci:

doc.supportedTypes

The different FreeCAD modules, although they added their object types to FreeCAD, are not automatically loaded in the python console. This is to avoid having a very slow startup. Modules are loaded only when you need them. So, for example, to explore what's inside the Part module:

import Part Part.

But we'll talk more about the Part module below.

By now, you know a bit more about the different modules of FreeCAD: The core modules (FreeCAD, FreeCADGui), and the workbenches modules (Part, Mesh, Sketcher). The other important modules are the 3d scene module (pivy) and the interface module (pyqt), we'll talk about them too below.

Now it's time to explore a bit deeper the important ones, which are the workbench modules.

Mesh
Meshes are a very simple kind of 3D objects, used for example by Sketchup, Blender or 3D studio Max. They are composed of 3 elements: points (also called vertices), lines (also called edges) and faces. In many applications, FreeCAD included, faces can have only 3 vertices. But of course nothing prevents you from having a bigger plane face made of several coplanar triangles.

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:

import Mesh mymesh = Mesh.createSphere mymesh. mymesh.Facets mymesh.Points meshobj = doc.addObject("Mesh::Feature","MyMesh") meshobj.Mesh = mymesh doc.recompute

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:

import Part myshape = Part.makeSphere(10) myshape. myshape.Volume myshape.Area shapeobj = doc.addObject("Part::Feature","MyShape") shapeobj.Shape = myshape doc.recompute

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:

Part.show(myshape)

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:

import Draft Draft. rec = Draft.makeRectangle(5,2) mvec = FreeCAD.Vector(4,4,0) Draft.move(rec,mvec) Draft.move(box,mvec)

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:

from PyQt4 import QtGui QtGui.QMessageBox.information(None,"Apollo program","Houston, we have a problem")

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!