Scripts/fr

Other languages:
Macros
Introduction à Python
Index
Tutoriel
Thème
Scripting
Niveau
Base
Temps d'exécution estimé
Auteurs
onekk Carlo
Version de FreeCAD
0.19
Fichiers exemples
Voir aussi
None

Introduction

Par script, nous entendons la création d'objets topologiques à l'aide de l'interpréteur Python de FreeCAD. FreeCAD pourrait être utilisé comme un "très bon" remplaçant d'OpenSCAD, principalement parce qu'il possède un véritable interpréteur Python, ce qui signifie qu'il dispose d'un véritable langage de programmation, presque tout ce que vous pouvez faire avec l'interface graphique est réalisable avec un script Python.

Malheureusement, les informations sur les scripts dans la documentation, et même dans ce wiki sont éparpillées et manquent d'uniformité "d'écriture" et la plupart d'entre elles sont expliquées d'une manière trop technique.

Commencer

Le premier obstacle d'une manière simple à la création de scripts est qu'il n'y a pas de moyen direct d'accéder à l'éditeur Python interne de FreeCAD via un élément de menu ou une icône dans la zone de la barre d'outils, mais sachant que FreeCAD ouvre un fichier avec un .py dans l'éditeur Python interne, l'astuce la plus simple est de créer dans votre éditeur de texte préféré, puis de l'ouvrir avec la commande habituelle Fichier → Ouvrir.

Pour faire les choses d'une manière polie, le fichier doit être écrit avec un certain ordre, l'éditeur Python FreeCAD a une bonne "Syntaxe Highlighting" qui manque dans de nombreux éditeurs simples comme le Notepad de Windows ou certains éditeurs Linux de base, il suffit donc d'écrire ces quelques lignes : 

"""filename.py

   A short description of what the script does

"""

Enregistrez-les avec un nom significatif avec l'extension .py et chargez le fichier résultant dans FreeCAD, avec la commande Fichier → Ouvrir.

Un exemple simple de ce qu'il est nécessaire d'avoir dans un script est présenté dans cette partie du code que vous pourriez utiliser comme modèle pour presque tous les futurs scripts: 

"""filename.py

   First FreeCAD Script

"""

import FreeCAD
from FreeCAD import Placement, Rotation, Vector
import FreeCADGui

DOC_NAME = "Wiki_Example"
DOC = FreeCAD.newDocument(DOC_NAME)
FreeCAD.setActiveDocument(DOC.Name)

ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)

# Helper function

def set_view():
    """Rearrange View."""
    if not FreeCAD.GuiUp:
        return
    doc = FreeCADGui.ActiveDocument
    if doc is None:
        return
    view = doc.ActiveView
    if view is None:
        return
    # Check if the view is a 3D view:
    if not hasattr(view, "getSceneGraph"):
        return
    view.viewAxometric()
    view.fitAll()

Certaines astuces sont incorporées dans le code ci-dessus:

Commençons par un petit script qui fait un très petit travail, mais qui montre la puissance de cette approche. 

# Script functions

def my_box(name, len, wid, hei):
    """Create a box."""
    obj_b = DOC.addObject("Part::Box", name)
    obj_b.Length = len
    obj_b.Width = wid
    obj_b.Height = hei

    DOC.recompute()

    return obj_b

# objects definition

obj = my_box("test_cube", 5, 5, 5)

set_view()

Ecrivez les lignes de code ci-dessus après # Script functions et appuyez sur la flèche verte dans la Barre d'outils des macros

Vous verrez des choses magiques, un nouveau document est ouvert nommé "Wiki_example" et vous verrez dans la vue 3D un Cube comme ci-dessous.

Test cube

Quelque chose en plus

Pas si surprenant ? Oui, mais il faut commencer quelque part, on peut faire la même chose avec un Cylindre, ajouter ces lignes de code après la fonction my_box() et avant la ligne : # objects definition. 

def my_cyl(name, ang, rad, hei):
    """Create a Cylinder."""
    obj = DOC.addObject("Part::Cylinder", name)
    obj.Angle = ang
    obj.Radius = rad
    obj.Height = hei

    DOC.recompute()

    return obj

Même ici, rien de trop excitant. Mais veuillez noter quelques particularités:

Maintenant, que faire avec ces géométries?

Introduisons les opérations booléennes. Comme exemple pour démmarrer, placez ces lignes après my_cyl, cela crée une fonction pour une Fusion également connue sous le nom d'opération Union : 

def fuse_obj(name, obj_0, obj_1):
    """Fuse two objects."""
    obj = DOC.addObject("Part::Fuse", name)
    obj.Base = obj_0
    obj.Tool = obj_1
    obj.Refine = True
    DOC.recompute()

    return obj

