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:
 * créer de nouveaux objets
 * modifier les objets existants
 * modifier la représentation 3D de ces objets
 * modifier l'interface de FreeCAD

Il y a aussi d'autres manières d'utiliser Python dans 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.

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.

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

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 :

Vous pouvez donner un nom au nouveau document en faisant :

doc = FreeCAD.newDocument("Projet01") mettre le nom entre guillemets car c'est une chaîne de caractères alphabétique

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 :

Explorons les options disponibles dans la fenêtre qui vient de s'afficher.

En règle générale,


 * 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.

Nous allons utiliser une des méthodes suivantes pour ajouter un nouvel objet à notre document :

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, peu de commandes mettront de manière automatique le projet à jour.

Vous devrez le faire manuellement :

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 "Part::Box" vous demandez-vous ? Et, comment peut-on savoir quels autres types d'objets peuvent être ajoutés ?

Tout est ici :

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

Tapez :

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

Ceci affichera la hauteur courante de notre "box".

Maintenant, nous allons essayer de changer cette valeur,

Tapez :

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 :

Une autre caractéristique commune des objets dans FreeCAD est leur emplacement dans l'espace, (accessible par le volet Vue combinée → Propriétés → Données → Placement, ou, par le menu  Édition → Positionnement...).

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 :

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 "géometrie" 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 :

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

When you start FreeCAD, the python console already loads 2 base modules: FreeCAD and FreeCADGui (which can also be accessed by their shortcuts App and Gui). They contain all kinds of generic functionality to work with documents and their objects. To illustrate our concept, see that both FreeCAD and FreeCADGui contain an ActiveDocument attribute, which is the currently opened document. FreeCAD.ActiveDocument and FreeCADGui.ActiveDocument are not the same object. They are the two components of a FreeCAD document, and they contain different attributes and methods. For example, FreeCADGui.ActiveDocument contains ActiveView, which is the currently opened 3D view

Modules
Now you must surely wonder, what else than "Part::Box" can I do? The FreeCAD base application is more or less an empty container. Without its modules, it can do little more than creating new, empty documents. The true power of FreeCAD is in its faithful modules. Each of them adds not only new workbenches to the interface, but also new python commands and new object types. As a result, several different or even totally incompatible object types can coexist in the same document. The most important modules in FreeCAD, that we'll look at in this tutorial, are Part, Mesh, Sketcher or Draft.

Sketcher and Draft both use the Part module to create and handle their geometry, which are BRep while Mesh is totally independent, and handles its own objects. More about that below.

You can check all the available base object types for the current document like this:

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:

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:

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

Read more about mesh scripting...

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

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

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

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

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

Read more about part scripting...

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

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

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

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

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

Read more about pyqt here...

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

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