FreeCAD Scripting Basics/fr

Python scripting in FreeCAD
FreeCAD a été programmé dés la première ligne de code dans le but d'être totalement contrôlé par des scripts écrits en Python. Presque toutes les procédures de FreeCAD, telles que l'interface, le contenu des scènes, même la représentation du contenu des vues 3D, sont accessibles à partir de l'interpréteur Python ou de vos propres scripts. Par conséquence, FreeCAD est probablement l'une des applications d'ingénierie la plus profondément personnalisable et évolutive disponible actuellement.

Dans son état actuel, FreeCAD a très peu de commandes de base pour interagir avec vos objets 3D, FreeCAD est encore jeune et est encore au stade de développement, de plus, la philosophie du développement de FreeCAD est orientée de manière à fournir une plate-forme CAD plutôt qu'une application d'utilisation spécifique.

Grâce aux scripts Python utilisables dans FreeCAD, nous avons un moyen très simple et rapide de voir et de tester les nouvelles fonctionnalités des modules élaborés par la communauté internationale des utilisateurs, des utilisateurs qui, généralement connaissent la programmation Python.

Python est l'un des langages interprétés les plus populaires et, généralement considéré comme très facile à apprendre, bientôt, vous pourrez aussi écrire vos scripts pour modeler "votre propre" FreeCAD.

Si vous n'êtes pas familier avec Python, nous vous recommandons de chercher des tutoriels sur internet et "jeter un œil rapide" sur sa structure. Python est un langage très facile à apprendre, en particulier parce qu'il peut être exécuté à l'intérieur de l'interpréteur, de la plus simple commande jusqu'à l'élaboration de programmes complexes, il peut être exécuté à la volée sans avoir besoin de compilateur. FreeCAD dispose de son propre interpréteur Python intégré. Si vous ne voyez pas de fenêtre intitulée Console Python comme illustré ci-dessous, vous pouvez l'activer en cliquant dans la barre d'outils Affichage -> Vues -> Console Python pour afficher l’interpréteur Python.

L'interpréteur Python
A partir de l’interpréteur Python, vous pouvez accéder à l'ensemble des modules Python installés, les modules originaux de FreeCAD, ainsi que tous les modules supplémentaires que vous installerez plus tard dans FreeCAD. La capture d'écran ci-dessous vous montre l'interpréteur Python:



