Filling in branch from trunk

source/blender/python/api2_2x/doc/Metaball.py

@@ -0,0 +1,246 @@
+# Blender.Metaball module and the Metaball PyType metaball
+
+"""
+The Blender.Metaball submodule
+
+This module provides access to B{Metaball} data in Blender and the elements they contain.
+
+
+Example::
+ import Blender
+ mb = Blender.Metaball.New()
+ for i in xrange(20):
+   element= mb.elements.add()
+   element.co = Blender.Mathutils.Vector(i, 0, 0) 
+ sce = Blender.Scene.GetCurrent()
+ sce.objects.new(mb)
+
+
+
+Example::
+    # Converts the active armature into metaballs
+    from Blender import *
+    def main():
+
+            scn= Scene.GetCurrent()
+            ob_arm= scn.objects.active
+            if not ob_arm or ob_arm.type!='Armature':
+                    Draw.PupMenu('No Armature Selected')
+                    return
+            arm= ob_arm.data
+
+            res= Draw.PupFloatInput('res:', 0.2, 0.05, 2.0)
+            if not res:
+                    return
+
+            # Make a metaball
+            mb= Metaball.New()
+            mb.wiresize= res
+
+            # Link to the Scene
+            ob_mb = scn.objects.new(ob_mb)
+            ob_arm.sel= 0
+            ob_mb.setMatrix(ob_arm.matrixWorld)
+
+
+            meta_type= 0 # all elemts are ball type
+            meta_stiffness= 2.0 # Volume
+
+            for bone in arm.bones.values():
+                    print bone
+
+                    # Find out how many metaballs to add based on bone length, 4 min
+                    length= bone.length
+                    if length < res:
+                            mballs= 4
+                    else:
+                            mballs= int(length/res)
+                            if mballs < 4:
+                                    mballs = 4
+
+                    print 'metaball count', mballs
+
+                    # get the bone properties
+                    head_rad= bone.headRadius
+                    tail_rad= bone.tailRadius
+
+                    head_loc= bone.head['ARMATURESPACE']
+                    tail_loc= bone.tail['ARMATURESPACE']
+
+
+                    for i in range(mballs):
+                            f= float(i)
+
+                            w1= f/mballs # weighting of this position on the bone for rad and loc
+                            w2= 1-w1
+
+                            loc= head_loc*w1 + tail_loc*w2
+                            rad= (head_rad*w1 + tail_rad*w2) * 1.3
+
+                            # Add the metaball
+                            ml= mb.elements.add()
+                            ml.co= loc
+                            ml.radius= rad
+                            ml.stiffness= meta_stiffness
+
+
+            Window.RedrawAll()
+
+    main()
+
+@type Types: readonly dictionary
+@var Types: MeteElement types.
+    - BALL
+    - TUBE
+    - PLANE
+    - ELIPSOID
+    - CUBE
+
+@type Update: readonly dictionary
+@var Update: MeteElement types.
+    - ALWAYS
+    - HALFRES
+    - FAST
+    - NEVER
+
+"""
+
+
+def New (name):
+	"""
+	Creates a new Metaball.
+	@type name: string
+	@param name: The name of the metaball. If this parameter is not given (or not valid) blender will assign a name to the metaball.
+	@rtype: Blender Metaball
+	@return: The created Metaball.
+	"""
+
+def Get (name):
+	"""
+	Get the Metaball from Blender.
+	@type name: string
+	@param name: The name of the requested Metaball.
+	@rtype: Blender Metaball or a list of Blender Metaballs
+	@return: It depends on the 'name' parameter:
+			- (name): The Metaball with the given name;
+			- ():     A list with all Metaballs in the current scene.
+	"""
+
+class Metaball:
+	"""
+	The Metaball object
+	===================
+	This metaball gives access to generic data from all metaballs in Blender.
+	@ivar elements: Element iterator of MetaElemSeq type.
+	@type elements: MetaElemSeq
+	@ivar wiresize: display resolution.
+		Value clamped between 0.05 and 1.0.
+
+		A lower value results in more polygons.
+	@type wiresize: float
+	@ivar rendersize: render resolution.
+		Value clamped between 0.05 and 1.0.
+
+		A lower value results in more polygons.
+	@type rendersize: float
+	@ivar thresh: Threshold setting for this metaball.
+		Value clamped between 0.0 and 5.0.
+	@type thresh: float
+	@ivar materials: List of up to 16 Materials or None types
+		Only the first material of the mother-ball used at the moment.
+	@type materials: list
+	@ivar update: The update method to use for this metaball.
+	@type update: int
+	"""
+	
+	def __copy__():
+		"""
+		Return a copy of this metaball object data.
+		@rtype: Metaball
+		@return: Metaball
+		"""
+
+import id_generics
+Metaball.__doc__ += id_generics.attributes 
+
+
+class MetaElemSeq:
+	"""
+	The MetaElemSeq object
+	======================
+		This object provides sequence and iterator access to the metaballs elements.
+		The elements accessed within this iterator "wraps" the actual metaball elements; changing any
+		of the elements's attributes will immediately change the data in the metaball.
+
+		This iterator is most like pythons 'set' type.
+	"""
+
+	def add():
+		"""
+		Append a new element to the metaball.
+		no arguments are taken, instead a new metaelement is
+		added to the metaball data and returned.
+		This new element can then be modified.
+
+		@return: a new meta element.
+		@rtype: Metaelement
+		"""
+
+	def remove(element):
+		"""
+		remove an element from the metaball data.
+		
+		if the element is not a part of the metaball data, an error will be raised.
+
+		@return: None
+		@rtype: None
+		"""
+
+	def __iter__():
+		"""
+		Iterate over elements in this metaball.
+
+		@return: One of the metaelem in this metaball.
+		@rtype: Metaelem
+		"""
+
+	def __len__():
+		"""
+		Iterate over elements in this metaball.
+
+		@return: The number of elements in this metaball
+		@rtype: int
+		"""
+
+class Metaelem:
+	"""
+	The Metaelem object
+	===================
+	This gives direct access to meta element data within a metaball.
+	@ivar type: The type of the metaball.
+		Values must be from L{Types}
+
+		Example::
+			from Blender import Metaball
+			mb= Metaball.Get('mb')
+			for el in mb.elements:
+			  el.type= Metaball.Types.CUBE
+	@type type: int
+	@ivar co: The location of this element.
+	@type co: Vector
+	@ivar dims: Element dimensions.
+		Values clamped between 0 and 20 on all axies.
+	@type dims: Vector
+	@ivar quat: Element rotation.
+	@type quat: Quaternion
+	@ivar stiffness: Element stiffness.
+		Value clamped between 0 and 10.
+	@type stiffness: float
+	@ivar radius: Element radius.
+		Value clamped between 0 and 5000.
+	@type radius: float
+	@ivar negative: Element negative volume status.
+	@type negative: bool
+	@ivar hide: Element hidden status.
+	@type hide: bool
+	"""