user: Give a detailed overview of Driver Variables: syntax, arguments, return values, common patterns.

assistant: Variables are references to properties, transformation channels, or the result of a comparison
between transformations of two objects.

Drivers should access object data via *Driver Variables*, rather than direct references in the Python expression,
in order for dependencies to be correctly tracked.

[image reference removed]

Add, Copy, Paste buttons.

Add Input Variable
:   Adds a new Driver Variable.

Copy/Paste Variables
:   Copies the current variable list so it can be pasted into another driver’s variable list.

Name
:   Name for use in scripted expressions.
    The name must start with a letter, and only contain letters, digits, or underscores.

Variable Type
:   The type of variable to use.

    Single Property
    :   [image reference removed]

        Retrieves the value of an RNA property, specified by a data-block reference and a path string.

        In case of transform properties, this will return the exact value of the UI property,
        while Transform Channel will take parenting and/or constraints into account as needed.

        See also [Custom Properties](../../files/custom_properties.xhtml#files-data-blocks-custom-properties).

        ID Type
        :   The ID-block type. For example: Key, Image, Object, Material.

        ID
        :   The ID of the ID-block type. For example: “Material.001”.

        RNA Path
        :   The RNA name of the property, based on a subset of Python attribute access syntax.
            For example: `location.x` or `location[0]` for the X location animation channel
            value (before parenting or constraints), or `["prop_name"]` for a custom property.

        Fallback
        :   If enabled, allows specifying a fallback value to use as the variable value if the RNA Path cannot
            be resolved, instead of causing a driver evaluation failure. For more info see
            [Context Property](#bpy-types-drivervariable-type) below.

    Transform Channel
    :   [image reference removed]

        Retrieves the value of a Transform channel from an object or bone.

        ID
        :   ID of the object. For example: Cube, Armature, Camera.

        Bone
        :   For armatures, the name of the Armature bone. For example: “Bone”, “Bone.002”, “Arm.r”.

        Type
        :   For example, X Location, X Rotation, X Scale.

            The *Average Scale* option retrieves the combined scale value,
            computed as the cubic root of the total change in volume.
            Unlike *X/Y/Z Scale*, this value can be negative if the object is flipped by negative scaling.

        Mode (Rotation)
        :   For rotation channels, specifies the type of rotation data to use, including
            different explicit [Euler](../../glossary/index.xhtml#term-Euler) orders. Defaults to using the Euler order of
            the target. See [Rotation Channel Modes](#rotation-channel-modes).

        Space
        :   World Space, Transform Space, Local Space.

        [image reference removed]

    Rotational Difference
    :   Provides the value of the rotational difference between two objects or bones, in radians.

        Bone
        :   For armatures, the name of the Armature bone. For example: “Bone”, “Bone.002”, “Arm.r”.

    Distance
    :   [image reference removed]

        Provides the value of the distance between two objects or bones.

        Bone
        :   For armatures, the name of the Armature bone. For example: “Bone”, “Bone.002”, “Arm.r”.

        Space
        :   World Space, Transform Space, Local Space.

    Context Property
    :   [image reference removed]

        Provides the value of a property that is implicitly referring to either a scene
        or a view layer of the currently evaluating animation system.
        This is a weak reference which does not lead to the scene or view layer
        referenced from the driver to be linked when linking animation data.

        An example when such properties comes in play is referring to a transformation
        of the active camera. It is possible to set up a driver in a character file,
        and make the driver use the set camera when the character is linked into a set.

        Context
        :   Active Scene, Active View Layer.

        RNA Path
        :   The RNA name of the property, based on a subset of Python attribute access syntax.
            For example: `camera.location.x` or `camera.location[0]` for the camera X location animation
            channel value (before parenting or constraints), or `["prop_name"]` for a custom property.

        Fallback
        :   If enabled, allows specifying a fallback value to use as the variable value if the RNA Path cannot
            be resolved, instead of causing a driver evaluation failure.

            This feature can be very useful for making drivers more robust when implementing scene-global options
            using custom properties. When the object is linked into a different scene, these custom properties may
            not exist there, and the fallbacks can be used to provide sensible default values.

            Fallbacks can also be used to [emulate](workflow_examples.xhtml#driver-attribute-node-emulation)
            the lookup behavior of the View Layer mode of the material
            [Attribute Node](../../render/shader_nodes/input/attribute.xhtml).

Value
:   Shows the value of the variable.

### Rotation Channel Modes

Rotation Transform Channels support a number of operation modes, including:

Auto Euler
:   Uses the [Euler](../../glossary/index.xhtml#term-Euler) order of the target to decompose rotation into channels.

XYZ Euler, …
:   Explicitly specifies the [Euler](../../glossary/index.xhtml#term-Euler) rotation order to use.

Quaternion
:   Provides the [Quaternion](../../glossary/index.xhtml#term-Quaternion) representation of the rotation.

Swing and X/Y/Z Twist
:   Decomposes the rotation into two parts: a [Swing](../../glossary/index.xhtml#term-Swing) rotation that aims the specified
    axis in its final direction, followed by a [Twist](../../glossary/index.xhtml#term-Swing) rotation around that axis.
    This is often necessary for driving corrective [Shape Keys](../shape_keys/index.xhtml)
    and bones for organic joint rotation.

    This decomposition is often produced in rigs by using a helper bone with
    a [Damped Track Constraint](../constraints/tracking/damped_track.xhtml)
    to extract the swing part, and its child with
    [Copy Transforms](../constraints/transform/copy_transforms.xhtml)
    to extract the twist component.

    The channels values for *Swing and Y Twist* are:

    [image reference removed]

    Falloff curves for weighted angles.

    Y Rotation
    :   True angle of the twist rotation.

    W Rotation
    :   True angle of the swing rotation, independent of its direction.

    X Rotation, Z Rotation
    :   Weighted angles that represent the amount of swing around the X/Z axis.

        The magnitude of the angle equals *W Rotation* when the rotation is purely around
        that axis, and fades out to zero as the direction changes toward the other axis,
        following the falloff curves from the graph on the right.

    Mathematically, the swing angles are computed from quaternion components,
    using \(2 \arccos(w)\) for *W* and \(2 \arcsin(x)\) etc. for the others.
    The component of the swing rotation that corresponds to the twist axis is always 0,
    and is replaced by the twist angle.