Joint Limit Motion

Computes a joint move that respects THE JOINT'S MECHANICAL LIMITS, not just the shortest angle -- and REFUSES, rather than clamps, a target the joint cannot reach.

THE SILENT FAILURE. The standard way to find the shortest rotation between two angles wraps the difference into [-pi, pi]. It is correct arithmetic, and for a joint with hard mechanical limits it is dangerous, because the 'shortest' path can pass through an angle the joint is PHYSICALLY UNABLE to reach.

Concretely: a joint at +170 degrees with a target of -170 degrees. The wrapped difference says the move is 20 degrees the short way, straight through 180. If the joint's limits stop at plus or minus 175, that path does not exist. The arithmetic is right; the motion is impossible; and nothing in the calculation knows the difference.

AND CLAMPING IS THE WRONG REMEDY. Clamping a target into range produces a move that succeeds and goes somewhere other than where it was asked to go -- which for a physical machine is worse than refusing, because the caller believes the command was honoured.

So an unreachable target is refused with the reason, and a reachable one is planned along a path that stays inside the limits even when that is the long way round.

VERIFIED: 69 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function isAngle(x: unknown): x is Angle;
  export function describeAngle(angle: Angle): string;
  export function describeUnknown(x: unknown): string;
  export function continuousJoint(): ContinuousJointLimits;
  export function limitedJoint(min: Angle, max: Angle): LimitedJointLimits;
  export function isJointLimits(x: unknown): x is JointLimits;
  export function planJointMove( current: Angle, target: Angle, limits: JointLimits, options?: PlanJointMoveOptions ): JointMoveResult;

  export type AngleUnit = "rad" | "deg";
  export type JointLimits = ContinuousJointLimits | LimitedJointLimits;
  export type JointMoveDirection = "positive" | "negative" | "none";
  export type JointMoveResult = JointMovePlan | JointMoveRefusal;