Rien d'exceptionnel ici aussi, notez cependant l'uniformité dans le codage des fonctions. Cette approche est plus linéaire que celles vues autour d'autres tutoriels sur les scripts, cette "linéarité" aide grandement à la lisibilité et aussi avec les opérations couper-copier-coller.

Utilisons les géométries, supprimons les lignes sous la section de code commençant par # objects definition et insérons les lignes suivantes: 

# objects definition

obj = my_box("test_cube", 5, 5, 5)

obj1 = my_cyl("test_cyl", 360, 2, 10)

fuse_obj("Fusion", obj, obj1)

set_view()

Lancez le script avec la flèche verte et nous verrons dans la vue 3D quelque chose comme :

Cube et cylindre

Placement

Le concept de placement est relativement complexe, voir tutoriel avion pour une explication plus approfondie.

Nous avons généralement besoin de placer des géométries respectueuses les unes des autres, lorsque la construction d'un objet complexe est une tâche récurrente, le moyen le plus courant est d'utiliser la propriété geometry Placement.

FreeCAD offre un large choix de moyens pour définir cette propriété, l'un est plus adapté à l'autre en fonction des connaissances et du parcours de l'utilisateur, mais plus l'écriture est simple et expliquée dans le Tutoriel cité, plus il utilise une définition particulière de la partie Rotation de Placement, assez facile à apprendre. 

FreeCAD.Placement(Vector(0, 0, 0), FreeCAD.Rotation(10, 20, 30), Vector(0, 0, 0))

Mais par rapport à d'autres considérations, une chose est cruciale, la géométrie point de référence, c'est-à-dire le point à partir duquel l'objet est modélisé par FreeCAD, comme décrit dans ce tableau, copié de Placement :

Objet Point de référence
Part.Box gauche (minx), avant (miny), bas (minz) sommet
Part.Sphere centre de la sphère
Part.Cylinder centre de la face inférieure
Part.Cone centre de la face inférieure (ou sommet si le rayon inférieur est 0)
Part.Torus centre du tore
Fonctions dérivées d'esquisses La fonction hérite de la position de l'esquisse sous-jacente. Les esquisses commencent toujours par Position = (0, 0, 0). Cette position correspond à l'origine dans l'esquisse.

Cette information doit être gardée à l'esprit, en particulier lorsque nous devons appliquer une rotation.

Quelques exemples peuvent vous aider, supprimez la fonction my_box et toutes les lignes après la fonction my_cyl et ajoutez le code ci-dessous après la fonction my_cyl : 

def my_sphere(name, rad):
    """Create a Sphere."""
    obj = DOC.addObject("Part::Sphere", name)
    obj.Radius = rad

    DOC.recompute()

    return obj

def my_box2(name, len, wid, hei, cent=False, off_z=0):
    """Create a box with an optional z offset."""
    obj_b = DOC.addObject("Part::Box", name)
    obj_b.Length = len
    obj_b.Width = wid
    obj_b.Height = hei

    if cent is True:
        pos = Vector(len * -0.5, wid * -0.5, off_z)
    else:
        pos = Vector(0, 0, off_z)

    obj_b.Placement = Placement(pos, ROT0, VEC0)

    DOC.recompute()

    return obj_b

def mfuse_obj(name, objs):
    """Fuse multiple objects."""
    obj = DOC.addObject("Part::MultiFuse", name)
    obj.Shapes = objs
    obj.Refine = True
    DOC.recompute()

    return obj

def airplane():
    """Create an airplane shaped solid."""
    fuselage_length = 30
    fuselage_diameter = 5
    wing_span = fuselage_length * 1.75
    wing_width = 7.5
    wing_thickness = 1.5
    tail_height = fuselage_diameter * 3.0
    tail_position = fuselage_length * 0.70
    tail_offset = tail_position - (wing_width * 0.5)

    obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)

    obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)

    obj3 = my_sphere("nose", fuselage_diameter)
    obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)

    obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
    obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)

    objs = (obj1, obj2, obj3, obj4)

    obj = mfuse_obj("airplane", objs)
    obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))

    DOC.recompute()

    return obj

# objects definition

airplane()

set_view()

Expliquons quelque chose dans le code:

Exemple d'un avion
Rotation de l'avion
Propriété de placement

On peut facilement remarquer que la géométrie de l'avion tourne autour de son "barycentre" ou "centre de gravité", que j'ai fixé au centre de l'aile, un endroit relativement "naturel", mais qui pourrait être placé n'importe où vous voulez.

Le premier Vector(0, 0, 0) est le vecteur de translation, non utilisé ici, mais si vous remplacez airplane() par ces lignes : 

obj_f = airplane()

