Программируемые объекты

From FreeCAD Documentation
Revision as of 19:31, 19 September 2014 by FuzzyBot (talk | contribs) (Updating to match new version of source page)

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

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

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

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

Простой пример

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

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

Доступные свойства

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

 obj.supportedProperties()

Вы получите список доступных свойств:

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::PropertyColor
App::PropertyColorList
App::PropertyMaterial
App::PropertyPath
App::PropertyFile
App::PropertyFileIncluded
App::PropertyPythonObject
Part::PropertyPartShape
Part::PropertyGeometryList
Part::PropertyShapeHistory
Part::PropertyFilletEdges
Sketcher::PropertyConstraintList

При добавлении новых свойств к пользовательским объектам, позаботьтесь об этом:

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

Property Type

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

  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

Другие примеры по сложней

Этот пример использует Модуль Деталей для создания октаэдра, задем создает собственное coin представление с помощью pivy.

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

 import FreeCAD, FreeCADGui, Part
 
    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

Теперь , мы обладаем визуальным представлением объекта, ответственного за отображение объекта в 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

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

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

Создание выделяемых объектов

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

 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)

Просто, создайтеa узел SoFCSelection, затем добавте к нему узлы вашей геометрии, после добавте его к вашему главному узлу, вместо добавления напрямую всех ваши узлов геометрии.

Работа с простыми формами

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

 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()
PyQt/ru
Embedding FreeCAD/ru