Scripted objects/ru

Введение
Кроме стандартных типов объектов, таких как аннотации, полигональные сетки и детали, FreeCAD также предлагает удивительную возможность создавать параметрические объекты, 100% написанные на Python, такие объекты называются (Python Features). Они ведут себя точно так же, как любой другой объект FreeCAD, автоматически сохраняются и восстанавливаются при сохранении или загрузке файла.

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

Примечание: Имеется возможность упаковки python кода внутрь FreeCAD файла, используя json сериализацию с помощью App::PropertyPythonObject, но этот код в конечном счете нельзя будет запустить напрямую, поэтому это мало подходит для наших целей.

Python Features следуют тому же правилу что и все остальные FreeCAD features: они разделены на App и GUI части. App часть, Объект Документ (Document Object), определяет геометрию нашего объекта, тогда как его GUI часть, Объект Визуального Представления (View Provider Object) определяет, как объект будет отображаться на экране. Объект View Provider, как и любая другая FreeCAD feature, доступен только при запуске FreeCAD в его собственном графическом интерфейсе. Существует несколько свойств и методов, доступных для создания вашего объекта. Свойства должны принадлежать к любому из предопределенных типов свойств, предлагаемых FreeCAD, и отображаться в окне просмотра свойств, чтобы пользователь мог их редактировать. Таким образом, объекты Feature Python полностью параметричны. Вы можете задать свойства как Данных, так и свойства Вида.



Простой пример
Следующий пример можно найти в файле src/Mod/TemplatePyMod/FeaturePython.py вместе с несколькими другими примерами:



Что необходимо отметить
Если Ваш объект полагается на то, что будет пересчитан во время создания, Вы должны сделать это вручную в функции, поскольку пересчёт не вызывается автоматически. Этот пример не требует этого поскольку метод класса  имеет тот же эффект, что и функция, но пример ниже полагается на то, что будет пересчитан перед тем как будет показан в окне трёхмерного просмотра. В этих примерах это делается вручную с помощью, но в более сложных сценариях Вы должны решить, где пересчитать либо весь документ, или объект FeaturePython.

Этот пример создаёт несколько исключений трасс стека в окне отчётов. Это поскольку метод  класса  вызывается каждый раз как свойство добавляется в. Когда первое было добавлено, параметры Width и Height и потому попытки доступа к ним безуспешны.

Описание и  находится в теме форума obj.Proxy.Type is a dict, not a string.



Доступные методы
Полное описание доступно на странице методы FeaturePython.



Доступные свойства
Свойства - это "строительные блоки" объекта FeaturePython. Через них пользователь может взаимодействовать с объектом и вносить изменения в него. После создания нового FeaturePython объекта в вашем документе ( a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ),вы можете получить список доступных свойств, с помощью:

