Pose Operators¶

bpy.ops.pose.armature_apply(selected=False)¶

Apply the current pose as the new rest pose

Parameters: selected (boolean, (optional)) – Selected Only, Only apply the selected bones (with propagation to children)

bpy.ops.pose.autoside_names(axis='XAXIS')¶

Automatically renames the selected bones according to which side of the target axis they fall on

Parameters

axis (enum in ['XAXIS', 'YAXIS', 'ZAXIS'], (optional)) –

Axis, Axis tag names with

XAXIS X-Axis, Left/Right.
YAXIS Y-Axis, Front/Back.
ZAXIS Z-Axis, Top/Bottom.

bpy.ops.pose.bone_layers(layers=(False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False))¶

Change the layers that the selected bones belong to

Parameters: layers (boolean array of 32 items, (optional)) – Layer, Armature layers that bone belongs to

bpy.ops.pose.breakdown(percentage=0.5, prev_frame=0, next_frame=0, channels='ALL', axis_lock='FREE')¶

Create a suitable breakdown pose on the current frame

Parameters

percentage (float in [0, 1], (optional)) – Percentage, Weighting factor for which keyframe is favored more
prev_frame (int in [-1048574, 1048574], (optional)) – Previous Keyframe, Frame number of keyframe immediately before the current frame
next_frame (int in [-1048574, 1048574], (optional)) – Next Keyframe, Frame number of keyframe immediately after the current frame
channels (enum in ['ALL', 'LOC', 'ROT', 'SIZE', 'BBONE', 'CUSTOM'], (optional)) –
Channels, Set of properties that are affected
- ALL All Properties, All properties, including transforms, bendy bone shape, and custom properties.
- LOC Location, Location only.
- ROT Rotation, Rotation only.
- SIZE Scale, Scale only.
- BBONE Bendy Bone, Bendy Bone shape properties.
- CUSTOM Custom Properties, Custom properties.
axis_lock (enum in ['FREE', 'X', 'Y', 'Z'], (optional)) –
Axis Lock, Transform axis to restrict effects to
- FREE Free, All axes are affected.
- X X, Only X-axis transforms are affected.
- Y Y, Only Y-axis transforms are affected.
- Z Z, Only Z-axis transforms are affected.

bpy.ops.pose.constraint_add(type='')¶

Add a constraint to the active bone

Parameters

type (enum in ['CAMERA_SOLVER', 'FOLLOW_TRACK', 'OBJECT_SOLVER', 'COPY_LOCATION', 'COPY_ROTATION', 'COPY_SCALE', 'COPY_TRANSFORMS', 'LIMIT_DISTANCE', 'LIMIT_LOCATION', 'LIMIT_ROTATION', 'LIMIT_SCALE', 'MAINTAIN_VOLUME', 'TRANSFORM', 'TRANSFORM_CACHE', 'CLAMP_TO', 'DAMPED_TRACK', 'IK', 'LOCKED_TRACK', 'SPLINE_IK', 'STRETCH_TO', 'TRACK_TO', 'ACTION', 'ARMATURE', 'CHILD_OF', 'FLOOR', 'FOLLOW_PATH', 'PIVOT', 'SHRINKWRAP'], (optional)) –

Type

