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, CLAMPTO,
  35         PYTHON, CHILDOF, TRANSFORM, NULL
  36
  37 @type Settings: readonly dictionary
  38 @var Settings: Constant dict used for changing constraint settings.
  39         - Used for all constraints
  40                 - TARGET (Object) (Note: not used by Limit Location (LIMITLOC),
  41                         Limit Rotation (LIMITROT), Limit Scale (LIMITSIZE))
  42                 - BONE (string): name of Bone sub-target (for armature targets) (Note: not
  43                         used by Stretch To (STRETCHTO), Limit Location (LIMITLOC), Limit Rotation
  44                         (LIMITROT), Limit Scale (LIMITSIZE), Follow Path (FOLLOWPATH), Clamp To (CLAMPTO))
  45         - Used by some constraints:
  46                 - OWNERSPACE (int): for TRACKTO, COPYLOC, COPYROT, COPYSIZE, LIMITLOC, LIMITROT, LIMITSIZE, PYTHON, TRANSFORM
  47                         If the owner is an object, values are SPACE_WORLD, SPACE_LOCAL
  48                         If the owner is a bone, values are SPACE_WORLD, SPACE_POSE, SPACE_PARLOCAL, SPACE_LOCAL
  49                 - TARGETSPACE (int): for TRACKTO, COPYLOC, COPYROT, COPYSIZE, PYTHON, TRANSFORM, ACTION
  50                         If the owner is an object, values are SPACE_WORLD, SPACE_LOCAL
  51                         If the owner is a bone, values are SPACE_WORLD, SPACE_POSE, SPACE_PARLOCAL, SPACE_LOCAL
  52         - Used by IK Solver (IKSOLVER) constraint:
  53                 - TOLERANCE (float): clamped to [0.0001:1.0]
  54                 - ITERATIONS (int): clamped to [1,10000]
  55                 - CHAINLEN (int): clamped to [0,255]
  56                 - POSWEIGHT (float): clamped to [0.01,1.0]
  57                 - ROTWEIGHT (float): clamped to [0.01,1.0]
  58                 - ROTATE (bool)
  59                 - USETIP (bool)
  60         - Used by Action (ACTION) constraint:
  61                 - ACTION (Action Object)
  62                 - START (int): clamped to [1,maxframe]
  63                 - END (int): clamped to [1,maxframe]
  64                 - MIN (float): clamped to [-1000.0,1000.0] for Location, [-180.0,180.0] for Rotation, [0.0001,1000.0] for Scaling
  65                 - MAX (float): clamped to [-1000.0,1000.0] for Location, [-180.0,180.0] for Rotation, [0.0001,1000.0] for Scaling
  66                 - KEYON (int): values are XLOC, YLOC, ZLOC, XROT, YROT, ZROT, XSIZE, YSIZE, ZSIZE
  67         - Used by Track To (TRACKTO) constraint:
  68                 - TRACK (int): values are TRACKX, TRACKY, TRACKZ, TRACKNEGX,
  69                         TRACKNEGY, TRACKNEGZ
  70                 - UP (int): values are UPX, UPY, UPZ
  71         - Used by Stretch To (STRETCHTO) constraint:
  72                 - RESTLENGTH (float): clamped to [0.0:100.0]
  73                 - VOLVARIATION (float): clamped to [0.0:100.0]
  74                 - VOLUMEMODE (int): values are VOLUMEXZ, VOLUMEX, VOLUMEZ,
  75                         VOLUMENONE
  76                 - PLANE (int): values are PLANEX, PLANEZ
  77         - Used by Follow Path (FOLLOWPATH) constraint:
  78                 - FOLLOW (bool)
  79                 - OFFSET (float): clamped to [-maxframe:maxframe]
  80                 - FORWARD (int): values are TRACKX, TRACKY, TRACKZ, TRACKNEGX,
  81                         TRACKNEGY, TRACKNEGZ
  82                 - UP (int): values are UPX, UPY, UPZ
  83         - Used by Lock Track (FOLLOWPATH) constraint:
  84                 - TRACK (int): values are TRACKX, TRACKY, TRACKZ, TRACKNEGX,
  85                         TRACKNEGY, TRACKNEGZ
  86                 - LOCK (int): values are LOCKX, LOCKY, LOCKZ
  87         - Used by Clamp To (CLAMPTO) constraint:
  88                 - CLAMP (int): values are CLAMPAUTO, CLAMPX, CLAMPY, CLAMPZ
  89                 - CLAMPCYCLIC (bool)
  90         - Used by Floor (FLOOR) constraint:
  91                 - MINMAX (int): values are MINX, MINY, MINZ, MAXX, MAXY, MAXZ
  92                 - OFFSET (float): clamped to [-100.0,100.0]
  93                 - STICKY (bool)
  94         - Used by Copy Location (COPYLOC) and Copy Rotation (COPYROT)
  95                 - COPY (bitfield): any combination of COPYX, COPYY and COPYZ with possible addition of COPYXINVERT, COPYYINVERT and COPYZINVERT to invert that particular input (if on).
  96         - Used by Copy Size (COPYSIZE) constraint:
  97                 - COPY (bitfield): any combination of COPYX, COPYY and COPYZ
  98         - Used by Limit Location (LIMITLOC) constraint:
  99                 - LIMIT (bitfield): any combination of LIMIT_XMIN, LIMIT_XMAX,
 100                         LIMIT_YMIN, LIMIT_YMAX, LIMIT_ZMIN, LIMIT_ZMAX
 101                 - XMIN (float): clamped to [-1000.0,1000.0]
 102                 - XMAX (float): clamped to [-1000.0,1000.0]
 103                 - YMIN (float): clamped to [-1000.0,1000.0]
 104                 - YMAX (float): clamped to [-1000.0,1000.0]
 105                 - ZMIN (float): clamped to [-1000.0,1000.0]
 106                 - ZMAX (float): clamped to [-1000.0,1000.0]
 107         - Used by Limit Rotation (LIMITROT) constraint:
 108                 - LIMIT (bitfield): any combination of LIMIT_XROT, LIMIT_YROT,
 109                         LIMIT_ZROT
 110                 - XMIN (float): clamped to [-360.0,360.0]
 111                 - XMAX (float): clamped to [-360.0,360.0]
 112                 - YMIN (float): clamped to [-360.0,360.0]
 113                 - YMAX (float): clamped to [-360.0,360.0]
 114                 - ZMIN (float): clamped to [-360.0,360.0]
 115                 - ZMAX (float): clamped to [-360.0,360.0]
 116         - Used by Limit Scale (LIMITSIZE) constraint:
 117                 - LIMIT (bitfield): any combination of LIMIT_XMIN, LIMIT_XMAX,
 118                         LIMIT_YMIN, LIMIT_YMAX, LIMIT_ZMIN, LIMIT_ZMAX
 119                 - XMIN (float): clamped to [0.0001,1000.0]
 120                 - XMAX (float): clamped to [0.0001,1000.0]
 121                 - YMIN (float): clamped to [0.0001,1000.0]
 122                 - YMAX (float): clamped to [0.0001,1000.0]
 123                 - ZMIN (float): clamped to [0.0001,1000.0]
 124                 - ZMAX (float): clamped to [0.0001,1000.0]
 125         - Used by Python Script (PYTHON) constraint:
 126                 - SCRIPT (Text): script to use
 127                 - PROPERTIES (IDProperties): ID-Properties of constraint
 128         - Used by Child Of (CHILDOF) constraint:
 129                 - COPY (bitfield): any combination of PARLOCX, PARLOCY, PARLOCZ,
 130                         PARROTX, PARROTY, PARROTZ, PARSIZEX, PARSIZEY, PARSIZEZ.
 131         - Used by Transformation (TRANSFORM) constraint:
 132                 - FROM (int): values are LOC, ROT, SCALE
 133                 - TO (int): values are LOC, ROT, SCALE
 134                 - MAPX, MAPY, MAPZ (int): values are LOC, ROT, SCALE
 135                 - EXTRAPOLATE (bool)
 136                 - FROM_MINX, FROM_MINY, FROM_MINZ, FROM_MAXX,
 137                   FROM_MAXY, FROM_MAXZ (float):
 138                   If FROM==LOC, then is clamped to [-1000.0, 1000.0]
 139                   If FROM==ROT, then is clamped to [-360.0, 360.0]
 140                   If FROM==SCALE, then is clamped to [0.0001, 1000.0]
 141                 - TO_MINX, TO_MINY, TO_MINZ, TO_MAXX, TO_MAXY, TO_MAXZ (float):
 142                   If TO==LOC, then is clamped to [-1000.0, 1000.0]
 143                   If TO==ROT, then is clamped to [-360.0, 360.0]
 144                   If TO==SCALE, then is clamped to [0.0001, 1000.0]
 145
 146 """
 147
 148 class Constraints:
 149         """
 150         The Constraints object
 151         ======================
 152         This object provides access to sequence of
 153         L{constraints<Constraint.Constraint>} for a particular object.
 154         They can be accessed from L{Object.constraints<Object.Object.constraints>}.
 155         or L{PoseBone.constraints<Pose.PoseBone.constraints>}.
 156         """
 157
 158         def __getitem__(index):
 159                 """
 160                 This operator returns one of the constraints in the stack.
 161                 @type index: int
 162                 @return: an Constraint object
 163                 @rtype: Constraint
 164                 @raise KeyError: index was out of range
 165                 """
 166
 167         def __len__():
 168                 """
 169                 Returns the number of constraints in the constraint stack.
 170                 @return: number of Constraints
 171                 @rtype: int
 172                 """
 173
 174         def append(type):
 175                 """
 176                 Appends a new constraint to the end of the constraint stack.
 177                 @param type: a constant specifying the type of constraint to create. as from L{Type}
 178                 @type type: int constant
 179                 @rtype: Constraint
 180                 @return: the new Constraint
 181                 """
 182
 183         def remove(con):
 184                 """
 185                 Remove a constraint from this objects constraint sequence.
 186                 @param con: a constraint from this sequence to remove.
 187                 @type con: Constraint
 188                 @note: Accessing attributes of the constraint after it is removed will
 189                 throw an exception.
 190                 """
 191
 192         def moveUp(con):
 193                 """
 194                 Moves the constraint up in the object's constraint stack.
 195                 @param con: a constraint from this sequence to remove.
 196                 @type con: Constraint
 197                 @rtype: None
 198                 """
 199
 200         def moveDown(con):
 201                 """
 202                 Moves the constraint down in the object's constraint stack.
 203                 @param con: a constraint from this sequence to remove.
 204                 @type con: Constraint
 205                 @rtype: None
 206                 """
 207
 208 class Constraint:
 209         """
 210         The Constraint object
 211         =====================
 212         This object provides access to a constraint for a particular object
 213         accessed from L{Constraints}.
 214         @ivar name: The name of this constraint. 29 chars max.
 215         @type name: string
 216         @ivar type: The type of this constraint. Read-only.  The returned value
 217         matches the types in L{Type}.
 218         @type type: int
 219         @ivar influence: The influence value of the constraint.  Valid values
 220         are in the range [0.0,1.0].
 221         @type influence: float
 222         """
 223
 224         def __getitem__(key):
 225                 """
 226                 This operator returns one of the constraint's data attributes.
 227                 @param key: value from constraint's L{Constraint.Settings} constant
 228                 @type key: int constant
 229                 @return: the requested data
 230                 @rtype: varies
 231                 @raise KeyError: the key does not exist for the constraint
 232                 """
 233
 234         def __setitem__(key):
 235                 """
 236                 This operator changes one of the constraint's data attributes.
 237                 @param key: value from constraint's L{Constraint.Settings} constant
 238                 @type key: int constant
 239                 @raise KeyError: the key does not exist for the constraint
 240                 """
 241
 242         def insertKey(frame):
 243                 """
 244                 Adds an influence keyframe for the constraint Ipo.
 245                 @rtype: None
 246                 @param frame: the frame number at which to insert the key.
 247                 @type frame: float
 248                 """