Python scripting tutorial/fr

Introduction
Python est un langage de programmation qui est relativement facile à apprendre et à comprendre. Il est open-source et multi-plateforme et peut être utilisé à de nombreuses fins : des scripts shell simples aux programmes très complexes. Mais son utilisation la plus répandue se trouve dans le langage de script intégré dans d'autres applications. C'est ainsi qu'il est utilisé dans FreeCAD. Depuis la console Python, ou depuis des scripts personnalisés, vous pouvez contrôler FreeCAD et lui faire effectuer des opérations très complexes.

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 existe plusieurs façons d'utiliser Python dans FreeCAD :
 * Depuis l'interpréteur Python de FreeCAD, où vous pouvez exécuter du code dans une interface du style " ligne de commande ".
 * Depuis les macros, qui sont un moyen pratique d'ajouter rapidement un outil manquant à l'interface FreeCAD.
 * A partir de scripts externes, qui peuvent être utilisés pour créer des solutions assez complexes, même des Ateliers entiers.

Dans ce tutoriel, nous allons travailler sur quelques exemples de base pour vous aider à démarrer, mais il y a beaucoup plus de documentations sur les scripts Python disponibles sur ce wiki. Si vous êtes totalement nouveau sur Python et que vous voulez comprendre comment cela fonctionne, nous avons également une Introduction à Python.

Important Avant de travailler avec les scripts Python, ouvrez la fenêtre de préférences et cochez les deux cases en bas: Ensuite, allez dans le menu et cochez : Cela vous évitera de nombreux soucis
 * Rediriger les messages interne Python vers la Vue rapport
 * Rediriger les erreurs internes de Python vers la vue rapport
 * Vue Rapport

Ecrire 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 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).

There are two ways to write Python code in FreeCAD. In the Python console (select from the menu) or in the Macro editor (select  from the menu). In the console you write Python commands one by one, executing them by pressing, while macros can contain more complex code made up of several lines, executed only when the macro is executed.



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 :

Let's start by creating a new empty 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.

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.

FreeCAD has been designed so that it can also be used without its user interface, as a command-line application. Almost every object in FreeCAD therefore consists of two parts: an, its "geometry" component, and a , its "visual" component. When you work in command-line mode, the geometry part is present, but the visual part is disabled.

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" :

