Scripted objects: Difference between revisions
(Add scenegraph SwitchNode explanation.) |
No edit summary |
||
(80 intermediate revisions by 13 users not shown) | |||
Line 1: | Line 1: | ||
<languages/> |
<languages/> |
||
<translate> |
<translate> |
||
<!--T:28--> |
<!--T:28--> |
||
{{Docnav |
{{Docnav |
||
|[[Topological_data_scripting|Topological data scripting]] |
|||
|[[PySide|PySide]] |
|||
|[[Scenegraph|Scenegraph]] |
|||
|[[Embedding FreeCAD|Embedding FreeCAD]] |
|||
}} |
}} |
||
</translate> |
|||
{{TOCright}} |
|||
<translate> |
|||
==Introduction== <!--T:75--> |
|||
<!--T:1--> |
<!--T:1--> |
||
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. |
Besides the standard object types such as annotations, meshes and parts objects, FreeCAD also offers the amazing possibility to build 100% python-scripted parametric objects, called [[App_FeaturePython|Python Features]]. Those objects will behave exactly as any other FreeCAD object, and are saved and restored automatically on file save/load. |
||
<!--T:2--> |
<!--T:2--> |
||
One particularity must be understood |
One particularity must be understood: For security reasons, FreeCAD files never carry any embedded code. The Python code that you write to create parametric objects is never saved inside a file. This means that if you open a file containing such an object on another machine, if that python code is not available on that machine, the object won't be fully recreated. If you distribute such objects to others, you will need to distribute your Python script too, for example as a [[Macros|Macro]]. |
||
<!--T:77--> |
|||
'''Note''': It is possible to pack python code inside a FreeCAD file using json serializing with an App::PropertyPythonObject, but that code can never directly be run, and therefore has little use for our purpose here. |
|||
<!--T:3--> |
<!--T:3--> |
||
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. |
[[App_FeaturePython|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. |
||
<!--T: |
== Basic example == <!--T:78--> |
||
'''Hint:''' In former versions we used Python's [http://docs.python.org/release/2.5/lib/module-cPickle.html cPickle] module. However, this module executes arbitrary code and thus causes a security problem. Thus, we moved to Python's json module. |
|||
<!--T:5--> |
|||
The following sample can be found in the [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/TemplatePyMod/FeaturePython.py src/Mod/TemplatePyMod/FeaturePython.py] file, together with several other examples: |
The following sample can be found in the [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/TemplatePyMod/FeaturePython.py src/Mod/TemplatePyMod/FeaturePython.py] file, together with several other examples: |
||
</translate> |
</translate> |
||
{{Code|code= |
{{Code|code= |
||
Line 31: | Line 41: | ||
def __init__(self, obj): |
def __init__(self, obj): |
||
'''Add some custom properties to our box feature''' |
'''Add some custom properties to our box feature''' |
||
obj.addProperty("App::PropertyLength","Length","Box","Length of the box").Length=1.0 |
obj.addProperty("App::PropertyLength", "Length", "Box", "Length of the box").Length = 1.0 |
||
obj.addProperty("App::PropertyLength","Width","Box","Width of the box").Width=1.0 |
obj.addProperty("App::PropertyLength", "Width", "Box", "Width of the box").Width = 1.0 |
||
obj.addProperty("App::PropertyLength","Height","Box", "Height of the box").Height=1.0 |
obj.addProperty("App::PropertyLength", "Height", "Box", "Height of the box").Height = 1.0 |
||
obj.Proxy = self |
obj.Proxy = self |
||
def onChanged(self, fp, prop): |
def onChanged(self, fp, prop): |
||
'''Do something when a property has changed''' |
'''Do something when a property has changed''' |
||
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n") |
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n") |
||
def execute(self, fp): |
def execute(self, fp): |
||
'''Do something when doing a recomputation, this method is mandatory''' |
'''Do something when doing a recomputation, this method is mandatory''' |
||
Line 47: | Line 57: | ||
def __init__(self, obj): |
def __init__(self, obj): |
||
'''Set this object to the proxy object of the actual view provider''' |
'''Set this object to the proxy object of the actual view provider''' |
||
obj.addProperty("App::PropertyColor","Color","Box","Color of the box").Color=(1.0,0.0,0.0) |
obj.addProperty("App::PropertyColor","Color", "Box", "Color of the box").Color = (1.0, 0.0, 0.0) |
||
obj.Proxy = self |
obj.Proxy = self |
||
def attach(self, obj): |
def attach(self, obj): |
||
'''Setup the scene sub-graph of the view provider, this method is mandatory''' |
'''Setup the scene sub-graph of the view provider, this method is mandatory''' |
||
Line 56: | Line 66: | ||
self.scale = coin.SoScale() |
self.scale = coin.SoScale() |
||
self.color = coin.SoBaseColor() |
self.color = coin.SoBaseColor() |
||
data=coin.SoCube() |
data=coin.SoCube() |
||
self.shaded.addChild(self.scale) |
self.shaded.addChild(self.scale) |
||
self.shaded.addChild(self.color) |
self.shaded.addChild(self.color) |
||
self.shaded.addChild(data) |
self.shaded.addChild(data) |
||
obj.addDisplayMode(self.shaded,"Shaded"); |
obj.addDisplayMode(self.shaded, "Shaded"); |
||
style=coin.SoDrawStyle() |
style=coin.SoDrawStyle() |
||
style.style = coin.SoDrawStyle.LINES |
style.style = coin.SoDrawStyle.LINES |
||
Line 68: | Line 78: | ||
self.wireframe.addChild(self.color) |
self.wireframe.addChild(self.color) |
||
self.wireframe.addChild(data) |
self.wireframe.addChild(data) |
||
obj.addDisplayMode(self.wireframe,"Wireframe"); |
obj.addDisplayMode(self.wireframe, "Wireframe"); |
||
self.onChanged(obj,"Color") |
self.onChanged(obj,"Color") |
||
def updateData(self, fp, prop): |
def updateData(self, fp, prop): |
||
'''If a property of the handled feature has changed we have the chance to handle this here''' |
'''If a property of the handled feature has changed we have the chance to handle this here''' |
||
Line 77: | Line 87: | ||
w = fp.getPropertyByName("Width") |
w = fp.getPropertyByName("Width") |
||
h = fp.getPropertyByName("Height") |
h = fp.getPropertyByName("Height") |
||
self.scale.scaleFactor.setValue(float(l),float(w),float(h)) |
self.scale.scaleFactor.setValue(float(l), float(w), float(h)) |
||
pass |
pass |
||
def getDisplayModes(self,obj): |
def getDisplayModes(self,obj): |
||
'''Return a list of display modes.''' |
'''Return a list of display modes.''' |
||
Line 86: | Line 96: | ||
modes.append("Wireframe") |
modes.append("Wireframe") |
||
return modes |
return modes |
||
def getDefaultDisplayMode(self): |
def getDefaultDisplayMode(self): |
||
'''Return the name of the default display mode. It must be defined in getDisplayModes.''' |
'''Return the name of the default display mode. It must be defined in getDisplayModes.''' |
||
return "Shaded" |
return "Shaded" |
||
def setDisplayMode(self,mode): |
def setDisplayMode(self,mode): |
||
'''Map the display mode defined in attach with those defined in getDisplayModes.\ |
'''Map the display mode defined in attach with those defined in getDisplayModes.\ |
||
Since they have the same names nothing needs to be done. This method is optional''' |
Since they have the same names nothing needs to be done. This method is optional''' |
||
return mode |
return mode |
||
def onChanged(self, vp, prop): |
def onChanged(self, vp, prop): |
||
'''Here we can do something when a single property got changed''' |
'''Here we can do something when a single property got changed''' |
||
Line 101: | Line 111: | ||
if prop == "Color": |
if prop == "Color": |
||
c = vp.getPropertyByName("Color") |
c = vp.getPropertyByName("Color") |
||
self.color.rgb.setValue(c[0],c[1],c[2]) |
self.color.rgb.setValue(c[0], c[1], c[2]) |
||
def getIcon(self): |
def getIcon(self): |
||
'''Return the icon in XPM format which will appear in the tree view. This method is\ |
'''Return the icon in XPM format which will appear in the tree view. This method is\ |
||
Line 133: | Line 143: | ||
" ####### "}; |
" ####### "}; |
||
""" |
""" |
||
def |
def dumps(self): |
||
'''When saving the document this object gets stored using Python's json module.\ |
'''When saving the document this object gets stored using Python's json module.\ |
||
Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\ |
Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\ |
||
to return a tuple of all serializable objects or None.''' |
to return a tuple of all serializable objects or None.''' |
||
return None |
return None |
||
def |
def loads(self,state): |
||
'''When restoring the serialized object from document we have the chance to set some internals here.\ |
'''When restoring the serialized object from document we have the chance to set some internals here.\ |
||
Since no data were serialized nothing needs to be done here.''' |
Since no data were serialized nothing needs to be done here.''' |
||
return None |
return None |
||
def makeBox(): |
def makeBox(): |
||
FreeCAD.newDocument() |
FreeCAD.newDocument() |
||
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") |
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython", "Box") |
||
Box(a) |
Box(a) |
||
ViewProviderBox(a.ViewObject) |
ViewProviderBox(a.ViewObject) |
||
makeBox() |
makeBox() |
||
}} |
}} |
||
<translate> |
<translate> |
||
=== Things to note === <!--T:37--> |
|||
=== Things to note === <!--T:79--> |
|||
<!--T:37--> |
|||
If your object relies on being recomputed as soon as it is created, you must do this manually in the {{incode|__init__}} function as it is not called automatically. This example does not require it because the {{incode|onChanged}} method of the {{incode|Box}} class has the same effect as the {{incode|execute}} function, but the examples below rely on being recomputed before anything is displayed in the 3D view. In the examples, this is done manually with {{incode|ActiveDocument.recompute()}} but in more complex scenarios you need to decide where to recompute either the whole document or the FeaturePython object. |
If your object relies on being recomputed as soon as it is created, you must do this manually in the {{incode|__init__}} function as it is not called automatically. This example does not require it because the {{incode|onChanged}} method of the {{incode|Box}} class has the same effect as the {{incode|execute}} function, but the examples below rely on being recomputed before anything is displayed in the 3D view. In the examples, this is done manually with {{incode|ActiveDocument.recompute()}} but in more complex scenarios you need to decide where to recompute either the whole document or the FeaturePython object. |
||
Line 163: | Line 174: | ||
<!--T:36--> |
<!--T:36--> |
||
An explanation of {{incode|__getstate__}} and {{incode|__setstate__}} is in the forum thread [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009&start=10#p377892 obj.Proxy.Type is a dict, not a string]. |
An explanation of {{incode|__getstate__}} and {{incode|__setstate__}} which have been replaced by {{incode|dumps}} and {{incode|loads}} is in the forum thread [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009&start=10#p377892 obj.Proxy.Type is a dict, not a string]. |
||
<!--T:93--> |
|||
{{incode|obj.addProperty(...)}} returns {{incode|obj}}, so that the value of the property can be set on the same line: |
|||
Properties are the true building stones of FeaturePython objects. Through them, the user will be able to interact and modify your object. After creating a new FeaturePython object in your document ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), you can get a list of the available properties by issuing: |
|||
<!--T:94--> |
|||
</translate> |
|||
{{Code|code= |
{{Code|code= |
||
obj.addProperty("App::PropertyLength", "Length", "Box", "Length of the box").Length = 1.0 |
|||
obj.supportedProperties() |
|||
}} |
}} |
||
<translate> |
|||
<!--T:7--> |
|||
You will get a list of available properties: |
|||
</translate> |
|||
{{Code|code= |
|||
App::PropertyBool |
|||
App::PropertyBoolList |
|||
App::PropertyFloat |
|||
App::PropertyFloatList |
|||
App::PropertyFloatConstraint |
|||
App::PropertyQuantity |
|||
App::PropertyQuantityConstraint |
|||
App::PropertyAngle |
|||
App::PropertyDistance |
|||
App::PropertyLength |
|||
App::PropertySpeed |
|||
App::PropertyAcceleration |
|||
App::PropertyForce |
|||
App::PropertyPressure |
|||
App::PropertyInteger |
|||
App::PropertyIntegerConstraint |
|||
App::PropertyPercent |
|||
App::PropertyEnumeration |
|||
App::PropertyIntegerList |
|||
App::PropertyIntegerSet |
|||
App::PropertyMap |
|||
App::PropertyString |
|||
App::PropertyUUID |
|||
App::PropertyFont |
|||
App::PropertyStringList |
|||
App::PropertyLink |
|||
App::PropertyLinkSub |
|||
App::PropertyLinkList |
|||
App::PropertyLinkSubList |
|||
App::PropertyMatrix |
|||
App::PropertyVector |
|||
App::PropertyVectorList |
|||
App::PropertyPlacement |
|||
App::PropertyPlacementLink |
|||
App::PropertyPlacementList |
|||
App::PropertyColor |
|||
App::PropertyColorList |
|||
App::PropertyMaterial |
|||
App::PropertyPath |
|||
App::PropertyFile |
|||
App::PropertyFileIncluded |
|||
App::PropertyPythonObject |
|||
Part::PropertyPartShape |
|||
Part::PropertyGeometryList |
|||
Part::PropertyShapeHistory |
|||
Part::PropertyFilletEdges |
|||
Sketcher::PropertyConstraintList |
|||
}} |
|||
<translate> |
|||
<!--T: |
<!--T:95--> |
||
Which is equivalent to: |
|||
When adding properties to your custom objects, take care of this: |
|||
* Do not use characters "<" or ">" in the properties descriptions (that would break the xml pieces in the .fcstd file) |
|||
* Properties are stored alphabetically in a .fcstd file. If you have a shape in your properties, any property whose name comes after "Shape" in alphabetic order, will be loaded AFTER the shape, which can cause strange behaviours. |
|||
<!--T: |
<!--T:96--> |
||
A complete list of property attributes can be seen in the [https://github.com/FreeCAD/FreeCAD/blob/master/src/App/PropertyStandard.h PropertyStandard C++ header file]. |
|||
For instance, if you want to allow the user to enter only a limited range of values (e.g. using PropertyIntegerConstraint), in Python you will assign a tuple containing not only the property value, but also the lower and upper limit as well as the stepsize, as below: |
|||
</translate> |
|||
{{Code|code= |
{{Code|code= |
||
obj.addProperty("App::PropertyLength", "Length", "Box", "Length of the box") |
|||
prop = (value, lower, upper, stepsize) |
|||
obj.Length = 1.0 |
|||
}} |
}} |
||
<translate> |
|||
== |
== Other more complex example == <!--T:83--> |
||
By default the properties can be updated. It is possible to make the properties read-only, for instance in the case one wants to show the result of a method. It is also possible to hide the property. |
|||
The property type can be set using |
|||
<!--T:11--> |
|||
</translate> |
|||
This example makes use of the [[Part_Workbench|Part]] module to create an octahedron, then creates its coin representation with pivy. |
|||
{{Code|code= |
|||
obj.setEditorMode("MyPropertyName", mode) |
|||
}} |
|||
<translate> |
|||
<!--T:10--> |
|||
where mode is a short int that can be set to: |
|||
0 -- default mode, read and write |
|||
1 -- read-only |
|||
2 -- hidden |
|||
<!--T:21--> |
|||
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. |
|||
<!--T:31--> |
|||
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). |
|||
<!--T:32--> |
|||
Example of output property (see also https://forum.freecadweb.org/viewtopic.php?t=24928): |
|||
</translate> |
|||
{{Code|code= |
|||
obj.addProperty("App::PropertyString","MyCustomProperty","","",8) |
|||
}} |
|||
<translate> |
|||
<!--T:33--> |
|||
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 |
|||
<!--T:34--> |
|||
You can find these different property types defined in the [https://github.com/FreeCAD/FreeCAD/blob/master/src/App/PropertyContainer.h source code C++ header for PropertyContainer] |
|||
== Other more complex example == <!--T:11--> |
|||
This example makes use of the [[Part Module|Part Module]] to create an octahedron, then creates its coin representation with pivy. |
|||
<!--T:12--> |
<!--T:12--> |
||
Line 315: | Line 224: | ||
v5 = FreeCAD.Vector(fp.Length/2,fp.Width/2,fp.Height/2) |
v5 = FreeCAD.Vector(fp.Length/2,fp.Width/2,fp.Height/2) |
||
v6 = FreeCAD.Vector(fp.Length/2,fp.Width/2,-fp.Height/2) |
v6 = FreeCAD.Vector(fp.Length/2,fp.Width/2,-fp.Height/2) |
||
# Make the wires/faces |
# Make the wires/faces |
||
f1 = self.make_face(v1,v2,v5) |
f1 = self.make_face(v1,v2,v5) |
||
Line 356: | Line 265: | ||
self.data=coin.SoCoordinate3() |
self.data=coin.SoCoordinate3() |
||
self.face=coin. |
self.face=coin.SoIndexedFaceSet() |
||
self.shaded.addChild(self.scale) |
self.shaded.addChild(self.scale) |
||
Line 383: | Line 292: | ||
self.data.point.set1Value(cnt,i.X,i.Y,i.Z) |
self.data.point.set1Value(cnt,i.X,i.Y,i.Z) |
||
cnt=cnt+1 |
cnt=cnt+1 |
||
self.face.coordIndex.set1Value(0,0) |
self.face.coordIndex.set1Value(0,0) |
||
self.face.coordIndex.set1Value(1,1) |
self.face.coordIndex.set1Value(1,1) |
||
Line 474: | Line 383: | ||
""" |
""" |
||
def |
def dumps(self): |
||
return None |
return None |
||
def |
def loads(self,state): |
||
return None |
return None |
||
}} |
}} |
||
Line 494: | Line 403: | ||
<translate> |
<translate> |
||
== Making objects selectable == <!--T: |
== Making objects selectable == <!--T:84--> |
||
<!--T:15--> |
|||
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. |
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. |
||
Line 502: | Line 413: | ||
<!--T:40--> |
<!--T:40--> |
||
Here is the molecule example above, adapted to make the elements of the molecule selectable: |
Here is the molecule example above, adapted to make the elements of the molecule selectable: |
||
</translate> |
</translate> |
||
{{Code|code= |
{{Code|code= |
||
Line 573: | Line 485: | ||
return 'Atom2' |
return 'Atom2' |
||
raise NotImplementedError |
raise NotImplementedError |
||
def updateData(self, fp, prop): |
def updateData(self, fp, prop): |
||
Line 585: | Line 496: | ||
self.trl2.translation=(p.x,p.y,p.z) |
self.trl2.translation=(p.x,p.y,p.z) |
||
def |
def dumps(self): |
||
return None |
return None |
||
def |
def loads(self,state): |
||
return None |
return None |
||
Line 600: | Line 511: | ||
<translate> |
<translate> |
||
== Working with simple shapes == <!--T: |
== Working with simple shapes == <!--T:85--> |
||
<!--T:17--> |
|||
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: |
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: |
||
Line 643: | Line 556: | ||
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(100,0,0) |
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(100,0,0) |
||
obj.Proxy = self |
obj.Proxy = self |
||
def execute(self, fp): |
def execute(self, fp): |
||
'''"Print a short message when doing a recomputation, this method is mandatory" ''' |
'''"Print a short message when doing a recomputation, this method is mandatory" ''' |
||
Line 664: | Line 577: | ||
<translate> |
<translate> |
||
== Scenegraph Structure == |
== Scenegraph Structure == <!--T:86--> |
||
<!--T:43--> |
|||
You may have noticed that the examples above construct their scenegraphs in slightly different ways. Some use {{incode|obj.addDisplayMode(node, "modename")}} while others use {{incode|obj.SwitchNode.getChild(x).addChild(y)}}. |
You may have noticed that the examples above construct their scenegraphs in slightly different ways. Some use {{incode|obj.addDisplayMode(node, "modename")}} while others use {{incode|obj.SwitchNode.getChild(x).addChild(y)}}. |
||
<!--T:44--> |
|||
Each feature in a FreeCAD document is based the following scenegraph structure: |
Each feature in a FreeCAD document is based the following scenegraph structure: |
||
</translate> |
|||
{{Code|code= |
{{Code|code= |
||
RootNode |
RootNode |
||
\- SwitchNode |
|||
\- Shaded |
|||
- Wireframe |
|||
- etc |
|||
}} |
}} |
||
<translate> |
|||
<!--T:46--> |
|||
The {{incode|SwitchNode}} displays only one of its children, depending on which display mode is selection in FreeCAD. |
The {{incode|SwitchNode}} displays only one of its children, depending on which display mode is selection in FreeCAD. |
||
<!--T:47--> |
|||
The examples which use {{incode|addDisplayMode}} are constructing their scenegraphs solely out of coin3d scenegraph elements. Under the covers, {{incode|addDisplayMode}} adds a new child to the {{incode|SwitchNode}}; the name of that node will match the display mode it was passed. |
The examples which use {{incode|addDisplayMode}} are constructing their scenegraphs solely out of coin3d scenegraph elements. Under the covers, {{incode|addDisplayMode}} adds a new child to the {{incode|SwitchNode}}; the name of that node will match the display mode it was passed. |
||
<!--T:48--> |
|||
The examples which use {{incode|SwitchNode.getChild(x).addChild}} also construct part of their geometry using functions from the Part workbench, such as {{incode|fp.Shape = Part.makeLine(fp.p1,fp.p2)}}. This constructs the different display mode scenegraphs under the {{incode|SwitchNode}}; when we later come to add coin3d elements to the scenegraph, we need to add them to the existing display mode scenegraphs using {{incode|addChild}} rather than creating a new child of the {{incode|SwitchNode}}. |
|||
The examples which use {{incode|SwitchNode.getChild(x).addChild}} also construct part of their geometry using functions from the Part workbench, such as {{incode|1=fp.Shape = Part.makeLine(fp.p1,fp.p2)}}. This constructs the different display mode scenegraphs under the {{incode|SwitchNode}}; when we later come to add coin3d elements to the scenegraph, we need to add them to the existing display mode scenegraphs using {{incode|addChild}} rather than creating a new child of the {{incode|SwitchNode}}. |
|||
<!--T:49--> |
|||
When using {{incode|addDisplayMode()}} to add geometry to the scenegraph, each display mode should have its own node which is passed to {{incode|addDisplayMode()}}; 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. |
|||
<!--T:50--> |
|||
Here is the above molecule example, adapted to be drawn only with Coin3D scenegraph objects instead of using objects from the Part workbench: |
|||
</translate> |
|||
{{Code|code= |
|||
import Part |
|||
from pivy import coin |
|||
class Molecule: |
|||
def __init__(self, obj): |
|||
''' Add two point properties ''' |
|||
obj.addProperty("App::PropertyVector","p1","Line","Start point") |
|||
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(5,0,0) |
|||
obj.Proxy = self |
|||
def onChanged(self, fp, prop): |
|||
pass |
|||
def execute(self, fp): |
|||
''' Print a short message when doing a recomputation, this method is mandatory ''' |
|||
pass |
|||
class ViewProviderMolecule: |
|||
def __init__(self, obj): |
|||
''' Set this object to the proxy object of the actual view provider ''' |
|||
self.constructed = False |
|||
obj.Proxy = self |
|||
self.ViewObject = obj |
|||
def attach(self, obj): |
|||
material = coin.SoMaterial() |
|||
material.diffuseColor = (1.0, 0.0, 0.0) |
|||
material.emissiveColor = (1.0, 0.0, 0.0) |
|||
drawStyle = coin.SoDrawStyle() |
|||
drawStyle.pointSize.setValue(10) |
|||
drawStyle.style = coin.SoDrawStyle.LINES |
|||
wireframe = coin.SoGroup() |
|||
shaded = coin.SoGroup() |
|||
self.wireframe = wireframe |
|||
self.shaded = shaded |
|||
self.coords = coin.SoCoordinate3() |
|||
self.coords.point.setValues(0, 2, [FreeCAD.Vector(0, 0, 0), FreeCAD.Vector(1, 0, 0)]) |
|||
wireframe += self.coords |
|||
wireframe += drawStyle |
|||
wireframe += material |
|||
shaded += self.coords |
|||
shaded += drawStyle |
|||
shaded += material |
|||
g = coin.SoGroup() |
|||
sel1 = coin.SoType.fromName('SoFCSelection').createInstance() |
|||
sel1.style = 'EMISSIVE_DIFFUSE' |
|||
p1 = coin.SoType.fromName('SoIndexedPointSet').createInstance() |
|||
p1.coordIndex.set1Value(0, 0) |
|||
sel1 += p1 |
|||
g += sel1 |
|||
wireframe += g |
|||
shaded += g |
|||
g = coin.SoGroup() |
|||
sel2 = coin.SoType.fromName('SoFCSelection').createInstance() |
|||
sel2.style = 'EMISSIVE_DIFFUSE' |
|||
p2 = coin.SoType.fromName('SoIndexedPointSet').createInstance() |
|||
p2.coordIndex.set1Value(0, 1) |
|||
sel2 += p2 |
|||
g += sel2 |
|||
wireframe += g |
|||
shaded += g |
|||
g = coin.SoGroup() |
|||
sel3 = coin.SoType.fromName('SoFCSelection').createInstance() |
|||
sel3.style = 'EMISSIVE_DIFFUSE' |
|||
p3 = coin.SoType.fromName('SoIndexedLineSet').createInstance() |
|||
p3.coordIndex.setValues(0, 2, [0, 1]) |
|||
sel3 += p3 |
|||
g += sel3 |
|||
wireframe += g |
|||
shaded += g |
|||
obj.addDisplayMode(wireframe, 'Wireframe') |
|||
obj.addDisplayMode(shaded, 'Shaded') |
|||
self.sel1 = sel1 |
|||
self.sel2 = sel2 |
|||
self.sel3 = sel3 |
|||
self.constructed = True |
|||
self.updateData(obj.Object, 'p2') |
|||
def getDetailPath(self, subname, path, append): |
|||
vobj = self.ViewObject |
|||
if append: |
|||
path.append(vobj.RootNode) |
|||
path.append(vobj.SwitchNode) |
|||
mode = vobj.SwitchNode.whichChild.getValue() |
|||
FreeCAD.Console.PrintWarning("getDetailPath: mode {} is active\n".format(mode)) |
|||
if mode >= 0: |
|||
mode = vobj.SwitchNode.getChild(mode) |
|||
path.append(mode) |
|||
sub = Part.splitSubname(subname)[-1] |
|||
print(sub) |
|||
if sub == 'Atom1': |
|||
path.append(self.sel1) |
|||
elif sub == 'Atom2': |
|||
path.append(self.sel2) |
|||
elif sub == 'Line': |
|||
path.append(self.sel3) |
|||
else: |
|||
path.append(mode.getChild(0)) |
|||
return True |
|||
def getElementPicked(self, pp): |
|||
path = pp.getPath() |
|||
if path.findNode(self.sel1) >= 0: |
|||
return 'Atom1' |
|||
if path.findNode(self.sel2) >= 0: |
|||
return 'Atom2' |
|||
if path.findNode(self.sel3) >= 0: |
|||
return 'Line' |
|||
raise NotImplementedError |
|||
def updateData(self, fp, prop): |
|||
"If a property of the handled feature has changed we have the chance to handle this here" |
|||
# fp is the handled feature, prop is the name of the property that has changed |
|||
if not self.constructed: |
|||
return |
|||
if prop == "p1": |
|||
p = fp.getPropertyByName("p1") |
|||
self.coords.point.set1Value(0, p) |
|||
elif prop == "p2": |
|||
p = fp.getPropertyByName("p2") |
|||
self.coords.point.set1Value(1, p) |
|||
def getDisplayModes(self, obj): |
|||
return ['Wireframe', 'Shaded'] |
|||
def getDefaultDisplayMode(self): |
|||
return 'Shaded' |
|||
def setDisplayMode(self, mode): |
|||
return mode |
|||
def dumps(self): |
|||
return None |
|||
def loads(self,state): |
|||
return None |
|||
def makeMolecule(): |
|||
FreeCAD.newDocument() |
|||
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Molecule") |
|||
Molecule(a) |
|||
b=ViewProviderMolecule(a.ViewObject) |
|||
a.touch() |
|||
FreeCAD.ActiveDocument.recompute() |
|||
return a,b |
|||
a,b = makeMolecule() |
|||
}} |
|||
<translate> |
|||
== Part Design scripted objects == <!--T:87--> |
|||
<!--T:88--> |
|||
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. |
|||
<!--T:89--> |
|||
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. |
|||
<!--T:90--> |
|||
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. |
|||
<!--T:91--> |
|||
First, the class definition file: |
|||
</translate> |
|||
{{Code|code= |
|||
# -*- coding: utf-8 -*- |
|||
#classes should go in pdtube.py |
|||
import FreeCAD, FreeCADGui, Part |
|||
class PDTube: |
|||
def __init__(self,obj): |
|||
obj.addProperty("App::PropertyLength","Radius1","Tube","Radius1").Radius1 = 5 |
|||
obj.addProperty("App::PropertyLength","Radius2","Tube","Radius2").Radius2 = 10 |
|||
obj.addProperty("App::PropertyLength","Height","Tube","Height of tube").Height = 10 |
|||
self.makeAttachable(obj) |
|||
obj.Proxy = self |
|||
def makeAttachable(self, obj): |
|||
if int(FreeCAD.Version()[1]) >= 19: |
|||
obj.addExtension('Part::AttachExtensionPython') |
|||
else: |
|||
obj.addExtension('Part::AttachExtensionPython', obj) |
|||
obj.setEditorMode('Placement', 0) #non-readonly non-hidden |
|||
def execute(self,fp): |
|||
outer_cylinder = Part.makeCylinder(fp.Radius2, fp.Height) |
|||
inner_cylinder = Part.makeCylinder(fp.Radius1, fp.Height) |
|||
if fp.Radius1 == fp.Radius2: #just make cylinder |
|||
tube_shape = outer_cylinder |
|||
elif fp.Radius1 < fp.Radius2: |
|||
tube_shape = outer_cylinder.cut(inner_cylinder) |
|||
else: #invert rather than error out |
|||
tube_shape = inner_cylinder.cut(outer_cylinder) |
|||
if not hasattr(fp, "positionBySupport"): |
|||
self.makeAttachable(fp) |
|||
fp.positionBySupport() |
|||
tube_shape.Placement = fp.Placement |
|||
#BaseFeature (shape property of type Part::PropertyPartShape) is provided for us |
|||
#with the PartDesign::FeaturePython and related classes, but it might be empty |
|||
#if our object is the first object in the tree. it's a good idea to check |
|||
#for its existence in case we want to make type Part::FeaturePython, which won't have it |
|||
if hasattr(fp, "BaseFeature") and fp.BaseFeature != None: |
|||
if "Subtractive" in fp.TypeId: |
|||
full_shape = fp.BaseFeature.Shape.cut(tube_shape) |
|||
else: |
|||
full_shape = fp.BaseFeature.Shape.fuse(tube_shape) |
|||
full_shape.transformShape(fp.Placement.inverse().toMatrix(), True) #borrowed from gears workbench |
|||
fp.Shape = full_shape |
|||
else: |
|||
fp.Shape = tube_shape |
|||
if hasattr(fp,"AddSubShape"): #PartDesign::FeatureAdditivePython and |
|||
#PartDesign::FeatureSubtractivePython have this |
|||
#property but PartDesign::FeaturePython does not |
|||
#It is the shape used for copying in pattern features |
|||
#for example in making a polar pattern |
|||
tube_shape.transformShape(fp.Placement.inverse().toMatrix(), True) |
|||
fp.AddSubShape = tube_shape |
|||
class PDTubeVP: |
|||
def __init__(self, obj): |
|||
'''Set this object to the proxy object of the actual view provider''' |
|||
obj.Proxy = self |
|||
def attach(self,vobj): |
|||
self.vobj = vobj |
|||
def updateData(self, fp, prop): |
|||
'''If a property of the handled feature has changed we have the chance to handle this here''' |
|||
pass |
|||
def getDisplayModes(self,obj): |
|||
'''Return a list of display modes.''' |
|||
modes=[] |
|||
modes.append("Flat Lines") |
|||
modes.append("Shaded") |
|||
modes.append("Wireframe") |
|||
return modes |
|||
def getDefaultDisplayMode(self): |
|||
'''Return the name of the default display mode. It must be defined in getDisplayModes.''' |
|||
return "Flat Lines" |
|||
def setDisplayMode(self,mode): |
|||
'''Map the display mode defined in attach with those defined in getDisplayModes.\ |
|||
Since they have the same names nothing needs to be done. This method is optional''' |
|||
return mode |
|||
def onChanged(self, vp, prop): |
|||
'''Here we can do something when a single property got changed''' |
|||
#FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n") |
|||
pass |
|||
def getIcon(self): |
|||
'''Return the icon in XPM format which will appear in the tree view. This method is\ |
|||
optional and if not defined a default icon is shown.''' |
|||
return """ |
|||
/* XPM */ |
|||
static const char * ViewProviderBox_xpm[] = { |
|||
"16 16 6 1", |
|||
" c None", |
|||
". c #141010", |
|||
"+ c #615BD2", |
|||
"@ c #C39D55", |
|||
"# c #000000", |
|||
"$ c #57C355", |
|||
" ........", |
|||
" ......++..+..", |
|||
" .@@@@.++..++.", |
|||
" .@@@@.++..++.", |
|||
" .@@ .++++++.", |
|||
" ..@@ .++..++.", |
|||
"###@@@@ .++..++.", |
|||
"##$.@@$#.++++++.", |
|||
"#$#$.$$$........", |
|||
"#$$####### ", |
|||
"#$$#$$$$$# ", |
|||
"#$$#$$$$$# ", |
|||
"#$$#$$$$$# ", |
|||
" #$#$$$$$# ", |
|||
" ##$$$$$# ", |
|||
" ####### "}; |
|||
""" |
|||
def dumps(self): |
|||
'''When saving the document this object gets stored using Python's json module.\ |
|||
Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\ |
|||
to return a tuple of all serializable objects or None.''' |
|||
return None |
|||
def loads(self,state): |
|||
'''When restoring the serialized object from document we have the chance to set some internals here.\ |
|||
Since no data were serialized nothing needs to be done here.''' |
|||
return None |
|||
}} |
|||
<translate> |
|||
<!--T:92--> |
|||
And now the macro file to create the object: |
|||
</translate> |
|||
{{Code|code= |
|||
# -*- coding: utf-8 -*- |
|||
#pdtube.FCMacro |
|||
import pdtube |
|||
#above line needed if the class definitions above are place in another file: PDTube.py |
|||
#this is needed if the tube object is to remain parametric after restarting FreeCAD and loading |
|||
#a document containing the object |
|||
body = FreeCADGui.ActiveDocument.ActiveView.getActiveObject("pdbody") |
|||
if not body: |
|||
FreeCAD.Console.PrintError("No active body.\n") |
|||
else: |
|||
from PySide import QtGui |
|||
window = FreeCADGui.getMainWindow() |
|||
items = ["Additive","Subtractive","Neither additive nor subtractive"] |
|||
item,ok =QtGui.QInputDialog.getItem(window,"Select tube type","Select whether you want additive, subtractive, or neither:",items,0,False) |
|||
if ok: |
|||
if item == items[0]: |
|||
className = "PartDesign::FeatureAdditivePython" |
|||
elif item == items[1]: |
|||
className = "PartDesign::FeatureSubtractivePython" |
|||
else: |
|||
className = "PartDesign::FeaturePython" #not usable in pattern features, such as polar pattern |
|||
tube = FreeCAD.ActiveDocument.addObject(className,"Tube") |
|||
pdtube.PDTube(tube) |
|||
pdtube.PDTubeVP(tube.ViewObject) |
|||
body.addObject(tube) #optionally we can also use body.insertObject() for placing at particular place in tree |
|||
}} |
|||
<translate> |
|||
== Available object types == <!--T:97--> |
|||
<!--T:98--> |
|||
The list of all object types you can create with {{incode|FreeCAD.ActiveDocument.addObject()}} can be obtained with {{incode|FreeCAD.ActiveDocument.supportedTypes()}}. Only object types with a name ending in {{incode|Python}} can be used for scripted objects. These are listed here (for FreeCAD v0.21): |
|||
</translate> |
|||
* {{incode|App::DocumentObjectGroupPython}} |
|||
* {{incode|App::FeaturePython}} |
|||
* {{incode|App::GeometryPython}} |
|||
* {{incode|App::LinkElementPython}} |
|||
* {{incode|App::LinkGroupPython}} |
|||
* {{incode|App::LinkPython}} |
|||
* {{incode|App::MaterialObjectPython}} |
|||
* {{incode|App::PlacementPython}} |
|||
* {{incode|Part::CustomFeaturePython}} |
|||
* {{incode|Part::FeaturePython}} |
|||
* {{incode|Part::Part2DObjectPython}} |
|||
* {{incode|Path::FeatureAreaPython}} |
|||
* {{incode|Path::FeatureAreaViewPython}} |
|||
* {{incode|Path::FeatureCompoundPython}} |
|||
* {{incode|Path::FeaturePython}} |
|||
* {{incode|Path::FeatureShapePython}} |
|||
* {{incode|Sketcher::SketchObjectPython}} |
|||
* {{incode|TechDraw::DrawComplexSectionPython}} |
|||
* {{incode|TechDraw::DrawLeaderLinePython}} |
|||
* {{incode|TechDraw::DrawPagePython}} |
|||
* {{incode|TechDraw::DrawRichAnnoPython}} |
|||
* {{incode|TechDraw::DrawTemplatePython}} |
|||
* {{incode|TechDraw::DrawTilePython}} |
|||
* {{incode|TechDraw::DrawTileWeldPython}} |
|||
* {{incode|TechDraw::DrawViewPartPython}} |
|||
* {{incode|TechDraw::DrawViewPython}} |
|||
* {{incode|TechDraw::DrawViewSectionPython}} |
|||
* {{incode|TechDraw::DrawViewSymbolPython}} |
|||
* {{incode|TechDraw::DrawWeldSymbolPython}} |
|||
<translate> |
|||
== Available methods == <!--T:80--> |
|||
<!--T:76--> |
|||
See [[FeaturePython_methods|FeaturePython methods]] for the complete reference. |
|||
== Available properties == <!--T:81--> |
|||
<!--T:6--> |
|||
Properties are the true building blocks of FeaturePython objects. Through them, you will be able to interact and modify your object. After creating a new FeaturePython object in your document, you can get a list of the available properties: |
|||
</translate> |
|||
{{Code|code= |
|||
obj = FreeCAD.ActiveDocument.addObject("App::FeaturePython", "Box") |
|||
obj.supportedProperties() |
|||
}} |
|||
<translate> |
|||
<!--T:7--> |
|||
See [[FeaturePython_Custom_Properties|FeaturePython Custom Properties]] for an overview. |
|||
<!--T:8--> |
|||
When adding properties to your custom objects, take care of this: |
|||
* Do not use characters {{Incode|<}} or {{Incode|>}} in the properties descriptions (that would break the xml pieces in the .FCStd file). |
|||
* Properties are stored alphabetically in a .FCStd file. If you have a shape in your properties, any property whose name comes after "Shape" in alphabetic order, will be loaded AFTER the shape, which can cause strange behaviors. |
|||
<!--T:99--> |
|||
The properties are defined in the [https://github.com/FreeCAD/FreeCAD/blob/master/src/App/PropertyStandard.h PropertyStandard C++ header file]. |
|||
=== Property types === <!--T:82--> |
|||
<!--T:9--> |
|||
By default properties can be updated, but it is possible to make properties read-only, for instance if one wants to show the result of a method. It is also possible to hide a property. The property type can be set using: |
|||
</translate> |
|||
{{Code|code= |
|||
obj.setEditorMode("MyPropertyName", mode) |
|||
}} |
|||
<translate> |
|||
<!--T:10--> |
|||
where mode is a short int that can be set to: |
|||
0 -- default mode, read and write |
|||
1 -- read-only |
|||
2 -- hidden |
|||
<!--T:100--> |
|||
The mode can also be set using a list of strings, e.g. {{incode|obj.setEditorMode("Placement", ["ReadOnly", "Hidden"])}}. |
|||
<!--T:21--> |
|||
The EditorModes are not set at FreeCAD file reload. This could to be done by the {{Incode|loads}} function. See http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072. By using the {{Incode|setEditorMode}} the properties are only read-only in the [[Property_editor|Property editor]]. They can still be changed from Python. To really make them read-only the setting has to be passed directly inside the {{Incode|addProperty}} function. See http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 for an example. |
|||
<!--T:31--> |
|||
Using the direct setting in the {{Incode|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). |
|||
<!--T:32--> |
|||
Example of output property (see also https://forum.freecadweb.org/viewtopic.php?t=24928): |
|||
</translate> |
|||
{{Code|code= |
|||
obj.addProperty("App::PropertyString", "MyCustomProperty", "", "", 8) |
|||
}} |
|||
<translate> |
|||
<!--T:33--> |
|||
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 |
|||
<!--T:34--> |
|||
The property types are defined in the [https://github.com/FreeCAD/FreeCAD/blob/master/src/App/PropertyContainer.h PropertyContainer C++ header file]. |
|||
== Available extensions == <!--T:101--> |
|||
<!--T:102--> |
|||
The list of available extensions can be obtained with {{incode|grep -RI EXTENSION_PROPERTY_SOURCE_TEMPLATE}} in the repository of the source code and is given here (for FreeCAD v0.21). |
|||
<!--T:103--> |
|||
For objects: |
|||
</translate> |
|||
* {{incode|App::GeoFeatureGroupExtensionPython}} |
|||
* {{incode|App::GroupExtensionPython}} |
|||
* {{incode|App::LinkBaseExtensionPython}} |
|||
* {{incode|App::LinkExtensionPython}} |
|||
* {{incode|App::OriginGroupExtensionPython}} |
|||
* {{incode|Part::AttachExtensionPython}} |
|||
* {{incode|TechDraw::CosmeticExtensionPython}} |
|||
<translate> |
|||
<!--T:104--> |
|||
For view objects: |
|||
</translate> |
|||
* {{incode|Gui::ViewProviderExtensionPython}} |
|||
* {{incode|Gui::ViewProviderGeoFeatureGroupExtensionPython}} |
|||
* {{incode|Gui::ViewProviderGroupExtensionPython}} |
|||
* {{incode|Gui::ViewProviderOriginGroupExtensionPython}} |
|||
* {{incode|PartGui::ViewProviderAttachExtensionPython}} |
|||
* {{incode|PartGui::ViewProviderSplineExtensionPython}} |
|||
<translate> |
|||
<!--T:105--> |
|||
There exist other extensions but they do not work as-is: |
|||
</translate> |
|||
* {{incode|App::ExtensionPython}} |
|||
* {{incode|TechDrawGui::ViewProviderCosmeticExtensionPython}} |
|||
* {{incode|TechDrawGui::ViewProviderDrawingViewExtensionPython}} |
|||
* {{incode|TechDrawGui::ViewProviderPageExtensionPython}} |
|||
* {{incode|TechDrawGui::ViewProviderTemplateExtensionPython}} |
|||
<translate> |
|||
== Further information == <!--T:18--> |
== Further information == <!--T:18--> |
||
Line 694: | Line 1,118: | ||
<!--T:42--> |
<!--T:42--> |
||
Interesting forum threads about scripted objects: |
Interesting forum threads about scripted objects: |
||
</translate> |
</translate> |
||
* [http://forum.freecadweb.org/viewtopic.php?f=22&t=13740 Python object attributes lost at load] |
* [http://forum.freecadweb.org/viewtopic.php?f=22&t=13740 Python object attributes lost at load] |
||
* [http://forum.freecadweb.org/viewtopic.php?t=12139 New FeaturePython is grey] |
* [http://forum.freecadweb.org/viewtopic.php?t=12139 New FeaturePython is grey] |
||
* [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009 Explanation on |
* [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009 Explanation on dumps and loads], [https://docs.python.org/3/library/pickle.html#object.__getstate__ official documentation] |
||
* [https://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 Eigenmode frequency always 0?] |
* [https://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 Eigenmode frequency always 0?] |
||
* [https://forum.freecadweb.org/viewtopic.php?f=22&t=21330 how to implement python feature's setEdit properly?] |
* [https://forum.freecadweb.org/viewtopic.php?f=22&t=21330 how to implement python feature's setEdit properly?] |
||
Line 704: | Line 1,129: | ||
<!--T:24--> |
<!--T:24--> |
||
In addition to the examples presented here have a look at FreeCAD source code [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/TemplatePyMod/FeaturePython.py src/Mod/TemplatePyMod/FeaturePython.py] for more examples. |
In addition to the examples presented here have a look at FreeCAD source code [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/TemplatePyMod/FeaturePython.py src/Mod/TemplatePyMod/FeaturePython.py] for more examples. |
||
<!--T:25--> |
<!--T:25--> |
||
{{Docnav |
{{Docnav |
||
|[[Topological_data_scripting|Topological data scripting]] |
|||
|[[PySide|PySide]] |
|||
|[[Scenegraph|Scenegraph]] |
|||
|[[Embedding FreeCAD|Embedding FreeCAD]] |
|||
}} |
}} |
||
</translate> |
</translate> |
||
{{Powerdocnavi{{#translation:}}}} |
{{Powerdocnavi{{#translation:}}}} |
||
[[Category:Developer Documentation{{#translation:}}]] |
|||
[[Category:Python Code{{#translation:}}]] |
[[Category:Python Code{{#translation:}}]] |
||
{{clear}} |
Latest revision as of 08:46, 2 February 2024
Introduction
Besides the standard object types such as annotations, meshes and parts objects, FreeCAD also offers the amazing possibility to build 100% python-scripted parametric 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: For security reasons, FreeCAD files never carry any embedded code. The Python code that you write to create parametric objects is never saved inside a file. This means that if you open a file containing such an object on another machine, if that python code is not available on that machine, the object won't be fully recreated. If you distribute such objects to others, you will need to distribute your Python script too, for example as a Macro.
Note: It is possible to pack python code inside a FreeCAD file using json serializing with an App::PropertyPythonObject, but that code can never directly be run, and therefore has little use for our purpose here.
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.
Basic example
The following sample can be found in the src/Mod/TemplatePyMod/FeaturePython.py file, together with several other examples:
'''Examples for a feature class and its view provider.'''
import FreeCAD, FreeCADGui
from pivy import coin
class Box:
def __init__(self, obj):
'''Add some custom properties to our box feature'''
obj.addProperty("App::PropertyLength", "Length", "Box", "Length of the box").Length = 1.0
obj.addProperty("App::PropertyLength", "Width", "Box", "Width of the box").Width = 1.0
obj.addProperty("App::PropertyLength", "Height", "Box", "Height of the box").Height = 1.0
obj.Proxy = self
def onChanged(self, fp, prop):
'''Do something when a property has changed'''
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
def execute(self, fp):
'''Do something when doing a recomputation, this method is mandatory'''
FreeCAD.Console.PrintMessage("Recompute Python Box feature\n")
class ViewProviderBox:
def __init__(self, obj):
'''Set this object to the proxy object of the actual view provider'''
obj.addProperty("App::PropertyColor","Color", "Box", "Color of the box").Color = (1.0, 0.0, 0.0)
obj.Proxy = self
def attach(self, obj):
'''Setup the scene sub-graph of the view provider, this method is mandatory'''
self.shaded = coin.SoGroup()
self.wireframe = coin.SoGroup()
self.scale = coin.SoScale()
self.color = coin.SoBaseColor()
data=coin.SoCube()
self.shaded.addChild(self.scale)
self.shaded.addChild(self.color)
self.shaded.addChild(data)
obj.addDisplayMode(self.shaded, "Shaded");
style=coin.SoDrawStyle()
style.style = coin.SoDrawStyle.LINES
self.wireframe.addChild(style)
self.wireframe.addChild(self.scale)
self.wireframe.addChild(self.color)
self.wireframe.addChild(data)
obj.addDisplayMode(self.wireframe, "Wireframe");
self.onChanged(obj,"Color")
def updateData(self, fp, prop):
'''If a property of the handled feature has changed we have the chance to handle this here'''
# fp is the handled feature, prop is the name of the property that has changed
l = fp.getPropertyByName("Length")
w = fp.getPropertyByName("Width")
h = fp.getPropertyByName("Height")
self.scale.scaleFactor.setValue(float(l), float(w), float(h))
pass
def getDisplayModes(self,obj):
'''Return a list of display modes.'''
modes=[]
modes.append("Shaded")
modes.append("Wireframe")
return modes
def getDefaultDisplayMode(self):
'''Return the name of the default display mode. It must be defined in getDisplayModes.'''
return "Shaded"
def setDisplayMode(self,mode):
'''Map the display mode defined in attach with those defined in getDisplayModes.\
Since they have the same names nothing needs to be done. This method is optional'''
return mode
def onChanged(self, vp, prop):
'''Here we can do something when a single property got changed'''
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
if prop == "Color":
c = vp.getPropertyByName("Color")
self.color.rgb.setValue(c[0], c[1], c[2])
def getIcon(self):
'''Return the icon in XPM format which will appear in the tree view. This method is\
optional and if not defined a default icon is shown.'''
return """
/* XPM */
static const char * ViewProviderBox_xpm[] = {
"16 16 6 1",
" c None",
". c #141010",
"+ c #615BD2",
"@ c #C39D55",
"# c #000000",
"$ c #57C355",
" ........",
" ......++..+..",
" .@@@@.++..++.",
" .@@@@.++..++.",
" .@@ .++++++.",
" ..@@ .++..++.",
"###@@@@ .++..++.",
"##$.@@$#.++++++.",
"#$#$.$$$........",
"#$$####### ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
" #$#$$$$$# ",
" ##$$$$$# ",
" ####### "};
"""
def dumps(self):
'''When saving the document this object gets stored using Python's json module.\
Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\
to return a tuple of all serializable objects or None.'''
return None
def loads(self,state):
'''When restoring the serialized object from document we have the chance to set some internals here.\
Since no data were serialized nothing needs to be done here.'''
return None
def makeBox():
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython", "Box")
Box(a)
ViewProviderBox(a.ViewObject)
makeBox()
Things to note
If your object relies on being recomputed as soon as it is created, you must do this manually in the __init__
function as it is not called automatically. This example does not require it because the onChanged
method of the Box
class has the same effect as the execute
function, but the examples below rely on being recomputed before anything is displayed in the 3D view. In the examples, this is done manually with ActiveDocument.recompute()
but in more complex scenarios you need to decide where to recompute either the whole document or the FeaturePython object.
This example produces a number of exception stack traces in the report view window. This is because the onChanged
method of the Box
class is called each time a property is added in __init__
. When the first one is added, the Width and Height properties don't exist yet and so the attempt to access them fails.
An explanation of __getstate__
and __setstate__
which have been replaced by dumps
and loads
is in the forum thread obj.Proxy.Type is a dict, not a string.
obj.addProperty(...)
returns obj
, so that the value of the property can be set on the same line:
obj.addProperty("App::PropertyLength", "Length", "Box", "Length of the box").Length = 1.0
Which is equivalent to:
obj.addProperty("App::PropertyLength", "Length", "Box", "Length of the box")
obj.Length = 1.0
Other more complex example
This example makes use of the Part module to create an octahedron, then creates its coin representation with pivy.
First is the Document object itself:
import FreeCAD, FreeCADGui, Part
import pivy
from pivy import coin
class Octahedron:
def __init__(self, obj):
"Add some custom properties to our box feature"
obj.addProperty("App::PropertyLength","Length","Octahedron","Length of the octahedron").Length=1.0
obj.addProperty("App::PropertyLength","Width","Octahedron","Width of the octahedron").Width=1.0
obj.addProperty("App::PropertyLength","Height","Octahedron", "Height of the octahedron").Height=1.0
obj.addProperty("Part::PropertyPartShape","Shape","Octahedron", "Shape of the octahedron")
obj.Proxy = self
def execute(self, fp):
# Define six vetices for the shape
v1 = FreeCAD.Vector(0,0,0)
v2 = FreeCAD.Vector(fp.Length,0,0)
v3 = FreeCAD.Vector(0,fp.Width,0)
v4 = FreeCAD.Vector(fp.Length,fp.Width,0)
v5 = FreeCAD.Vector(fp.Length/2,fp.Width/2,fp.Height/2)
v6 = FreeCAD.Vector(fp.Length/2,fp.Width/2,-fp.Height/2)
# Make the wires/faces
f1 = self.make_face(v1,v2,v5)
f2 = self.make_face(v2,v4,v5)
f3 = self.make_face(v4,v3,v5)
f4 = self.make_face(v3,v1,v5)
f5 = self.make_face(v2,v1,v6)
f6 = self.make_face(v4,v2,v6)
f7 = self.make_face(v3,v4,v6)
f8 = self.make_face(v1,v3,v6)
shell=Part.makeShell([f1,f2,f3,f4,f5,f6,f7,f8])
solid=Part.makeSolid(shell)
fp.Shape = solid
# helper mehod to create the faces
def make_face(self,v1,v2,v3):
wire = Part.makePolygon([v1,v2,v3,v1])
face = Part.Face(wire)
return face
Then, we have the view provider object, responsible for showing the object in the 3D scene:
class ViewProviderOctahedron:
def __init__(self, obj):
"Set this object to the proxy object of the actual view provider"
obj.addProperty("App::PropertyColor","Color","Octahedron","Color of the octahedron").Color=(1.0,0.0,0.0)
obj.Proxy = self
def attach(self, obj):
"Setup the scene sub-graph of the view provider, this method is mandatory"
self.shaded = coin.SoGroup()
self.wireframe = coin.SoGroup()
self.scale = coin.SoScale()
self.color = coin.SoBaseColor()
self.data=coin.SoCoordinate3()
self.face=coin.SoIndexedFaceSet()
self.shaded.addChild(self.scale)
self.shaded.addChild(self.color)
self.shaded.addChild(self.data)
self.shaded.addChild(self.face)
obj.addDisplayMode(self.shaded,"Shaded");
style=coin.SoDrawStyle()
style.style = coin.SoDrawStyle.LINES
self.wireframe.addChild(style)
self.wireframe.addChild(self.scale)
self.wireframe.addChild(self.color)
self.wireframe.addChild(self.data)
self.wireframe.addChild(self.face)
obj.addDisplayMode(self.wireframe,"Wireframe");
self.onChanged(obj,"Color")
def updateData(self, fp, prop):
"If a property of the handled feature has changed we have the chance to handle this here"
# fp is the handled feature, prop is the name of the property that has changed
if prop == "Shape":
s = fp.getPropertyByName("Shape")
self.data.point.setNum(6)
cnt=0
for i in s.Vertexes:
self.data.point.set1Value(cnt,i.X,i.Y,i.Z)
cnt=cnt+1
self.face.coordIndex.set1Value(0,0)
self.face.coordIndex.set1Value(1,1)
self.face.coordIndex.set1Value(2,2)
self.face.coordIndex.set1Value(3,-1)
self.face.coordIndex.set1Value(4,1)
self.face.coordIndex.set1Value(5,3)
self.face.coordIndex.set1Value(6,2)
self.face.coordIndex.set1Value(7,-1)
self.face.coordIndex.set1Value(8,3)
self.face.coordIndex.set1Value(9,4)
self.face.coordIndex.set1Value(10,2)
self.face.coordIndex.set1Value(11,-1)
self.face.coordIndex.set1Value(12,4)
self.face.coordIndex.set1Value(13,0)
self.face.coordIndex.set1Value(14,2)
self.face.coordIndex.set1Value(15,-1)
self.face.coordIndex.set1Value(16,1)
self.face.coordIndex.set1Value(17,0)
self.face.coordIndex.set1Value(18,5)
self.face.coordIndex.set1Value(19,-1)
self.face.coordIndex.set1Value(20,3)
self.face.coordIndex.set1Value(21,1)
self.face.coordIndex.set1Value(22,5)
self.face.coordIndex.set1Value(23,-1)
self.face.coordIndex.set1Value(24,4)
self.face.coordIndex.set1Value(25,3)
self.face.coordIndex.set1Value(26,5)
self.face.coordIndex.set1Value(27,-1)
self.face.coordIndex.set1Value(28,0)
self.face.coordIndex.set1Value(29,4)
self.face.coordIndex.set1Value(30,5)
self.face.coordIndex.set1Value(31,-1)
def getDisplayModes(self,obj):
"Return a list of display modes."
modes=[]
modes.append("Shaded")
modes.append("Wireframe")
return modes
def getDefaultDisplayMode(self):
"Return the name of the default display mode. It must be defined in getDisplayModes."
return "Shaded"
def setDisplayMode(self,mode):
return mode
def onChanged(self, vp, prop):
"Here we can do something when a single property got changed"
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
if prop == "Color":
c = vp.getPropertyByName("Color")
self.color.rgb.setValue(c[0],c[1],c[2])
def getIcon(self):
return """
/* XPM */
static const char * ViewProviderBox_xpm[] = {
"16 16 6 1",
" c None",
". c #141010",
"+ c #615BD2",
"@ c #C39D55",
"# c #000000",
"$ c #57C355",
" ........",
" ......++..+..",
" .@@@@.++..++.",
" .@@@@.++..++.",
" .@@ .++++++.",
" ..@@ .++..++.",
"###@@@@ .++..++.",
"##$.@@$#.++++++.",
"#$#$.$$$........",
"#$$####### ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
" #$#$$$$$# ",
" ##$$$$$# ",
" ####### "};
"""
def dumps(self):
return None
def loads(self,state):
return None
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):
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Octahedron")
Octahedron(a)
ViewProviderOctahedron(a.ViewObject)
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.
Once the parts of the scenegraph that are to be selectable are inside SoFCSelection nodes, you then need to provide two methods to handle the selection path. The selection path can take the form of a string giving the names of each element in the path, or of an array of scenegraph objects. The two methods you provide are getDetailPath
, which converts from a string path to an array of scenegraph objects, and getElementPicked
, which takes an element which has been clicked on in the scenegraph and returns its string name (note, not its string path).
Here is the molecule example above, adapted to make the elements of the molecule selectable:
class Molecule:
def __init__(self, obj):
''' Add two point properties '''
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(5,0,0)
obj.Proxy = self
def onChanged(self, fp, prop):
if prop == "p1" or prop == "p2":
''' Print the name of the property that has changed '''
fp.Shape = Part.makeLine(fp.p1,fp.p2)
def execute(self, fp):
''' Print a short message when doing a recomputation, this method is mandatory '''
fp.Shape = Part.makeLine(fp.p1,fp.p2)
class ViewProviderMolecule:
def __init__(self, obj):
''' Set this object to the proxy object of the actual view provider '''
obj.Proxy = self
self.ViewObject = obj
sep1=coin.SoSeparator()
sel1 = coin.SoType.fromName('SoFCSelection').createInstance()
# sel1.policy.setValue(coin.SoSelection.SHIFT)
sel1.ref()
sep1.addChild(sel1)
self.trl1=coin.SoTranslation()
sel1.addChild(self.trl1)
sel1.addChild(coin.SoSphere())
sep2=coin.SoSeparator()
sel2 = coin.SoType.fromName('SoFCSelection').createInstance()
sel2.ref()
sep2.addChild(sel2)
self.trl2=coin.SoTranslation()
sel2.addChild(self.trl2)
sel2.addChild(coin.SoSphere())
obj.RootNode.addChild(sep1)
obj.RootNode.addChild(sep2)
self.updateData(obj.Object, 'p2')
self.sel1 = sel1
self.sel2 = sel2
def getDetailPath(self, subname, path, append):
vobj = self.ViewObject
if append:
path.append(vobj.RootNode)
path.append(vobj.SwitchNode)
mode = vobj.SwitchNode.whichChild.getValue()
if mode >= 0:
mode = vobj.SwitchNode.getChild(mode)
path.append(mode)
sub = Part.splitSubname(subname)[-1]
if sub == 'Atom1':
path.append(self.sel1)
elif sub == 'Atom2':
path.append(self.sel2)
else:
path.append(mode.getChild(0))
return True
def getElementPicked(self, pp):
path = pp.getPath()
if path.findNode(self.sel1) >= 0:
return 'Atom1'
if path.findNode(self.sel2) >= 0:
return 'Atom2'
raise NotImplementedError
def updateData(self, fp, prop):
"If a property of the handled feature has changed we have the chance to handle this here"
# fp is the handled feature, prop is the name of the property that has changed
if prop == "p1":
p = fp.getPropertyByName("p1")
self.trl1.translation=(p.x,p.y,p.z)
elif prop == "p2":
p = fp.getPropertyByName("p2")
self.trl2.translation=(p.x,p.y,p.z)
def dumps(self):
return None
def loads(self,state):
return None
def makeMolecule():
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("Part::FeaturePython","Molecule")
Molecule(a)
ViewProviderMolecule(a.ViewObject)
FreeCAD.ActiveDocument.recompute()
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:
import FreeCAD as App
import FreeCADGui
import FreeCAD
import Part
class Line:
def __init__(self, obj):
'''"App two point properties" '''
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(1,0,0)
obj.Proxy = self
def execute(self, fp):
'''"Print a short message when doing a recomputation, this method is mandatory" '''
fp.Shape = Part.makeLine(fp.p1,fp.p2)
a=FreeCAD.ActiveDocument.addObject("Part::FeaturePython","Line")
Line(a)
a.ViewObject.Proxy=0 # just set it to something different from None (this assignment is needed to run an internal notification)
FreeCAD.ActiveDocument.recompute()
Same code with use ViewProviderLine
import FreeCAD as App
import FreeCADGui
import FreeCAD
import Part
class Line:
def __init__(self, obj):
'''"App two point properties" '''
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(100,0,0)
obj.Proxy = self
def execute(self, fp):
'''"Print a short message when doing a recomputation, this method is mandatory" '''
fp.Shape = Part.makeLine(fp.p1,fp.p2)
class ViewProviderLine:
def __init__(self, obj):
''' Set this object to the proxy object of the actual view provider '''
obj.Proxy = self
def getDefaultDisplayMode(self):
''' Return the name of the default display mode. It must be defined in getDisplayModes. '''
return "Flat Lines"
a=FreeCAD.ActiveDocument.addObject("Part::FeaturePython","Line")
Line(a)
ViewProviderLine(a.ViewObject)
App.ActiveDocument.recompute()
Scenegraph Structure
You may have noticed that the examples above construct their scenegraphs in slightly different ways. Some use obj.addDisplayMode(node, "modename")
while others use obj.SwitchNode.getChild(x).addChild(y)
.
Each feature in a FreeCAD document is based the following scenegraph structure:
RootNode
\- SwitchNode
\- Shaded
- Wireframe
- etc
The SwitchNode
displays only one of its children, depending on which display mode is selection in FreeCAD.
The examples which use addDisplayMode
are constructing their scenegraphs solely out of coin3d scenegraph elements. Under the covers, addDisplayMode
adds a new child to the SwitchNode
; the name of that node will match the display mode it was passed.
The examples which use SwitchNode.getChild(x).addChild
also construct part of their geometry using functions from the Part workbench, such as fp.Shape = Part.makeLine(fp.p1,fp.p2)
. This constructs the different display mode scenegraphs under the SwitchNode
; when we later come to add coin3d elements to the scenegraph, we need to add them to the existing display mode scenegraphs using addChild
rather than creating a new child of the SwitchNode
.
When using addDisplayMode()
to add geometry to the scenegraph, each display mode should have its own node which is passed to addDisplayMode()
; 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:
import Part
from pivy import coin
class Molecule:
def __init__(self, obj):
''' Add two point properties '''
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(5,0,0)
obj.Proxy = self
def onChanged(self, fp, prop):
pass
def execute(self, fp):
''' Print a short message when doing a recomputation, this method is mandatory '''
pass
class ViewProviderMolecule:
def __init__(self, obj):
''' Set this object to the proxy object of the actual view provider '''
self.constructed = False
obj.Proxy = self
self.ViewObject = obj
def attach(self, obj):
material = coin.SoMaterial()
material.diffuseColor = (1.0, 0.0, 0.0)
material.emissiveColor = (1.0, 0.0, 0.0)
drawStyle = coin.SoDrawStyle()
drawStyle.pointSize.setValue(10)
drawStyle.style = coin.SoDrawStyle.LINES
wireframe = coin.SoGroup()
shaded = coin.SoGroup()
self.wireframe = wireframe
self.shaded = shaded
self.coords = coin.SoCoordinate3()
self.coords.point.setValues(0, 2, [FreeCAD.Vector(0, 0, 0), FreeCAD.Vector(1, 0, 0)])
wireframe += self.coords
wireframe += drawStyle
wireframe += material
shaded += self.coords
shaded += drawStyle
shaded += material
g = coin.SoGroup()
sel1 = coin.SoType.fromName('SoFCSelection').createInstance()
sel1.style = 'EMISSIVE_DIFFUSE'
p1 = coin.SoType.fromName('SoIndexedPointSet').createInstance()
p1.coordIndex.set1Value(0, 0)
sel1 += p1
g += sel1
wireframe += g
shaded += g
g = coin.SoGroup()
sel2 = coin.SoType.fromName('SoFCSelection').createInstance()
sel2.style = 'EMISSIVE_DIFFUSE'
p2 = coin.SoType.fromName('SoIndexedPointSet').createInstance()
p2.coordIndex.set1Value(0, 1)
sel2 += p2
g += sel2
wireframe += g
shaded += g
g = coin.SoGroup()
sel3 = coin.SoType.fromName('SoFCSelection').createInstance()
sel3.style = 'EMISSIVE_DIFFUSE'
p3 = coin.SoType.fromName('SoIndexedLineSet').createInstance()
p3.coordIndex.setValues(0, 2, [0, 1])
sel3 += p3
g += sel3
wireframe += g
shaded += g
obj.addDisplayMode(wireframe, 'Wireframe')
obj.addDisplayMode(shaded, 'Shaded')
self.sel1 = sel1
self.sel2 = sel2
self.sel3 = sel3
self.constructed = True
self.updateData(obj.Object, 'p2')
def getDetailPath(self, subname, path, append):
vobj = self.ViewObject
if append:
path.append(vobj.RootNode)
path.append(vobj.SwitchNode)
mode = vobj.SwitchNode.whichChild.getValue()
FreeCAD.Console.PrintWarning("getDetailPath: mode {} is active\n".format(mode))
if mode >= 0:
mode = vobj.SwitchNode.getChild(mode)
path.append(mode)
sub = Part.splitSubname(subname)[-1]
print(sub)
if sub == 'Atom1':
path.append(self.sel1)
elif sub == 'Atom2':
path.append(self.sel2)
elif sub == 'Line':
path.append(self.sel3)
else:
path.append(mode.getChild(0))
return True
def getElementPicked(self, pp):
path = pp.getPath()
if path.findNode(self.sel1) >= 0:
return 'Atom1'
if path.findNode(self.sel2) >= 0:
return 'Atom2'
if path.findNode(self.sel3) >= 0:
return 'Line'
raise NotImplementedError
def updateData(self, fp, prop):
"If a property of the handled feature has changed we have the chance to handle this here"
# fp is the handled feature, prop is the name of the property that has changed
if not self.constructed:
return
if prop == "p1":
p = fp.getPropertyByName("p1")
self.coords.point.set1Value(0, p)
elif prop == "p2":
p = fp.getPropertyByName("p2")
self.coords.point.set1Value(1, p)
def getDisplayModes(self, obj):
return ['Wireframe', 'Shaded']
def getDefaultDisplayMode(self):
return 'Shaded'
def setDisplayMode(self, mode):
return mode
def dumps(self):
return None
def loads(self,state):
return None
def makeMolecule():
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Molecule")
Molecule(a)
b=ViewProviderMolecule(a.ViewObject)
a.touch()
FreeCAD.ActiveDocument.recompute()
return a,b
a,b = makeMolecule()
Part Design scripted objects
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:
# -*- coding: utf-8 -*-
#classes should go in pdtube.py
import FreeCAD, FreeCADGui, Part
class PDTube:
def __init__(self,obj):
obj.addProperty("App::PropertyLength","Radius1","Tube","Radius1").Radius1 = 5
obj.addProperty("App::PropertyLength","Radius2","Tube","Radius2").Radius2 = 10
obj.addProperty("App::PropertyLength","Height","Tube","Height of tube").Height = 10
self.makeAttachable(obj)
obj.Proxy = self
def makeAttachable(self, obj):
if int(FreeCAD.Version()[1]) >= 19:
obj.addExtension('Part::AttachExtensionPython')
else:
obj.addExtension('Part::AttachExtensionPython', obj)
obj.setEditorMode('Placement', 0) #non-readonly non-hidden
def execute(self,fp):
outer_cylinder = Part.makeCylinder(fp.Radius2, fp.Height)
inner_cylinder = Part.makeCylinder(fp.Radius1, fp.Height)
if fp.Radius1 == fp.Radius2: #just make cylinder
tube_shape = outer_cylinder
elif fp.Radius1 < fp.Radius2:
tube_shape = outer_cylinder.cut(inner_cylinder)
else: #invert rather than error out
tube_shape = inner_cylinder.cut(outer_cylinder)
if not hasattr(fp, "positionBySupport"):
self.makeAttachable(fp)
fp.positionBySupport()
tube_shape.Placement = fp.Placement
#BaseFeature (shape property of type Part::PropertyPartShape) is provided for us
#with the PartDesign::FeaturePython and related classes, but it might be empty
#if our object is the first object in the tree. it's a good idea to check
#for its existence in case we want to make type Part::FeaturePython, which won't have it
if hasattr(fp, "BaseFeature") and fp.BaseFeature != None:
if "Subtractive" in fp.TypeId:
full_shape = fp.BaseFeature.Shape.cut(tube_shape)
else:
full_shape = fp.BaseFeature.Shape.fuse(tube_shape)
full_shape.transformShape(fp.Placement.inverse().toMatrix(), True) #borrowed from gears workbench
fp.Shape = full_shape
else:
fp.Shape = tube_shape
if hasattr(fp,"AddSubShape"): #PartDesign::FeatureAdditivePython and
#PartDesign::FeatureSubtractivePython have this
#property but PartDesign::FeaturePython does not
#It is the shape used for copying in pattern features
#for example in making a polar pattern
tube_shape.transformShape(fp.Placement.inverse().toMatrix(), True)
fp.AddSubShape = tube_shape
class PDTubeVP:
def __init__(self, obj):
'''Set this object to the proxy object of the actual view provider'''
obj.Proxy = self
def attach(self,vobj):
self.vobj = vobj
def updateData(self, fp, prop):
'''If a property of the handled feature has changed we have the chance to handle this here'''
pass
def getDisplayModes(self,obj):
'''Return a list of display modes.'''
modes=[]
modes.append("Flat Lines")
modes.append("Shaded")
modes.append("Wireframe")
return modes
def getDefaultDisplayMode(self):
'''Return the name of the default display mode. It must be defined in getDisplayModes.'''
return "Flat Lines"
def setDisplayMode(self,mode):
'''Map the display mode defined in attach with those defined in getDisplayModes.\
Since they have the same names nothing needs to be done. This method is optional'''
return mode
def onChanged(self, vp, prop):
'''Here we can do something when a single property got changed'''
#FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
pass
def getIcon(self):
'''Return the icon in XPM format which will appear in the tree view. This method is\
optional and if not defined a default icon is shown.'''
return """
/* XPM */
static const char * ViewProviderBox_xpm[] = {
"16 16 6 1",
" c None",
". c #141010",
"+ c #615BD2",
"@ c #C39D55",
"# c #000000",
"$ c #57C355",
" ........",
" ......++..+..",
" .@@@@.++..++.",
" .@@@@.++..++.",
" .@@ .++++++.",
" ..@@ .++..++.",
"###@@@@ .++..++.",
"##$.@@$#.++++++.",
"#$#$.$$$........",
"#$$####### ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
" #$#$$$$$# ",
" ##$$$$$# ",
" ####### "};
"""
def dumps(self):
'''When saving the document this object gets stored using Python's json module.\
Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\
to return a tuple of all serializable objects or None.'''
return None
def loads(self,state):
'''When restoring the serialized object from document we have the chance to set some internals here.\
Since no data were serialized nothing needs to be done here.'''
return None
And now the macro file to create the object:
# -*- coding: utf-8 -*-
#pdtube.FCMacro
import pdtube
#above line needed if the class definitions above are place in another file: PDTube.py
#this is needed if the tube object is to remain parametric after restarting FreeCAD and loading
#a document containing the object
body = FreeCADGui.ActiveDocument.ActiveView.getActiveObject("pdbody")
if not body:
FreeCAD.Console.PrintError("No active body.\n")
else:
from PySide import QtGui
window = FreeCADGui.getMainWindow()
items = ["Additive","Subtractive","Neither additive nor subtractive"]
item,ok =QtGui.QInputDialog.getItem(window,"Select tube type","Select whether you want additive, subtractive, or neither:",items,0,False)
if ok:
if item == items[0]:
className = "PartDesign::FeatureAdditivePython"
elif item == items[1]:
className = "PartDesign::FeatureSubtractivePython"
else:
className = "PartDesign::FeaturePython" #not usable in pattern features, such as polar pattern
tube = FreeCAD.ActiveDocument.addObject(className,"Tube")
pdtube.PDTube(tube)
pdtube.PDTubeVP(tube.ViewObject)
body.addObject(tube) #optionally we can also use body.insertObject() for placing at particular place in tree
Available object types
The list of all object types you can create with FreeCAD.ActiveDocument.addObject()
can be obtained with FreeCAD.ActiveDocument.supportedTypes()
. Only object types with a name ending in Python
can be used for scripted objects. These are listed here (for FreeCAD v0.21):
App::DocumentObjectGroupPython
App::FeaturePython
App::GeometryPython
App::LinkElementPython
App::LinkGroupPython
App::LinkPython
App::MaterialObjectPython
App::PlacementPython
Part::CustomFeaturePython
Part::FeaturePython
Part::Part2DObjectPython
Path::FeatureAreaPython
Path::FeatureAreaViewPython
Path::FeatureCompoundPython
Path::FeaturePython
Path::FeatureShapePython
Sketcher::SketchObjectPython
TechDraw::DrawComplexSectionPython
TechDraw::DrawLeaderLinePython
TechDraw::DrawPagePython
TechDraw::DrawRichAnnoPython
TechDraw::DrawTemplatePython
TechDraw::DrawTilePython
TechDraw::DrawTileWeldPython
TechDraw::DrawViewPartPython
TechDraw::DrawViewPython
TechDraw::DrawViewSectionPython
TechDraw::DrawViewSymbolPython
TechDraw::DrawWeldSymbolPython
Available methods
See FeaturePython methods for the complete reference.
Available properties
Properties are the true building blocks of FeaturePython objects. Through them, you will be able to interact and modify your object. After creating a new FeaturePython object in your document, you can get a list of the available properties:
obj = FreeCAD.ActiveDocument.addObject("App::FeaturePython", "Box")
obj.supportedProperties()
See FeaturePython Custom Properties for an overview.
When adding properties to your custom objects, take care of this:
- Do not use characters
<
or>
in the properties descriptions (that would break the xml pieces in the .FCStd file). - Properties are stored alphabetically in a .FCStd file. If you have a shape in your properties, any property whose name comes after "Shape" in alphabetic order, will be loaded AFTER the shape, which can cause strange behaviors.
The properties are defined in the PropertyStandard C++ header file.
Property types
By default properties can be updated, but it is possible to make properties read-only, for instance if one wants to show the result of a method. It is also possible to hide a property. The property type can be set using:
obj.setEditorMode("MyPropertyName", mode)
where mode is a short int that can be set to:
0 -- default mode, read and write 1 -- read-only 2 -- hidden
The mode can also be set using a list of strings, e.g. obj.setEditorMode("Placement", ["ReadOnly", "Hidden"])
.
The EditorModes are not set at FreeCAD file reload. This could to be done by the loads
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 the Property editor. They can 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):
obj.addProperty("App::PropertyString", "MyCustomProperty", "", "", 8)
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
The property types are defined in the PropertyContainer C++ header file.
Available extensions
The list of available extensions can be obtained with grep -RI EXTENSION_PROPERTY_SOURCE_TEMPLATE
in the repository of the source code and is given here (for FreeCAD v0.21).
For objects:
App::GeoFeatureGroupExtensionPython
App::GroupExtensionPython
App::LinkBaseExtensionPython
App::LinkExtensionPython
App::OriginGroupExtensionPython
Part::AttachExtensionPython
TechDraw::CosmeticExtensionPython
For view objects:
Gui::ViewProviderExtensionPython
Gui::ViewProviderGeoFeatureGroupExtensionPython
Gui::ViewProviderGroupExtensionPython
Gui::ViewProviderOriginGroupExtensionPython
PartGui::ViewProviderAttachExtensionPython
PartGui::ViewProviderSplineExtensionPython
There exist other extensions but they do not work as-is:
App::ExtensionPython
TechDrawGui::ViewProviderCosmeticExtensionPython
TechDrawGui::ViewProviderDrawingViewExtensionPython
TechDrawGui::ViewProviderPageExtensionPython
TechDrawGui::ViewProviderTemplateExtensionPython
Further information
Additional pages:
- Scripted objects saving attributes
- Scripted objects migration
- Scripted objects with attachment
- Viewproviders
Interesting forum threads about scripted objects:
- Python object attributes lost at load
- New FeaturePython is grey
- Explanation on dumps and loads, official documentation
- Eigenmode frequency always 0?
- how to implement python feature's setEdit properly?
In addition to the examples presented here have a look at FreeCAD source code src/Mod/TemplatePyMod/FeaturePython.py for more examples.
- FreeCAD scripting: Python, Introduction to Python, Python scripting tutorial, FreeCAD Scripting Basics
- Modules: Builtin modules, Units, Quantity
- Workbenches: Workbench creation, Gui Commands, Commands, Installing more workbenches
- Meshes and Parts: Mesh Scripting, Topological data scripting, Mesh to Part, PythonOCC
- Parametric objects: Scripted objects, Viewproviders (Custom icon in tree view)
- Scenegraph: Coin (Inventor) scenegraph, Pivy
- Graphical interface: Interface creation, Interface creation completely in Python (1, 2, 3, 4, 5), PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Embedding: Embedding FreeCAD, Embedding FreeCADGui
- Other: Expressions, Code snippets, Line drawing function, FreeCAD vector math library (deprecated)
- Hubs: User hub, Power users hub, Developer hub