AutoMovie API
    Preparing search index...

    Function fitDigitToTarget

    • Put a point of a digit (its tip or its pad, a frame on its distal phalanx) on a world point, with the digit's own joints alone, inside their range of motion: the inverse kinematics of one finger or the thumb with the hand where the pose has placed it.

      Every free axis of every joint of the digit (an axis its constraint does not hold immobile) is a variable, in clinical degrees. The fit has two tasks in priority order. The first puts the effector on the target: its residual is the distance between them. The second, bettered only in what the first leaves free, turns the effector's normal onto the target normal when one is given (the misalignment scaled by the effector's distance from its joint, an arc length, so a degree of tilt counts as the millimetres it swings the phalanx) and keeps a finger's interphalangeal coupling, the distal joint following the middle one at the ratio coupling (the coupling of hand animation, DIP = 2/3 PIP, Rijpkema and Girard 1991, SIGGRAPH 25(4):339-348, as relayed by the hand-animation literature; provisional until read at the source), its residual likewise that distance times the angle by which the distal joint misses the ratio. The point goal, optionally eased by soft IK as described below, is never traded against a normal or a coupling it does not allow.

      Each descent is fitDigitDescent: damped task-priority least squares (Nakamura, Hanafusa and Yoshikawa 1987; Chiaverini 1997) with the active set of a projected Newton method (Bertsekas 1982) for the joints on a bound, and Levenberg-Marquardt damping (Madsen, Nielsen and Tingleff 2004). The Jacobians are read by central differences on the engine's own forward kinematics, so the angles mean what resolvePose displays, and every trial is projected into the range (clampJointToSkeleton) before it is measured. The point counts as reached within the effector's motion for one resolution step of every joint, and a descent stops when its step moves no joint by more than ROM_TOLERANCE, the resolution to which the engine resolves a joint's angle. The fit is a continuation: it descends from the pose's own angles for the digit, so a caller that seeds each fit from the one before follows a moving target in one basin, its joints moving continuously. Only when that fit cannot reach the target (the tip farther from it than one joint resolution of every joint would move it) does it restart from the middle of every range, where a digit folded the wrong way round its target is not trapped, keeping the restart only if it comes nearer; it never takes the better of two starts for a target the continued fit reaches, an argmin that would switch basins between neighbouring targets. A caller's rate softens the target near full extension, where the exact inverse has an unbounded derivative: the exponential soft IK of Andy Nicholas (2006), demonstrated in Jeremie Passerin's "Control Rig: 5.3: Soft IK" (2024, https://dev.epicgames.com/community/learning/tutorials/y4Ll/unreal-engine-control-rig-5-3-soft-ik). Below the soft band the target is unchanged; within it, some reach is traded for a bounded radial extension rate. The band's width comes from the chain's lengths and the requested rate, not the seed's posture. This controls the full-extension singularity, not every possible change of basin of a constrained digit. The result is deterministic for its input: fixed starts, a fixed order of variables and no random draw. A target outside the digit's workspace is fitted as nearly as this constrained local solve reaches it. With rate it fits the eased target instead, so its constrained minimum may differ from the original target's. In either case residual reports distance to the original target, including any reach traded away, so a caller refuses or accepts by its own bound.

      Parameters

      Returns IAutoMovieFitDigitToTarget.IResult

      The digit's fitted joints, the effector's world point and the residual.

      When the digit names no joint, a bone cannot be resolved, or rate is not finite and positive.