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 (in [-inf, inf], default 0.0)

Type:

float

bbone_curveinz

Z-axis handle offset for start of the B-Bone’s curve, adjusts curvature (in [-inf, inf], default 0.0)

Type:

float

bbone_curveoutx

X-axis handle offset for end of the B-Bone’s curve, adjusts curvature (in [-inf, inf], default 0.0)

Type:

float

bbone_curveoutz

Z-axis handle offset for end of the B-Bone’s curve, adjusts curvature (in [-inf, inf], default 0.0)

Type:

float

bbone_custom_handle_end

Bone that serves as the end handle for the B-Bone curve (readonly)

Type:

PoseBone

bbone_custom_handle_start

Bone that serves as the start handle for the B-Bone curve (readonly)

Type:

PoseBone

bbone_easein

Length of first Bézier Handle (for B-Bones only) (in [-inf, inf], default 0.0)

Type:

float

bbone_easeout

Length of second Bézier Handle (for B-Bones only) (in [-inf, inf], default 0.0)

Type:

float

bbone_rollin

Roll offset for the start of the B-Bone, adjusts twist (in [-inf, inf], default 0.0)

Type:

float

bbone_rollout

Roll offset for the end of the B-Bone, adjusts twist (in [-inf, inf], default 0.0)

Type:

float

bbone_scalein

Scale factors for the start of the B-Bone, adjusts thickness (for tapering effects) (array of 3 items, in [-inf, inf], default (1.0, 1.0, 1.0))

Type:

mathutils.Vector

bbone_scaleout

Scale factors for the end of the B-Bone, adjusts thickness (for tapering effects) (array of 3 items, in [-inf, inf], default (1.0, 1.0, 1.0))

Type:

mathutils.Vector

bone

Bone associated with this PoseBone (readonly, never None)

Type:

Bone

child

Child of this pose bone (readonly)

Type:

PoseBone

color

(readonly)

Type:

BoneColor

constraints

Constraints that act on this pose channel (default None, readonly)

Type:

PoseBoneConstraints[Constraint]

custom_shape

Object that defines custom display shape for this bone

Type:

Object

custom_shape_rotation_euler

Adjust the rotation of the custom shape (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Euler

custom_shape_scale_xyz

Adjust the size of the custom shape (array of 3 items, in [-inf, inf], default (1.0, 1.0, 1.0))

Type:

mathutils.Vector

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 (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Vector

custom_shape_wire_width

Adjust the line thickness of custom shapes (in [1, 16], default 0.0)

Type:

float

head

Location of head of the channel’s bone (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0), readonly)

Type:

mathutils.Vector

hide

Bone is not visible except for Edit Mode (default False)

Type:

bool

ik_linear_weight

Weight of scale constraint for IK (in [0, 1], default 0.0)

Type:

float

ik_max_x

Maximum angles for IK Limit (in [0, 3.14159], default 0.0)

Type:

float

ik_max_y

Maximum angles for IK Limit (in [0, 3.14159], default 0.0)

Type:

float

ik_max_z

Maximum angles for IK Limit (in [0, 3.14159], default 0.0)

Type:

float

ik_min_x

Minimum angles for IK Limit (in [-3.14159, 0], default 0.0)

Type:

float

ik_min_y

Minimum angles for IK Limit (in [-3.14159, 0], default 0.0)

Type:

float

ik_min_z

Minimum angles for IK Limit (in [-3.14159, 0], default 0.0)

Type:

float

ik_rotation_weight

Weight of rotation constraint for IK (in [0, 1], default 0.0)

Type:

float

ik_stiffness_x

IK stiffness around the X axis (in [0, 0.99], default 0.0)

Type:

float

ik_stiffness_y

IK stiffness around the Y axis (in [0, 0.99], default 0.0)

Type:

float

ik_stiffness_z

IK stiffness around the Z axis (in [0, 0.99], default 0.0)

Type:

float

ik_stretch

Allow scaling of the bone for IK (in [0, 1], default 0.0)

Type:

float

is_in_ik_chain

Is part of an IK chain (default False, readonly)

Type:

bool

length

Length of the bone (in [-inf, inf], default 0.0, readonly)

Type:

float

location

(array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Vector

lock_ik_x

Disallow movement around the X axis (default False)

Type:

bool

lock_ik_y

Disallow movement around the Y axis (default False)

Type:

bool

lock_ik_z

Disallow movement around the Z axis (default False)

Type:

bool

lock_location

Lock editing of location when transforming (array of 3 items, default (False, False, False))

Type:

bpy_prop_array[bool]

lock_rotation

Lock editing of rotation when transforming (array of 3 items, default (False, False, False))

Type:

bpy_prop_array[bool]

lock_rotation_w

Lock editing of ‘angle’ component of four-component rotations when transforming (default False)

Type:

bool

lock_rotations_4d

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

Type:

bool

lock_scale

Lock editing of scale when transforming (array of 3 items, default (False, False, False))

Type:

bpy_prop_array[bool]

matrix

Final 4×4 matrix after constraints and drivers are applied, in the armature object space (multi-dimensional array 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)))

Type:

mathutils.Matrix

matrix_basis

Alternative access to location/scale/rotation relative to the parent and own rest bone (multi-dimensional array 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)))

Type:

mathutils.Matrix

matrix_channel