A partir de l’interpréteur, vous pouvez exécuter du code Python et naviguer à travers les classes et fonctions disponibles. FreeCAD fournit un navigateur de classe très pratique pour l'exploration de votre nouvel univers qu'est FreeCAD. Lorsque vous tapez le nom d'une classe connue suivie d'un "." (point) (ce qui veut dire que vous voulez ajouter quelque chose après le point à partir de cette classe), une fenêtre s'ouvre et vous renseigne sur les options et méthodes disponibles dans cette classe. Lorsque vous sélectionnez une option, le texte d'aide qui lui est associé (s'il est disponible) est automatiquement affiché:



Alors, commencez ici en tapant App. ou Gui. (Attention à la casse App est différent de app) et regardez ce qui se passe.

Une autre façon plus simple d'explorer Python le contenu des modules et des classes est d'utiliser la commande d'affichage dir.

Par exemple, en tapant dir tous les modules actuellements répertoriés et chargés dans FreeCAD s'affichent.Si vous tapez dir(App) tout ce qu'il y a à l'intérieur du module App sera affiché, etc.

Une autre caractéristique utile de l'interprèteur est la possibilité de revenir en arrière dans l'historique des commandes et récupérer une ligne de code que vous avez tapé plus tôt. Pour naviguer dans l'historique des commandes, il suffit d'utiliser ou.

Si vous cliquez avec le bouton droit de la souris dans la fenêtre de l'interpréteur, vous avez également les options classiques d'un traitement de texte, telles que copier tout l'histoire (utile lorsque vous voulez expérimenter votre code avant de faire votre script final), ou d'insérer un nom de fichier avec le chemin complet.

Aide Python
Dans le menu Aide de FreeCAD, vous trouverez une entrée portant la mention Modules Python, qui va ouvrir dans le navigateur une fenêtre contenant la liste complète, de la documentation de l'ensemble des modules Python à disposition de l’interpréteur FreeCAD, c'est à dire les modules fournis avec Python et ceux intégrés dans FreeCAD. La documentation disponible dépend de l'effort que le développeur a mis pour documenter le code son module, les modules Python en général, ont la réputation d'être bien documentés. FreeCAD doit rester ouvert pour travailler avec ce système de documentation.

Modules incorporés (Built-in)
FreeCAD étant conçu pour être exécuté sans interface graphique (GUI), la quasi-totalité de ses fonctionnalités est séparé en deux groupes: les fonctionnalités de base, nommés «App», et la fonctionnalité graphique, nommée «Gui». Donc, nos deux principaux modules dans FreeCAD sont appelés App et Gui.

Ces deux modules peuvent également être accessibles à partir des scripts, respectivement avec les noms FreeCAD et FreeCADGui. Ils sont accessibles même hors de l’interpréteur.


 * Dans l'App module, vous trouverez tout ce qui concerne l'application elle-même, comme, les procédures d'ouvrir ou fermeture de fichiers, comme l'ouverture de la feuille active ou lister le contenu de la feuille . ..


 * Dans l'Gui module, vous trouverez des outils pour accéder et gérer les éléments graphiques, comme les boutons utilisateurs et leur barres d'outils, et, plus intéressant, la représentation graphique de l'ensemble du contenu FreeCAD.

Lister tout le contenu de ces modules est un contre-productif, car ils grandissent très vite compte tenu de la progression du développement de FreeCAD.

Mais les deux outils fourni (le navigateur de classe et de l'aide de Python) vous donnerons, à tout moment, une complète documentation mise à jour sur ces modules.

Les objets "App" et "Gui"
Comme nous l'avons dit, dans FreeCAD, tout est séparé entre le noyau et la représentation du projet. Y compris les objets 3D.

Vous pouvez accéder aux propriétés des objets (appelés fonctions dans FreeCAD) via le module App, et modifier la façon dont ils sont représentés sur l'écran via le module de Gui.

Par exemple, un cube possède des propriétés qui le définissent, (comme la largeur, longueur, hauteur) qui sont stockées dans un App objet et, les propriétés de représentation (comme la couleur des faces, le mode de dessin) qui sont stockées dans un objet correspondant Gui.

This way of doing things allows a very wide range of uses, like having algorithms work only on the definition part of features, without the need to care about any visual part, or even redirect the content of the document to non-graphical application, such as lists, spreadsheets, or element analysis.

For every App object in your document, there exists a corresponding Gui object. Infact the document itself has both App and a Gui objects. This, of course, is only valid when you run FreeCAD with its full interface. In the command-line version no GUI exists, so only App objects are availible. Note that the Gui part of objects is re-generated every time an App object is marked as 'to be recomputed' (for example when one of its parameters changes), so changes you might have made directly to the Gui object may be lost.

To access the App part of something, you type: where "ObjectName" is the name of your object. You can also type: To access the Gui part of the same object, you type: where "ObjectName" is the name of your object. You can also type: If we have no GUI (for example we are in command-line mode), the last line will return 'None'.

The Document objects
In FreeCAD all your work resides inside Documents. A document contains your geometry and can be saved to a file. Several documents can be opened at the same time. The document, like the geometry contained inside, has App and Gui objects. App object contains your actual geometry definitions, while the Gui object contains the different views of your document. You can open several windows, each one viewing your work with a different zoom factor or point of view. These views are all part of your document's Gui object.

To access the App part the currently open (active) document, you type: To create a new document, type: To access the Gui part the currently open (active) document, you type: To access the current view, you type:

Using additional modules
The FreeCAD and FreeCADGui modules are solely responsibles for creating and managing objects in the FreeCAD document. They don't actually do anything such as creating or modifying geometry. That is because that geometry can be of several types, and so it is managed by additional modules, each responsible for managing a certain geometry type. For example, the Part Module uses the OpenCascade kernel, and therefore is able to create and manipulate B-rep type geometry, which is what OpenCascade is built for. The Mesh Module is able to build and modify mesh objects. That way, FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types could be added easily in the future.

Creating objects
Each module has its own way to treat its geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules: will list you all the possible objects you can create. For example, let's create a mesh (treated by the mesh module) and a part (treated by the part module): The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with dir(myMesh) and dir(myPart). Except for one, myMesh has a "Mesh" property and "Part" has a "Shape" property. That is where the Mesh and Part data are stored. For example, let's create a Part cube and store it in our myPart object: You could try storing the cube inside the Mesh property of the myMesh object, it will return an error complaining of the wrong type. That is because those properties are made to store only a certain type. In the myMesh's Mesh property, you can only save stuff created with the Mesh module. Note that most modules also have a shortcut to add their geometry to the document:

Modifying objects
Modifying an object is done the same way: Now let's change the shape by a bigger one:

Querying objects
You can always look at the type of an object like this: or know if an object is derived from one of the basic ones (Part Feature, Mesh Feature, etc): Now you can really start playing with FreeCAD! To look at what you can do with the Part Module, read the Part scripting page, or the Mesh Scripting page for working with the Mesh Module. Note that, although the Part and Mesh modules are the most complete and widely used, other modules such as the Draft Module also have scripting APIs that can be useful to you. For a complete list of each modules and their available tools, visit the Category:API section.