Python scripting tutorial/ru

Введение
Python - это язык программирования, относительно простой в изучении и понимании. Он является многоплатформенным языком с открытым исходным кодом и может использоваться в разных целях: от программирования простых скриптов до очень сложных программ. Но он наиболее распространен как язык сценариев, внедряемых в другие приложения. Так он используется и внутри FreeCAD. Из консоли Python или с помощью собственных скриптов вы можете управлять FreeCAD, заставляя его выполнять очень сложные операции.

Например, из сценария Python вы можете:
 * Создать новые объекты.
 * Изменить существующие объекты.
 * Изменить трехмерное представление этих объектов.
 * Изменить интерфейс FreeCAD.

Существует несколько способов использования Python в FreeCAD:
 * Из Интерпретатора Python в FreeCAD, где вы можете запускать простые команды, симулируя интерфейс командной строки
 * Из макросов, которые являются удобным способом быстрого добавления недостающего функционала в интерфейс FreeCAD
 * Из внешних скриптов, которые можно использовать для создания довольно сложных решений, даже верстаков.

В этом руководстве мы рассмотрим несколько базовых примеров, которые помогут вам начать работу. В этой вики также имеется гораздо больше документации по Python сценариям. Если вы абсолютный новичок в Python и хотите понять, как это работает, у нас есть базовый курс Введение в Python.

Перед написанием сценариев Python, перейдите в окно и проверьте, отмечены ли два пункта: Затем перейдите в и отметьте:



Написание кода Python
Существует два простых способа написания кода Python в FreeCAD: в консоли Python (выберите в меню ) или из редактора макросов (выберите в меню ). В консоли вы последовательно пишете python команды, которые выполняются при нажатии. Макросы могут содержать более сложный многострочный код, который выполняется только во время запуска макроса.



В этом руководстве можно использовать оба метода. Можно копировать/вставлять по одной строчке в консоли Python и нажимать, или копировать/вставлять весь код в новое окно макроса.



Изучение FreeCAD
Начнём с создания нового пустого документа:

Если Вы вводите это в консоли Python FreeCADа, то заметите, что как только Вы ввели (слово FreeCAD с последующей точкой), появится окно, позволяющее быстро автозаполнить продолжение строки. Даже лучше, каждый ввод в списке автодополнения содержит подсказку. Это облегчает раскрытие имеющейся функциональности. Перед выбором, взгляните на другие доступные опции.



Теперь наш новый документ будет создан. Это похоже на нажатие кнопки на панели инструментов. Фактически, большинство кнопок в FreeCAD ничего не делают, кроме выполнения одной или нескольких строк кода Python. Даже лучше, вы можете установить параметр в, чтобы. Это будет выводить в консоль весь код Python, который выполняется при нажатии кнопок. Очень полезно, чтобы узнать, как воспроизводить действия в Python.

Теперь вернёмся назад в документ и посмотрим, что мы можем с ним сделать:

Изучим доступные варианты. Обычно имена, начинающиеся с заглавной буквы, это атрибуты, они содержат значения, а имена с маленькой буквы являются функциями (называемые так же методами), они "что-то делают". Имена, начинающиеся с подчёркиваний, обычно используются для внутренних нужд модуля, и Вам не следует обращать на них внимание. Используем один из методов для добавления в документ нового объекта:

Ничего не произошло. Почему? Потому что FreeCAD создан для больших проектов. Однажды он будет работать с сотнями сложных взаимосвязанных объектов. Возможно, что внесение небольшого изменения может иметь большое значение, вам может потребоваться пересчитать весь документ, что может занять много времени ... По этой причине почти никакая команда не обновляет сцену автоматически. Вы должны сделать это вручную:

Теперь наш куб появился в окне трёхмерного вида. Большинство кнопок панелей инструментов фактически делают две вещи: добавляют объект и выполняют пересчёт. Если Вы включите в настройках опцию и попробуете добавить сферу с соответствующей кнопкой, Вы увидите две строки Python кода, выполняемые одна за другой.

Теперь рассмотрим содержимое нашего куба:

Вы немедленно увидите несколько очень интересных вещей вроде этого:

Это покажет текущую высоту нашего куба. Теперь попробуем её изменить:

