1
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
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
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
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
190 """
191 Save all changes and update the armature. (Leaves Editmode)
192 @note: Must have called makeEditable() first.
193 @rtype: None
194 """
196 """
197 Return a copy of this armature.
198 @rtype: Armature
199 """
201 """
202 Return a copy of this armature.
203 @rtype: Armature
204 """
205
206 import id_generics
207 Armature.__doc__ += id_generics.attributes
208
210 """
211 The BonesDict object
212 ====================
213 This object gives gives dictionary like access to the bones in an armature.
214 It is internal to blender but is called as 'Armature.bones'
215
216 Removing a bone:
217 Example::
218 del myArmature.bones['bone_name']
219 Adding a bone:
220 Example::
221 myEditBone = Armature.Editbone()
222 myArmature.bones['bone_name'] = myEditBone
223 """
224
226 """
227 Return the key, value pairs in this dictionary
228 @rtype: string, BPy_bone
229 @return: All strings, and py_bones in the armature (in that order)
230 """
231
233 """
234 Return the keys in this dictionary
235 @rtype: string
236 @return: All strings representing the bone names
237 """
238
240 """
241 Return the values in this dictionary
242 @rtype: BPy_bone
243 @return: All BPy_bones in this dictionary
244 """
245
247 """
248 The Bone object
249 ===============
250 This object gives access to Bone-specific data in Blender. This object
251 cannot be instantiated but is returned by BonesDict when the armature is not in editmode.
252 @ivar name: The name of this Bone.
253 @type name: String
254 @ivar roll: This Bone's roll value.
255 Keys are:
256 - 'ARMATURESPACE' - this roll in relation to the armature
257 - 'BONESPACE' - the roll in relation to itself
258 @type roll: Dictionary
259 @ivar head: This Bone's "head" ending position when in rest state.
260 Keys are:
261 - 'ARMATURESPACE' - this head position in relation to the armature
262 - 'BONESPACE' - the head position in relation to itself.
263 @type head: Dictionary
264 @ivar tail: This Bone's "tail" ending position when in rest state.
265 Keys are:
266 - 'ARMATURESPACE' - this tail position in relation to the armature
267 - 'BONESPACE' - the tail position in relation to itself
268 @type tail: Dictionary
269 @ivar matrix: This Bone's matrix. This cannot be set.
270 Keys are:
271 - 'ARMATURESPACE' - this matrix of the bone in relation to the armature
272 - 'BONESPACE' - the matrix of the bone in relation to itself
273 @type matrix: Matrix Object
274 @ivar parent: The parent Bone.
275 @type parent: Bone Object
276 @ivar children: The children directly attached to this bone.
277 @type children: List of Bone Objects
278 @ivar weight: The bone's weight.
279 @type weight: Float
280 @ivar options: Various bone options which can be:
281 - Armature.CONNECTED: IK to parent
282 - Armature.HINGE: No parent rotation or scaling
283 - Armature.NO_DEFORM: The bone does not deform geometry
284 - Armature.MULTIPLY: Multiply vgroups by envelope
285 - Armature.HIDDEN_EDIT: Hide bones in editmode
286 - Armature.ROOT_SELECTED: Selection of root ball of bone
287 - Armature.BONE_SELECTED: Selection of bone
288 - Armature.TIP_SELECTED: Selection of tip ball of bone
289 @type options: List of Constants
290 @ivar subdivision: The number of bone subdivisions.
291 @type subdivision: Int
292 @ivar deformDist: The deform distance of the bone
293 @type deformDist: Float
294 @ivar length: The length of the bone. This cannot be set.
295 @type length: Float
296 @ivar headRadius: The radius of this bones head (used for envalope bones)
297 @type headRadius: Float
298 @ivar tailRadius: The radius of this bones head (used for envalope bones)
299 @type tailRadius: Float
300 @ivar layerMask: Layer bitmask
301 Example::
302 # set bone to layers 14 and 16
303 bone.layerMask = (1<<13) + (1<<15)
304 @type layerMask: Int
305 """
306
308 """
309 Whether or not this bone has a parent
310 @rtype: Bool
311 """
312
314 """
315 Whether or not this bone has children
316 @rtype: Bool
317 """
318
320 """
321 Gets all the children under this bone including the children's children.
322 @rtype: List of Bone object
323 @return: all bones under this one
324 """
325
327 """
328 The Editbone Object
329 ===================
330 This object is a wrapper for editbone data and is used only in the manipulation
331 of the armature in editmode.
332 @ivar name: The name of this Bone.
333 @type name: String
334 @ivar roll: This Bone's roll value (armaturespace).
335 @type roll: Float
336 @ivar head: This Bone's "head" ending position when in rest state (armaturespace).
337 @type head: Vector Object
338 @ivar tail: This Bone's "tail" ending position when in rest state (armaturespace).
339 @type tail: Vector Object
340 @ivar matrix: This Bone's matrix. (armaturespace)
341 @type matrix: Matrix Object
342 @ivar parent: The parent Bone.
343 @type parent: Editbone Object
344 @ivar weight: The bone's weight.
345 @type weight: Float
346 @ivar options: Various bone options which can be:
347 - Armature.CONNECTED: IK to parent
348 - Armature.HINGE: No parent rotation or scaling
349 - Armature.NO_DEFORM: The bone does not deform geometry
350 - Armature.MULTIPLY: Multiply vgroups by envelope
351 - Armature.HIDDEN_EDIT: Hide bones in editmode
352 - Armature.ROOT_SELECTED: Selection of root ball of bone
353 - Armature.BONE_SELECTED: Selection of bone
354 - Armature.TIP_SELECTED: Selection of tip ball of bone
355 @type options: List of Constants
356 @ivar subdivision: The number of bone subdivisions.
357 @type subdivision: Int
358 @ivar deformDist: The deform distance of the bone
359 @type deformDist: Float
360 @ivar length: The length of the bone. This cannot be set.
361 @type length: Float
362 @ivar headRadius: The radius of this bones head (used for envalope bones)
363 @type headRadius: Float
364 @ivar tailRadius: The radius of this bones head (used for envalope bones)
365 @type tailRadius: Float
366 """
367
369 """
370 Whether or not this bone has a parent
371 @rtype: Bool
372 """
373
375 """
376 Set the parent to None
377 @rtype: None
378 """
379