Вы получите список доступных свойств, которые более подробно описаны на странице пользовательских свойств объекта FeaturePython:


 * App::PropertyAcceleration
 * App::PropertyAngle
 * App::PropertyArea
 * App::PropertyBool
 * App::PropertyBoolList
 * App::PropertyColor
 * App::PropertyColorList
 * App::PropertyDirection
 * App::PropertyDistance
 * App::PropertyEnumeration
 * App::PropertyExpressionEngine
 * App::PropertyFile
 * App::PropertyFileIncluded
 * App::PropertyFloat
 * App::PropertyFloatConstraint
 * App::PropertyFloatList
 * App::PropertyFont
 * App::PropertyForce
 * App::PropertyFrequency
 * App::PropertyInteger
 * App::PropertyIntegerConstraint
 * App::PropertyIntegerList
 * App::PropertyIntegerSet
 * App::PropertyLength
 * App::PropertyLink
 * App::PropertyLinkChild
 * App::PropertyLinkGlobal
 * App::PropertyLinkHidden
 * App::PropertyLinkList
 * App::PropertyLinkListChild
 * App::PropertyLinkListGlobal
 * App::PropertyLinkListHidden
 * App::PropertyLinkSub
 * App::PropertyLinkSubChild
 * App::PropertyLinkSubGlobal
 * App::PropertyLinkSubHidden
 * App::PropertyLinkSubList
 * App::PropertyLinkSubListChild
 * App::PropertyLinkSubListGlobal
 * App::PropertyLinkSubListHidden
 * App::PropertyMap
 * App::PropertyMaterial
 * App::PropertyMaterialList
 * App::PropertyMatrix
 * App::PropertyPath
 * App::PropertyPercent
 * App::PropertyPersistentObject
 * App::PropertyPlacement
 * App::PropertyPlacementLink
 * App::PropertyPlacementList
 * App::PropertyPosition
 * App::PropertyPrecision
 * App::PropertyPressure
 * App::PropertyPythonObject
 * App::PropertyQuantity
 * App::PropertyQuantityConstraint
 * App::PropertySpeed
 * App::PropertyString
 * App::PropertyStringList
 * App::PropertyUUID
 * App::PropertyVacuumPermittivity
 * App::PropertyVector
 * App::PropertyVectorDistance
 * App::PropertyVectorList
 * App::PropertyVolume
 * App::PropertyXLink
 * App::PropertyXLinkList
 * App::PropertyXLinkSub
 * App::PropertyXLinkSubList
 * Mesh::PropertyCurvatureList
 * Mesh::PropertyMeshKernel
 * Mesh::PropertyNormalList
 * Part::PropertyFilletEdges
 * Part::PropertyGeometryList
 * Part::PropertyPartShape
 * Part::PropertyShapeHistory
 * Path::PropertyPath
 * Path::PropertyTool
 * Path::PropertyTooltable
 * Sketcher::PropertyConstraintList
 * Spreadsheet::PropertyColumnWidths
 * Spreadsheet::PropertyRowHeights
 * Spreadsheet::PropertySheet
 * Spreadsheet::PropertySpreadsheetQuantity
 * TechDraw::PropertyCenterLineList
 * TechDraw::PropertyCosmeticEdgeList
 * TechDraw::PropertyCosmeticVertexList
 * TechDraw::PropertyGeomFormatList

При добавлении новых свойств к пользовательским объектам, позаботьтесь об этом:
 * Не используйте символы "<" или ">" в описании свойств (это вызовет поломку xml части .fcstd файла)
 * Свойства хранятся в .fcstd файле в алфавитном порядке. Если у вас есть форма(shape) в ваших свойствах, любое свойство имя которого идет, в алфавитном порядке, после "Shape", будет загружено ПОСЛЕ формы, что может привести к странному поведению.

Полный список атрибутов свойств можно посмотреть в заголовочном файле C++ PropertyStandard. Например, если Вы хотите позволить пользователю вводить ограниченный диапазон значений (например, используя using PropertyIntegerConstraint), в Python Вы назначаете кортеж, содержащий не только значение свойства, но и верхний, нижний предел и шаг изменения, как сделано ниже:



Типы свойств
По умолчанию свойства могут быть обновлены. Имеется возможность сделать свойство только для чтения (read-only), например, в случае если требуется отображать только результат выполнения метода. Также возможно создать скрытое (hidden) свойство. Сам же тип свойства можно задать с помощью:

где переменная mode (short int типа) - может иметь следующие значения: 0 -- значение по умолчанию, допускает как чтение, так и запись 1 -- свойство только для чтения (read-only) 2 -- скрытое свойство (hidden)

The EditorModes are not set at FreeCAD file reload. This could to be done by the __setstate__ function. See http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072. By using the setEditorMode the properties are only read only in PropertyEditor. They could still be changed from python. To really make them read only the setting has to be passed directly inside the addProperty function. See http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 for an example.

Using the direct setting in the addProperty function, you also have more possibilities. In particular, an interesting one is mark a property as an output property. This way FreeCAD won't mark the feature as touched when changing it (so no need to recompute).

