Leçon 3. Création d’objets 3D : boîte paramétrique

📘 Cours : Création d’add-ons pour FreeCAD

Objectif de la leçon : apprendre à créer des corps solides (boîtes, cylindres) via Python, comprendre la structure du document FreeCAD et créer un add-on qui construit une pièce paramétrique.

---

🧱 Partie 1. Comment est structuré un document dans FreeCAD ?

Avant de créer des objets, il est important de comprendre la hiérarchie des données dans FreeCAD :

Document (document)
└── Object (objet)
    └── Shape (géométrie)

• Document — est un fichier ouvert (.FCStd). Tout ce que vous créez se trouve à l’intérieur du document.
• Object — est un objet paramétrique : boîte, cylindre, esquisse, etc.
• Shape — est un corps géométrique (B-Rep) qui peut être visualisé.

💡 Vous travaillez toujours dans le contexte du document actif.

Comment obtenir le document actuel ?

doc = FreeCAD.ActiveDocument

Si aucun document n’existe, créez-en un nouveau :

doc = FreeCAD.newDocument("MyDesign")

---

📦 Partie 2. Création d’une boîte (Box) via Python

L’objet 3D le plus simple dans FreeCAD est Part::Box.

Exemple de code :

doc = FreeCAD.ActiveDocument or FreeCAD.newDocument()
box = doc.addObject("Part::Box", "MyBox")
box.Length = 20.0
box.Width = 10.0
box.Height = 5.0
doc.recompute()

Que se passe-t-il ici ?

1. doc.addObject("Part::Box", "MyBox")
   → crée un nouvel objet de type Box nommé "MyBox"
2. L’objet a des propriétés paramétriques : Length, Width, Height
3. doc.recompute()
   → reconstruit le modèle (obligatoire après modification des paramètres !)

🔸 Toutes les dimensions sont en millimètres (par défaut dans FreeCAD).

---

🛠 Partie 3. Add-on : « Boîte paramétrique »

Maintenant, créons un add-on qui crée une boîte avec des dimensions données.

Étape 1. Créez un dossier

.../Mod/ParamBoxAddon/

Étape 2. Fichier InitGui.py

# InitGui.py
import FreeCADGui
from ParamBoxAddon.param_box_workbench import ParamBoxWorkbench

FreeCADGui.addWorkbench(ParamBoxWorkbench())

Étape 3. Fichier param_box_workbench.py

# param_box_workbench.py
import FreeCAD, FreeCADGui

class CreateBoxCommand:
    def GetResources(self):
        return {
            "MenuText": "Create Box",
            "ToolTip": "Create a parametric box with default size"
        }

    def Activated(self):
        # Obtenir ou créer un document
        doc = FreeCAD.ActiveDocument
        if not doc:
            doc = FreeCAD.newDocument("BoxDesign")

        # Créer l'objet Box
        box = doc.addObject("Part::Box", "MyParamBox")
        box.Length = 30.0
        box.Width = 20.0
        box.Height = 10.0

        # Le recalcul est obligatoire !
        doc.recompute()

        # Optionnel : focus sur l'objet
        FreeCADGui.Selection.clearSelection()
        FreeCADGui.Selection.addSelection(box)

    def IsActive(self):
        return True


class ParamBoxWorkbench(FreeCADGui.Workbench):
    MenuText = "Parametric Box"
    ToolTip = "Create a simple parametric box"

    def Initialize(self):
        self.list = ["CreateBoxCommand"]
        self.appendToolbar("Box Tools", self.list)
        self.appendMenu("ParamBox", self.list)

    def GetClassName(self):
        return "Gui::PythonWorkbench"


FreeCADGui.addCommand("CreateBoxCommand", CreateBoxCommand())

---

▶️ Étape 4. Vérification du fonctionnement

1. Enregistrez les fichiers
2. Redémarrez FreeCAD
3. Sélectionnez l’environnement de travail « Boîte paramétrique »
4. Cliquez sur le bouton « Create Box »

✅ Un parallélépipède gris devrait apparaître dans la fenêtre 3D.

Vérifiez la parametricité !

1. Dans l’arborescence du projet (Modèle), double-cliquez sur MyParamBox
2. Dans le panneau Données, modifiez, par exemple, Length à 50
3. Appuyez sur Entrée → le modèle se mettra à jour automatiquement !

C’est la modélisation paramétrique.

---

🔍 Partie 4. Autres objets de base

Vous pouvez créer plus que de simples boîtes. Voici quelques exemples :

Cylindre

cyl = doc.addObject("Part::Cylinder", "MyCylinder")
cyl.Radius = 10.0
cyl.Height = 25.0

Sphère

sphere = doc.addObject("Part::Sphere", "MySphere")
sphere.Radius = 15.0

Cône

cone = doc.addObject("Part::Cone", "MyCone")
cone.Radius1 = 10.0  # rayon inférieur
cone.Radius2 = 5.0   # rayon supérieur
cone.Height = 20.0

💡 Tous ces objets se trouvent dans le module Part, qui est intégré à FreeCAD.

---

🧪 Exercice pratique

1. Modifiez l’add-on pour qu’il crée un cylindre, au lieu d’une boîte.
2. Faites en sorte que lors de la création, l’objet reçoive un nom unique (par exemple, Box_1, Box_2…) si un objet portant ce nom existe déjà.
3. Ajoutez une deuxième commande — « Create Cylinder » — au même environnement de travail.

Indice pour le nom unique :

base_name = "MyBox"
index = 1
name = base_name
while name in doc.Objects:
    name = f"{base_name}_{index}"
    index += 1
box = doc.addObject("Part::Box", name)

---

💡 Conseils de débogage

• Appelez toujours doc.recompute() après avoir modifié les paramètres
• Utilisez FreeCAD.Console.PrintMessage("Texte\n") pour le débogage (les messages apparaîtront dans la Vue Rapport)
• Vérifiez si le document existe avant de travailler avec lui

---

▶️ Et ensuite ?

Dans la Leçon 4, nous allons :

• Apprendre à créer une interface graphique (GUI) avec des champs de saisie
• Créer une fenêtre où l’utilisateur saisit la longueur, la largeur et la hauteur
• Et en cliquant sur un bouton — une boîte avec ces paramètres est construite

Ce sera déjà un véritable outil, et non une simple démonstration !