PoseBone(bpy_struct)#

base class — bpy_struct

class bpy.types.PoseBone(bpy_struct)#

Channel defining pose data for a bone in a Pose

bbone_curveinx#

X-axis handle offset for start of the B-Bone’s curve, adjusts curvature

Type:

float in [-inf, inf], default 0.0

bbone_curveinz#

Z-axis handle offset for start of the B-Bone’s curve, adjusts curvature

Type:

float in [-inf, inf], default 0.0

bbone_curveoutx#

X-axis handle offset for end of the B-Bone’s curve, adjusts curvature

Type:

float in [-inf, inf], default 0.0

bbone_curveoutz#

Z-axis handle offset for end of the B-Bone’s curve, adjusts curvature

Type:

float in [-inf, inf], default 0.0

bbone_custom_handle_end#

Bone that serves as the end handle for the B-Bone curve

Type:

PoseBone, (readonly)

bbone_custom_handle_start#

Bone that serves as the start handle for the B-Bone curve

Type:

PoseBone, (readonly)

bbone_easein#

Length of first Bézier Handle (for B-Bones only)

Type:

float in [-inf, inf], default 1.0

bbone_easeout#

Length of second Bézier Handle (for B-Bones only)

Type:

float in [-inf, inf], default 1.0

bbone_rollin#

Roll offset for the start of the B-Bone, adjusts twist

Type:

float in [-inf, inf], default 0.0

bbone_rollout#

Roll offset for the end of the B-Bone, adjusts twist

Type:

float in [-inf, inf], default 0.0

bbone_scalein#

Scale factors for the start of the B-Bone, adjusts thickness (for tapering effects)

Type:

mathutils.Vector of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

bbone_scaleout#

Scale factors for the end of the B-Bone, adjusts thickness (for tapering effects)

Type:

mathutils.Vector of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

bone#

Bone associated with this PoseBone

Type:

Bone, (readonly, never None)

child#

Child of this pose bone

Type:

PoseBone, (readonly)

color#
Type:

BoneColor, (readonly)

constraints#

Constraints that act on this pose channel

Type:

PoseBoneConstraints bpy_prop_collection of Constraint, (readonly)

custom_shape#

Object that defines custom display shape for this bone

Type:

Object

custom_shape_rotation_euler#

Adjust the rotation of the custom shape

Type:

mathutils.Euler rotation of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

custom_shape_scale_xyz#

Adjust the size of the custom shape

Type:

mathutils.Vector of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

custom_shape_transform#

Bone that defines the display transform of this custom shape

Type:

PoseBone

custom_shape_translation#

Adjust the location of the custom shape

Type:

mathutils.Vector of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

head#

Location of head of the channel’s bone

Type:

mathutils.Vector of 3 items in [-inf, inf], default (0.0, 0.0, 0.0), (readonly)

ik_linear_weight#

Weight of scale constraint for IK

Type:

float in [0, 1], default 0.0

ik_max_x#

Maximum angles for IK Limit

Type:

float in [0, 3.14159], default 0.0

ik_max_y#

Maximum angles for IK Limit

Type:

float in [0, 3.14159], default 0.0

ik_max_z#

Maximum angles for IK Limit

Type:

float in [0, 3.14159], default 0.0

ik_min_x#

Minimum angles for IK Limit

Type:

float in [-3.14159, 0], default 0.0

ik_min_y#

Minimum angles for IK Limit

Type:

float in [-3.14159, 0], default 0.0

ik_min_z#

Minimum angles for IK Limit

Type:

float in [-3.14159, 0], default 0.0

ik_rotation_weight#

Weight of rotation constraint for IK

Type:

float in [0, 1], default 0.0

ik_stiffness_x#

IK stiffness around the X axis

Type:

float in [0, 0.99], default 0.0

ik_stiffness_y#

IK stiffness around the Y axis

Type:

float in [0, 0.99], default 0.0

ik_stiffness_z#

IK stiffness around the Z axis

Type:

float in [0, 0.99], default 0.0

