Lezione 3. Creazione di oggetti 3D: scatola parametrica

📘 Corso di formazione: Creazione di addon per FreeCAD

Obiettivo della lezione: imparare a creare corpi solidi (scatole, cilindri) tramite Python, comprendere la struttura del documento FreeCAD e creare un addon che costruisce un pezzo parametrico.

---

🧱 Parte 1. Come è strutturato un documento in FreeCAD?

Prima di creare oggetti, è importante comprendere la gerarchia dei dati in FreeCAD:

Document (documento)
└── Object (oggetto)
    └── Shape (geometria)

• Document — è un file aperto (.FCStd). Tutto ciò che crei si trova all’interno del documento.
• Object — è un oggetto parametrico: scatola, cilindro, schizzo, ecc.
• Shape — è un corpo geometrico (B-Rep) che può essere visualizzato.

💡 Lavori sempre nel contesto del documento attivo.

Come ottenere il documento corrente?

doc = FreeCAD.ActiveDocument

Se non c’è un documento, creane uno nuovo:

doc = FreeCAD.newDocument("MyDesign")

---

📦 Parte 2. Creazione di una scatola (Box) tramite Python

L’oggetto 3D più semplice in FreeCAD è Part::Box.

Esempio di codice:

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()

Cosa succede qui?

1. doc.addObject("Part::Box", "MyBox")
   → crea un nuovo oggetto di tipo Box con il nome "MyBox"
2. L’oggetto ha proprietà parametriche: Length, Width, Height
3. doc.recompute()
   → ricostruisce il modello (obbligatorio dopo aver modificato i parametri!)

🔸 Tutte le dimensioni sono in millimetri (per impostazione predefinita in FreeCAD).

---

🛠 Parte 3. Addon: «Scatola parametrica»

Ora creeremo un addon che crea una scatola con dimensioni specificate.

Passo 1. Crea una cartella

.../Mod/ParamBoxAddon/

Passo 2. File InitGui.py

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

FreeCADGui.addWorkbench(ParamBoxWorkbench())

Passo 3. File 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):
        # Ottieni o crea un documento
        doc = FreeCAD.ActiveDocument
        if not doc:
            doc = FreeCAD.newDocument("BoxDesign")

        # Crea l'oggetto Box
        box = doc.addObject("Part::Box", "MyParamBox")
        box.Length = 30.0
        box.Width = 20.0
        box.Height = 10.0

        # Ricostruisci obbligatoriamente!
        doc.recompute()

        # Opzionale: focus sull'oggetto
        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())

---

▶️ Passo 4. Verifica del funzionamento

1. Salva i file
2. Riavvia FreeCAD
3. Seleziona l ambiente di lavoro «Parametric Box»
4. Clicca sul pulsante «Create Box»

✅ Dovrebbe apparire un parallelepipedo grigio nella finestra 3D.

Verifica la parametricità!

1. Nell albero del progetto (Model) fai doppio clic su MyParamBox
2. Nel pannello Data modifica, ad esempio, Length a 50
3. Premi Invio → il modello si aggiornerà automaticamente!

Questo è il modellazione parametrica.

---

🔍 Parte 4. Altri oggetti base

Puoi creare non solo scatole. Ecco alcuni esempi:

Cilindro

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

Sfera

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

Cono

cone = doc.addObject("Part::Cone", "MyCone")
cone.Radius1 = 10.0  # raggio inferiore
cone.Radius2 = 5.0   # raggio superiore
cone.Height = 20.0

💡 Tutti questi oggetti si trovano nel modulo Part, che è integrato in FreeCAD.

---

🧪 Esercizio pratico

1. Modifica l addon in modo che crei un cilindro, anziché una scatola.
2. Fai in modo che, alla creazione, l oggetto riceva un nome unico (ad esempio, Box_1, Box_2…), se un oggetto con lo stesso nome esiste già.
3. Aggiungi un secondo comando — «Create Cylinder» — allo stesso ambiente di lavoro.

Suggerimento per il nome unico:

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)

---

💡 Consigli per il debug

• Chiama sempre doc.recompute() dopo aver modificato i parametri
• Usa FreeCAD.Console.PrintMessage("Testo\n") per il debug (i messaggi appariranno nella Report View)
• Controlla se il documento esiste prima di lavorarci

---

▶️ Cosa c è dopo?

Nella Lezione 4 impareremo a:

• Creare un interfaccia grafica (GUI) con campi di input
• Creare una finestra in cui l utente inserisce lunghezza, larghezza e altezza
• E al clic di un pulsante — viene costruita una scatola con questi parametri

Questo sarà già uno strumento reale, non solo una dimostrazione!