user: Show practical ways to work with Bone(bpy_struct) in a Blender add-on or script – include code.

assistant: # Bone(bpy_struct)

base class — [`bpy_struct`](bpy.types.bpy_struct.html#bpy.types.bpy_struct "bpy.types.bpy_struct")

*class* bpy.types.Bone(*bpy_struct*)
:   Bone in an Armature data-block

    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:
        :   [`Bone`](#bpy.types.Bone "bpy.types.Bone")

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

        Type:
        :   [`Bone`](#bpy.types.Bone "bpy.types.Bone")

    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_handle_type_end
    :   Selects how the end handle of the B-Bone is computed

        - `AUTO`
          Automatic – Use connected parent and children to compute the handle.
        - `ABSOLUTE`
          Absolute – Use the position of the specified bone to compute the handle.
        - `RELATIVE`
          Relative – Use the offset of the specified bone from rest pose to compute the handle.
        - `TANGENT`
          Tangent – Use the orientation of the specified bone to compute the handle, ignoring the location.

        Type:
        :   enum in [`'AUTO'`, `'ABSOLUTE'`, `'RELATIVE'`, `'TANGENT'`], default `'AUTO'`

    bbone_handle_type_start
    :   Selects how the start handle of the B-Bone is computed

        - `AUTO`
          Automatic – Use connected parent and children to compute the handle.
        - `ABSOLUTE`
          Absolute – Use the position of the specified bone to compute the handle.
        - `RELATIVE`
          Relative – Use the offset of the specified bone from rest pose to compute the handle.
        - `TANGENT`
          Tangent – Use the orientation of the specified bone to compute the handle, ignoring the location.

        Type:
        :   enum in [`'AUTO'`, `'ABSOLUTE'`, `'RELATIVE'`, `'TANGENT'`], default `'AUTO'`

    bbone_handle_use_ease_end
    :   Multiply the B-Bone Ease Out channel by the local Y scale value of the end handle. This is done after the Scale Easing option and isn’t affected by it.

        Type:
        :   boolean, default False

    bbone_handle_use_ease_start
    :   Multiply the B-Bone Ease In channel by the local Y scale value of the start handle. This is done after the Scale Easing option and isn’t affected by it.

        Type:
        :   boolean, default False

    bbone_handle_use_scale_end
    :   Multiply B-Bone Scale Out channels by the local scale values of the end handle. This is done after the Scale Easing option and isn’t affected by it.

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

    bbone_handle_use_scale_start
    :   Multiply B-Bone Scale In channels by the local scale values of the start handle. This is done after the Scale Easing option and isn’t affected by it.

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

    bbone_mapping_mode
    :   Selects how the vertices are mapped to B-Bone segments based on their position

        - `STRAIGHT`
          Straight – Fast mapping that is good for most situations, but ignores the rest pose curvature of the B-Bone.
        - `CURVED`
          Curved – Slower mapping that gives better deformation for B-Bones that are sharply curved in rest pose.

        Type:
        :   enum in [`'STRAIGHT'`, `'CURVED'`], default `'STRAIGHT'`

    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`](mathutils.html#mathutils.Vector "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`](mathutils.html#mathutils.Vector "mathutils.Vector") of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)

    bbone_segments
    :   Number of subdivisions of bone (for B-Bones only)

        Type:
        :   int in [1, 32], default 0

    bbone_x
    :   B-Bone X size

        Type:
        :   float in [-inf, inf], default 0.0

    bbone_z
    :   B-Bone Z size

        Type:
        :   float in [-inf, inf], default 0.0

    children
    :   Bones which are children of this bone

        Type:
        :   [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`Bone`](#bpy.types.Bone "bpy.types.Bone"), (readonly)

    collections
    :   Bone Collections that contain this bone

        Type:
        :   [`BoneCollectionMemberships`](bpy.types.BoneCollectionMemberships.html#bpy.types.BoneCollectionMemberships "bpy.types.BoneCollectionMemberships") [`bpy_prop_collection`](bpy.types.bpy_prop_collection.html#bpy.types.bpy_prop_collection "bpy.types.bpy_prop_collection") of [`BoneCollection`](bpy.types.BoneCollection.html#bpy.types.BoneCollection "bpy.types.BoneCollection"), (readonly)

    color
    :   Type:
        :   [`BoneColor`](bpy.types.BoneColor.html#bpy.types.BoneColor "bpy.types.BoneColor"), (readonly)

    display_type
    :   - `ARMATURE_DEFINED`
          Armature Defined – Use display mode from armature (default).
        - `OCTAHEDRAL`
          Octahedral – Display bones as octahedral shape.
        - `STICK`
          Stick – Display bones as simple 2D lines with dots.
        - `BBONE`
          B-Bone – Display bones as boxes, showing subdivision and B-Splines.
        - `ENVELOPE`
          Envelope – Display bones as extruded spheres, showing deformation influence volume.
        - `WIRE`
          Wire – Display bones as thin wires, showing subdivision and B-Splines.

        Type:
        :   enum in [`'ARMATURE_DEFINED'`, `'OCTAHEDRAL'`, `'STICK'`, `'BBONE'`, `'ENVELOPE'`, `'WIRE'`], default `'OCTAHEDRAL'`

    envelope_distance
    :   Bone deformation distance (for Envelope deform only)

        Type:
        :   float in [0, 1000], default 0.0

    envelope_weight
    :   Bone deformation weight (for Envelope deform only)

        Type:
        :   float in [0, 1000], default 0.0

    head
    :   Location of head end of the bone relative to its parent

        Type:
        :   [`mathutils.Vector`](mathutils.html#mathutils.Vector "mathutils.Vector") of 3 items in [-inf, inf], default (0.0, 0.0, 0.0), (readonly)

    head_local
    :   Location of head end of the bone relative to armature

        Type:
        :   [`mathutils.Vector`](mathutils.html#mathutils.Vector "mathutils.Vector") of 3 items in [-inf, inf], default (0.0, 0.0, 0.0), (readonly)

    head_radius
    :   Radius of head of bone (for Envelope deform only)

        Type:
        :   float in [-inf, inf], default 0.0

    hide
    :   Bone is not visible when it is in Edit Mode

        Type:
        :   boolean, default False

    hide_select
    :   Bone is able to be selected

        Type:
        :   boolean, default False

    inherit_scale
    :   Specifies how the bone inherits scaling from the parent bone

        - `FULL`
          Full – Inherit all effects of parent scaling.
        - `FIX_SHEAR`
          Fix Shear – Inherit scaling, but remove shearing of the child in the rest orientation.
        - `ALIGNED`
          Aligned – Rotate non-uniform parent scaling to align with the child, applying parent X scale to child X axis, and so forth.
        - `AVERAGE`
          Average – Inherit uniform scaling representing the overall change in the volume of the parent.
        - `NONE`
          None – Completely ignore parent scaling.
        - `NONE_LEGACY`
          None (Legacy) – Ignore parent scaling without compensating for parent shear. Replicates the effect of disabling the original Inherit Scale checkbox..

        Type:
        :   enum in [`'FULL'`, `'FIX_SHEAR'`, `'ALIGNED'`, `'AVERAGE'`, `'NONE'`, `'NONE_LEGACY'`], default `'FULL'`

    length
    :   Length of the bone

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

    matrix
    :   3×3 bone matrix

        Type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 3 \* 3 items in [-inf, inf], default ((0.0, 0.0, 0.0), (0.0, 0.0, 0.0), (0.0, 0.0, 0.0)), (readonly)

    matrix_local
    :   4×4 bone matrix relative to armature

        Type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "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)

    name
    :   Type:
        :   string, default “”, (never None)

    parent
    :   Parent bone (in same Armature)

        Type:
        :   [`Bone`](#bpy.types.Bone "bpy.types.Bone"), (readonly)

    show_wire
    :   Bone is always displayed in wireframe regardless of viewport shading mode (useful for non-obstructive custom bone shapes)

        Type:
        :   boolean, default False

    tail
    :   Location of tail end of the bone relative to its parent

        Type:
        :   [`mathutils.Vector`](mathutils.html#mathutils.Vector "mathutils.Vector") of 3 items in [-inf, inf], default (0.0, 0.0, 0.0), (readonly)

    tail_local
    :   Location of tail end of the bone relative to armature

        Type:
        :   [`mathutils.Vector`](mathutils.html#mathutils.Vector "mathutils.Vector") of 3 items in [-inf, inf], default (0.0, 0.0, 0.0), (readonly)

    tail_radius
    :   Radius of tail of bone (for Envelope deform only)

        Type:
        :   float in [-inf, inf], default 0.0

    use_connect
    :   When bone has a parent, bone’s head is stuck to the parent’s tail

        Type:
        :   boolean, default False, (readonly)

    use_cyclic_offset
    :   When bone does not have a parent, it receives cyclic offset effects (Deprecated)

        Type:
        :   boolean, default False

    use_deform
    :   Enable Bone to deform geometry

        Type:
        :   boolean, default False

    use_endroll_as_inroll
    :   Add Roll Out of the Start Handle bone to the Roll In value

        Type:
        :   boolean, default False

    use_envelope_multiply
    :   When deforming bone, multiply effects of Vertex Group weights with Envelope influence

        Type:
        :   boolean, default False

    use_inherit_rotation
    :   Bone inherits rotation or scale from parent bone

        Type:
        :   boolean, default False

    use_local_location
    :   Bone location is set in local space

        Type:
        :   boolean, default False

    use_relative_parent
    :   Object children will use relative transform, like deform

        Type:
        :   boolean, default False

    use_scale_easing
    :   Multiply the final easing values by the Scale In/Out Y factors

        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_recursive
    :   A list of all children from this bone.

        (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.

        (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** (*boolean**,* *(**optional**)*) – Ensure that system properties are created if they do not exist yet

        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`](bpy.types.PropertyGroup.html#bpy.types.PropertyGroup "bpy.types.PropertyGroup")

    evaluate_envelope(*point*)
    :   Calculate bone envelope at given point

        Parameters:
        :   **point** ([`mathutils.Vector`](mathutils.html#mathutils.Vector "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]

    convert_local_to_pose(*matrix*, *matrix_local*, *\**, *parent_matrix=((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))*, *parent_matrix_local=((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))*, *invert=False*)
    :   Transform a matrix from Local to Pose space (or back), taking into account options like Inherit Scale and Local Location. Unlike Object.convert_space, this uses custom rest and pose matrices provided by the caller. If the parent matrices are omitted, the bone is assumed to have no parent.

        Parameters:
        :   - **matrix** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf]) – The matrix to transform
            - **matrix_local** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf]) – The custom rest matrix of this bone (Bone.matrix_local)
            - **parent_matrix** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf], (optional)) – The custom pose matrix of the parent bone (PoseBone.matrix)
            - **parent_matrix_local** ([`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf], (optional)) – The custom rest matrix of the parent bone (Bone.matrix_local)
            - **invert** (*boolean**,* *(**optional**)*) – Convert from Pose to Local space

        Returns:
        :   The transformed matrix

        Return type:
        :   [`mathutils.Matrix`](mathutils.html#mathutils.Matrix "mathutils.Matrix") of 4 \* 4 items in [-inf, inf]

        This method enables conversions between Local and Pose space for bones in
        the middle of updating the armature without having to update dependencies
        after each change, by manually carrying updated matrices in a recursive walk.

        ```
        def set_pose_matrices(obj, matrix_map):
            "Assign pose space matrices of all bones at once, ignoring constraints."

            def rec(pbone, parent_matrix):
                if pbone.name in matrix_map:
                    matrix = matrix_map[pbone.name]

                    # # Instead of:
                    # pbone.matrix = matrix
                    # bpy.context.view_layer.update()

                    # Compute and assign local matrix, using the new parent matrix.
                    if pbone.parent:
                        pbone.matrix_basis = pbone.bone.convert_local_to_pose(
                            matrix,
                            pbone.bone.matrix_local,
                            parent_matrix=parent_matrix,
                            parent_matrix_local=pbone.parent.bone.matrix_local,
                            invert=True
                        )
                    else:
                        pbone.matrix_basis = pbone.bone.convert_local_to_pose(
                            matrix,
                            pbone.bone.matrix_local,
                            invert=True
                        )
                else:
                    # Compute the updated pose matrix from local and new parent matrix.
                    if pbone.parent:
                        matrix = pbone.bone.convert_local_to_pose(
                            pbone.matrix_basis,
                            pbone.bone.matrix_local,
                            parent_matrix=parent_matrix,
                            parent_matrix_local=pbone.parent.bone.matrix_local,
                        )
                    else:
                        matrix = pbone.bone.convert_local_to_pose(
                            pbone.matrix_basis,
                            pbone.bone.matrix_local,
                        )

                # Recursively process children, passing the new matrix through.
                fo