Урок 3. 3D-объекты параметрический бокс

📘 Учебный курс: Создание аддонов для FreeCAD

Цель урока: научиться создавать твёрдые тела (коробки, цилиндры) через Python, понять структуру документа FreeCAD и сделать аддон, который строит параметрическую деталь.

---

🧱 Часть 1. Как устроен документ в FreeCAD?

Прежде чем создавать объекты, важно понять иерархию данных в FreeCAD:

Document (документ)
└── Object (объект)
    └── Shape (геометрия)

• Document — это открытый файл (.FCStd). Всё, что вы создаёте, находится внутри документа.
• Object — это параметрический объект: коробка, цилиндр, эскиз и т.д.
• Shape — это геометрическое тело (B-Rep), которое можно визуализировать.

💡 Вы всегда работаете в контексте активного документа.

Как получить текущий документ?

doc = FreeCAD.ActiveDocument

Если документа нет — создайте новый:

doc = FreeCAD.newDocument("MyDesign")

---

📦 Часть 2. Создание коробки (Box) через Python

Самый простой 3D-объект в FreeCAD — это Part::Box.

Пример кода:

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

Что происходит здесь?

1. doc.addObject("Part::Box", "MyBox")
   → создаёт новый объект типа Box с именем "MyBox"
2. У объекта есть параметрические свойства: Length, Width, Height
3. doc.recompute()
   → перестраивает модель (обязательно после изменения параметров!)

🔸 Все размеры — в миллиметрах (по умолчанию в FreeCAD).

---

🛠 Часть 3. Аддон: «Параметрический бокс»

Теперь создадим аддон, который создаёт коробку с заданными размерами.

Шаг 1. Создайте папку

.../Mod/ParamBoxAddon/

Шаг 2. Файл InitGui.py

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

FreeCADGui.addWorkbench(ParamBoxWorkbench())

Шаг 3. Файл 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):
        # Получаем или создаём документ
        doc = FreeCAD.ActiveDocument
        if not doc:
            doc = FreeCAD.newDocument("BoxDesign")

        # Создаём объект Box
        box = doc.addObject("Part::Box", "MyParamBox")
        box.Length = 30.0
        box.Width = 20.0
        box.Height = 10.0

        # Обязательно пересчитываем!
        doc.recompute()

        # Опционально: фокус на объекте
        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())

---

▶️ Шаг 4. Проверка работы

1. Сохраните файлы
2. Перезапустите FreeCAD
3. Выберите рабочую среду «Parametric Box»
4. Нажмите кнопку «Create Box»

✅ Должен появиться серый параллелепипед в 3D-окне.

Проверьте параметричность!

1. В дереве проекта (Model) дважды кликните по MyParamBox
2. В панели Data измените, например, Length на 50
3. Нажмите Enter → модель автоматически обновится!

Это и есть параметрическое моделирование.

---

🔍 Часть 4. Другие базовые объекты

Вы можете создавать не только коробки. Вот несколько примеров:

Цилиндр

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

Сфера

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

Конус

cone = doc.addObject("Part::Cone", "MyCone")
cone.Radius1 = 10.0  # нижний радиус
cone.Radius2 = 5.0   # верхний радиус
cone.Height = 20.0

💡 Все эти объекты находятся в модуле Part, который встроен в FreeCAD.

---

🧪 Практическое задание

1. Измените аддон так, чтобы он создавал цилиндр, а не коробку.
2. Сделайте так, чтобы при создании объект получал уникальное имя (например, Box_1, Box_2…), если объект с таким именем уже есть.
3. Добавьте вторую команду — «Create Cylinder» — в ту же рабочую среду.

Подсказка для уникального имени:

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)

---

💡 Советы по отладке

• Всегда вызывайте doc.recompute() после изменения параметров
• Используйте FreeCAD.Console.PrintMessage("Текст\n") для отладки (сообщения появятся в Report View)
• Проверяйте, существует ли документ перед работой с ним

---

▶️ Что дальше?

В Уроке 4 мы:

• Научимся создавать графический интерфейс (GUI) с полями ввода
• Сделаем окно, где пользователь вводит длину, ширину и высоту
• И по нажатию кнопки — строится бокс с этими параметрами

Это уже будет настоящий инструмент, а не просто демонстрация!