da69fb23c065187d5c6345766da9871feb2181e2
[blender.git] / source / blender / python / api2_2x / doc / Constraint.py
1 # Blender.Constraint module and the Constraint PyType object
2
3 """
4 The Blender.Constraint submodule
5
6 B{New}: 
7         -  provides access to Blender's constraint stack
8
9 This module provides access to the Constraint Data in Blender.
10
11 Examples::
12         from Blender import *
13
14         ob = Object.Get('Cube')
15         if len(ob.constraints) > 0:
16                 const = ob.constraints[0]
17                 if const.type == Constraint.Type.FLOOR:
18                         offs = const[Constraint.Settings.OFFSET]
19         
20 Or to print all the constraints attached to each bone in a pose::
21         from Blender import *
22         
23         ob = Object.Get('Armature')
24         pose = ob.getPose()
25         for bonename in pose.bones.keys():
26                 bone = pose.bones[bonename]
27                 for const in bone.constraints:
28                         print bone.name,'=>',const
29
30 @type Type: readonly dictionary
31 @var Type: Constant Constraint dict used by L{Constraints.append()} and 
32         for comparison with L{Constraint.type}.  Values are
33         TRACKTO, IKSOLVER, FOLLOWPATH, COPYROT, COPYLOC, COPYSIZE, ACTION,
34         LOCKTRACK, STRETCHTO, FLOOR, LIMITLOC, LIMITROT, LIMITSIZE, NULL
35
36 @type Settings: readonly dictionary
37 @var Settings: Constant dict used for changing constraint settings.
38         - Used for all constraints
39                 - TARGET (Object) (Note: not used by Limit Location (LIMITLOC), 
40                         Limit Rotation (LIMITROT), Limit Scale (LIMITSIZE))
41                 - BONE (string): name of Bone sub-target (for armature targets) (Note: not
42                         used by Stretch To (STRETCHTO), Limit Location (LIMITLOC), Limit Rotation 
43                         (LIMITROT), Limit Scale (LIMITSIZE))
44         - Used by IK Solver (IKSOLVER) constraint:
45                 - TOLERANCE (float): clamped to [0.0001:1.0]
46                 - ITERATIONS (int): clamped to [1,10000]
47                 - CHAINLEN (int): clamped to [0,255]
48                 - POSWEIGHT (float): clamped to [0.01,1.0]
49                 - ROTWEIGHT (float): clamped to [0.01,1.0]
50                 - ROTATE (bool)
51                 - USETIP (bool)
52         - Used by Action (ACTION) constraint:
53                 - ACTION (Action Object)
54                 - LOCAL (bool)
55                 - START (int): clamped to [1,maxframe]
56                 - END (int): clamped to [1,maxframe]
57                 - MIN (float): clamped to [-180.0,180.0]
58                 - MAX (float): clamped to [-180.0,180.0]
59                 - KEYON (int): values are XROT, YROT, ZROT
60         - Used by Track To (TRACKTO) constraint:
61                 - TRACK (int): values are TRACKX, TRACKY, TRACKZ, TRACKNEGX,
62                         TRACKNEGY, TRACKNEGZ
63                 - UP (int): values are UPX, UPY, UPZ
64         - Used by Stretch To (STRETCHTO) constraint:
65                 - RESTLENGTH (float): clamped to [0.0:100.0]
66                 - VOLVARIATION (float): clamped to [0.0:100.0]
67                 - VOLUMEMODE (int): values are VOLUMEXZ, VOLUMEX, VOLUMEZ,
68                         VOLUMENONE
69                 - PLANE (int): values are PLANEX, PLANEZ
70         - Used by Follow Path (FOLLOWPATH) constraint:
71                 - FOLLOW (bool)
72                 - OFFSET (float): clamped to [-maxframe:maxframe]
73                 - FORWARD (int): values are TRACKX, TRACKY, TRACKZ, TRACKNEGX,
74                         TRACKNEGY, TRACKNEGZ
75                 - UP (int): values are UPX, UPY, UPZ
76         - Used by Lock Track (FOLLOWPATH) constraint:
77                 - TRACK (int): values are TRACKX, TRACKY, TRACKZ, TRACKNEGX,
78                         TRACKNEGY, TRACKNEGZ
79                 - LOCK (int): values are LOCKX, LOCKY, LOCKZ
80         - Used by Floor (FLOOR) constraint:
81                 - MINMAX (int): values are MINX, MINY, MINZ, MAXX, MAXY, MAXZ
82                 - OFFSET (float): clamped to [-100.0,100.0]
83                 - STICKY (bool)
84         - Used by Copy Location (COPYLOC) and Copy Rotation (COPYROT)
85                 - COPY (bitfield): any combination of COPYX, COPYY and COPYZ
86                 - LOCAL (bool): Only for constraints which Armature targets.
87         - Used by Copy Size (COPYSIZE) constraint:
88                 - COPY (bitfield): any combination of COPYX, COPYY and COPYZ
89         - Used by Limit Location (LIMITLOC) constraint:
90                 - LIMIT (bitfield): any combination of LIMIT_XMIN, LIMIT_XMAX,
91                         LIMIT_YMIN, LIMIT_YMAX, LIMIT_ZMIN, LIMIT_ZMAX
92                 - LIMIT_LOCAL_BONE (boolean): USE WITH CAUTION. Only do something
93                         with this value if constraint is assigned to a bone.
94                 - LIMIT_LOCAL_NOPARENT (boolean): USE WITH CAUTION. Only do something
95                         with this value if constraint is assigned to an object with that 
96                         has been parented to something.
97                 - XMIN (float): clamped to [-1000.0,1000.0]
98                 - XMAX (float): clamped to [-1000.0,1000.0]
99                 - YMIN (float): clamped to [-1000.0,1000.0]
100                 - YMAX (float): clamped to [-1000.0,1000.0]
101                 - ZMIN (float): clamped to [-1000.0,1000.0]
102                 - ZMAX (float): clamped to [-1000.0,1000.0]
103         - Used by Limit Rotation (LIMITROT) constraint:
104                 - LIMIT (bitfield): any combination of LIMIT_XROT, LIMIT_YROT, 
105                         LIMIT_ZROT
106                 - LIMIT_LOCAL_BONE (boolean): USE WITH CAUTION. Only do something
107                         with this value if constraint is assigned to a bone.
108                 - XMIN (float): clamped to [-360.0,360.0]
109                 - XMAX (float): clamped to [-360.0,360.0]
110                 - YMIN (float): clamped to [-360.0,360.0]
111                 - YMAX (float): clamped to [-360.0,360.0]
112                 - ZMIN (float): clamped to [-360.0,360.0]
113                 - ZMAX (float): clamped to [-360.0,360.0]
114         - Used by Limit Scale (LIMITSIZE) constraint:
115                 - LIMIT (bitfield): any combination of LIMIT_XMIN, LIMIT_XMAX,
116                         LIMIT_YMIN, LIMIT_YMAX, LIMIT_ZMIN, LIMIT_ZMAX
117                 - XMIN (float): clamped to [-1000.0,1000.0]
118                 - XMAX (float): clamped to [-1000.0,1000.0]
119                 - YMIN (float): clamped to [-1000.0,1000.0]
120                 - YMAX (float): clamped to [-1000.0,1000.0]
121                 - ZMIN (float): clamped to [-1000.0,1000.0]
122                 - ZMAX (float): clamped to [-1000.0,1000.0]
123
124 """
125
126 class Constraints:
127         """
128         The Constraints object
129         ======================
130         This object provides access to sequence of
131         L{constraints<Constraint.Constraint>} for a particular object.
132         They can be accessed from L{Object.constraints<Object.Object.constraints>}.
133         or L{PoseBone.constraints<Pose.PoseBone.constraints>}.
134         """
135
136         def __getitem__(index):
137                 """
138                 This operator returns one of the constraints in the stack.
139                 @type index: int
140                 @return: an Constraint object
141                 @rtype: Constraint
142                 @raise KeyError: index was out of range
143                 """
144
145         def __len__():
146                 """
147                 Returns the number of constraints in the constraint stack.
148                 @return: number of Constraints
149                 @rtype: int
150                 """
151
152         def append(type):
153                 """
154                 Appends a new constraint to the end of the constraint stack.
155                 @param type: a constant specifying the type of constraint to create. as from L{Type}
156                 @type type: int constant
157                 @rtype: Constraint
158                 @return: the new Constraint
159                 """
160
161         def remove(con):
162                 """
163                 Remove a constraint from this objects constraint sequence.
164                 @param con: a constraint from this sequence to remove.
165                 @type con: Constraint
166                 @note: Accessing attributes of the constraint after it is removed will 
167                 throw an exception.
168                 """
169
170         def moveUp(con):
171                 """
172                 Moves the constraint up in the object's constraint stack.
173                 @param con: a constraint from this sequence to remove.
174                 @type con: Constraint
175                 @rtype: None
176                 """
177
178         def moveDown(con):
179                 """
180                 Moves the constraint down in the object's constraint stack.
181                 @param con: a constraint from this sequence to remove.
182                 @type con: Constraint
183                 @rtype: None
184                 """
185
186 class Constraint:
187         """
188         The Constraint object
189         =====================
190         This object provides access to a constraint for a particular object
191         accessed from L{Constraints}.
192         @ivar name: The name of this constraint. 29 chars max.
193         @type name: string
194         @ivar type: The type of this constraint. Read-only.  The returned value
195         matches the types in L{Type}.
196         @type type: int
197         @ivar influence: The influence value of the constraint.  Valid values
198         are in the range [0.0,1.0].
199         @type influence: float
200         """
201
202         def __getitem__(key):
203                 """
204                 This operator returns one of the constraint's data attributes.
205                 @param key: value from constraint's L{Constraint.Settings} constant
206                 @type key: int constant
207                 @return: the requested data
208                 @rtype: varies
209                 @raise KeyError: the key does not exist for the constraint
210                 """
211
212         def __setitem__(key):
213                 """
214                 This operator changes one of the constraint's data attributes.
215                 @param key: value from constraint's L{Constraint.Settings} constant
216                 @type key: int constant
217                 @raise KeyError: the key does not exist for the constraint
218                 """
219
220         def insertKey(frame):
221                 """
222                 Adds an influence keyframe for the constraint Ipo.  
223                 @rtype: None
224                 @param frame: the frame number at which to insert the key.
225                 @type frame: float
226                 """