Lekcja 3. Tworzenie obiektów 3D: Prostopadłościan parametryczny

Tutorial: Tworzenie Dodatków dla FreeCAD

Cel Lekcji: Nauczenie się tworzenia brył (prostopadłościanów, cylindrów) za pomocą Pythona, zrozumienie struktury dokumentu FreeCAD i stworzenie dodatku, który buduje część parametryczną.

Część 1. Jak jest zorganizowany dokument w FreeCAD?

Zanim zaczniesz tworzyć obiekty, ważne jest, aby zrozumieć hierarchię danych w FreeCAD:

1. Dokument ($\text{Document}$) – to otwarty plik ($\text{.FCStd}$). Wszystko, co tworzysz, znajduje się w dokumencie.
2. Obiekt ($\text{Object}$) – to obiekt parametryczny: prostopadłościan, cylinder, szkic itp.
3. Kształt ($\text{Shape}$) – to bryła geometryczna ($\text{B-Rep}$), którą można wizualizować.

Zawsze pracujesz w kontekście aktywnego dokumentu.

• Pobranie bieżącego dokumentu: doc = FreeCAD.ActiveDocument
• Tworzenie nowego dokumentu: doc = FreeCAD.newDocument("MyDesign")

Część 2. Tworzenie Prostopadłościanu za pomocą Pythona

Najprostszym obiektem 3D w FreeCAD jest $\text{Part::Box}$.

Przykład kodu:

Python

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() # Obowiązkowe po zmianie parametrów!

Wszystkie wymiary są w milimetrach (domyślnie w FreeCAD).

Część 3. Dodatek: „Prostopadłościan parametryczny”

Kluczowe kroki do stworzenia dodatku budującego prostopadłościan:

1. Utwórz folder: $\text{…/Mod/ParamBoxAddon/}$
2. Plik InitGui.py: Rejestruje środowisko pracy ($\text{workbench}$).
3. Plik param_box_workbench.py: Zawiera klasę $\text{CreateBoxCommand}$, która tworzy nowy prostopadłościan ($\text{Part::Box}$) z domyślnymi wymiarami ($\text{30.0 x 20.0 x 10.0}$) po wywołaniu.

Część 4. Inne Podstawowe Obiekty

Możesz tworzyć więcej brył za pomocą modułu $\text{Part}$:

• Cylinder: doc.addObject("Part::Cylinder", "MyCylinder") (właściwości: $\text{Radius}$, $\text{Height}$)
• Kula ($\text{Sphere}$): doc.addObject("Part::Sphere", "MySphere") (właściwość: $\text{Radius}$)
• Stożek ($\text{Cone}$): doc.addObject("Part::Cone", "MyCone") (właściwości: $\text{Radius1}$ – dół, $\text{Radius2}$ – góra, $\text{Height}$)

Zadanie Praktyczne

1. Zmodyfikuj dodatek, aby tworzył cylinder zamiast prostopadłościanu.
2. Zapewnij unikalną nazwę dla tworzonego obiektu (np. $\text{Box\_1, Box\_2…}$).
3. Dodaj drugą komendę $\ll\text{Create Cylinder}\gg$ do tego samego środowiska pracy.

---

Lekcja 4. Graficzny Interfejs Użytkownika (GUI): Okno Dialogowe z Polami Wejściowymi – Code 1001

Tutorial: Tworzenie Dodatków dla FreeCAD

Cel Lekcji: Stworzenie okna z polami do wprowadzania długości, szerokości i wysokości, a następnie zbudowanie prostopadłościanu z tymi parametrami po kliknięciu przycisku.

W Tym Artykule

• 01 Część 1. Jak działa GUI w FreeCAD?
• 02 Część 2. Dodatek: „Box Builder with GUI” (Kreator Prostopadłościanów z GUI)
• 04 Krok 4. Sprawdzenie Działania
• 05 Zadanie Praktyczne
• 06 Wskazówki do Pracy z GUI
• 07 Co dalej?

Część 1. Jak działa GUI w FreeCAD?

FreeCAD używa $\text{PySide}$ – wrappera Pythona dla biblioteki Qt (tej samej, której używają Blender, Maya i wiele innych programów).

Kluczowe komponenty:

• $\text{QtGui.QDialog}$ – okno modalne
• $\text{QtGui.QLineEdit}$ – pole do wprowadzania tekstu
• $\text{QtGui.QPushButton}$ – przycisk
• $\text{QtGui.QFormLayout}$ – wygodny układ „etykieta + pole”

Wszystkie elementy GUI są tworzone wewnątrz skryptu Pythona, bez plików zewnętrznych.

Część 2. Dodatek: „Box Builder with GUI”

Krok 3. Plik box_builder_workbench.py

Python

# box_builder_workbench.py
import FreeCAD, FreeCADGui
from PySide import QtGui, QtCore

# === FUNKCJA TWORZENIA PROSTOPADŁOŚCIANU ===
def create_box(length, width, height, name="CustomBox"):
    doc = FreeCAD.ActiveDocument
    if not doc:
        doc = FreeCAD.newDocument("BoxBuilder")

    # Unikalna nazwa
    base_name = name
    index = 1
    obj_name = base_name
    while obj_name in [obj.Name for obj in doc.Objects]:
        obj_name = f"{base_name}_{index}"
        index += 1

    box = doc.addObject("Part::Box", obj_name)
    box.Length = length
    box.Width = width
    box.Height = height
    doc.recompute()
    return box

# === OKNO DIALOGOWE ===
class BoxBuilderDialog(QtGui.QDialog):
    def __init__(self):
        super(BoxBuilderDialog, self).__init__()
        self.setWindowTitle("Box Builder")
        self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
        self.resize(300, 150)

        # Pola wejściowe
        self.length_input = QtGui.QLineEdit("30.0")
        self.width_input = QtGui.QLineEdit("20.0")
        self.height_input = QtGui.QLineEdit("10.0")

        # Przyciski
        self.create_button = QtGui.QPushButton("Create Box")
        self.cancel_button = QtGui.QPushButton("Cancel")

        # Łączenie przycisków
        self.create_button.clicked.connect(self.on_create)
        self.cancel_button.clicked.connect(self.reject)

        # Układ (Layout)
        layout = QtGui.QFormLayout()
        layout.addRow("Length (mm):", self.length_input)
        layout.addRow("Width (mm):", self.width_input)
        layout.addRow("Height (mm):", self.height_input)

        button_layout = QtGui.QHBoxLayout()
        button_layout.addWidget(self.create_button)
        button_layout.addWidget(self.cancel_button)

        main_layout = QtGui.QVBoxLayout()
        main_layout.addLayout(layout)
        main_layout.addLayout(button_layout)

        self.setLayout(main_layout)

    def on_create(self):
        try:
            length = float(self.length_input.text())
            width = float(self.width_input.text())
            height = float(self.height_input.text())

            if length <= 0 or width <= 0 or height <= 0:
                raise ValueError("All dimensions must be positive")

            create_box(length, width, height)
            self.accept() # Zamknij okno
        except ValueError as e:
            QtGui.QMessageBox.warning(self, "Input Error", f"Invalid input:\n{str(e)}")

# === KOMENDA ===
class BoxBuilderCommand:
    # ...
    def Activated(self):
        dialog = BoxBuilderDialog()
        dialog.exec_() # Wywołanie modalne
    # ...

# === ŚRODOWISKO PRACY (WORKBENCH) ===
class BoxBuilderWorkbench(FreeCADGui.Workbench):
    # ...
    pass

FreeCADGui.addCommand("BoxBuilderCommand", BoxBuilderCommand())

Zadanie Praktyczne

1. Dodaj czwarte pole: „Nazwa” – aby użytkownik mógł ustawić nazwę obiektu.
2. Upewnij się, że jeśli nazwa jest pusta, zostanie użyta domyślna wartość („$\text{CustomBox}$”).
3. Dodaj pole wyboru ($\text{checkbox}$) „Center on origin” (Wyśrodkuj na początku układu współrzędnych) $\rightarrow$ jeśli jest włączone, prostopadłościan powinien być wyśrodkowany.

Wskazówka do centrowania:

Po utworzeniu prostopadłościanu zmień jego właściwość $\text{Placement}$:

Python

from FreeCAD import Vector
box.Placement.Base = Vector(-length/2, -width/2, height/2)