CAMERA_SOLVER Camera Solver.
FOLLOW_TRACK Follow Track.
OBJECT_SOLVER Object Solver.
COPY_LOCATION Copy Location, Copy the location of a target (with an optional offset), so that they move together.
COPY_ROTATION Copy Rotation, Copy the rotation of a target (with an optional offset), so that they rotate together.
COPY_SCALE Copy Scale, Copy the scale factors of a target (with an optional offset), so that they are scaled by the same amount.
COPY_TRANSFORMS Copy Transforms, Copy all the transformations of a target, so that they move together.
LIMIT_DISTANCE Limit Distance, Restrict movements to within a certain distance of a target (at the time of constraint evaluation only).
LIMIT_LOCATION Limit Location, Restrict movement along each axis within given ranges.
LIMIT_ROTATION Limit Rotation, Restrict rotation along each axis within given ranges.
LIMIT_SCALE Limit Scale, Restrict scaling along each axis with given ranges.
MAINTAIN_VOLUME Maintain Volume, Compensate for scaling one axis by applying suitable scaling to the other two axes.
TRANSFORM Transformation, Use one transform property from target to control another (or same) property on owner.
TRANSFORM_CACHE Transform Cache, Look up the transformation matrix from an external file.
CLAMP_TO Clamp To, Restrict movements to lie along a curve by remapping location along curve’s longest axis.
DAMPED_TRACK Damped Track, Point towards a target by performing the smallest rotation necessary.
IK Inverse Kinematics, Control a chain of bones by specifying the endpoint target (Bones only).
LOCKED_TRACK Locked Track, Rotate around the specified (‘locked’) axis to point towards a target.
SPLINE_IK Spline IK, Align chain of bones along a curve (Bones only).
STRETCH_TO Stretch To, Stretch along Y-Axis to point towards a target.
TRACK_TO Track To, Legacy tracking constraint prone to twisting artifacts.
ACTION Action, Use transform property of target to look up pose for owner from an Action.
ARMATURE Armature, Apply weight-blended transformation from multiple bones like the Armature modifier.
CHILD_OF Child Of, Make target the ‘detachable’ parent of owner.
FLOOR Floor, Use position (and optionally rotation) of target to define a ‘wall’ or ‘floor’ that the owner can not cross.
FOLLOW_PATH Follow Path, Use to animate an object/bone following a path.
PIVOT Pivot, Change pivot point for transforms (buggy).
SHRINKWRAP Shrinkwrap, Restrict movements to surface of target mesh.

bpy.ops.pose.constraint_add_with_targets(type='')¶

Add a constraint to the active bone, with target (where applicable) set to the selected Objects/Bones

Parameters

type (enum in ['CAMERA_SOLVER', 'FOLLOW_TRACK', 'OBJECT_SOLVER', 'COPY_LOCATION', 'COPY_ROTATION', 'COPY_SCALE', 'COPY_TRANSFORMS', 'LIMIT_DISTANCE', 'LIMIT_LOCATION', 'LIMIT_ROTATION', 'LIMIT_SCALE', 'MAINTAIN_VOLUME', 'TRANSFORM', 'TRANSFORM_CACHE', 'CLAMP_TO', 'DAMPED_TRACK', 'IK', 'LOCKED_TRACK', 'SPLINE_IK', 'STRETCH_TO', 'TRACK_TO', 'ACTION', 'ARMATURE', 'CHILD_OF', 'FLOOR', 'FOLLOW_PATH', 'PIVOT', 'SHRINKWRAP'], (optional)) –

Type

