Path scripting/fr

Introduction
L'atelier Path propose des outils pour importer, créer, manipuler et exporter des [|parcours-outils] dans FreeCAD. Avec eux, l'utilisateur peut importer, voir et modifier des programmes G-Code existants, créer des chemins d'outils depuis des formes 3D et exporter ces chemins d'outils vers G-Code.

À l'heure actuelle, l'atelier Path est encore au début de son développement et ne peut encore pas vous proposer les fonctionnalités avancées de certains logiciels commerciaux. Néanmoins, son interface de script pour python vous facilite la modification ou le développement d'outils plus puissants et est, pour l'instant, plus destiné aux utilisateurs avec des connaissances en scripting python qu'aux utilisateurs finaux.

Ci-dessous, vous trouverez une description plus approfondie de l'API de scripting python.

Démarrage rapide
Les objets Path de FreeCAD Path sont des commandes de séquences de déplacement. Voici un utilisation typique:

Format G-Code interne de FreeCAD
Un concept préliminaire est important à appréhender. La plus grande partie de l'implémentation ci-dessous est fortement liée aux commandes de déplacement qui ont les même noms que ceux de G-Code mais sans être proche d'une implémentation spécifique à un contrôleur. Nous avons choisi des noms tels que « G0 » pour indiquer un mouvement « rapide » ou « G1 » pour un déplacement « d'alimentation » pour la performance (sauvegarde de fichier efficace) etpour minimiser le travail de traduction de et vers les autres formats G-Code. Puis que le monde de la CNC parle des milliers de dialectes G-Code, nous avons choisi de rester avec une partie simplifiée de ce code. On pourrait décrire le format G-Code de FreeCAD's comme une forme indépendante des machines.

Les données Path sont sauvegardées directement sous cette forme de G-Code dans les fichiers .FCStd

Toutes les traductions de et vers des dialectes G-Code FreeCAD sont réalisés par des scripts pre et post. Cela cignifie que si vous voulez travailler avec une machine qui utilise un contrôleur spécifique LinuxCNC, Fanuc, Mitusubishi, ou HAAS, etc., vous devrez utiliser (ou écrire s'il n'existe pas) un prost-processeurr pour ce contrôle particulier (allez voir la section « Importer et exporter du G-Code » ci-dessous).

Référence GCode
Les règles et les lignes directrices suivantes définissent le jeu de G-Code employé en interne dans FreeCAD:


 * la donnée G-Code, dans les objets Path de FreeCAD, est séparée en « Commandes ». Une Commande est définie par un nom qui doit débuter par G ou M et (optionnellement) des arguments, qui sont sous la forme Lettre = Nombre Flottant, par exemple X 0.02 ou Y 3.5 ou F 300. Ce sont des exemples typiques de commandes G-Code de FreeCAD:

G0 X2.5 Y0 (The command name is G0, the arguments are X=2.5 and Y=0)

G1 X30 (The command name is G1, the only argument is X=30)

G90 (The command name is G90, there are no arguments)


 * For the numeric part of a G or M command, both "G1" or "G01" forms are supported.
 * Only commands starting with G or M are supported at the moment.
 * Only millimeters are accepted at the moment. G20/G21 are not considered.
 * Arguments are always sorted alphabetically. This means that if you create a command with "G1 X2 Y4 F300", it will be stored as "G1 F300 X2 Y4"
 * Arguments cannot be repeated inside a same command. For example, "G1 X1 Y2 X2 Y3" will not work. You will need to split it into two commands, for example: "G1 X1 Y2, G1 X2 Y3"
 * X, Y, Z, A, B, C arguments are absolute or relative, depending on the current G90/G91 mode. Default (if not specified) is absolute.
 * I, J, K are always relative to the last point. K can be omitted.
 * X, Y, or Z (and A, B, C) can be omitted. In this case, the previous X, Y or Z coordinates are maintained.
 * Gcode commands other than the ones listed in the table below are supported, that is, they are saved inside the path data (as long as they comply to the rules above, of course), but they simply won't produce any visible result on screen. For example, you could add a G81 command, it will be stored, but not displayed.

The Command object
The Command object represents a gcode command. It has three attributes: Name, Parameters and Placement, and two methods: toGCode and setFromGCode. Internally, it contains only a name and a dictionary of parameters. The rest (placement and gcode) is computed to/from this data.

The Path object
The Path object holds a list of commands As a shortcut, a Path object can also be created directly from a full GCode sequence. It will be divided into a sequence of commands automatically.

