Script di oggetti

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

Oltre ai tipi di oggetti standard, come le Annotazioni, gli oggetti Mesh e gli oggetti Parte, FreeCAD offre anche la straordinaria possibilità di costruire al 100% oggetti in script di Python, chiamati Python Feature (Caratteristiche Python). Questi oggetti si comportano esattamente come un qualsiasi altro oggetto di FreeCAD, e sono salvati e ripristinati automaticamente con salva/apri il file.

Deve essere conosciuta una loro particolarità: questi oggetti vengono salvati in un file FcStd di FreeCAD con il modulo json di Python. Tale modulo converte un oggetto Python in una stringa, permettendo di aggiungerlo al file salvato. Quando l'oggetto viene caricato, il modulo json utilizza questa stringa per ricreare l'oggetto originale, fornendo l'accesso al codice sorgente da cui ha creato l'oggetto. Questo significa che se si salva un oggetto personalizzato e lo si apre su una macchina in cui non è presente il codice Python che ha generato l'oggetto, l'oggetto non può essere ricreato. Quando si forniscono ad altri utenti questi oggetti, è necessario fornire anche gli script di Python che li hanno creati.

Le Python Features seguono le stesse regole di tutte le altre funzionalità di FreeCAD: sono divise in una parte App e una parte GUI. La parte App, cioè il Document Object (oggetto del documento), definisce la geometria dell'oggetto, mentre la sua parte grafica, cioè il View Provider Object (fornitore della vista dell'oggetto), definisce come l'oggetto viene disegnato sullo schermo. Il View Provider Object, come qualsiasi altro elemento di FreeCAD, è disponibile solo quando si esegue FreeCAD nella sua GUI (interfaccia grafica). Per costruire il proprio oggetto, sono disponibili diversi metodi e proprietà. La Proprietà deve essere una qualsiasi dei tipi di proprietà predefinite che FreeCAD mette a disposizione. Le proprietà disponibili sono quelle che appaiono nella finestra di visualizzazione delle proprietà per consentire all'utente di modificarle. Con questa procedura, gli oggetti FeaturePython sono realmente e totalmente parametrici. E' possibile definire separatamente le proprietà per l'oggetto e per la sua ViewObject (rappresentazione).

Nota. In versioni precedenti abbiamo usato il modulo cPickle di Python. Questo modulo, però, esegue un codice arbitrario e provoca quindi un problema di sicurezza. Per questo motivo ora utilizziamo il modulo json di Python.

Esempio base

L'esempio seguente si trova nella directory src/Mod/TemplatePyMod/FeaturePython.py, che contiene anche molti altri esempi:

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

Propietà disponibili

Le proprietà sono i veri e propri mattoni per la costruzione degli oggetti FeaturePython. Attraverso di esse, l'utente è in grado di interagire e modificare l'oggetto. Dopo aver creato un nuovo oggetto FeaturePython nel documento ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), è possibile ottenere un elenco delle proprietà disponibili digitando:

 obj.supportedProperties()

Si ottiene l'elenco delle proprietà disponibili:

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

Quando si aggiungono delle proprietà agli oggetti personalizzati, stare attenti a questo:

  • Non utilizzare i caratteri "<" o ">" nelle descrizioni delle proprietà (questo spezza le parti xml nel file .fcstd)
  • Le proprietà sono memorizzate in ordine alfabetico nel file .fcstd. Se si dispone di una forma (Shape) nelle proprietà, qualsiasi proprietà il cui nome, in ordine alfabetico, viene dopo "Shape", verrà caricato DOPO la forma (Shape), e questo può causare strani comportamenti.

Tipi di Proprietà

Di default, le proprietà possono essere aggiornate. È possibile creare delle proprietà di sola lettura, per esempio nel caso si vuole mostrare il risultato di un metodo. È anche possibile nascondere una proprietà. Il tipo di proprietà può essere impostata usando

  obj.setEditorMode("MyPropertyName", mode)

dove mode è un indice che può essere impostato:

 0 -- default mode, lettura e scrittura
 1 -- solo lettura
 2 -- nascosto

Altro esempio più complesso

In questo esempio si utilizza il Modulo Parte per creare un ottaedro, quindi si crea la sua rappresentazione Coin con Pivy.

Prima si crea l'oggetto del documento:

 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

In seguito si crea il fornitore della vista dell'oggetto (view provider object), responsabile di mostrare l'oggetto nella scena 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

Infine, dopo che l'oggetto e il suo visualizzatore sono definiti, basta solo chiamarli:

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

Rendere gli oggetti selezionabili

Se volete rendere il vostro oggetto selezionabile, o almeno una parte di esso, facendo clic su di esso nella finestra, è necessario includere la sua geometria Coin all'interno di un nodo SoFCSelection. Se l'oggetto ha una rappresentazione complessa, con widget, annotazioni, etc, si potrebbe voler includere solo una parte di esso in un SoFCSelection. Tutto quello che compone un SoFCSelection viene costantemente analizzato da FreeCAD per rilevare selezioni/preselezioni, quindi non ha senso sovraccaricarlo con delle scansioni non necessarie. Ecco ciò che si dovrebbe fare per includere un self.face nell'esempio precedente:

 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)

Praticamente, si crea un nodo SoFCSelection, quindi si aggiungono ad esso i nodi della geometria, e poi lo si aggiunge al nodo principale, invece di aggiungere direttamente i nodi geometria.

Lavorare con le forme semplici

Se l'oggetto parametrico produce semplicemente una forma, non è necessario utilizzare un fornitore di vista dell'oggetto (view provider object). La forma viene visualizzata utilizzando la rappresentazione della forma standard di 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()