Co dalej?

W Lekcji 5 nauczymy się:

• Jak zapisywać ustawienia pomiędzy uruchomieniami FreeCAD
• Zapewnić zapamiętanie ostatnio wprowadzonej wartości wymiaru
• Użyć wbudowanego mechanizmu FreeCAD: $\text{FreeCAD.ParamGet()}$

---

Lekcja 7. Publikowanie Dodatku: Od Folderu do GitHub i Menedżera Dodatków – Code 1001

Cel Lekcji: Przygotowanie dodatku do dystrybucji, stworzenie metadanych i opublikowanie go na GitHub, aby każdy użytkownik FreeCAD mógł go zainstalować jednym kliknięciem.

Część 1. Czym jest Menedżer Dodatków?

Menedżer Dodatków ($\text{Tools} \to \text{Addon Manager}$) to wbudowane narzędzie FreeCAD, które:

• Pokazuje katalog ponad 300 oficjalnych dodatków.
• Pozwala instalować, aktualizować i usuwać dodatki bez ręcznego kopiowania plików.
• Współpracuje z repozytoriami GitHub.

Aby Twój dodatek się tam pojawił, musisz:

1. Przesłać go na GitHub.
2. Dodać plik $\text{package.xml}$.
3. (Opcjonalnie) Wysłać $\text{PR}$ (Pull Request) do $\text{FreeCAD-addons}$.

Część 3. Tworzenie package.xml

Utwórz plik $\text{package.xml}$ w katalogu głównym:

XML

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1"
         xmlns="[Namespace Usunięty]">
    <name>BoxBuilderAddon</name>
    <description>
        A simple tool to create parametric boxes with custom dimensions
        and GUI. Saves last used values between sessions.
    </description>
    <version>1.0.0</version>
    <date>2025-04-05</date>
    <maintainer email="your.email@example.com">Your Name</maintainer>
    <license file="LICENSE">LGPL-2.1-or-later</license>
    <icon>Resources/icons/box_builder.svg</icon>
    <content>
        <workbench>BoxBuilderAddon</workbench>
    </content>
    <dependencies>
        <freecad>0.20</freecad>
    </dependencies>
</package>

Część 4. Plik LICENSE

Utwórz plik $\text{LICENSE}$ z tekstem licencji.

Przykład dla LGPL-2.1:

1. Przejdź do: Usunięty link.
2. Skopiuj cały tekst.
3. Wklej go do pliku $\text{LICENSE}$.

Część 6. Publikowanie na GitHub

Kroki:

1. Zarejestruj się na GitHub.
2. Kliknij New repository.
3. Nazwa: $\text{BoxBuilderAddon}$.
4. Zainicjuj bez $\text{README}$.
5. Kliknij Create repository.
6. Postępuj zgodnie z instrukcjami, aby przesłać swój lokalny folder:

Bash

git init
git add .
git commit -m "Initial release"
git branch -M main
git remote add origin [Usunięty URL Repozytorium]
git push -u origin main

Zastąp yourname swoją nazwą użytkownika GitHub.

Część 7. Testowanie Instalacji

Aby dodatek pojawił się na oficjalnej liście, musisz przesłać Pull Request do: Usunięty link.

Nawet bez tego, użytkownicy mogą go zainstalować za pomocą bezpośredniego linku:

• W Menedżerze Dodatków: $\text{Tools} \to \text{Addon Manager} \to \dots \to \text{Install custom addon}$
• Wklej URL: Usunięty link.

Co dalej?

• Dodanie obsługi centrowania (z zadania z Lekcji 5).
• Implementacja wielokrotnego wprowadzania (tworzenie siatki prostopadłościanów).
• Integracja z $\text{PartDesign}$ w celu tworzenia brył obrotowych.
• Napisanie dodatku dla własnego zadania: śruby, ramy, obliczenia itp..

Poniższe wideo może być pomocne, ponieważ pokazuje, jak instalować dodatki w pokrewnym programie CAD/3D (Blenderze), co może dostarczyć ogólnego kontekstu dla zarządzania dodatkami.

Jak instalować dodatki w Blenderze (z GitHub i Blender.org) [Usunięty link do wideo]