automatchBiped(_:to:jointOffsets:)

Creates a retargeting configuration for bipedal characters using automatic joint matching.

Declaration

@MainActor static func automatchBiped(_ sourceSkeleton: SkeletonResource, to targetSkeleton: SkeletonResource, jointOffsets: [String : simd_quatf] = [:]) throws -> RetargetingConfiguration

Parameters

sourceSkeleton:
The skeleton of the animation to retarget.
targetSkeleton:
The skeleton that will receive the re-targeted animation.
jointOffsets:
Optional quaternion offsets applied to specific joints during configuration creation. Keys must match joint names in the target skeleton. The function applies offsets on top of the automatically detected joint correspondences and bakes them into the configuration.

Return Value

A configured retargeting instance ready for animation processing.

Discussion

This method uses an automatic matching algorithm to analyze both skeletal hierarchies and establish correspondences between key joints. The algorithm performs joint identification to locate required anatomical landmarks and generates a retargeting configuration accordingly.

Required Joints

The algorithm identifies and requires the following joints in both skeletons:

Core: Hips, Spine Base, Chest, Neck Base, Head
Arms: Left/Right Shoulder, Upper Arm, Elbow, Wrist
Legs: Left/Right Upper Leg, Knee, Ankle, Toe

Optional Joints

The algorithm can optionally identify and use:

Toe End joints (Left/Right Toe End)
Finger Base joints (Left/Right Finger Base 0-4)

Algorithm Behavior

Performs automatic joint identification using joint names and hierarchical structure.
Supports T-pose and A-pose configurations.
May optimize the resulting configuration by culling unnecessary joints.
Applies joint offsets on top of automatically detected correspondences during configuration creation.

Example

do {
    // Basic biped retargeting
    let config = try RetargetingConfiguration.automatchBiped(
        humanoidSourceSkeleton,
        to: humanoidTargetSkeleton
    )

    // With joint adjustments
    let jointOffsets: [String: simd_quatf] = [
        "LeftShoulder": simd_quatf(angle: .pi / 18, axis: simd_float3(0, 0, 1)),
        "RightWrist": simd_quatf(angle: -.pi / 36, axis: simd_float3(1, 0, 0))
    ]
    let refinedConfig = try RetargetingConfiguration.automatchBiped(
        humanoidSourceSkeleton,
        to: humanoidTargetSkeleton,
        jointOffsets: jointOffsets
    )
} catch {
    print("Failed to create retargeting configuration: \(error.localizedDescription)")
}