CAMERA_SOLVER Camera Solver.
FOLLOW_TRACK Follow Track.
OBJECT_SOLVER Object Solver.
COPY_LOCATION Copy Location, Copy the location of a target (with an optional offset), so that they move together.
COPY_ROTATION Copy Rotation, Copy the rotation of a target (with an optional offset), so that they rotate together.
COPY_SCALE Copy Scale, Copy the scale factors of a target (with an optional offset), so that they are scaled by the same amount.
COPY_TRANSFORMS Copy Transforms, Copy all the transformations of a target, so that they move together.
LIMIT_DISTANCE Limit Distance, Restrict movements to within a certain distance of a target (at the time of constraint evaluation only).
LIMIT_LOCATION Limit Location, Restrict movement along each axis within given ranges.
LIMIT_ROTATION Limit Rotation, Restrict rotation along each axis within given ranges.
LIMIT_SCALE Limit Scale, Restrict scaling along each axis with given ranges.
MAINTAIN_VOLUME Maintain Volume, Compensate for scaling one axis by applying suitable scaling to the other two axes.
TRANSFORM Transformation, Use one transform property from target to control another (or same) property on owner.
TRANSFORM_CACHE Transform Cache, Look up the transformation matrix from an external file.
CLAMP_TO Clamp To, Restrict movements to lie along a curve by remapping location along curve’s longest axis.
DAMPED_TRACK Damped Track, Point towards a target by performing the smallest rotation necessary.
IK Inverse Kinematics, Control a chain of bones by specifying the endpoint target (Bones only).
LOCKED_TRACK Locked Track, Rotate around the specified (‘locked’) axis to point towards a target.
SPLINE_IK Spline IK, Align chain of bones along a curve (Bones only).
STRETCH_TO Stretch To, Stretch along Y-Axis to point towards a target.
TRACK_TO Track To, Legacy tracking constraint prone to twisting artifacts.
ACTION Action, Use transform property of target to look up pose for owner from an Action.
ARMATURE Armature, Apply weight-blended transformation from multiple bones like the Armature modifier.
CHILD_OF Child Of, Make target the ‘detachable’ parent of owner.
FLOOR Floor, Use position (and optionally rotation) of target to define a ‘wall’ or ‘floor’ that the owner can not cross.
FOLLOW_PATH Follow Path, Use to animate an object/bone following a path.
PIVOT Pivot, Change pivot point for transforms (buggy).
SHRINKWRAP Shrinkwrap, Restrict movements to surface of target mesh.

bpy.ops.pose.constraints_clear()¶: Clear all the constraints for the selected bones

bpy.ops.pose.constraints_copy()¶: Copy constraints to other selected bones

bpy.ops.pose.copy()¶: Copies the current pose of the selected bones to copy/paste buffer

bpy.ops.pose.flip_names(do_strip_numbers=False)¶

Flips (and corrects) the axis suffixes of the names of selected bones

Parameters: do_strip_numbers (boolean, (optional)) – Strip Numbers, Try to remove right-most dot-number from flipped names (WARNING: may result in incoherent naming in some cases)

bpy.ops.pose.group_add()¶: Add a new bone group

bpy.ops.pose.group_assign(type=0)¶

Add selected bones to the chosen bone group

Parameters: type (int in [0, inf], (optional)) – Bone Group Index

bpy.ops.pose.group_deselect()¶: Deselect bones of active Bone Group

bpy.ops.pose.group_move(direction='UP')¶

Change position of active Bone Group in list of Bone Groups

Parameters: direction (enum in ['UP', 'DOWN'], (optional)) – Direction, Direction to move the active Bone Group towards

bpy.ops.pose.group_remove()¶: Remove the active bone group

bpy.ops.pose.group_select()¶: Select bones in active Bone Group

bpy.ops.pose.group_sort()¶: Sort Bone Groups by their names in ascending order

bpy.ops.pose.group_unassign()¶: Remove selected bones from all bone groups

bpy.ops.pose.hide(unselected=False)¶

Tag selected bones to not be visible in Pose Mode

Parameters: unselected (boolean, (optional)) – Unselected

bpy.ops.pose.ik_add(with_targets=True)¶

Add IK Constraint to the active Bone

Parameters: with_targets (boolean, (optional)) – With Targets, Assign IK Constraint with targets derived from the select bones/objects

bpy.ops.pose.ik_clear()¶: Remove all IK Constraints from selected bones

bpy.ops.pose.loc_clear()¶: Reset locations of selected bones to their default values

bpy.ops.pose.paste(flipped=False, selected_mask=False)¶

Paste the stored pose on to the current pose

Parameters

flipped (boolean, (optional)) – Flipped on X-Axis, Paste the stored pose flipped on to current pose
selected_mask (boolean, (optional)) – On Selected Only, Only paste the stored pose on to selected bones in the current pose

bpy.ops.pose.paths_calculate(start_frame=1, end_frame=250, bake_location='HEADS')¶