ik_stretch#

Allow scaling of the bone for IK

Type:

float in [0, 1], default 0.0

is_in_ik_chain#

Is part of an IK chain

Type:

boolean, default False, (readonly)

length#

Length of the bone

Type:

float in [-inf, inf], default 0.0, (readonly)

location#
Type:

mathutils.Vector of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

lock_ik_x#

Disallow movement around the X axis

Type:

boolean, default False

lock_ik_y#

Disallow movement around the Y axis

Type:

boolean, default False

lock_ik_z#

Disallow movement around the Z axis

Type:

boolean, default False

lock_location#

Lock editing of location when transforming

Type:

boolean array of 3 items, default (False, False, False)

lock_rotation#

Lock editing of rotation when transforming

Type:

boolean array of 3 items, default (False, False, False)

lock_rotation_w#

Lock editing of ‘angle’ component of four-component rotations when transforming

Type:

boolean, default False

lock_rotations_4d#

Lock editing of four component rotations by components (instead of as Eulers)

Type:

boolean, default False

lock_scale#

Lock editing of scale when transforming

Type:

boolean array of 3 items, default (False, False, False)

matrix#

Final 4×4 matrix after constraints and drivers are applied, in the armature object space

Type:

mathutils.Matrix of 4 * 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0))

matrix_basis#

Alternative access to location/scale/rotation relative to the parent and own rest bone

Type:

mathutils.Matrix of 4 * 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0))

matrix_channel#

4×4 matrix of the bone’s location/rotation/scale channels (including animation and drivers) and the effect of bone constraints

Type:

mathutils.Matrix of 4 * 4 items in [-inf, inf], default ((0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0), (0.0, 0.0, 0.0, 0.0)), (readonly)

motion_path#

Motion Path for this element

Type:

MotionPath, (readonly)

name#
Type:

string, default “”, (never None)

parent#

Parent of this pose bone

Type:

PoseBone, (readonly)

rotation_axis_angle#

Angle of Rotation for Axis-Angle rotation representation

Type:

float array of 4 items in [-inf, inf], default (0.0, 0.0, 1.0, 0.0)

rotation_euler#

Rotation in Eulers

Type:

mathutils.Euler rotation of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)

rotation_mode#
Type:

enum in Object Rotation Mode Items, default ‘QUATERNION’

rotation_quaternion#

Rotation in Quaternions

Type:

mathutils.Quaternion rotation of 4 items in [-inf, inf], default (1.0, 0.0, 0.0, 0.0)

scale#
Type:

mathutils.Vector of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

tail#

Location of tail of the channel’s bone

Type:

mathutils.Vector of 3 items in [-inf, inf], default (0.0, 0.0, 0.0), (readonly)

use_custom_shape_bone_size#

Scale the custom object by the bone length

Type:

boolean, default False

use_ik_limit_x#

Limit movement around the X axis

Type:

boolean, default False

use_ik_limit_y#

Limit movement around the Y axis

Type:

boolean, default False

use_ik_limit_z#

Limit movement around the Z axis

Type:

boolean, default False

use_ik_linear_control#

Apply channel size as IK constraint if stretching is enabled

Type:

boolean, default False

use_ik_rotation_control#

Apply channel rotation as IK constraint

Type:

boolean, default False

basename#

The name of this bone before any ‘.’ character

(readonly)

center#

The midpoint between the head and the tail.

(readonly)

children#

(readonly)

children_recursive#

A list of all children from this bone.

Note

Takes O(len(bones)**2) time.

(readonly)

children_recursive_basename#

Returns a chain of children with the same base name as this bone. Only direct chains are supported, forks caused by multiple children with matching base names will terminate the function and not be returned.

Note

Takes O(len(bones)**2) time.

(readonly)

parent_recursive#

A list of parents, starting with the immediate parent

(readonly)

vector#

The direction this bone is pointing. Utility function for (tail - head)

(readonly)

x_axis#

Vector pointing down the x-axis of the bone.

(readonly)

y_axis#