4×4 matrix of the bone’s location/rotation/scale channels (including animation and drivers) and the effect of bone constraints (multi-dimensional array 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)

Type:

mathutils.Matrix

motion_path

Motion Path for this element (readonly)

Type:

MotionPath

name

(default “”, never None)

Type:

str

parent

Parent of this pose bone (readonly)

Type:

PoseBone

rotation_axis_angle

Angle of Rotation for Axis-Angle rotation representation (array of 4 items, in [-inf, inf], default (0.0, 0.0, 1.0, 0.0))

Type:

bpy_prop_array[float]

rotation_euler

Rotation in Eulers (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0))

Type:

mathutils.Euler

rotation_mode

The kind of rotation to apply, values from other rotation modes are not used (default 'QUATERNION')

Type:

Literal[Object Rotation Mode Items]

rotation_quaternion

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

Type:

mathutils.Quaternion

scale

(array of 3 items, in [-inf, inf], default (1.0, 1.0, 1.0))

Type:

mathutils.Vector

select

Bone is selected in Pose Mode (default False)

Type:

bool

tail

Location of tail of the channel’s bone (array of 3 items, in [-inf, inf], default (0.0, 0.0, 0.0), readonly)

Type:

mathutils.Vector

use_custom_shape_bone_size

Scale the custom object by the bone length (default True)

Type:

bool

use_ik_limit_x

Limit movement around the X axis (default False)

Type:

bool

use_ik_limit_y

Limit movement around the Y axis (default False)

Type:

bool

use_ik_limit_z

Limit movement around the Z axis (default False)

Type:

bool

use_ik_linear_control

Apply channel size as IK constraint if stretching is enabled (default False)

Type:

bool

use_ik_rotation_control

Apply channel rotation as IK constraint (default False)

Type:

bool

use_transform_around_custom_shape

Transform the bone as if it was a child of the Custom Shape Transform bone. This can be useful when combining shape-key and armature deformations. (default False)

Type:

bool

use_transform_at_custom_shape

The location and orientation of the Custom Shape Transform bone will be used for transform gizmos and for other transform operators in the 3D Viewport. When disabled, the 3D Viewport will still use the actual bone transform for these, even when the custom bone shape transform is overridden. (default False)

Type:

bool

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)

bl_system_properties_get(*, do_create=False)

DEBUG ONLY. Internal access to runtime-defined RNA data storage, intended solely for testing and debugging purposes. Do not access it in regular scripting work, and in particular, do not assume that it contains writable data

Parameters:

do_create (bool) – Ensure that system properties are created if they do not exist yet (optional)

Returns:

The system properties root container, or None if there are no system properties stored in this data yet, and its creation was not requested

Return type:

PropertyGroup

evaluate_envelope(point)

Calculate bone envelope at given point

Parameters:

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

Returns:

Factor, Envelope factor (in [-inf, inf])

Return type:

float

bbone_segment_index(point)

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

Parameters:

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

Returns:

index, The index of the first segment joint affecting the point, int

blend_next, The blend factor between the given and the following joint, float

Return type:

tuple[int, float]

bbone_segment_matrix(index, *, rest=False)

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

Parameters:

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

• rest (bool) – Return the rest pose matrix (optional)

Returns:

The resulting matrix in bone local space (multi-dimensional array of 4 * 4 items, in [-inf, inf])

Return type:

mathutils.Matrix

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:

import bpy


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 (bool) – Return the rest pose state (optional)

• ease (bool) – Apply scale from ease values (optional)

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

Returns:

handle1, The direction vector of the start handle in bone local space, mathutils.Vector

roll1, Roll of the start handle, float

handle2, The direction vector of the end handle in bone local space, mathutils.Vector

roll2, Roll of the end handle, float

Return type:

tuple[mathutils.Vector, float, mathutils.Vector, float]

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 (str) – The RNA type identifier.

• default (bpy.types.Struct | None) – The value to return when not found.

Returns:

The RNA type or default when not found.

Return type:

bpy.types.Struct

classmethod bl_rna_get_subclass_py(id, default=None, /)

Parameters:

• id (str) – The RNA type identifier.

• default (type | None) – The value to return when not found.

Returns:

The class or default when not found.

Return type:

type

Inherited Properties

bpy_struct.id_data

Inherited Functions

bpy_struct.as_pointer bpy_struct.driver_add bpy_struct.driver_remove bpy_struct.get bpy_struct.id_properties_clear bpy_struct.id_properties_ensure bpy_struct.id_properties_ui bpy_struct.is_property_hidden bpy_struct.is_property_overridable_library bpy_struct.is_property_readonly bpy_struct.is_property_set bpy_struct.items

bpy_struct.keyframe_delete bpy_struct.keyframe_insert bpy_struct.keys bpy_struct.path_from_id bpy_struct.path_from_module bpy_struct.path_resolve bpy_struct.pop bpy_struct.property_overridable_library_set bpy_struct.property_unset bpy_struct.rna_ancestors bpy_struct.type_recast bpy_struct.values

References

bpy.context.active_pose_bone bpy.context.pose_bone bpy.context.selected_pose_bones bpy.context.selected_pose_bones_from_active_object bpy.context.visible_pose_bones Object.convert_space

Pose.bones PoseBone.bbone_custom_handle_end PoseBone.bbone_custom_handle_start PoseBone.child PoseBone.custom_shape_transform PoseBone.parent