Optionalexcluded?: (Given the root's bone-local rotation at a swivel on one bend branch,
degrees, a test of whether every swivel from low to high degrees is
certain to score a positive overshoot (boxExcludedSwivels); omitted,
every step is scored. Only a certainty may be returned: the returned pose
is then the one the full sweep gives.
The factory and returned predicate run synchronously during this solve;
exceptions propagate and neither is retained after return. They must not
mutate rotations supplied by upper.
Optionalnear?: IAutoMovieSwivelNearThe seed of a fit of a nearby target to continue (IAutoMovieSwivelNear):
its branch, or the last branch when the target has fewer (two branches
meet at the span's ends), and its swivel refined within one step either
way to its tolerance, with no sweep; omitted, every swivel is swept.
Score one candidate's bone-local root and mid rotations: overshoot is
the total ROM overshoot in degrees, compared first, and deviation the
effort tie-break, compared second. The caller owns the decomposition
convention and the rig's constraints. With exact, deviation is a
lower bound of the tie-break and exact gives it exactly: a caller
whose tie-break ends in a costly non-negative term passes the rest as
the bound, and the term is computed only for a comparison the bound
cannot decide. With tie, tiebreak is a second key: two deviations
within tie of each other are one, and the lesser tiebreak decides
(task priority, Siciliano and Slotine 1991: the second objective only
among the first's optima).
Scoring is synchronous and may evaluate many candidates; the callback
must be deterministic, leave its borrowed rotations unchanged and return
finite scores. Exceptions abort the solve, and no score callback is kept
after the result is returned.
Optionaltie?: numberHow far apart two deviations may lie and still be one, the unit of
deviation, for a score with a second key (tiebreak); omitted, deviations
are compared exactly and tiebreak is not read.
Two-bone arm IK whose mid joint bends only about its own flexion hinge, with the chain root's free swivel spent on the rig's range of motion.
The elbow rotates by
θabouthingealone, so its abduction and twist decompose to zero, which is what an elbow's immobile axes require, and the bend plane is the hinge's own plane. Splitting the far segment into the part along the hinge and the part it swings gives the root-to-effector spanso the span equals the target distance where
R·cos(θ − φ) = distance² − k, withR = hypot(α, β)andφ = atan2(β, α): an arccos whose two roots are the chain's two bend branches. A target outside the reachable span takes the fully extended or fully folded root, so the effector stops on the reachable shell along the line to the target. A root outside the mid joint's ownrangestops at the nearer limit in the same way, the effector resting on the legal shell along that line and the result reporting theshortfall; of two branches the one stopping nearer the target is swept, because a candidate past the hinge's limit would be clamped by the caller afterwards and land somewhere no candidate was scored at.The root joint first aims
m(θ)at the target, then any extra rotation aboutm(θ)leaves the effector where it is. The function sweeps that swivel inSWIVEL_STEPincrements on each branch, ordering candidates by the leastovershoot(legal, zero, ahead of any other exactly; two positive ones tied within the decomposition's rounding,OVERSHOOT_ROUNDING), then the leastdeviation, both fromscore. Every local minimum of a sweep is then refined between its neighbouring steps by golden-section search under the same ordering, and the best of the sweeps and the refinements is returned. A pass whose two probes tie closes the bracket onto both, so a request mirrored left to right, whose probes are the same two exchanged, refines to the mirrored swivel. So the chosen pose follows a moving target continuously rather than in swivel steps, a legal interval narrower than one step is still found from the dip it leaves in the sweep, and between two basins the truly better one wins rather than the one a sample happened to fall nearer the bottom of. The caller owns the decomposition and the rig's ROM, so the geometry here holds no rig policy.A caller that can certify swivels its score refuses (
excluded) spares their scoring, and the pose is still the full sweep's. A step is skipped when every swivel within two steps of it is refused, and a step whose bracket, a step either way, is refused is not refined; every other step is scored and compared with its true neighbours, since a step that is not skipped and could be refined has both neighbours scored. When the pruned sweep finds a legal candidate, the full sweep's answer is that candidate: a refused swivel, a step or a refinement inside a refused bracket, is never legal, so it can never be ahead of a legal candidate (legality is compared exactly); every legal candidate of the full sweep is a scored step or the refinement of a step that is scored with the same neighbours, so it is the same candidate in both; and the ordering among legal candidates, met in the same order, is the same. When the pruned sweep finds none, the full sweep decides, so a chain that cannot reach legally still returns its least overshoot.A caller continuing a fit of a nearby target (
near) skips the sweep: the seed's branch, its swivel refined within one step either way by the same golden-section search under the same ordering, to the seed'stolerance(IAutoMovieSwivelNear). Every result names its branch and swivel, the seed a nearby fit continues from.Returns
nullfor a degenerate chain: a mid or end offset shorter than1e-6, a target within1e-6of the chain root, a hinge shorter than1e-6, orRbelow1e-9, a hinge parallel to the far segment that cannot change the span (armChainFault reports that rig).