Scripted objects/zh-cn

Besides the standard object types such as annotations, meshes and parts objects, FreeCAD also offers the amazing possibility to build 100% python-scripted objects, called Python Features. Those objects will behave exactly as any other FreeCAD object, and are saved and restored automatically on file save/load.

One particularity must be understood, those objects are saved in FreeCAD FcStd files with python's json module. That module turns a python object as a string, allowing it to be added to the saved file. On load, the json module uses that string to recreate the original object, provided it has access to the source code that created the object. This means that if you save such a custom object and open it on a machine where the python code that generated the object is not present, the object won't be recreated. If you distribute such objects to others, you will need to distribute the python script that created it together.

Python Features follow the same rule as all FreeCAD features: they are separated into App and GUI parts. The app part, the Document Object, defines the geometry of our object, while its GUI part, the View Provider Object, defines how the object will be drawn on screen. The View Provider Object, as any other FreeCAD feature, is only available when you run FreeCAD in its own GUI. There are several properties and methods available to build your object. Properties must be of any of the predefined properties types that FreeCAD offers, and will appear in the property view window, so they can be edited by the user. This way, FeaturePython objects are truly and totally parametric. you can define properties for the Object and its ViewObject separately.

Hint: In former versions we used Python's cPickle module. However, this module executes arbitrary code and thus causes a security problem. Thus, we moved to Python's json module.

初级例子
如下例子的源码在src/Mod/TemplatePyMod/FeaturePython.py 文件中. 该目录下里面还有一些其他例子:

可用属性
属性是真正构成FeaturePython物体的基石. 通过属性，用户可以控制和修改物体. 你在文档中创建一个新的FeaturePython物体后 ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), 要得到可用属性的列表，你可执行:

你可以列出所有属性:

在给定制物体添加属性时需注意如下事项:
 * 不要在属性的描述里使用字符 "<" or ">" (这将破坏 .fcstd 文件中xml部分. )
 * 属性在 .fcstd 文件中是按字母顺序保存的. 假如在你的属性中有一个shape属性, 那些名字排在"Shape"之后的属性将在shape之后加载. 这会导致一下意外的行为.

属性的类别
缺省状态下属性可以被更新. 让属性只读是可以的, 比如在希望显示执行一个方法后结果的情况下. 隐藏属性也是可以的. 可用如下方法设置属性的类别

其中mode是一个短整型变量，按如下设置: 0 -- 缺省设置, 可读写 1 -- 只读 2 -- 隐藏

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.

其它更复杂的例子
这个例子利用 零件模块 来创建一个八面体, 然后用pivy创建它的coin表达.

首先是Document文档物体本身:

然后是负责物体在3D场景中显示的物体:

Finally, once our object and its viewobject are defined, we just need to call them (The Octahedron class and viewprovider class code could be copied in the FreeCAD python console directly):

Making objects selectable
If you want to make your object selectable, or at least part of it, by clicking on it in the viewport, you must include its coin geometry inside a SoFCSelection node. If your object has complex representation, with widgets, annotations, etc, you might want to include only a part of it in a SoFCSelection. Everything that is a SoFCSelection is constantly scanned by FreeCAD to detect selection/preselection, so it makes sense try not to overload it with unneeded scanning. This is what you would do to include a self.face from the example above:

Simply, you create a SoFCSelection node, then you add your geometry nodes to it, then you add it to your main node, instead of adding your geometry nodes directly.

Working with simple shapes
If your parametric object simply outputs a shape, you don't need to use a view provider object. The shape will be displayed using FreeCAD's standard shape representation:

Same code with use ViewProviderLine

Further information
There are a few very interesting forum threads about scripted objects:

- http://forum.freecadweb.org/viewtopic.php?f=22&t=13740

- http://forum.freecadweb.org/viewtopic.php?t=12139

- https://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709

- https://forum.freecadweb.org/viewtopic.php?f=22&t=21330

In addition to the examples presented here have a look at FreeCAD source code src/Mod/TemplatePyMod/FeaturePython.py for more examples.