1
2
3 """
4 The Blender.Key submodule.
5
6 This module provides access to B{Key} objects in Blender.
7
8 @type Types: readonly dictionary
9 @var Types: The type of a key owner, indicating the type of data in the
10 data blocks.
11 - MESH - the key is a Mesh key; data blocks contain
12 L{NMVert<NMesh.NMVert>} vertices.
13 - CURVE - the key is a Curve key; data blocks contains either
14 L{BezTriples<BezTriple.BezTriple>} or points (represented by a list of
15 3 floating point numbers).
16 - LATTICE - the key is a Lattice key; data blocks contain
17 BPoints, each point represented by a list of 3 floating point numbers.
18 """
19
20 -def Get(name = None):
21 """
22 Get the named Key object from Blender. If the name is omitted, it
23 will retrieve a list of all keys in Blender.
24 @type name: string
25 @param name: the name of the requested key
26 @return: If name was given, return that Key object (or None if not
27 found). If a name was not given, return a list of every Key object
28 in Blender.
29 """
30
32 """
33 The Key object
34 ==============
35 An object with keyframes (L{Lattice}, L{NMesh} or
36 L{Curve}) will contain a Key object representing the
37 keyframe data.
38
39 @ivar ipo: Key Ipo. Contains the Ipo if one is assigned to the
40 object, B{None} otherwise. Setting to B{None} clears the current Ipo.
41 @type ipo: Blender Ipo
42 @ivar value: The value of the key. Read-only.
43 @type value: float
44 @ivar type: An integer from the L{Types} dictionary
45 representing the Key type. Read-only.
46 @type type: int
47 @ivar blocks: A list of KeyBlocks for the key. Read-only.
48 @type blocks: Blender KeyBlock.
49 @ivar relative: Indicates whether the key is relative(=True) or normal.
50 @type relative: bool
51 """
52
54 """
55 Get the L{Ipo} object associated with this key.
56 """
58 """
59 Get a list of L{KeyBlock}s, containing the keyframes defined for
60 this Key.
61 """
62
64 """
65 The KeyBlock object
66 ===================
67 Each Key object has a list of KeyBlocks attached, each KeyBlock
68 representing a keyframe.
69
70 @ivar curval: Current value of the corresponding IpoCurve. Read-only.
71 @type curval: float
72 @ivar name: The name of the Keyblock. Truncated to 32 characters.
73 @type name: string
74 @ivar pos: The position of the keyframe.
75 @type pos: float
76 @ivar slidermin: The minimum value for the action slider.
77 Value is clamped to the range [-10.0,10.0].
78 @type slidermin: float
79 @ivar slidermax: The maximum value for the action slider.
80 Value is clamped to the range [-10.0,10.0].
81 @type slidermax: float
82 @ivar vgroup: The assigned VGroup for the Key Block.
83 @type vgroup: string
84 @ivar data: The data of the KeyBlock (see L{getData}). This
85 attribute is read-only.
86 @type data: varies
87 """
88
90 """
91 Get the data of a KeyBlock, as a list of data items. Each item
92 will have a different data format depending on the type of this
93 Key.
94
95 Note that prior to 2.45 the behaviour of this function
96 was different (and very wrong). Old scripts might need to be
97 updated.
98
99 - Mesh keys have a list of L{Vectors<Mathutils.Vector>} objects in the data
100 block.
101 - Lattice keys have a list of L{Vectors<Mathutils.Vector>} objects in the data
102 block.
103 - Curve keys return either a list of tuples, eacn containing
104 four L{Vectors<Mathutils.Vector>} (if the curve is a Bezier curve),
105 or otherwise just a list of L{Vectors<Mathutils.Vector>}.
106
107 For bezier keys, the first three vectors in the tuple are the Bezier
108 triple vectors, while the fourth vector's first element is the curve tilt
109 (the other two elements are reserved and are currently unused).
110
111 For non-Bezier keys, the first three elements of the returned vector is
112 the curve handle point, while the fourth element is the tilt.
113
114
115 A word on relative shape keys; relative shape keys are not actually
116 stored as offsets to the base shape key (like you'd expect). Instead,
117 each shape key stores an entire model (actually the state of the mesh
118 vertices after exiting editmode with any given key active).
119
120 The additive offset for a shape key is calculated (when needed) by
121 comparing the shape key with its base key, which is always the very
122 first in the keyblock list.
123 """
124