← Back to branch summary

~diresu/blender/blender-command-port

« back to all changes in this revision

Viewing changes to source/blender/python/api2_2x/doc/Armature.py

  • Committer: theeth
  • Date: 2008-10-14 16:52:04 UTC
  • Revision ID: vcs-imports@canonical.com-20081014165204-r32w2gm6s0osvdhn
copy back trunk

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 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
 
 
127
class Armature:
 
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
 
 
168
        def __init__(name = 'myArmature'):
 
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
        
 
179
        def makeEditable():
 
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
 
 
191
        def update():
 
192
                """
 
193
                Save all changes and update the armature. (Leaves Editmode)
 
194
                @note: Must have called makeEditable() first.
 
195
                @rtype: None
 
196
                """
 
197
        def copy():
 
198
                """
 
199
                Return a copy of this armature.
 
200
                @rtype: Armature
 
201
                """
 
202
        def __copy__():
 
203
                """
 
204
                Return a copy of this armature.
 
205
                @rtype: Armature
 
206
                """
 
207
 
 
208
import id_generics
 
209
Armature.__doc__ += id_generics.attributes 
 
210
 
 
211
class BonesDict:
 
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
 
 
227
        def items():
 
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
 
 
234
        def keys():
 
235
                """
 
236
                Return the keys in this dictionary
 
237
                @rtype: string
 
238
                @return: All strings representing the bone names
 
239
                """
 
240
 
 
241
        def values():
 
242
                """
 
243
                Return the values in this dictionary
 
244
                @rtype: BPy_bone
 
245
                @return: All BPy_bones in this dictionary
 
246
                """
 
247
 
 
248
class Bone:
 
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
 
 
310
        def hasParent():
 
311
                """
 
312
                Whether or not this bone has a parent
 
313
                @rtype: Bool
 
314
                """
 
315
 
 
316
        def hasChildren():
 
317
                """
 
318
                Whether or not this bone has children
 
319
                @rtype: Bool
 
320
                """
 
321
 
 
322
        def getAllChildren():
 
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
 
 
329
class Editbone:
 
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
 
 
371
        def hasParent():
 
372
                """
 
373
                Whether or not this bone has a parent
 
374
                @rtype: Bool
 
375
                """
 
376
 
 
377
        def clearParent():
 
378
                """
 
379
                Set the parent to None
 
380
                @rtype: None
 
381
                """