Calculate paths for the selected bones

Parameters

start_frame (int in [-1048574, 1048574], (optional)) – Start, First frame to calculate bone paths on
end_frame (int in [-1048574, 1048574], (optional)) – End, Last frame to calculate bone paths on
bake_location (enum in ['HEADS', 'TAILS'], (optional)) –
Bake Location, Which point on the bones is used when calculating paths
- HEADS Heads, Calculate bone paths from heads.
- TAILS Tails, Calculate bone paths from tails.

bpy.ops.pose.paths_clear(only_selected=False)¶

Clear path caches for all bones, hold Shift key for selected bones only

Parameters: only_selected (boolean, (optional)) – Only Selected, Only clear paths from selected bones

bpy.ops.pose.paths_range_update()¶: Update frame range for motion paths from the Scene’s current frame range

bpy.ops.pose.paths_update()¶: Recalculate paths for bones that already have them

bpy.ops.pose.propagate(mode='WHILE_HELD', end_frame=250.0)¶

Copy selected aspects of the current pose to subsequent poses already keyframed

Parameters

mode (enum in ['WHILE_HELD', 'NEXT_KEY', 'LAST_KEY', 'BEFORE_FRAME', 'BEFORE_END', 'SELECTED_KEYS', 'SELECTED_MARKERS'], (optional)) –
Terminate Mode, Method used to determine when to stop propagating pose to keyframes
- WHILE_HELD While Held, Propagate pose to all keyframes after current frame that don’t change (Default behavior).
- NEXT_KEY To Next Keyframe, Propagate pose to first keyframe following the current frame only.
- LAST_KEY To Last Keyframe, Propagate pose to the last keyframe only (i.e. making action cyclic).
- BEFORE_FRAME Before Frame, Propagate pose to all keyframes between current frame and ‘Frame’ property.
- BEFORE_END Before Last Keyframe, Propagate pose to all keyframes from current frame until no more are found.
- SELECTED_KEYS On Selected Keyframes, Propagate pose to all selected keyframes.
- SELECTED_MARKERS On Selected Markers, Propagate pose to all keyframes occurring on frames with Scene Markers after the current frame.
end_frame (float in [1.17549e-38, inf], (optional)) – End Frame, Frame to stop propagating frames to (for ‘Before Frame’ mode)

bpy.ops.pose.push(percentage=0.5, prev_frame=0, next_frame=0, channels='ALL', axis_lock='FREE')¶

Exaggerate the current pose in regards to the breakdown pose

Parameters

percentage (float in [0, 1], (optional)) – Percentage, Weighting factor for which keyframe is favored more
prev_frame (int in [-1048574, 1048574], (optional)) – Previous Keyframe, Frame number of keyframe immediately before the current frame
next_frame (int in [-1048574, 1048574], (optional)) – Next Keyframe, Frame number of keyframe immediately after the current frame
channels (enum in ['ALL', 'LOC', 'ROT', 'SIZE', 'BBONE', 'CUSTOM'], (optional)) –
Channels, Set of properties that are affected
- ALL All Properties, All properties, including transforms, bendy bone shape, and custom properties.
- LOC Location, Location only.
- ROT Rotation, Rotation only.
- SIZE Scale, Scale only.
- BBONE Bendy Bone, Bendy Bone shape properties.
- CUSTOM Custom Properties, Custom properties.
axis_lock (enum in ['FREE', 'X', 'Y', 'Z'], (optional)) –
Axis Lock, Transform axis to restrict effects to
- FREE Free, All axes are affected.
- X X, Only X-axis transforms are affected.
- Y Y, Only Y-axis transforms are affected.
- Z Z, Only Z-axis transforms are affected.

bpy.ops.pose.push_rest(percentage=0.5, prev_frame=0, next_frame=0, channels='ALL', axis_lock='FREE')¶

Push the current pose further away from the rest pose

Parameters