Vector pointing down the y-axis of the bone.

(readonly)

z_axis#

Vector pointing down the z-axis of the bone.

(readonly)

evaluate_envelope(point)#

Calculate bone envelope at given point

Parameters:

point (mathutils.Vector of 3 items in [-inf, inf]) – Point, Position in 3d space to evaluate

Returns:

Factor, Envelope factor

Return type:

float in [-inf, inf]

bbone_segment_index(point)#

Retrieve the index and blend factor of the B-Bone segments based on vertex position

Parameters:

point (mathutils.Vector of 3 items in [-inf, inf]) – Point, Vertex position in armature pose space

Return (index, blend_next):

index, The index of the first segment joint affecting the point, int in [-inf, inf]

blend_next, The blend factor between the given and the following joint, float in [-inf, inf]

bbone_segment_matrix(index, rest=False)#

Retrieve the matrix of the joint between B-Bone segments if available

Parameters:
  • index (int in [0, inf]) – Index of the segment endpoint

  • rest (boolean, (optional)) – Return the rest pose matrix

Returns:

The resulting matrix in bone local space

Return type:

mathutils.Matrix of 4 * 4 items in [-inf, inf]

This example shows how to use B-Bone segment matrices to emulate deformation produced by the Armature modifier or constraint when assigned to the given bone (without Preserve Volume). The coordinates are processed in armature Pose space:

def bbone_deform_matrix(pose_bone, point):
    index, blend_next = pose_bone.bbone_segment_index(point)

    rest1 = pose_bone.bbone_segment_matrix(index, rest=True)
    pose1 = pose_bone.bbone_segment_matrix(index, rest=False)
    deform1 = pose1 @ rest1.inverted()

    # bbone_segment_index ensures that index + 1 is always valid
    rest2 = pose_bone.bbone_segment_matrix(index + 1, rest=True)
    pose2 = pose_bone.bbone_segment_matrix(index + 1, rest=False)
    deform2 = pose2 @ rest2.inverted()

    deform = deform1 * (1 - blend_next) + deform2 * blend_next

    return pose_bone.matrix @ deform @ pose_bone.bone.matrix_local.inverted()


# Armature modifier deforming vertices:
mesh = bpy.data.objects["Mesh"]
pose_bone = bpy.data.objects["Armature"].pose.bones["Bone"]

for vertex in mesh.data.vertices:
    vertex.co = bbone_deform_matrix(pose_bone, vertex.co) @ vertex.co

# Armature constraint modifying an object transform:
empty = bpy.data.objects["Empty"]
matrix = empty.matrix_world

empty.matrix_world = bbone_deform_matrix(pose_bone, matrix.translation) @ matrix
compute_bbone_handles(rest=False, ease=False, offsets=False)#

Retrieve the vectors and rolls coming from B-Bone custom handles

Parameters:
  • rest (boolean, (optional)) – Return the rest pose state

  • ease (boolean, (optional)) – Apply scale from ease values

  • offsets (boolean, (optional)) – Apply roll and curve offsets from bone properties

Return (handle1, roll1, handle2, roll2):

handle1, The direction vector of the start handle in bone local space, mathutils.Vector of 3 items in [-inf, inf]

roll1, Roll of the start handle, float in [-inf, inf]

handle2, The direction vector of the end handle in bone local space, mathutils.Vector of 3 items in [-inf, inf]

roll2, Roll of the end handle, float in [-inf, inf]

parent_index(parent_test)#

The same as ‘bone in other_bone.parent_recursive’ but saved generating a list.

translate(vec)#

Utility function to add vec to the head and tail of this bone

classmethod bl_rna_get_subclass(id, default=None)#
Parameters:

id (string) – The RNA type identifier.

Returns:

The RNA type or default when not found.

Return type:

bpy.types.Struct subclass

classmethod bl_rna_get_subclass_py(id, default=None)#
Parameters:

id (string) – The RNA type identifier.

Returns:

The class or default when not found.

Return type:

type

Inherited Properties

Inherited Functions

References