Manual:A gentle introduction/fr

Python est un langage populaire, open source, largement distribué, souvent utilisé comme langage de script, embarqué dans d'autre programme, comme c'est le cas dans FreeCAD. Il possède également des qualités qui le rende particulièrement attractif pour nous, utilisateurs de FreeCAD: il est facile à apprendre, surtout pour les novices en programmation, et il est embarqué dans d'autres logiciels, ce qui en fait un outil précieux à apprendre, car il pourra être réutilisé dans d'autres applications, comme Blender, Inkscape ou GRASS.

FreeCAD fait une utilisation intensive de Python. Avec lui, vous pouvez accéder et contrôler quasiment toutes les fonctions de FreeCAD. Vous pouvez, par exemple, créer de nouveaux objets, outils et panneaux. Certains ateliers de FreeCAD et la plupart des ateliers supplémentaires sont entièrement programmé en python. FreeCAD possède une console python avancée, disponible depuis le menu Affichage->Panneaux->Console Python. Il est souvent utile pour réaliser des opérations pour lesquelles il n'y a pas encore de boutons dans la barre d'outils, ou pour vérifier des formes, ou pour faire des tâches répétitives:



Mais la console python a une autre rôle très important: chaque fois qu'un bouton de la barre d'outils est cliqué, ou qu'une autre opération est réalisée dans FreeCAD, du code python est affiché puis exécuté dans la console. En laissant la console python ouverte, vous pouvez littéralement voire le code python se dérouler au fur et à mesure de votre travail, et, en un rien de temps, sans même vous en rendre compte, vous apprendrez le langage python.

FreeCAD possède également un système de macros, qui vous permets d’enregistrer vos actions pour les rejouer plus tard. Ce système utilise aussi la console python, en enregistrant simplement ce qui est fait à l'intérieur.

Dans ce chapitre, nous allons découvrir de façon très générale le langage Python. Si vous souhaitez en apprendre plus, la documentation wiki de FreeCAD possède une section extensive concernant la programmation python.

Écrire du code python
Il y a deux manières 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 la console Python, vous écrivez les lignes de code Python, une par une, qui seront exécutées lorsque vous appuyez sur la touche. Dans l'éditeur de macros, qui peuvent contenir un script plus complexe fait de plusieurs lignes de code, et sont exécuté uniquement lorsque vous cliquerez sur (triangle vert).

Dans ce chapitre, vous pourrez utiliser les deux méthodes, mais il est fortement recommandé d'utiliser la Console Python, car elle vous informera instantanément des erreurs que vous auriez pu faire en tapant.

Si c'est la première fois que vous programmez en Python, pensez à lire cette courte introduction à la programmation Python  avant d'aller plus loin. Cela rendra les concepts de base de Python plus clairs.

Manipuler des objets FreeCAD
Commençons pas créer un nouveau document vide:

doc = FreeCAD.newDocument

If you type this in the FreeCAD python console, you will notice that as soon as you type "FreeCAD." (the word FreeCAD followed by a dot), a windows pops up, allowing to quickly autocomplete the rest of your line. Even better, each entry in the autocomplete list has a tooltip explaining what it does. This makes it very easy to explore the functionality available. Before choosing "newDocument", have a look at the other options available.



As soon as you press Enter our new document will be created. This is similar to pressing the "new document" button on the toolbar. In Python, the dot is used to indicate something that is contained inside something else (newDocument is a function that is inside the FreeCAD module). The window that pops up therefore shows you everything that is contained inside "FreeCAD". If you would add a dot after newDocument, instead of the parentheses, it would show you everything that is contained inside the newDocument function. The parentheses are mandatory when you are calling a Python function, such as this one. We will illustrate that better below.

Now let's get back to our document. Let's see what we can do with it:

doc.

Explore the available options. Usually names that begin with a capital letter are attributes, they contain a value, while names that begin with small letter are functions (also called methods), they "do something". Names that begin with an underscore are usually there for the internal working of the module, and you shouldn't care about them. Let's use one of the methods to add a new object to our document:

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

Our box is added in the tree view, but nothing happens in the 3D view yet, because when working from Python, the document is never recomputed automatically. We must do that manually, whenever we need:

doc.recompute

Now our box appeared in the 3D view. Many of the toolbar buttons that add objects in FreeCAD actually do two things: add the object, and recompute. If you turned on the "show script commands in python console" option above, try now adding a sphere with the appropriate button in the Part Workbench, and you will see the two lines of python code being executed one after the other.

You can get a list of all possible object types like Part::Box:

doc.supportedTypes

Now let's explore the contents of our box:

box.

You'll immediately see a couple of very interesting things such as:

box.Height

This will print the current height of our box. Now let's try to change that:

box.Height = 5

If you select your box with the mouse, you will see that in the properties panel, under the Data tab, our Height property appears with the new value. All properties of a FreeCAD object that appear in the Data and View tabs are directly accessible by python too, by their names, like we did with the Height property. Data properties are accessed directly from the object itself, for example:

box.Length

View properties are stored inside a ViewObject. Each FreeCAd object possesses a ViewObject, which stores the visual properties of the object. When running FreeCAD without its Graphical Interface (for example when launching it from a terminal with the -c command line option, or using it from another Python script), the ViewObject is not available, since there is no visual at all.

For example, to access the line color of our box:

box.ViewObject.LineColor

Vectors and Placements
Vectors are a very fundamental concept in any 3D application. It is a list of 3 numbers (x, y and z), describing a point or position in the 3D space. A lot of things can be done with vectors, such as additions, subtractions, projections and much more. In FreeCAD vectors work like this:

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

Another common feature of FreeCAD objects is their Placement. As we saw in earlier chapters, each object has a Placement property, which contains the position (Base) and orientation (Rotation) of the object. It is easy to manipulate from Python, for example to move our object:

print(box.Placement) print(box.Placement.Base) box.Placement.Base = sumvec otherpla = FreeCAD.Placement otherpla.Base = FreeCAD.Vector(5,5,0) box.Placement = otherpla

Read more


 * Python
 * Working with Macros
 * Introduction to Python scripting
 * Using Python in FreeCAD
 * The Python scripting wiki hub