percentage (float in [0, 1], (optional)) – Percentage, Weighting factor for which keyframe is favored more
prev_frame (int in [-1048574, 1048574], (optional)) – Previous Keyframe, Frame number of keyframe immediately before the current frame
next_frame (int in [-1048574, 1048574], (optional)) – Next Keyframe, Frame number of keyframe immediately after the current frame
channels (enum in ['ALL', 'LOC', 'ROT', 'SIZE', 'BBONE', 'CUSTOM'], (optional)) –
Channels, Set of properties that are affected
- ALL All Properties, All properties, including transforms, bendy bone shape, and custom properties.
- LOC Location, Location only.
- ROT Rotation, Rotation only.
- SIZE Scale, Scale only.
- BBONE Bendy Bone, Bendy Bone shape properties.
- CUSTOM Custom Properties, Custom properties.
axis_lock (enum in ['FREE', 'X', 'Y', 'Z'], (optional)) –
Axis Lock, Transform axis to restrict effects to
- FREE Free, All axes are affected.
- X X, Only X-axis transforms are affected.
- Y Y, Only Y-axis transforms are affected.
- Z Z, Only Z-axis transforms are affected.

bpy.ops.pose.quaternions_flip()¶: Flip quaternion values to achieve desired rotations, while maintaining the same orientations

bpy.ops.pose.relax(percentage=0.5, prev_frame=0, next_frame=0, channels='ALL', axis_lock='FREE')¶

Make the current pose more similar to its breakdown pose

Parameters

percentage (float in [0, 1], (optional)) – Percentage, Weighting factor for which keyframe is favored more
prev_frame (int in [-1048574, 1048574], (optional)) – Previous Keyframe, Frame number of keyframe immediately before the current frame
next_frame (int in [-1048574, 1048574], (optional)) – Next Keyframe, Frame number of keyframe immediately after the current frame
channels (enum in ['ALL', 'LOC', 'ROT', 'SIZE', 'BBONE', 'CUSTOM'], (optional)) –
Channels, Set of properties that are affected
- ALL All Properties, All properties, including transforms, bendy bone shape, and custom properties.
- LOC Location, Location only.
- ROT Rotation, Rotation only.
- SIZE Scale, Scale only.
- BBONE Bendy Bone, Bendy Bone shape properties.
- CUSTOM Custom Properties, Custom properties.
axis_lock (enum in ['FREE', 'X', 'Y', 'Z'], (optional)) –
Axis Lock, Transform axis to restrict effects to
- FREE Free, All axes are affected.
- X X, Only X-axis transforms are affected.
- Y Y, Only Y-axis transforms are affected.
- Z Z, Only Z-axis transforms are affected.

bpy.ops.pose.relax_rest(percentage=0.5, prev_frame=0, next_frame=0, channels='ALL', axis_lock='FREE')¶

Make the current pose more similar to the rest pose

Parameters

percentage (float in [0, 1], (optional)) – Percentage, Weighting factor for which keyframe is favored more
prev_frame (int in [-1048574, 1048574], (optional)) – Previous Keyframe, Frame number of keyframe immediately before the current frame
next_frame (int in [-1048574, 1048574], (optional)) – Next Keyframe, Frame number of keyframe immediately after the current frame
channels (enum in ['ALL', 'LOC', 'ROT', 'SIZE', 'BBONE', 'CUSTOM'], (optional)) –
Channels, Set of properties that are affected
- ALL All Properties, All properties, including transforms, bendy bone shape, and custom properties.
- LOC Location, Location only.
- ROT Rotation, Rotation only.
- SIZE Scale, Scale only.
- BBONE Bendy Bone, Bendy Bone shape properties.
- CUSTOM Custom Properties, Custom properties.
axis_lock (enum in ['FREE', 'X', 'Y', 'Z'], (optional)) –
Axis Lock, Transform axis to restrict effects to
- FREE Free, All axes are affected.
- X X, Only X-axis transforms are affected.
- Y Y, Only Y-axis transforms are affected.
- Z Z, Only Z-axis transforms are affected.