Если вы выберете куб с помощью мыши, вы увидите, что Property editor на вкладке появится параметр. Все свойства объекта FreeCAD, которые появляются там (а также на вкладке, подробнее об этом позже), напрямую доступны также для Python по их именам, аналогично параметру. Попробуйте изменить другие размеры окна.



Вектора и размещение
Вектора это самая основная концепция в любом трёхмерном приложении. Вектор это список трёх чисел (x, y и z), описывающих точку или позицию в трёхмерном пространстве. С векторами делаются многие вещи, такие как сложение, вычитание, проекции и многое другое. В FreeCAD вектора работают примерно так:

Еще одно имеющееся у всех объектов FreeCAD свойство - это его размещение. Каждый объект имеет свойство, которое содержит (положение) и  (ориентация) объекта. Это легко манипулировать, например, чтобы переместить наш объект:

Теперь вы должны понять пару важных понятий, прежде чем мы продолжим.



App и Gui
FreeCAD был разработан так, чтобы его можно было использовать без пользовательского интерфейса, как приложение командной строки. Поэтому почти каждый объект в FreeCAD состоит из двух частей:, компонент "геометрии", и , его "визуальная" компонента. При работе в режиме командной строки геометрическая часть имеется, но визуальная часть отключена.

Для иллюстрации концепции давайте посмотрим на наш объект куба. Геометрические свойства куба, такие как его размеры, положение и т.д., хранятся в. А его визуальные свойства, такие как цвет, толщина линий и т.д., хранятся в. Это соответствует вкладкам «Данные» и «Вид» в Редакторе свойств. Доступ к объекту вида осуществляется следующим образом:

Теперь вы также можете изменить свойства на вкладке «Вид»:

Когда вы запускаете FreeCAD, консоль Python уже загрузила два базовых модуля: и (которые также могут быть доступны по их ярлыкам  и ). Они содержат все виды общих функций для работы с документами и их объектами. Для иллюстрации нашей концепции, посмотрите, что и, и содержат атрибут , который является текущим открытым документом. Однако и  это не один и тот же объект. Это два компонента документа FreeCAD, и содержат разные атрибуты и методы. Например, содержит, это текущий открытый трёхмерный вид.

Модули
Истинная сила FreeCAD заключается в его верных модулях. Базовое приложение FreeCAD - это более или менее пустой контейнер. Без своих модулей он может сделать немного больше, чем создавать новые, пустые документы. Каждый модуль добавляет к интерфейсу не только новые верстаки, но и новые команды Python и новые типы объектов. В результате несколько разных и даже полностью несовместимых типов объектов могут сосуществовать в одном документе. Наиболее важные модули в FreeCAD, которые мы рассмотрим в этом руководстве, это: Part, Mesh, Sketcher и Draft.

Модули Sketcher и Draft используют модуль Part для создания и поддержки их геометрии, в то время как модуль Mesh полностью независим и поддерживает собственные объекты. Подробнее об этом ниже.

Вы можете проверить все доступные типы базовых объектов для текущего документа следующим образом:

Различные модули FreeCAD не загружаются в консоль Python автоматически. Это нужно для того, чтобы избежать замедленного запуска. Модули загружаются только тогда, когда они вам нужны. Поэтому для исследования того, что, например, находится внутри модуля Part:

Но мы поговорим подробнее о модуле Part ниже.



Mesh
Сетки (meshes) это весьма простой тип трёхмерных объектов, используемых, например, в Sketchup, Blender и 3D Studio Max. Они состоят из 3 элементов: точек (также называемых вершинами), линий (также называемых ребрами) и граней. Во многих приложениях, включая FreeCAD, грани могут иметь только 3 вершины. Разумеется, ничто не мешает использовать более крупные грани, состоящее из нескольких копланарных треугольников.

Сетки просты, и благодаря простоте их можно иметь миллионами в одном документе. Однако в FreeCAD они имеют меньшее использование, и в основном там, где надо импортировать объекты в форматах сетки из других приложений. Модуль Mesh так же широко использовался в качестве основного тестового модуля в первые месяцы жизни FreeCAD.

Сеточные объекты и объекты FreeCAD - это разные вещи. Вы можете видеть объект FreeCAD как контейнер для объекта Mesh (и, как мы увидим ниже, также для объектов Part). Поэтому чтобы добавить объект сетки в FreeCAD, мы должны сначала создать объект FreeCAD и объект Mesh, а затем добавить объект Mesh в объект FreeCAD:

Это стандартный пример, который использует метод для создания сферы, но вы также можете создавать собственные сетки с нуля, определяя их вершины и грани.

Дальнейшее чтение о скриптах обработки сеток...



Part
Модуль Part это самый мощный модуль во всём FreeCAD. Он позволяет создавать и управлять объектами граничного представления (BRep). Объект BRep (Boundary Representation) определяется поверхностями, которые ограничивают и определяют внутренний объем. В отличие от сеток, объекты BRep могут иметь широкий спектр компонентов, от плоских граней до очень сложных поверхностей NURBS.

Модуль Part основан на мощной библиотеке OpenCasCade, обеспечивающей широкий спектр сложных операций над этими объектами, таких как логические операции, филетирование, лофты и т. д.

Модуль Part работает так же, как и модуль Mesh: вы создаете объект FreeCAD, объект Part, а затем добавляете объект Part к объекту FreeCAD:

Модуль Part, как и модуль Mesh, имеет ярлык, который автоматически создает объект FreeCAD и добавляет к нему форму, поэтому вы можете сократить последние три строки до:

Исследуя содержимое myshape, вы заметите много интересных подкомпонентов, таких как, , , и , и широкий спектр геометрических операций, таких как  (вычитание),  (пересечение) или  (объединение). Страница Топологические сценарии данных объясняет все это в деталях.

Читать далее про обработку объектов Part в скриптах...



Draft
FreeCAD включает в себя много других модулей, таких как Sketcher и Draft, которые также создают объекты Part. Эти модули добавляют дополнительные параметры к созданным объектам или даже реализуют в них совершенно новый способ обработки геометрии Part. Наш приведенный выше пример куба является идеальным примером параметрического объекта. Все, что вам нужно, чтобы определить куб, это указать параметры высоты, ширины и длины. Исходя из этого, объект автоматически рассчитает свою форму Part. FreeCAD позволяет вам создавать такие объекты в Python.

Модуль Draft добавляет двумерные параметрические типы объектов (которые являются объектами Part), такие как линии и круги, а также предоставляет некоторые общие функции, которые работают не только с объектами Draft, но и с любым объектом Part. Чтобы узнать, что доступно, просто сделайте:

Интерфейс
Пользовательский интерфейс FreeCAD сделан с помощью Qt, мощной системs графического интерфейса, отвечающей за рисование и обработку всех элементов управления, меню, панелей инструментов и кнопок вокруг окна трёхмерного просмотра. В Qt есть модуль PySide, через который Python получает доступ к интерфейсам Qt, таким как у FreeCAD. Давайте попробуем поработать с интерфейсом Qt и создать простой диалог:

Обратите внимание, что в появившемся диалоговом окне на панели инструментов есть значок FreeCAD, означающий, что Qt знает, что вызов был отдан из приложения FreeCAD. Можно манипулировать любой частью интерфейса FreeCAD.

Qt - это очень мощная система интерфейса, позволяющая делать очень сложные вещи. Она так же имеет несколько простых в использовании инструментов, таких как Qt Designer, с помощью которых вы можете создавать графические диалоги, а затем добавлять их в интерфейс FreeCAD с помощью нескольких строк кода Python.

Больше о PySide здесь...

Макросы
Теперь, уже хорошо понимая основы, где мы будем хранить наши скрипты Python и как мы собираемся запускать их внутри FreeCAD? Для этого есть простой механизм, называемый Макросы. Макросы - это скрипты Python, которые можно добавлять в панели инструментов и запускать кликом мыши. FreeCAD предоставляет простой текстовый редактор, где вы можете написать или вставить сценарии. Как только скрипт готов, используйте для определения ему кнопки, которую можно добавить на панели инструментов.

External scripts
An alternative method for creating, saving, and running your own Python scripts is to create them outside FreeCAD, using an editor of your choice (for example, Vim). To run your Python script inside FreeCAD, be sure to save it with the extension.

Then use to open your script. It will load into a new tab in the Main view area. You can run your script by clicking the button. Any errors or script output will be shown in the Report view.

When you make and save any modifications to your already-loaded script, a dialog box will appear asking whether you want to reload the modified script into FreeCAD.

Теперь вы готовы к более глубокому написанию сценариев FreeCAD. Так что, вперёд в Центр опытных пользователей!