Example of output property (see also https://forum.freecadweb.org/viewtopic.php?t=24928):

The property types that can be set at last parameter of the addProperty function are: 0 -- Prop_None, No special property type 1 -- Prop_ReadOnly, Property is read-only in the editor 2 -- Prop_Transient, Property won't be saved to file 4 -- Prop_Hidden, Property won't appear in the editor 8 -- Prop_Output, Modified property doesn't touch its parent container 16 -- Prop_NoRecompute, Modified property doesn't touch its container for recompute 32 -- Prop_NoPersist, Property won't be saved to file at all

Вы можете найти эти различные типы свойств, определённые в заголовочном файле PropertyContainer исходного кода C++.



Другой более сложный пример
Данный пример использует верстак Part для создания октаэдра, затем создает собственное Coin представление с помощью Pivy.

Сначала сам Документированный Объект:

Теперь, мы обладаем визуальным представлением объекта, ответственного за отображение объекта в 3D сцене:

Наконец, когда определен наш объект и его визуальный объект, нам просто нужно вызвать их:



Создание выделяемых объектов
Если вы хотите чтобы ваш объект можно было выбрать, или по крайней мере его часть, щелкнув по нему в окне, вы должны включить его Coin геометрию внутрь узла SoFCSelection. Если ваш объект обладает сложным представлением, с виджетами, аннотациями, и т.д, вам может потребоваться только часть его в SoFCSelection. Всё, что находится в SoFCSelection постоянно сканируется FreeCAD для обнаружения выделения/предварительного отбора, так что имеет смысл попробовать не перегружать его ненужным сканированием.

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

Вот вышеприведённый пример с молекулой, адаптированный для выбора элементов молекулы:



Работа с простыми формами
Если ваш параметрический объект - это просто геометрическая форма, то вам не нужно использовать view provider объект. Форма будет отображаться стандартными способами представления форм FreeCAD:

Тот же код с применением ViewProviderLine



Структура графа сцены
You may have noticed that the examples above construct their scenegraphs in slightly different ways. Some use while others use.

Each feature in a FreeCAD document is based the following scenegraph structure:

The displays only one of its children, depending on which display mode is selection in FreeCAD.

The examples which use are constructing their scenegraphs solely out of coin3d scenegraph elements. Under the covers, adds a new child to the ; the name of that node will match the display mode it was passed.

The examples which use also construct part of their geometry using functions from the Part workbench, such as. This constructs the different display mode scenegraphs under the ; when we later come to add coin3d elements to the scenegraph, we need to add them to the existing display mode scenegraphs using rather than creating a new child of the.

When using to add geometry to the scenegraph, each display mode should have its own node which is passed to ; don't reuse the same node for this. Doing so will confuse the selection mechanism. It's okay if each display mode's node has the same geometry nodes added below it, just the root of each display mode needs to be distinct.

Here is the above molecule example, adapted to be drawn only with Coin3D scenegraph objects instead of using objects from the Part workbench:



Программируемый объект Part Design
When making scripted objects in Part Design the process is similar to the scripted objects discussed above, but with a few additional considerations. We must handle 2 shape properties, one for the shape we see in the 3D view and another for the shape used by the pattern tools, such as polar pattern features. The object shapes also needs to be fused to any existing material already in the Body (or cut from it in the case of Subtractive features). And we must account for the placement and attachment of our objects a little bit differently.

Part Design scripted solid object features should be based on either PartDesign::FeaturePython, PartDesign::FeatureAdditivePython, or PartDesign::FeatureSubtractivePython rather than Part::FeaturePython. Only the Additive and Subtractive variants can be used in pattern features, and if based on Part::FeaturePython when the user drops the object into a Part Design Body it becomes a BaseFeature rather than being treated by the Body as a native Part Design object. Note: all of these are expected to be solids, so if you are making a non-solid feature it should be based on Part::FeaturePython or else the next feature in the tree will attempt to fuse to as a solid and it will fail.

Here is a simple example of making a Tube primitive, similar to the Tube primitive in Part Workbench except this one will be a Part Design solid feature object. For this we will 2 separate files: pdtube.FCMacro and pdtube.py. The .FCMacro file will be executed by the user to create the object. The .py file will hold the class definitions, imported by the .FCMacro. The reason for doing it this way is to maintain the parametric nature of the object after restarting FreeCAD and opening a document containing one of our Tubes.

First, the class definition file:

And now the macro file to create the object:



Дополнительная информация
Дополнительные страницы Вики FreeCADа:
 * Scripted objects saving attributes
 * Scripted objects migration
 * Scripted objects with attachment
 * Viewproviders

Интересные темы форума про создание объектов с помощью скриптов:


 * Python object attributes lost at load
 * New FeaturePython is grey
 * Explanation on __getstate__ and __setstate__, official documentation
 * Eigenmode frequency always 0?
 * how to implement python feature's setEdit properly?

В дополнение к представленным примерам, посмотрите FreeCAD src/Mod/TemplatePyMod/FeaturePython.py, находящийся в папке с исходными кодами FreeCAD.