==Python API==
[blender.git] / source / blender / python / api2_2x / doc / Armature.py
1 # Blender.Armature module and the Armature PyType object
2
3 """
4 The Blender.Armature submodule.
5
6 Armature
7 ========
8
9 This module provides access to B{Armature} objects in Blender.  These are
10 "skeletons", used to deform and animate other objects -- meshes, for
11 example.
12
13 Example::
14   import Blender
15   from Blender import Armature
16   from Blender.Mathutils import *
17   #
18   arms = Armature.Get()
19   for arm in arms.values():
20     arm.drawType = Armature.STICK #set the draw type
21     arm.makeEditable() #enter editmode
22
23     #generating new editbone
24     eb = Armature.Editbone()
25     eb.roll = 10
26     eb.parent = arm.bones['Bone.003']
27     eb.head = Vector(1,1,1)
28     eb.tail = Vector(0,0,1)
29     eb.options = [Armature.HINGE, Armature.CONNECTED]
30
31     #add the bone
32     arm.bones['myNewBone'] = eb
33   
34     #delete an old bone
35     del arm.bones['Bone.002']
36
37     arm.update()  #save changes
38
39     for bone in arm.bones.values():
40       #print bone.matrix['ARMATURESPACE']
41       print bone.parent, bone.name
42       print bone.children, bone.name
43       print bone.options, bone.name
44
45
46 Example::
47         # Adds empties for every bone in the selected armature, an example of getting worldspace locations for bones.
48         from Blender import *
49         def test_arm():
50                 scn= Scene.GetCurrent()
51                 arm_ob= scn.objects.active
52
53                 if not arm_ob or arm_ob.type != 'Armature':
54                         Draw.PupMenu('not an armature object')
55                         return
56
57                 # Deselect all
58                 for ob in scn.objects:
59                         if ob != arm_ob:
60                                 ob.sel= 0
61
62                 arm_mat= arm_ob.matrixWorld
63
64                 arm_data= arm_ob.getData()
65
66                 bones= arm_data.bones.values()
67                 for bone in bones:
68                         bone_mat= bone.matrix['ARMATURESPACE']
69                         bone_mat_world= bone_mat*arm_mat
70
71                         ob_empty= scn.objects.new('Empty')
72                         ob_empty.setMatrix(bone_mat_world)
73
74         test_arm()
75
76 @var CONNECTED: Connect this bone to parent
77 @type CONNECTED: Constant
78 @var HINGE: Don't inherit rotation or scale from parent
79 @type HINGE: Constant
80 @var NO_DEFORM: If bone will not deform geometry
81 @type NO_DEFORM: Constant
82 @var MULTIPLY: Multiply bone with vertex group
83 @type MULTIPLY: Constant
84 @var HIDDEN_EDIT: Bone is hidden in editmode
85 @type HIDDEN_EDIT: Constant
86 @var ROOT_SELECTED: Root of the Bone is selected
87 @type ROOT_SELECTED: Constant
88 @var BONE_SELECTED: Bone is selected
89 @type BONE_SELECTED: Constant
90 @var TIP_SELECTED: Tip of the Bone is selected
91 @type TIP_SELECTED: Constant
92 @var OCTAHEDRON: Bones drawn as octahedrons
93 @type OCTAHEDRON: Constant
94 @var STICK: Bones drawn as a line
95 @type STICK: Constant
96 @var BBONE: Bones draw as a segmented B-spline
97 @type BBONE: Constant
98 @var ENVELOPE: Bones draw as a stick with envelope influence
99 @type ENVELOPE: Constant
100 """
101
102 def Get (name = None):
103   """
104   Get the Armature object(s) from Blender.
105   @type name: string, nothing, or list of strings
106   @param name: The string name of an armature.
107   @rtype: Blender Armature or a list of Blender Armatures
108   @return: It depends on the I{name} parameter:
109       - (name): The Armature object with the given I{name};
110       - (name, name, ...): A list of Armature objects
111       - ():     A list with all Armature objects in the current scene.
112   @warning: In versions 2.42 and earlier, a string argument for an armature
113     that doesn't exist will return None.  Later versions raise a Value error.
114   """
115
116 def New (name = None):
117         """
118         Return a new armature.
119         @type name: string or nothing
120         @param name: The string name of the new armature.
121         @rtype: Blender Armature.
122         @return: A new armature.
123         """
124
125 class Armature:
126         """
127         The Armature object
128         ===================
129                 This object gives access to Armature-specific data in Blender.
130         @ivar bones: A Dictionary of Bones (BonesDict) that make up this armature.
131         @type bones: BonesDict Object
132         @ivar vertexGroups: Whether vertex groups define deformation
133         @type vertexGroups: Bool
134         @ivar envelopes: Whether bone envelopes define deformation
135         @type envelopes: Bool
136         @ivar restPosition: Show rest position (no posing possible)
137         @type restPosition: Bool
138         @ivar delayDeform: Don't deform children when manipulating bones
139         @type delayDeform: Bool
140         @ivar drawAxes: Draw bone axes
141         @type drawAxes: Bool
142         @ivar drawNames: Draw bone names
143         @type drawNames: Bool
144         @ivar ghost: Draw ghosts around frame for current Action
145         @type ghost: Bool
146         @ivar ghostStep: Number of frames between ghosts
147         @type ghostStep: Int
148         @ivar drawType: The drawing type that is used to display the armature
149         Acceptable values are:
150                         - Armature.OCTAHEDRON: bones drawn as octahedrons
151                         - Armature.STICK: bones drawn as sticks
152                         - Armature.BBONE: bones drawn as b-bones
153                         - Armature.ENVELOPE: bones drawn as sticks with envelopes
154         @type drawType: Constant Object
155         @ivar mirrorEdit: X-axis mirrored editing
156         @type mirrorEdit: Bool
157         @ivar autoIK: Adds temporary IK chains while grabbing bones
158         @type autoIK: Bool
159         @ivar layerMask: Layer bitmask
160                 Example::
161                         # set armature to layers 14 and 16
162                         armature.layerMask = (1<<13) + (1<<15)
163         @type layerMask: Int
164         """
165
166         def __init__(name = 'myArmature'):
167                 """
168                 Initializer for the Armature TypeObject.
169                 Example::
170                           myNewArmature = Blender.Armature.Armature('AR_1')
171                 @param name: The name for the new armature
172                 @type name: string
173                 @return: New Armature Object
174                 @rtype: Armature Object
175                 """
176         
177         def makeEditable():
178                 """
179                 Put the armature into EditMode for editing purposes. (Enters Editmode)
180                 @warning: Using Window.Editmode() to switch the editmode manually will cause problems and possibly even crash Blender.
181                 @warning: This is only needed for operations such as adding and removing bones.
182                 @warning: Do access pose data until you have called update() or settings will be lost. 
183                 @warning: The armature should not be in manual editmode
184                 prior to calling this method. The armature must be parented
185                 to an object prior to editing.
186                 @rtype: None
187                 """
188
189         def update():
190                 """
191                 Save all changes and update the armature. (Leaves Editmode)
192                 @note: Must have called makeEditable() first.
193                 @rtype: None
194                 """
195
196 import id_generics
197 Armature.__doc__ += id_generics.attributes 
198
199 class BonesDict:
200         """
201         The BonesDict object
202         ====================
203                 This object gives gives dictionary like access to the bones in an armature. 
204                 It is internal to blender but is called as 'Armature.bones'
205
206                 Removing a bone: 
207                 Example::
208                         del myArmature.bones['bone_name']
209                 Adding a bone:
210                 Example::
211                         myEditBone = Armature.Editbone()
212                         myArmature.bones['bone_name'] = myEditBone
213         """
214
215         def items():
216                 """
217                 Return the key, value pairs in this dictionary
218                 @rtype: string, BPy_bone
219                 @return: All strings, and py_bones in the armature (in that order)
220                 """
221
222         def keys():
223                 """
224                 Return the keys in this dictionary
225                 @rtype: string
226                 @return: All strings representing the bone names
227                 """
228
229         def values():
230                 """
231                 Return the values in this dictionary
232                 @rtype: BPy_bone
233                 @return: All BPy_bones in this dictionary
234                 """
235
236 class Bone:
237         """
238         The Bone object
239         ===============
240                 This object gives access to Bone-specific data in Blender. This object
241                 cannot be instantiated but is returned by BonesDict when the armature is not in editmode.
242         @ivar name: The name of this Bone.
243         @type name: String
244         @ivar roll: This Bone's roll value.
245                 Keys are:
246                          - 'ARMATURESPACE' - this roll in relation to the armature
247                          - 'BONESPACE' - the roll in relation to itself 
248         @type roll: Dictionary
249         @ivar head: This Bone's "head" ending position when in rest state.
250                 Keys are:
251                          - 'ARMATURESPACE' - this head position in relation to the armature
252                          - 'BONESPACE' - the head position in relation to itself.
253         @type head: Dictionary
254         @ivar tail: This Bone's "tail" ending position when in rest state.
255                 Keys are:
256                          - 'ARMATURESPACE' - this tail position in relation to the armature
257                          - 'BONESPACE' - the tail position in relation to itself 
258         @type tail: Dictionary
259         @ivar matrix: This Bone's matrix. This cannot be set.
260                 Keys are:
261                          - 'ARMATURESPACE' - this matrix of the bone in relation to the armature
262                          - 'BONESPACE' - the matrix of the bone in relation to itself 
263         @type matrix: Matrix Object
264         @ivar parent: The parent Bone.
265         @type parent: Bone Object
266         @ivar children: The children directly attached to this bone.
267         @type children: List of Bone Objects
268         @ivar weight: The bone's weight.
269         @type weight: Float
270         @ivar options: Various bone options which can be:
271                          - Armature.CONNECTED: IK to parent
272                          - Armature.HINGE: No parent rotation or scaling
273                          - Armature.NO_DEFORM: The bone does not deform geometry
274                          - Armature.MULTIPLY: Multiply vgroups by envelope
275                          - Armature.HIDDEN_EDIT: Hide bones in editmode
276                          - Armature.ROOT_SELECTED: Selection of root ball of bone
277                          - Armature.BONE_SELECTED: Selection of bone
278                          - Armature.TIP_SELECTED: Selection of tip ball of bone
279         @type options: List of Constants
280         @ivar subdivision: The number of bone subdivisions.
281         @type subdivision: Int
282         @ivar deformDist: The deform distance of the bone
283         @type deformDist: Float
284         @ivar length: The length of the bone. This cannot be set.
285         @type length: Float
286         @ivar headRadius: The radius of this bones head (used for envalope bones)
287         @type headRadius: Float
288         @ivar tailRadius: The radius of this bones head (used for envalope bones)
289         @type tailRadius: Float
290         @ivar layerMask: Layer bitmask
291                 Example::
292                         # set bone to layers 14 and 16
293                         bone.layerMask = (1<<13) + (1<<15)
294         @type layerMask: Int
295         """
296
297         def hasParent():
298                 """
299                 Whether or not this bone has a parent
300                 @rtype: Bool
301                 """
302
303         def hasChildren():
304                 """
305                 Whether or not this bone has children
306                 @rtype: Bool
307                 """
308
309         def getAllChildren():
310                 """
311                 Gets all the children under this bone including the children's children.
312                 @rtype: List of Bone object
313                 @return: all bones under this one
314                 """
315
316 class Editbone:
317         """
318         The Editbone Object
319         ===================
320                 This object is a wrapper for editbone data and is used only in the manipulation
321                 of the armature in editmode.
322         @ivar name: The name of this Bone.
323         @type name: String
324         @ivar roll: This Bone's roll value (armaturespace).
325         @type roll: Float
326         @ivar head: This Bone's "head" ending position when in rest state (armaturespace).
327         @type head: Vector Object
328         @ivar tail: This Bone's "tail" ending position when in rest state (armaturespace).
329         @type tail: Vector Object
330         @ivar matrix: This Bone's matrix. (armaturespace)
331         @type matrix: Matrix Object
332         @ivar parent: The parent Bone.
333         @type parent: Editbone Object
334         @ivar weight: The bone's weight.
335         @type weight: Float
336         @ivar options: Various bone options which can be:
337                          - Armature.CONNECTED: IK to parent
338                          - Armature.HINGE: No parent rotation or scaling
339                          - Armature.NO_DEFORM: The bone does not deform geometry
340                          - Armature.MULTIPLY: Multiply vgroups by envelope
341                          - Armature.HIDDEN_EDIT: Hide bones in editmode
342                          - Armature.ROOT_SELECTED: Selection of root ball of bone
343                          - Armature.BONE_SELECTED: Selection of bone
344                          - Armature.TIP_SELECTED: Selection of tip ball of bone
345         @type options: List of Constants
346         @ivar subdivision: The number of bone subdivisions.
347         @type subdivision: Int
348         @ivar deformDist: The deform distance of the bone
349         @type deformDist: Float
350         @ivar length: The length of the bone. This cannot be set.
351         @type length: Float
352         @ivar headRadius: The radius of this bones head (used for envalope bones)
353         @type headRadius: Float
354         @ivar tailRadius: The radius of this bones head (used for envalope bones)
355         @type tailRadius: Float
356         """
357
358         def hasParent():
359                 """
360                 Whether or not this bone has a parent
361                 @rtype: Bool
362                 """
363
364         def clearParent():
365                 """
366                 Set the parent to None
367                 @rtype: None
368                 """