Lorsque vous démarrez FreeCAD, la console python charge 2 modules de base : FreeCAD et FreeCADGui (qui peuvent également être 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 qu'est-ce que l'on peut faire d'autre, mis à part "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).

The true power of FreeCAD lies in its faithful modules. The FreeCAD base application is more or less an empty container. Without its modules it can do little more than create new, empty documents. Each module not only adds new workbenches to the interface, but also new Python commands and new object types. As a result several different, and 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 and Draft.

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, modélisation surfacique ou (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:

Même si les différents modules de FreeCAD ont ajoutés leurs types d'objets, les modules ne sont pas automatiquement chargé dans la console python dans le but d'éviter de ralentir le démarrage. Les modules, ne sont chargés que lorsque vous en avez besoin.

Ainsi, par exemple, pour explorer ce qui est à l'intérieur de "Part Module" (Atelier Pièce), faites:

Mais nous parlerons plus en détail du module "Part module" ci-dessous.

Mesh (Maillage)
L'outil "Mesh (mailles)" est un type d'objet 3D très simple, utilisé par exemple par Google SketchUp, Blender ou 3D studio Max.

Il est composé de 3 éléments:


 * 1 de points (également appelé sommets ou Vertex)


 * 2 de lignes, (également appelé bords ou arêtes)


 * 3 de faces.

Dans de nombreuses applications, FreeCAD inclus des faces qui possèdent que 3 sommets. Mais bien sûr, rien ne vous empêche d'avoir la face d'un gros avion avec une multitude de triangles coplanaires.

Les maillages sont simples, mais parce qu'ils sont simples, vous pouvez facilement en avoir des millions dans un seul document. Cependant, dans FreeCAD, ils sont peu utilisés et la plupart du temps vous pouvez donc importer des objets au format de maillage (.stl, .obj) à partir d’autres applications. Le module Mesh a également été largement utilisé comme module de test principal au départ du développement de FreeCAD.

L'objet Mesh et l'objet FreeCAD sont deux choses totalement différentes. Vous pouvez voir l'objet FreeCAD comme conteneur d'un Objet Mesh (nous le verrons ci-dessous avec les Objets Part).

Ainsi, afin d'ajouter un Objet Mesh à FreeCAD, nous devons d'abord créer un Objet FreeCAD, créer un Objet Mesh et ensuite ajouter l'Objet Mesh à l'Objet FreeCAD:

Il s'agit ici d'un exemple classique, qui utilise la méthode createSphere pour créer automatiquement une sphère mais vous pouvez très bien créer des maillages personnalisés à partir de rien, en définissant leurs sommets et leurs faces.

Ici plus de renseignements sur les scripts Mesh ...

Part (Boîte à outils)
La boîte à outils est le module le plus puissant de l'ensemble FreeCAD. Il permet de créer et de manipuler des objets B-Rep. Ce type d'objet, contrairement à Mesh, peut avoir une grande variété de composantes. Pour mémoire, B-rep qui signifie boundary representation, ce qui signifie en français Représentation par les Bords ou modélisation surfacique. Ces surfaces peuvent être une grande variété d'objets, tel que des surfaces planes ou des surfaces très complexes NURBS (pour Non-Uniform Rational Basis Splines). Ils contribuent également à la notion de volume.

The Part Module is the most powerful module in the whole of FreeCAD. It allows you to create and manipulate BRep objects. BRep stands for "Boundary Representation". A BRep object is defined by surfaces that enclose and define an inner volume. Unlike meshes, BRep objects can have a wide variety of components from planar faces to very complex NURBS surfaces.

La Boîte à outils est basée sur la puissante bibliothèque OpenCascade, qui permet un large éventail d'opérations complexes, qui peuvent être facilement effectuées sur ces objets, tels que, les opérations booléennes, le filetage, balayage, etc ..

Le module fonctionne en partie de la même manière que le module Mesh:

Vous créez un Objet FreeCAD puis un Objet Part et après, ajoutez l'Objet Part à l'Objet FreeCAD:

Le module Part (tout comme le module Mesh) dispose également d'un raccourci qui crée automatiquement un Objet dans FreeCAD et lui ajoute une forme, vous pouvez ainsi sauter les 3 dernières lignes ci-dessus:

En explorant le contenu de myShape. dans la fenêtre, vous remarquerez de nombreuses et intéressantes options disponibles comme Faces, Edges, Vertexes, Solids ou Shells et un large éventail d'opérations géométriques telles soustraction, intersection ou union. La page Script pour les pièces explique tout cela en détail.

Ici plus de renseignements sur données topologiques de scripts Part

Draft (projet de dessin)
FreeCAD propose de nombreux autres modules, tels que Atelier sketcher(esquisse) et  Atelier draft (projet) qui créent également des objets Pièce. Ces modules ajoutent des paramètres supplémentaires aux objets créés voire implémentent une toute nouvelle façon de gérer la géométrie de la pièce qu'ils contiennent. Notre exemple de boîte ci-dessus est un exemple parfait d'objet paramétrique. Pour définir cette zone, il vous suffit de spécifier les paramètres hauteur, largeur et longueur. Sur cette base, l’objet calculera automatiquement la forme de sa partie. FreeCAD vous permet de Objets créés par script.

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

Le Module Draft ajoute une série d'objets de types 2D paramétriques (qui sont tous des objets Part) tels que les lignes et les cercles, et fournit également quelques fonctions génériques qui ne travaillent pas seulement sur ​​les objets fabriqués, mais sur n'importe quel objet Part.

Pour voir ce qui est disponible, il suffit de faire:

Interface
L'interface utilisateur (Gui) de FreeCAD est faite avec Qt, un puissant système de création d'interface visuelle graphique, chargé de construire et de gérer, commandes, menus, barres d'outils, boutons 3D ... Qt fournit un module appelé PySide (en) qui permet à Python d'accéder et de modifier les interfaces contruites avec Qt, comme FreeCAD.

Essayons de travailler avec l'interface Qt et de construire une simple boîte de dialogue:

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

Une boîte de dialogue apparaît et nous voyons aussi l'icone de FreeCAD, ce qui signifie que Qt sait que l'ordre d'affichage de la fenêtre a été fait à l'intérieur de l'application FreeCAD. Nous pouvons donc facilement et partiellement modifier l'interface de FreeCAD.

Qt est un système de construction d'interface très puissant qui vous permet de faire des choses très complexes. Qt possède aussi une panoplie d'outils tel que Qt Designer avec lequel vous pouvez concevoir vos boîtes de dialogue graphique et de les ajouter à l'interface de FreeCAD avec quelques lignes de code Python.

Plus de renseignements sur PyQt ici et ici PyQt

Macros
Maintenant que vous avez une bonne connaissance des notions de base, où allons-nous placer nos scripts Python ? Comment allons-nous les lancer à partir de FreeCAD?

Il y a pour cela un mécanisme appelé Macros. Une macro est tout simplement un script en Python qui peut être ensuite ajouté à la barre d'outils et lancé à partir d'un simple clic de souris.

FreeCAD est fournit avec un petit éditeur de texte (Macro → Macros → Créer) où vous pouvez écrire ou coller des scripts. Une fois le script terminé, allez dans Outils → Personnaliser → Macros où vous pouvez définir un bouton pour votre macro puis ajouter ce bouton à la barre d'outils.

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 inside FreeCAD? There is an easy mechanism for that, called Macros. A macro is a Python script that can be added to a toolbar and launched via a mouse click. FreeCAD provides you with a simple text editor where you can write or paste scripts. Once the script is done, use to define a button for it that can be added to toolbars.

Vous êtes maintenant prêt pour un script FreeCAD plus approfondi. Rendez-vous sur la Documentation pour utilisateurs avancés!