print(obj_F.Placement)

Vous verrez dans la fenêtre Rapport ce texte: 

Placement [Pos=(0, -21, 21), Yaw-Pitch-Roll=(0, 0, -90)]

Que s'est-il passé?

FreeCAD a traduit Vector(0, 0, 0), FreeCAD.Rotation(0, 0, -90), Vector(0, 0, tail_position) en d'autres termes notre définition Placement qui spécifie trois composants, Translation, Rotation et centre de rotation en valeurs "internes" de seulement deux composants, Translation et Rotation.

vous pouvez facilement visualiser la valeur de tail_position en utilisant une instruction print dans la fonction airplane() et voir que c'est : 

tail_position = 21.0

en d'autres termes, le centre de rotation de la géométrie est à Vector(0, 0, 21), mais ce centre de rotation n'est pas affiché dans l'interface graphique, il pourrait être entré comme Placement, il n'a pas pu être facilement récupéré.

C'est le sens du mot "maladroit" que j'ai utilisé pour définir la propriété Placement.


Voici l'exemple de code complet avec un docstring de script décent selon la convention de docstrings de Google : 

"""Sample code.

Filename:
   airplane.py

Author:
    Dormeletti Carlo (onekk)

Version:
    1.0

License:
    Creative Commons Attribution 3.0

Summary:
    This is sample code written for a FreeCAD Wiki page.
    It creates an airplane shaped solid using standard "Part WB" shapes.

"""

import FreeCAD
from FreeCAD import Placement, Rotation, Vector
import FreeCADGui

DOC_NAME = "Wiki_Example"
DOC = FreeCAD.newDocument(DOC_NAME)
FreeCAD.setActiveDocument(DOC.Name)

ROT0 = Rotation(0, 0, 0)
VEC0 = Vector(0, 0, 0)

# Helper function

def set_view():
    """Rearrange View."""
    if not FreeCAD.GuiUp:
        return
    doc = FreeCADGui.ActiveDocument
    if doc is None:
        return
    view = doc.ActiveView
    if view is None:
        return
    # Check if the view is a 3D view:
    if not hasattr(view, "getSceneGraph"):
        return
    view.viewAxometric()
    view.fitAll()

# Script functions

def my_cyl(name, ang, rad, hei):
    """Create a Cylinder."""
    obj = DOC.addObject("Part::Cylinder", name)
    obj.Angle = ang
    obj.Radius = rad
    obj.Height = hei

    DOC.recompute()

    return obj

def my_sphere(name, rad):
    """Create a Sphere."""
    obj = DOC.addObject("Part::Sphere", name)
    obj.Radius = rad

    DOC.recompute()

    return obj

def my_box2(name, len, wid, hei, cent=False, off_z=0):
    """Create a box with an optional z offset."""
    obj_b = DOC.addObject("Part::Box", name)
    obj_b.Length = len
    obj_b.Width = wid
    obj_b.Height = hei

    if cent is True:
        pos = Vector(len * -0.5, wid * -0.5, off_z)
    else:
        pos = Vector(0, 0, off_z)

    obj_b.Placement = Placement(pos, ROT0, VEC0)

    DOC.recompute()

    return obj_b

def mfuse_obj(name, objs):
    """Fuse multiple objects."""
    obj = DOC.addObject("Part::MultiFuse", name)
    obj.Shapes = objs
    obj.Refine = True
    DOC.recompute()

    return obj

def airplane():
    """Create an airplane shaped solid."""
    fuselage_length = 30
    fuselage_diameter = 5
    wing_span = fuselage_length * 1.75
    wing_width = 7.5
    wing_thickness = 1.5
    tail_height = fuselage_diameter * 3.0
    tail_position = fuselage_length * 0.70
    tail_offset = tail_position - (wing_width * 0.5)

    obj1 = my_cyl("main_body", 360, fuselage_diameter, fuselage_length)

    obj2 = my_box2("wings", wing_span, wing_thickness, wing_width, True, tail_offset)

    obj3 = my_sphere("nose", fuselage_diameter)
    obj3.Placement = Placement(Vector(0, 0, fuselage_length), ROT0, VEC0)

    obj4 = my_box2("tail", wing_thickness, tail_height, wing_width, False, 0)
    obj4.Placement = Placement(Vector(0, tail_height * -1, 0), ROT0, VEC0)

    objs = (obj1, obj2, obj3, obj4)

    obj = mfuse_obj("airplane", objs)
    obj.Placement = Placement(VEC0, Rotation(0, 0, -90), Vector(0, 0, tail_position))

    DOC.recompute()

    return obj

# objects definition

airplane()

set_view()


Macros
Introduction à Python
Index
Hub utilisateurs expérimentés