bpy.ops.pose.reveal(select=True)¶

Reveal all bones hidden in Pose Mode

Parameters: select (boolean, (optional)) – Select

bpy.ops.pose.rot_clear()¶: Reset rotations of selected bones to their default values

bpy.ops.pose.rotation_mode_set(type='QUATERNION')¶

Set the rotation representation used by selected bones

Parameters

type (enum in ['QUATERNION', 'XYZ', 'XZY', 'YXZ', 'YZX', 'ZXY', 'ZYX', 'AXIS_ANGLE'], (optional)) –

Rotation Mode

QUATERNION Quaternion (WXYZ), No Gimbal Lock.
XYZ XYZ Euler, XYZ Rotation Order - prone to Gimbal Lock (default).
XZY XZY Euler, XZY Rotation Order - prone to Gimbal Lock.
YXZ YXZ Euler, YXZ Rotation Order - prone to Gimbal Lock.
YZX YZX Euler, YZX Rotation Order - prone to Gimbal Lock.
ZXY ZXY Euler, ZXY Rotation Order - prone to Gimbal Lock.
ZYX ZYX Euler, ZYX Rotation Order - prone to Gimbal Lock.
AXIS_ANGLE Axis Angle, Axis Angle (W+XYZ), defines a rotation around some axis defined by 3D-Vector.

bpy.ops.pose.scale_clear()¶: Reset scaling of selected bones to their default values

bpy.ops.pose.select_all(action='TOGGLE')¶

Toggle selection status of all bones

Parameters

action (enum in ['TOGGLE', 'SELECT', 'DESELECT', 'INVERT'], (optional)) –

Action, Selection action to execute

TOGGLE Toggle, Toggle selection for all elements.
SELECT Select, Select all elements.
DESELECT Deselect, Deselect all elements.
INVERT Invert, Invert selection of all elements.

bpy.ops.pose.select_constraint_target()¶: Select bones used as targets for the currently selected bones

bpy.ops.pose.select_grouped(extend=False, type='LAYER')¶

Select all visible bones grouped by similar properties

Parameters

extend (boolean, (optional)) – Extend, Extend selection instead of deselecting everything first
type (enum in ['LAYER', 'GROUP', 'KEYINGSET'], (optional)) –
Type
- LAYER Layer, Shared layers.
- GROUP Group, Shared group.
- KEYINGSET Keying Set, All bones affected by active Keying Set.

bpy.ops.pose.select_hierarchy(direction='PARENT', extend=False)¶

Select immediate parent/children of selected bones

Parameters

direction (enum in ['PARENT', 'CHILD'], (optional)) – Direction
extend (boolean, (optional)) – Extend, Extend the selection

bpy.ops.pose.select_linked()¶: Select all bones linked by parent/child connections to the current selection

bpy.ops.pose.select_linked_pick(extend=False)¶

Select bones linked by parent/child connections under the mouse cursor

Parameters: extend (boolean, (optional)) – Extend, Extend selection instead of deselecting everything first

bpy.ops.pose.select_mirror(only_active=False, extend=False)¶

Mirror the bone selection

Parameters

only_active (boolean, (optional)) – Active Only, Only operate on the active bone
extend (boolean, (optional)) – Extend, Extend the selection

bpy.ops.pose.select_parent()¶: Select bones that are parents of the currently selected bones

bpy.ops.pose.transforms_clear()¶: Reset location, rotation, and scaling of selected bones to their default values

bpy.ops.pose.user_transforms_clear(only_selected=True)¶

Reset pose bone transforms to keyframed state

Parameters: only_selected (boolean, (optional)) – Only Selected, Only visible/selected bones

bpy.ops.pose.visual_transform_apply()¶: Apply final constrained position of pose bones to their transform