157e8b28656b6c5eb90b3c8ed79ee3292d55203c
[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         """
160
161         def __init__(name = 'myArmature'):
162                 """
163                 Initializer for the Armature TypeObject.
164                 Example::
165                           myNewArmature = Blender.Armature.Armature('AR_1')
166                 @param name: The name for the new armature
167                 @type name: string
168                 @return: New Armature Object
169                 @rtype: Armature Object
170                 """
171         
172         def makeEditable():
173                 """
174                 Put the armature into EditMode for editing purposes. (Enters Editmode)
175                 @warning: Using Window.Editmode() to switch the editmode manually will cause problems and possibly even crash Blender.
176                 @warning: This is only needed for operations such as adding and removing bones.
177                 @warning: Do access pose data until you have called update() or settings will be lost. 
178                 @warning: The armature should not be in manual editmode
179                 prior to calling this method. The armature must be parented
180                 to an object prior to editing.
181                 @rtype: None
182                 """
183
184         def update():
185                 """
186                 Save all changes and update the armature. (Leaves Editmode)
187                 @note: Must have called makeEditable() first.
188                 @rtype: None
189                 """
190
191 import id_generics
192 Armature.__doc__ += id_generics.attributes 
193
194 class BonesDict:
195         """
196         The BonesDict object
197         ====================
198                 This object gives gives dictionary like access to the bones in an armature. 
199                 It is internal to blender but is called as 'Armature.bones'
200
201                 Removing a bone: 
202                 Example::
203                         del myArmature.bones['bone_name']
204                 Adding a bone:
205                 Example::
206                         myEditBone = Armature.Editbone()
207                         myArmature.bones['bone_name'] = myEditBone
208         """
209
210         def items():
211                 """
212                 Return the key, value pairs in this dictionary
213                 @rtype: string, BPy_bone
214                 @return: All strings, and py_bones in the armature (in that order)
215                 """
216
217         def keys():
218                 """
219                 Return the keys in this dictionary
220                 @rtype: string
221                 @return: All strings representing the bone names
222                 """
223
224         def values():
225                 """
226                 Return the values in this dictionary
227                 @rtype: BPy_bone
228                 @return: All BPy_bones in this dictionary
229                 """
230
231 class Bone:
232         """
233         The Bone object
234         ===============
235                 This object gives access to Bone-specific data in Blender. This object
236                 cannot be instantiated but is returned by BonesDict when the armature is not in editmode.
237         @ivar name: The name of this Bone.
238         @type name: String
239         @ivar roll: This Bone's roll value.
240                 Keys are:
241                          - 'ARMATURESPACE' - this roll in relation to the armature
242                          - 'BONESPACE' - the roll in relation to itself 
243         @type roll: Dictionary
244         @ivar head: This Bone's "head" ending position when in rest state.
245                 Keys are:
246                          - 'ARMATURESPACE' - this head position in relation to the armature
247                          - 'BONESPACE' - the head position in relation to itself.
248         @type head: Dictionary
249         @ivar tail: This Bone's "tail" ending position when in rest state.
250                 Keys are:
251                          - 'ARMATURESPACE' - this tail position in relation to the armature
252                          - 'BONESPACE' - the tail position in relation to itself 
253         @type tail: Dictionary
254         @ivar matrix: This Bone's matrix. This cannot be set.
255                 Keys are:
256                          - 'ARMATURESPACE' - this matrix of the bone in relation to the armature
257                          - 'BONESPACE' - the matrix of the bone in relation to itself 
258         @type matrix: Matrix Object
259         @ivar parent: The parent Bone.
260         @type parent: Bone Object
261         @ivar children: The children directly attached to this bone.
262         @type children: List of Bone Objects
263         @ivar weight: The bone's weight.
264         @type weight: Float
265         @ivar options: Various bone options which can be:
266                          - Armature.CONNECTED: IK to parent
267                          - Armature.HINGE: No parent rotation or scaling
268                          - Armature.NO_DEFORM: The bone does not deform geometry
269                          - Armature.MULTIPLY: Multiply vgroups by envelope
270                          - Armature.HIDDEN_EDIT: Hide bones in editmode
271                          - Armature.ROOT_SELECTED: Selection of root ball of bone
272                          - Armature.BONE_SELECTED: Selection of bone
273                          - Armature.TIP_SELECTED: Selection of tip ball of bone
274         @type options: List of Constants
275         @ivar subdivision: The number of bone subdivisions.
276         @type subdivision: Int
277         @ivar deformDist: The deform distance of the bone
278         @type deformDist: Float
279         @ivar length: The length of the bone. This cannot be set.
280         @type length: Float
281         @ivar headRadius: The radius of this bones head (used for envalope bones)
282         @type headRadius: Float
283         @ivar tailRadius: The radius of this bones head (used for envalope bones)
284         @type tailRadius: Float
285         """
286
287         def hasParent():
288                 """
289                 Whether or not this bone has a parent
290                 @rtype: Bool
291                 """
292
293         def hasChildren():
294                 """
295                 Whether or not this bone has children
296                 @rtype: Bool
297                 """
298
299         def getAllChildren():
300                 """
301                 Gets all the children under this bone including the children's children.
302                 @rtype: List of Bone object
303                 @return: all bones under this one
304                 """
305
306 class Editbone:
307         """
308         The Editbone Object
309         ===================
310                 This object is a wrapper for editbone data and is used only in the manipulation
311                 of the armature in editmode.
312         @ivar name: The name of this Bone.
313         @type name: String
314         @ivar roll: This Bone's roll value (armaturespace).
315         @type roll: Float
316         @ivar head: This Bone's "head" ending position when in rest state (armaturespace).
317         @type head: Vector Object
318         @ivar tail: This Bone's "tail" ending position when in rest state (armaturespace).
319         @type tail: Vector Object
320         @ivar matrix: This Bone's matrix. (armaturespace)
321         @type matrix: Matrix Object
322         @ivar parent: The parent Bone.
323         @type parent: Editbone Object
324         @ivar weight: The bone's weight.
325         @type weight: Float
326         @ivar options: Various bone options which can be:
327                          - Armature.CONNECTED: IK to parent
328                          - Armature.HINGE: No parent rotation or scaling
329                          - Armature.NO_DEFORM: The bone does not deform geometry
330                          - Armature.MULTIPLY: Multiply vgroups by envelope
331                          - Armature.HIDDEN_EDIT: Hide bones in editmode
332                          - Armature.ROOT_SELECTED: Selection of root ball of bone
333                          - Armature.BONE_SELECTED: Selection of bone
334                          - Armature.TIP_SELECTED: Selection of tip ball of bone
335         @type options: List of Constants
336         @ivar subdivision: The number of bone subdivisions.
337         @type subdivision: Int
338         @ivar deformDist: The deform distance of the bone
339         @type deformDist: Float
340         @ivar length: The length of the bone. This cannot be set.
341         @type length: Float
342         @ivar headRadius: The radius of this bones head (used for envalope bones)
343         @type headRadius: Float
344         @ivar tailRadius: The radius of this bones head (used for envalope bones)
345         @type tailRadius: Float
346         """
347
348         def hasParent():
349                 """
350                 Whether or not this bone has a parent
351                 @rtype: Bool
352                 """
353
354         def clearParent():
355                 """
356                 Set the parent to None
357                 @rtype: None
358                 """