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 LOCKED_EDIT: Prevents the bone from being transformed in editmode
93 @type LOCKED_EDIT: Constant
94 @var OCTAHEDRON: Bones drawn as octahedrons
95 @type OCTAHEDRON: Constant
96 @var STICK: Bones drawn as a line
97 @type STICK: Constant
98 @var BBONE: Bones draw as a segmented B-spline
99 @type BBONE: Constant
100 @var ENVELOPE: Bones draw as a stick with envelope influence
101 @type ENVELOPE: Constant
102 """
103
104 -def Get (name = None):
105 """
106 Get the Armature object(s) from Blender.
107 @type name: string, nothing, or list of strings
108 @param name: The string name of an armature.
109 @rtype: Blender Armature or a list of Blender Armatures
110 @return: It depends on the I{name} parameter:
111 - (name): The Armature object with the given I{name};
112 - (name, name, ...): A list of Armature objects
113 - (): A list with all Armature objects in the current scene.
114 @warning: In versions 2.42 and earlier, a string argument for an armature
115 that doesn't exist will return None. Later versions raise a Value error.
116 """
117
118 -def New (name = None):
119 """
120 Return a new armature.
121 @type name: string or nothing
122 @param name: The string name of the new armature.
123 @rtype: Blender Armature.
124 @return: A new armature.
125 """
126
128 """
129 The Armature object
130 ===================
131 This object gives access to Armature-specific data in Blender.
132 @ivar bones: A Dictionary of Bones (BonesDict) that make up this armature.
133 @type bones: BonesDict Object
134 @ivar vertexGroups: Whether vertex groups define deformation
135 @type vertexGroups: Bool
136 @ivar envelopes: Whether bone envelopes define deformation
137 @type envelopes: Bool
138 @ivar restPosition: Show rest position (no posing possible)
139 @type restPosition: Bool
140 @ivar delayDeform: Don't deform children when manipulating bones
141 @type delayDeform: Bool
142 @ivar drawAxes: Draw bone axes
143 @type drawAxes: Bool
144 @ivar drawNames: Draw bone names
145 @type drawNames: Bool
146 @ivar ghost: Draw ghosts around frame for current Action
147 @type ghost: Bool
148 @ivar ghostStep: Number of frames between ghosts
149 @type ghostStep: Int
150 @ivar drawType: The drawing type that is used to display the armature
151 Acceptable values are:
152 - Armature.OCTAHEDRON: bones drawn as octahedrons
153 - Armature.STICK: bones drawn as sticks
154 - Armature.BBONE: bones drawn as b-bones
155 - Armature.ENVELOPE: bones drawn as sticks with envelopes
156 @type drawType: Constant Object
157 @ivar mirrorEdit: X-axis mirrored editing
158 @type mirrorEdit: Bool
159 @ivar autoIK: Adds temporary IK chains while grabbing bones
160 @type autoIK: Bool
161 @ivar layerMask: Layer bitmask
162 Example::
163 # set armature to layers 14 and 16
164 armature.layerMask = (1<<13) + (1<<15)
165 @type layerMask: Int
166 """
167
169 """
170 Initializer for the Armature TypeObject.
171 Example::
172 myNewArmature = Blender.Armature.Armature('AR_1')
173 @param name: The name for the new armature
174 @type name: string
175 @return: New Armature Object
176 @rtype: Armature Object
177 """
178
180 """
181 Put the armature into EditMode for editing purposes. (Enters Editmode)
182 @warning: Using Window.Editmode() to switch the editmode manually will cause problems and possibly even crash Blender.
183 @warning: This is only needed for operations such as adding and removing bones.
184 @warning: Do access pose data until you have called update() or settings will be lost.
185 @warning: The armature should not be in manual editmode
186 prior to calling this method. The armature must be parented
187 to an object prior to editing.
188 @rtype: None
189 """
190
192 """
193 Save all changes and update the armature. (Leaves Editmode)
194 @note: Must have called makeEditable() first.
195 @rtype: None
196 """
198 """
199 Return a copy of this armature.
200 @rtype: Armature
201 """
203 """
204 Return a copy of this armature.
205 @rtype: Armature
206 """
207
208 import id_generics
209 Armature.__doc__ += id_generics.attributes
210
212 """
213 The BonesDict object
214 ====================
215 This object gives gives dictionary like access to the bones in an armature.
216 It is internal to blender but is called as 'Armature.bones'
217
218 Removing a bone:
219 Example::
220 del myArmature.bones['bone_name']
221 Adding a bone:
222 Example::
223 myEditBone = Armature.Editbone()
224 myArmature.bones['bone_name'] = myEditBone
225 """
226
228 """
229 Return the key, value pairs in this dictionary
230 @rtype: string, BPy_bone
231 @return: All strings, and py_bones in the armature (in that order)
232 """
233
235 """
236 Return the keys in this dictionary
237 @rtype: string
238 @return: All strings representing the bone names
239 """
240
242 """
243 Return the values in this dictionary
244 @rtype: BPy_bone
245 @return: All BPy_bones in this dictionary
246 """
247
249 """
250 The Bone object
251 ===============
252 This object gives access to Bone-specific data in Blender. This object
253 cannot be instantiated but is returned by BonesDict when the armature is not in editmode.
254 @ivar name: The name of this Bone.
255 @type name: String
256 @ivar roll: This Bone's roll value.
257 Keys are:
258 - 'ARMATURESPACE' - this roll in relation to the armature
259 - 'BONESPACE' - the roll in relation to itself
260 @type roll: Dictionary
261 @ivar head: This Bone's "head" ending position when in rest state.
262 Keys are:
263 - 'ARMATURESPACE' - this head position in relation to the armature
264 - 'BONESPACE' - the head position in relation to itself.
265 @type head: Dictionary
266 @ivar tail: This Bone's "tail" ending position when in rest state.
267 Keys are:
268 - 'ARMATURESPACE' - this tail position in relation to the armature
269 - 'BONESPACE' - the tail position in relation to itself
270 @type tail: Dictionary
271 @ivar matrix: This Bone's matrix. This cannot be set.
272 Keys are:
273 - 'ARMATURESPACE' - this matrix of the bone in relation to the armature
274 - 'BONESPACE' - the matrix of the bone in relation to itself
275 @type matrix: Matrix Object
276 @ivar parent: The parent Bone.
277 @type parent: Bone Object
278 @ivar children: The children directly attached to this bone.
279 @type children: List of Bone Objects
280 @ivar weight: The bone's weight.
281 @type weight: Float
282 @ivar options: Various bone options which can be:
283 - Armature.CONNECTED: IK to parent
284 - Armature.HINGE: No parent rotation or scaling
285 - Armature.NO_DEFORM: The bone does not deform geometry
286 - Armature.MULTIPLY: Multiply vgroups by envelope
287 - Armature.HIDDEN_EDIT: Hide bones in editmode
288 - Armature.ROOT_SELECTED: Selection of root ball of bone
289 - Armature.BONE_SELECTED: Selection of bone
290 - Armature.TIP_SELECTED: Selection of tip ball of bone
291 - Armature.LOCKED_EDIT: Prevents the bone from being transformed in editmode
292 @type options: List of Constants
293 @ivar subdivision: The number of bone subdivisions.
294 @type subdivision: Int
295 @ivar deformDist: The deform distance of the bone
296 @type deformDist: Float
297 @ivar length: The length of the bone. This cannot be set.
298 @type length: Float
299 @ivar headRadius: The radius of this bones head (used for envalope bones)
300 @type headRadius: Float
301 @ivar tailRadius: The radius of this bones head (used for envalope bones)
302 @type tailRadius: Float
303 @ivar layerMask: Layer bitmask
304 Example::
305 # set bone to layers 14 and 16
306 bone.layerMask = (1<<13) + (1<<15)
307 @type layerMask: Int
308 """
309
311 """
312 Whether or not this bone has a parent
313 @rtype: Bool
314 """
315
317 """
318 Whether or not this bone has children
319 @rtype: Bool
320 """
321
323 """
324 Gets all the children under this bone including the children's children.
325 @rtype: List of Bone object
326 @return: all bones under this one
327 """
328
330 """
331 The Editbone Object
332 ===================
333 This object is a wrapper for editbone data and is used only in the manipulation
334 of the armature in editmode.
335 @ivar name: The name of this Bone.
336 @type name: String
337 @ivar roll: This Bone's roll value (armaturespace).
338 @type roll: Float
339 @ivar head: This Bone's "head" ending position when in rest state (armaturespace).
340 @type head: Vector Object
341 @ivar tail: This Bone's "tail" ending position when in rest state (armaturespace).
342 @type tail: Vector Object
343 @ivar matrix: This Bone's matrix. (armaturespace)
344 @type matrix: Matrix Object
345 @ivar parent: The parent Bone.
346 @type parent: Editbone Object
347 @ivar weight: The bone's weight.
348 @type weight: Float
349 @ivar options: Various bone options which can be:
350 - Armature.CONNECTED: IK to parent
351 - Armature.HINGE: No parent rotation or scaling
352 - Armature.NO_DEFORM: The bone does not deform geometry
353 - Armature.MULTIPLY: Multiply vgroups by envelope
354 - Armature.HIDDEN_EDIT: Hide bones in editmode
355 - Armature.ROOT_SELECTED: Selection of root ball of bone
356 - Armature.BONE_SELECTED: Selection of bone
357 - Armature.TIP_SELECTED: Selection of tip ball of bone
358 @type options: List of Constants
359 @ivar subdivision: The number of bone subdivisions.
360 @type subdivision: Int
361 @ivar deformDist: The deform distance of the bone
362 @type deformDist: Float
363 @ivar length: The length of the bone. This cannot be set.
364 @type length: Float
365 @ivar headRadius: The radius of this bones head (used for envalope bones)
366 @type headRadius: Float
367 @ivar tailRadius: The radius of this bones head (used for envalope bones)
368 @type tailRadius: Float
369 """
370
372 """
373 Whether or not this bone has a parent
374 @rtype: Bool
375 """
376
378 """
379 Set the parent to None
380 @rtype: None
381 """
382