A configuration for retargeting skeletal animations between different skeletons.
``RetargetingConfiguration`` enables the transfer of animations from one skeleton
to another, automatically mapping joints and adapting poses to accommodate different
skeletal structures. This is particularly useful for applying animations across different
character models or creatures.
## Usage
Create configurations using the static factory methods for common skeleton types:
- ``automatchBiped(_:to:jointOffsets:)`` for humanoid/bipedal characters
- ``automatchQuadruped(_:sourceTransform:to:targetTransform:jointOffsets:)`` for four-legged creatures
## Example
```swift
do {
// Basic biped retargeting
let config = try RetargetingConfiguration.automatchBiped(
sourceCharacterSkeleton,
to: targetCharacterSkeleton
)
// With joint offset adjustments applied during configuration creation
let jointOffsets: [String: simd_quatf] = [
"LeftShoulder": simd_quatf(angle: 0.1, axis: simd_float3(0, 1, 0)),
"RightShoulder": simd_quatf(angle: -0.1, axis: simd_float3(0, 1, 0))
]
let configWithOffsets = try RetargetingConfiguration.automatchBiped(
sourceCharacterSkeleton,
to: targetCharacterSkeleton,
jointOffsets: jointOffsets
)
} catch {
print("Failed to create retargeting configuration: \(error.localizedDescription)")
}
```
## Performance Considerations
- Configuration creation is computationally expensive and should be cached when possible.
- The automatic matching algorithm analyzes skeleton hierarchies to establish joint correspondences.
- Joint offsets are baked into the configuration during creation, not applied at runtime.
Creates a retargeting configuration for bipedal characters with custom root transforms.
This overload allows you to specify custom transforms for the root bones of both skeletons,
which is useful when the characters are positioned or oriented differently in their bind poses.
The function applies the transforms during the automatic matching process to establish proper correspondences.
The automatic matching algorithm has the same joint requirements and behavior as ``automatchBiped(_:to:jointOffsets:)``.
## Example
```swift
do {
// Source character facing +Z, target facing +X
let sourceTransform = Transform(rotation: simd_quatf(angle: 0, axis: simd_float3(0, 1, 0)))
let targetTransform = Transform(rotation: simd_quatf(angle: .pi/2, axis: simd_float3(0, 1, 0)))
let config = try RetargetingConfiguration.automatchBiped(
sourceSkeleton,
sourceTransform: sourceTransform,
to: targetSkeleton,
targetTransform: targetTransform
)
} catch {
print("Failed to create retargeting configuration: \(error.localizedDescription)")
}
```
- Parameters:
- sourceSkeleton: The skeleton of the animation to retarget.
- sourceTransform: Transform applied to the source skeleton's root during matching (defaults to identity).
- targetSkeleton: The skeleton that will receive the re-targeted animation.
- targetTransform: Transform applied to the target skeleton's root during matching (defaults to identity).
- 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.
- Returns: A configured retargeting instance ready for animation processing.
- Throws: An error if configuration creation fails. All errors provide descriptive messages via their
`localizedDescription` property. Common failures include:
- A joint offset was specified for a joint name that doesn't exist in the target skeleton.
- The algorithm could not identify required joints in one or both skeletons.
- Joint identification or rig generation failed.
Creates a retargeting configuration for bipedal characters using automatic joint matching.
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
```swift
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)")
}
```
- 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.
- Returns: A configured retargeting instance ready for animation processing.
- Throws: An error if configuration creation fails. All errors provide descriptive messages via their
`localizedDescription` property. Common failures include:
- A joint offset was specified for a joint name that doesn't exist in the target skeleton.
- The algorithm could not identify required joints in one or both skeletons.
- Joint identification or rig generation failed.
Creates a retargeting configuration for quadrupedal characters using automatic joint matching.
- Parameters:
- sourceSkeleton: The skeleton of the animation to retarget.
- sourceTransform: Transform applied to the source skeleton's root during matching (defaults to identity).
- targetSkeleton: The skeleton that will receive the re-targeted animation.
- targetTransform: Transform applied to the target skeleton's root during matching (defaults to identity).
- 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.
- Returns: A configured retargeting instance ready for animation processing.
- Throws: An error if configuration creation fails. All errors provide descriptive messages via their
`localizedDescription` property. Common failures include:
- A joint offset was specified for a joint name that doesn't exist in the target skeleton.
- The algorithm could not identify required joints in one or both skeletons.
- Joint identification or rig generation failed.