The Path feature
The Path feature is a FreeCAD document object, that holds a path, and represents it in the 3D view. The Path feature also holds a Placement property. Changing the value of that placement will change the position of the Feature in the 3D view, although the Path information itself won't be modified. The transformation is purely visual. This allows you, for example, to create a Path around a face that has a particular orientation on your model, that is not the same orientation as your cutting material will have on the CNC machine.

However, Path Compounds can make use of the Placement of their children (see below).

The Tool and Tooltable objects
The Tool object contains the definitions of a CNC tool. The Tooltable object contains an ordered list of tools. Tooltables are attached as a property to Path Project features, and can also be edited via the GUI, by double-clicking a project in the tree view, and clicking the "Edit tooltable" button in the task views that opens.

From that dialog, tooltables can be imported from FreeCAD's .xml and HeeksCad's .tooltable formats, and exported to FreeCAD's .xml format.

The Path Compound feature
The aim of this feature is to gather one or more toolpaths and associate it (them) with a tooltable. The Compound feature also behaves like a standard FreeCAD group, so you can add or remove objects to/from it directly from the tree view. You can also reorder items by double-clicking the Compound object in the Tree view, and reorder its elements in the Task view that opens. An important feature of Path Compounds is the possibility to take into account the Placement of their child paths or not, by setting their UsePlacements property to True or False. If not, the Path data of their children will simply be added sequentially. If True, each command of the child paths, if containing position information (G0, G1, etc..) will first be transformed by the Placement before being added.

Creating a compound with just one child path allows you therefore to turn the child path's Placement "real" (it affects the Path data).

The Path Project feature
The Path project is an extended kind of Compound, that has a couple of additional machine-related properties such as a tooltable. It is made mainly to be the main object type you'll want to export to gcode once your whole path setup is ready. The Project object is now coded in python, so its creation mechanism is a bit different: The Path module also features a GUI tooltable editor that can be called from python, giving it an object that has a ToolTable property:

The Path Shape feature
This feature is a normal Path object with an additional Shape property. By giving that property a Wire shape, its path will be automatically calculated from the shape. Note that in this case the placement is automatically set to the first point of the wire, and the object is therefore not movable anymore by changing its placement. To move it, the underlying shape itself must be moved.

Python features
Both Path::Feature and Path::FeatureShape features have a python version, respectively named Path::FeaturePython and Path::FeatureShapePython, that can be used in python code to create more advanced parametric objects derived from them.

Native format
GCode files can be directly imported and exported via the GUI, by using the "open", "insert" or "export" menu items. After the file name is acquired, a dialog pops up to ask which processing script must be used. It can also be done from python:

Path information is stored into Path objects using a subset of gcode described in the "FreeCAD's internal GCode format"section above. This subset can be imported or exported "as is", or converted to/from a particular version of GCode suited for your machine.

If you have a very simple and standard GCode program, that complies to the rules described in the "FreeCAD's internal GCode format" section above, for example the boomerang from http://www.cnccookbook.com/GWESampleFiles.html, it can be imported directly into a Path object, without translation (this is equivalent to using the "None" option of the GUI dialog):

In the same manner, you can obtain the path information as "agnostic" gcode, and store it manually in a file:

If you need a different output, though, you will need to convert this agnostic GCode into a format suited for your machine. That is the job of post-processing scripts.

Using pre- and post-processing scripts
If you have a gcode file written for a particular machine, which doesn't comply to the internal rules used by FreeCAD, described in the "FreeCAD's internal GCode format" section above, it might fail to import and/or render properly in the 3D view. To remedy to this, you must use a pre-processing script, which will convert from your machine-specific format to the FreeCAD format.

If you know the name of the pre-processing script to use, you can import your file using it, from the python console like this: In the same manner, you can output a path object to GCode, using a post_processor script like this:

Writing processing scripts
Pre- and post-processing scripts behave like other common FreeCAD imports/exporters. When choosing a pre/post processing script from the dialog, the import/export process will be redirected to the specified given script. Preprocessing scripts must contain at least the following methods open(filename) and insert(filename,docname). Postprocessing scripts need to implement export(objectslist,filename).

Scripts are placed into either the Mod/Path/PathScripts folder or the user's macro path directory. You can give them any name you like but by convention, and to be picked by the GUI dialog, pre-processing scripts names must end with "_pre", post-processing scripts with "_post" (make sure to use the underscore, not the hyphen, otherwise python cannot import it). This is an example of a very, very simple preprocessor. More complex examples are found in the Mod/Path/PathScripts folder: Pre- and post-processors work exactly the same way. They just do the contrary: The pre scripts convert from specific GCode to FreeCAD's "agnostic" GCode, while post scripts convert from FreeCAD's "agnostic" GCode to machine-specific GCode.