Scripted objects/cs: Difference between revisions

From FreeCAD Documentation
(Created page with "== Dostupné vlastnosti == Vlastnosti jsou skutečné základní kameny pythonovských objektů. Jejich prostřednictvím je uživatel schopen pracovat s objektem. Po vytvoře...")
(Updating to match new version of source page)
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<languages/>
{{docnav|PySide|Embedding FreeCAD}}

Kromě standardních objektových typů jako jsou anotace, sítě a díly, nabízí FreeCAD skvělou možnost vytváření objektů 100% vytvořených skritpy Pythonu, které se nazývají Pythonovské objekty. Tyto objekty se chovají stejně jako jiné objekty FreeCADu a jsou ukládány a načítány automaticky při ukládání a otevírání souboru.
Kromě standardních objektových typů jako jsou anotace, sítě a díly, nabízí FreeCAD skvělou možnost vytváření objektů 100% vytvořených skritpy Pythonu, které se nazývají Pythonovské objekty. Tyto objekty se chovají stejně jako jiné objekty FreeCADu a jsou ukládány a načítány automaticky při ukládání a otevírání souboru.


Je třeba pochopit jednu zvláštnost, tyto objekty jsou ukádány ve FcStd souborech FreeCADu s pythonovským modulem [http://docs.python.org/2/library/json.html json]. Tento modul převede pythonovský objekt do řetězce, který je pak možno uložit v souboru. Při načítání naopak tento modul použije uložený řetězec ke znovuvytvoření původního objektu, při tom musí mít přístup ke zdojovému kódu, který vytvoří objektu. To znamená, že když uložíte takový uživatelský objekt a pak jej otevíráte na počítači kde není pythonovský kód, tak nebude tento objekt znovuvytvořen. Když tedy distribuujete takový objekt někomu jinému, musíte společně s ním distribuovat i pythonovský skript který objekt vytváří.
Je třeba pochopit jednu zvláštnost, tyto objekty jsou ukládány ve FcStd souborech FreeCADu s pythonovským modulem [http://docs.python.org/2/library/json.html json]. Tento modul převede pythonovský objekt do řetězce, který je pak možno uložit v souboru. Při načítání naopak tento modul použije uložený řetězec ke znovuvytvoření původního objektu, při tom musí mít přístup ke zdrojovému kódu, který vytvoří objekt. To znamená, že když uložíte takový uživatelský objekt a pak jej otevíráte na počítači kde není pythonovský kód, tak nebude tento objekt vytvořen. Když tedy distribuujete takový objekt někomu jinému, musíte společně s ním distribuovat i pythonovský skript, který objekt vytváří.


Pythonovský objekt má stejné pravidlo jako FreeCAD: Aplikace a GUI jsou odděleny do samostatných částí. Aplikační část, Document Object, definuje konstrukci objektu, zatímco část GUI, View Provider Object, definuje jak bude objekt zobrazen na displeji. View Provider Object, stejně jako další GUI objekty FreeCADu je dostupný pouze když FreeCAD běží se svým vlastním GUI. Pro vytvoření objektu je použitelné několik vlastností a metod. Vlastnosti musejí být některé z předdefinovaných typových vlastností které nabízí FreeCAD a zobrazují se v dialogovém okně vlastností, takže mohou být uživatelem upravovány. Tímto způsobem jsou Pythonovské objekty věrně a zcela parametrizovány. Můžete samostatně definovat vlastnosti objektu a jeho zobrazovacího objektu.
Pythonovský objekt má stejné pravidlo jako FreeCAD: Aplikace a GUI jsou odděleny do samostatných částí. Aplikační část, Document Object, definuje konstrukci objektu, zatímco část GUI, View Provider Object, definuje jak bude objekt zobrazen na displeji. View Provider Object, stejně jako další GUI objekty FreeCADu je dostupný pouze když FreeCAD běží se svým vlastním GUI. Pro vytvoření objektu je použitelných několik vlastností a metod. Vlastnosti musejí být některé z předdefinovaných typových vlastností, které nabízí FreeCAD a zobrazují se v dialogovém okně vlastností, takže mohou být uživatelem upravovány. Tímto způsobem jsou Pythonovské objekty správně a zcela parametrizovány. Můžete samostatně definovat vlastnosti objektu a jeho zobrazovacího objektu.


'''Rada:''' Ve starších verzích jsme používali pythonovský modul [http://docs.python.org/release/2.5/lib/module-cPickle.html cPickle]. Nicméně tento modul spouští libovolný kód a to může být bezpečnostní problém. Proto jsme přešli k pythonovskému modulu json.
'''Informace:''' Ve starších verzích jsme používali pythonovský modul [http://docs.python.org/release/2.5/lib/module-cPickle.html cPickle]. Nicméně tento modul spouští libovolný kód a to může být bezpečnostní problém. Proto jsme přešli k pythonovskému modulu json.


<div class="mw-translate-fuzzy">
== Základní příklad ==
== Základní příklad ==
Následující příklad najdete v souboru [http://free-cad.svn.sourceforge.net/viewvc/free-cad/trunk/src/Mod/TemplatePyMod/FeaturePython.py?view=markup src/Mod/TemplatePyMod/FeaturePython.py], společně s několika dalšími příklady:
Následující příklad najdete v souboru [http://free-cad.svn.sourceforge.net/viewvc/free-cad/trunk/src/Mod/TemplatePyMod/FeaturePython.py?view=markup src/Mod/TemplatePyMod/FeaturePython.py], společně s několika dalšími příklady:
</div>
<syntaxhighlight>
{{Code|code=
"Examples for a feature class and its view provider."
'''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(l,w,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 __getstate__(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 __setstate__(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)
</syntaxhighlight>
== Dostupné vlastnosti ==
Vlastnosti jsou skutečné základní kameny pythonovských objektů. Jejich prostřednictvím je uživatel schopen pracovat s objektem. Po vytvoření Pythonovského objektu v dokumentu ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), obdržíte seznam dostupných vlastností zadáním:
<syntaxhighlight>
obj.supportedProperties()
</syntaxhighlight>
You will get a list of available properties:
<syntaxhighlight>
App::PropertyBool
App::PropertyFloat
App::PropertyFloatList
App::PropertyFloatConstraint
App::PropertyAngle
App::PropertyDistance
App::PropertyInteger
App::PropertyIntegerConstraint
App::PropertyPercent
App::PropertyEnumeration
App::PropertyIntegerList
App::PropertyString
App::PropertyStringList
App::PropertyLink
App::PropertyLinkList
App::PropertyMatrix
App::PropertyVector
App::PropertyVectorList
App::PropertyPlacement
App::PropertyPlacementLink
App::PropertyColor
App::PropertyColorList
App::PropertyMaterial
App::PropertyPath
App::PropertyFile
App::PropertyFileIncluded
Part::PropertyPartShape
Part::PropertyFilletContour
Part::PropertyCircle
</syntaxhighlight>
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.


import FreeCAD, FreeCADGui
from pivy import coin


class Box:
==Property Type==
def __init__(self, obj):
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.
'''Add some custom properties to our box feature'''
The property type can be set using
obj.addProperty("App::PropertyLength","Length","Box","Length of the box").Length=1.0
<syntaxhighlight>
obj.addProperty("App::PropertyLength","Width","Box","Width of the box").Width=1.0
obj.setEditorMode("MyPropertyName", mode)
obj.addProperty("App::PropertyLength","Height","Box", "Height of the box").Height=1.0
</syntaxhighlight>
obj.Proxy = self
where mode is a short int that can be set to:
0 -- default mode, read and write
def onChanged(self, fp, prop):
1 -- read-only
'''Do something when a property has changed'''
2 -- hidden
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")

== Other more complex example ==
def execute(self, fp):
This example makes use of the [[Part Module]] to create an octahedron, then creates its coin representation with pivy.
'''Do something when doing a recomputation, this method is mandatory'''
FreeCAD.Console.PrintMessage("Recompute Python Box feature\n")


class ViewProviderBox:
First is the Document object itself:
def __init__(self, obj):
<syntaxhighlight>
'''Set this object to the proxy object of the actual view provider'''
import FreeCAD, FreeCADGui, Part
obj.addProperty("App::PropertyColor","Color","Box","Color of the box").Color=(1.0,0.0,0.0)
obj.Proxy = self
class Octahedron:
def attach(self, obj):
'''Setup the scene sub-graph of the view provider, this method is mandatory'''
def __init__(self, obj):
self.shaded = coin.SoGroup()
"Add some custom properties to our box feature"
self.wireframe = coin.SoGroup()
obj.addProperty("App::PropertyLength","Length","Octahedron","Length of the octahedron").Length=1.0
self.scale = coin.SoScale()
obj.addProperty("App::PropertyLength","Width","Octahedron","Width of the octahedron").Width=1.0
self.color = coin.SoBaseColor()
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
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 execute(self, fp):
def updateData(self, fp, prop):
'''If a property of the handled feature has changed we have the chance to handle this here'''
# Define six vetices for the shape
# fp is the handled feature, prop is the name of the property that has changed
v1 = FreeCAD.Vector(0,0,0)
v2 = FreeCAD.Vector(fp.Length,0,0)
l = fp.getPropertyByName("Length")
v3 = FreeCAD.Vector(0,fp.Width,0)
w = fp.getPropertyByName("Width")
v4 = FreeCAD.Vector(fp.Length,fp.Width,0)
h = fp.getPropertyByName("Height")
self.scale.scaleFactor.setValue(float(l),float(w),float(h))
v5 = FreeCAD.Vector(fp.Length/2,fp.Width/2,fp.Height/2)
pass
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
def getDisplayModes(self,obj):
# helper mehod to create the faces
'''Return a list of display modes.'''
def make_face(self,v1,v2,v3):
wire = Part.makePolygon([v1,v2,v3,v1])
modes=[]
face = Part.Face(wire)
modes.append("Shaded")
return face
modes.append("Wireframe")
return modes
</syntaxhighlight>
Then, we have the view provider object, responsible for showing the object in the 3D scene:
<syntaxhighlight>
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):
def getDefaultDisplayMode(self):
"Setup the scene sub-graph of the view provider, this method is mandatory"
'''Return the name of the default display mode. It must be defined in getDisplayModes.'''
self.shaded = coin.SoGroup()
return "Shaded"
self.wireframe = coin.SoGroup()
self.scale = coin.SoScale()
self.color = coin.SoBaseColor()
def setDisplayMode(self,mode):
self.data=coin.SoCoordinate3()
'''Map the display mode defined in attach with those defined in getDisplayModes.\
self.face=coin.SoIndexedLineSet()
Since they have the same names nothing needs to be done. This method is optional'''
return mode
def onChanged(self, vp, prop):
self.shaded.addChild(self.scale)
'''Here we can do something when a single property got changed'''
self.shaded.addChild(self.color)
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
self.shaded.addChild(self.data)
self.shaded.addChild(self.face)
if prop == "Color":
obj.addDisplayMode(self.shaded,"Shaded");
c = vp.getPropertyByName("Color")
style=coin.SoDrawStyle()
self.color.rgb.setValue(c[0],c[1],c[2])
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):
def getIcon(self):
"If a property of the handled feature has changed we have the chance to handle this here"
'''Return the icon in XPM format which will appear in the tree view. This method is\
# fp is the handled feature, prop is the name of the property that has changed
optional and if not defined a default icon is shown.'''
if prop == "Shape":
return """
s = fp.getPropertyByName("Shape")
/* XPM */
self.data.point.setNum(6)
static const char * ViewProviderBox_xpm[] = {
cnt=0
"16 16 6 1",
for i in s.Vertexes:
" c None",
self.data.point.set1Value(cnt,i.X,i.Y,i.Z)
". c #141010",
cnt=cnt+1
"+ c #615BD2",
"@ c #C39D55",
self.face.coordIndex.set1Value(0,0)
"# c #000000",
self.face.coordIndex.set1Value(1,1)
"$ c #57C355",
self.face.coordIndex.set1Value(2,2)
" ........",
self.face.coordIndex.set1Value(3,-1)
" ......++..+..",
" .@@@@.++..++.",
" .@@@@.++..++.",
" .@@ .++++++.",
" ..@@ .++..++.",
"###@@@@ .++..++.",
"##$.@@$#.++++++.",
"#$#$.$$$........",
"#$$####### ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
"#$$#$$$$$# ",
" #$#$$$$$# ",
" ##$$$$$# ",
" ####### "};
"""
def __getstate__(self):
self.face.coordIndex.set1Value(4,1)
'''When saving the document this object gets stored using Python's json module.\
self.face.coordIndex.set1Value(5,3)
Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\
self.face.coordIndex.set1Value(6,2)
to return a tuple of all serializable objects or None.'''
self.face.coordIndex.set1Value(7,-1)
return None
def __setstate__(self,state):
self.face.coordIndex.set1Value(8,3)
'''When restoring the serialized object from document we have the chance to set some internals here.\
self.face.coordIndex.set1Value(9,4)
Since no data were serialized nothing needs to be done here.'''
self.face.coordIndex.set1Value(10,2)
return None
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 __getstate__(self):
return None
def __setstate__(self,state):
return None
</syntaxhighlight>
Finally, once our object and its viewobject are defined, we just need to call them:
<syntaxhighlight>
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Octahedron")
Octahedron(a)
ViewProviderOctahedron(a.ViewObject)
</syntaxhighlight>
== 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:
<syntaxhighlight>
selectionNode = coin.SoType.fromName("SoFCSelection").createInstance()
selectionNode.documentName.setValue(FreeCAD.ActiveDocument.Name)
selectionNode.objectName.setValue(obj.Object.Name) # here obj is the ViewObject, we need its associated App Object
selectionNode.subElementName.setValue("Face")
selectNode.addChild(self.face)
...
self.shaded.addChild(selectionNode)
self.wireframe.addChild(selectionNode)
</syntaxhighlight>
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 ==
def makeBox():
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:
FreeCAD.newDocument()
<syntaxhighlight>
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box")
class Line:
def __init__(self, obj):
Box(a)
ViewProviderBox(a.ViewObject)

makeBox()

}}

== Dostupné vlastnosti ==
Vlastnosti jsou skutečné základní kameny pythonovských objektů. Jejich prostřednictvím je uživatel schopen pracovat s objektem. Po vytvoření Pythonovského objektu v dokumentu ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), obdržíte seznam dostupných vlastností zadáním:

{{Code|code=
obj.supportedProperties()
}}
Dostanete seznam dostupných vlastností:
{{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
}}

Když do uživatelského objektu přidáváte vlastnosti dejte pozor na::
* Nepoužívejte znaky "<" a ">" v popisu vlastnosti (odděluje to části XML v souboru .fcstd)
* Vlastnosti jsou uloženy podle abecedy ve .fcstd souboru. Máte-li ve vlastnostech tvar (shape), jakékoliv jméno vlastnosti, které je za "Shape" podle abecedy, bude nataženo až po tvaru, což může zapříčinit neočekávané chování.

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:

{{Code|code=
prop = (value, lower, upper, stepsize)
}}

==Typ vlastnosti==
Standardně mohou být vlastnosti upravovány. Je ale možné nastavit vlastnosti pouze ke čtení, třeba když má jenom zobrazovat výstup výsledku metody. Je možné také vlastnost skrýt.
Typ vlastnosti může být nastaven použitím

{{Code|code=
obj.setEditorMode("MyPropertyName", mode)
}}

kde mode je malá celočíselná hodnota, které může být nastavena na:
0 -- defaultní mód, čtení i zápis
1 -- pouze čtení
2 -- skryto

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

{{Code|code=
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


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]

<div class="mw-translate-fuzzy">
== Další složitější příklady ==
Tento příklad používá [[Part Module/cs|Modul Díl]] k vytvoření osmistěnu a potom vytvoří pomocí Pivy jeho reprezentaci v Coinu.
</div>

První je samotné vytvoření dokumentu:

{{Code|code=
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
}}

Pak máme objekt pro zobrazení (view provider object), zodpovědný za zobrazení objektu ve 3D:

{{Code|code=
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.SoIndexedLineSet()

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 __getstate__(self):
return None

def __setstate__(self,state):
return None
}}

A nakonec, když je objekt i jeho zobrazení definováno, stačí ho už jen zavolat:

{{Code|code=
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Octahedron")
Octahedron(a)
ViewProviderOctahedron(a.ViewObject)
}}

== Zpřístupnění objektu k výběru ==
Chcete-li aby bylo možné objekt vybrat nebo alespoň jeho část, kliknutím na něj v pohledu, musíte včlenit jeho Coin konstrukci do uzlu SoFCSelection. Má-li objekt komplexní zobrazení s widgety, anotacemi atd., můžete chtít včlenit do SoFCSelection pouze nějakou část. Všechno co je SoFCSelection je průběžně skenováno FreeCADem pro detekci výběru/předvýběru, takže je rozumné nepřetěžovat jej zbytečným skenováním. Tady je co byste měli zahrnout do self.face z příkladu nahoře.

{{Code|code=
selectionNode = coin.SoType.fromName("SoFCSelection").createInstance()
selectionNode.documentName.setValue(FreeCAD.ActiveDocument.Name)
selectionNode.objectName.setValue(obj.Object.Name) # here obj is the ViewObject, we need its associated App Object
selectionNode.subElementName.setValue("Face")
selectNode.addChild(self.face)
...
self.shaded.addChild(selectionNode)
self.wireframe.addChild(selectionNode)
}}

Jednoduše vytvoříte uzel SoFCSelection, potom přidáte konstrukční uzly a potom přidáte hlavní uzel misto přímého přidávání konstrukčních uzlů.

== Práce s jednoduchými tvary ==
Jestliže z parametrického objektu vychází jednoduchý tvar, není nutné používat zobrazovací objekt. Tvar bude zobrazován použitím standardního zobrazování tvarů ve FreeCADu.

{{Code|code=
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'''

{{Code|code=
import FreeCAD as App
import FreeCADGui
import FreeCAD
import Part

class Line:
def __init__(self, obj):
'''"App two point properties" '''
'''"App two point properties" '''
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(1,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" '''
fp.Shape = Part.makeLine(fp.p1,fp.p2)
fp.Shape = Part.makeLine(fp.p1,fp.p2)

class ViewProviderLine:
a=FreeCAD.ActiveDocument.addObject("Part::FeaturePython","Line")
def __init__(self, obj):
Line(a)
''' Set this object to the proxy object of the actual view provider '''
a.ViewObject.Proxy=0 # just set it to something different from None (this assignment is needed to run an internal notification)
obj.Proxy = self
FreeCAD.ActiveDocument.recompute()

</syntaxhighlight>
def getDefaultDisplayMode(self):
{{docnav|PyQt|Embedding FreeCAD}}
''' 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()
}}

<div class="mw-translate-fuzzy">
{{docnav/cs|[[PySide/cs|PySide]]|[[Embedding FreeCAD/cs|Vkládání FreeCADu]]}}
</div>

- [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]

- [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?]

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.

{{docnav|PySide|Embedding FreeCAD}}

{{Userdocnavi}}

<div class="mw-translate-fuzzy">
[[Category:Poweruser Documentation/cs|Kategorie:Dokumentace pokročilého uživatele]]
[[Category:Python Code/cs|Kategorie:Python kódy]]
</div>


[[Category:Poweruser Documentation]]
[[Category:Python Code]]
[[Category:Python Code]]



{{clear}}
{{clear}}
<languages/>

Revision as of 21:22, 10 July 2019

PySide
Embedding FreeCAD

Kromě standardních objektových typů jako jsou anotace, sítě a díly, nabízí FreeCAD skvělou možnost vytváření objektů 100% vytvořených skritpy Pythonu, které se nazývají Pythonovské objekty. Tyto objekty se chovají stejně jako jiné objekty FreeCADu a jsou ukládány a načítány automaticky při ukládání a otevírání souboru.

Je třeba pochopit jednu zvláštnost, tyto objekty jsou ukládány ve FcStd souborech FreeCADu s pythonovským modulem json. Tento modul převede pythonovský objekt do řetězce, který je pak možno uložit v souboru. Při načítání naopak tento modul použije uložený řetězec ke znovuvytvoření původního objektu, při tom musí mít přístup ke zdrojovému kódu, který vytvoří objekt. To znamená, že když uložíte takový uživatelský objekt a pak jej otevíráte na počítači kde není pythonovský kód, tak nebude tento objekt vytvořen. Když tedy distribuujete takový objekt někomu jinému, musíte společně s ním distribuovat i pythonovský skript, který objekt vytváří.

Pythonovský objekt má stejné pravidlo jako FreeCAD: Aplikace a GUI jsou odděleny do samostatných částí. Aplikační část, Document Object, definuje konstrukci objektu, zatímco část GUI, View Provider Object, definuje jak bude objekt zobrazen na displeji. View Provider Object, stejně jako další GUI objekty FreeCADu je dostupný pouze když FreeCAD běží se svým vlastním GUI. Pro vytvoření objektu je použitelných několik vlastností a metod. Vlastnosti musejí být některé z předdefinovaných typových vlastností, které nabízí FreeCAD a zobrazují se v dialogovém okně vlastností, takže mohou být uživatelem upravovány. Tímto způsobem jsou Pythonovské objekty správně a zcela parametrizovány. Můžete samostatně definovat vlastnosti objektu a jeho zobrazovacího objektu.

Informace: Ve starších verzích jsme používali pythonovský modul cPickle. Nicméně tento modul spouští libovolný kód a to může být bezpečnostní problém. Proto jsme přešli k pythonovskému modulu json.

Základní příklad

Následující příklad najdete v souboru src/Mod/TemplatePyMod/FeaturePython.py, společně s několika dalšími příklady:

'''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 __getstate__(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 __setstate__(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()

Dostupné vlastnosti

Vlastnosti jsou skutečné základní kameny pythonovských objektů. Jejich prostřednictvím je uživatel schopen pracovat s objektem. Po vytvoření Pythonovského objektu v dokumentu ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), obdržíte seznam dostupných vlastností zadáním:

obj.supportedProperties()

Dostanete seznam dostupných vlastností:

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

Když do uživatelského objektu přidáváte vlastnosti dejte pozor na::

  • Nepoužívejte znaky "<" a ">" v popisu vlastnosti (odděluje to části XML v souboru .fcstd)
  • Vlastnosti jsou uloženy podle abecedy ve .fcstd souboru. Máte-li ve vlastnostech tvar (shape), jakékoliv jméno vlastnosti, které je za "Shape" podle abecedy, bude nataženo až po tvaru, což může zapříčinit neočekávané chování.

A complete list of property attributes can be seen in the 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:

prop = (value, lower, upper, stepsize)

Typ vlastnosti

Standardně mohou být vlastnosti upravovány. Je ale možné nastavit vlastnosti pouze ke čtení, třeba když má jenom zobrazovat výstup výsledku metody. Je možné také vlastnost skrýt. Typ vlastnosti může být nastaven použitím

obj.setEditorMode("MyPropertyName", mode)

kde mode je malá celočíselná hodnota, které může být nastavena na:

 0 -- defaultní mód, čtení  i zápis
 1 -- pouze čtení
 2 -- skryto

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

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


You can find these different property types defined in the source code C++ header for PropertyContainer

Další složitější příklady

Tento příklad používá Modul Díl k vytvoření osmistěnu a potom vytvoří pomocí Pivy jeho reprezentaci v Coinu.

První je samotné vytvoření dokumentu:

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

Pak máme objekt pro zobrazení (view provider object), zodpovědný za zobrazení objektu ve 3D:

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

     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 __getstate__(self):
     return None

  def __setstate__(self,state):
     return None

A nakonec, když je objekt i jeho zobrazení definováno, stačí ho už jen zavolat:

FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Octahedron")
Octahedron(a)
ViewProviderOctahedron(a.ViewObject)

Zpřístupnění objektu k výběru

Chcete-li aby bylo možné objekt vybrat nebo alespoň jeho část, kliknutím na něj v pohledu, musíte včlenit jeho Coin konstrukci do uzlu SoFCSelection. Má-li objekt komplexní zobrazení s widgety, anotacemi atd., můžete chtít včlenit do SoFCSelection pouze nějakou část. Všechno co je SoFCSelection je průběžně skenováno FreeCADem pro detekci výběru/předvýběru, takže je rozumné nepřetěžovat jej zbytečným skenováním. Tady je co byste měli zahrnout do self.face z příkladu nahoře.

selectionNode = coin.SoType.fromName("SoFCSelection").createInstance()
selectionNode.documentName.setValue(FreeCAD.ActiveDocument.Name)
selectionNode.objectName.setValue(obj.Object.Name) # here obj is the ViewObject, we need its associated App Object
selectionNode.subElementName.setValue("Face")
selectNode.addChild(self.face)
...
self.shaded.addChild(selectionNode)
self.wireframe.addChild(selectionNode)

Jednoduše vytvoříte uzel SoFCSelection, potom přidáte konstrukční uzly a potom přidáte hlavní uzel misto přímého přidávání konstrukčních uzlů.

Práce s jednoduchými tvary

Jestliže z parametrického objektu vychází jednoduchý tvar, není nutné používat zobrazovací objekt. Tvar bude zobrazován použitím standardního zobrazování tvarů ve FreeCADu.

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

- Python object attributes lost at load

- New FeaturePython is grey

- 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.

PySide
Embedding FreeCAD