Calculate joint angles from pose landmarks

Pick the joint as the vertex and one landmark either side of it. Subtract the vertex from each to get two vectors, u and v, pointing along the segments. The angle between u and v is the joint angle.

The textbook route is the dot product: cos θ = (u·v) / (|u||v|), then take the arccosine. It works, but arccosine loses precision near 0° and 180° — exactly where a straight arm or leg sits — and it can only ever answer 0–180°, so it cannot tell a knee bending forwards from one bending backwards.

Use atan2 of the cross product and the dot product instead: θ = atan2(u×v, u·v). It is accurate everywhere, needs no division, and keeps the direction — the sign says which way v lies from u.

import math

def joint_angle(a, b, c, width, height):
    """Angle at b, swept from a to c, in degrees 0–360.

    a, b, c are landmarks with normalized x and y (0–1, origin top-left).
    width and height are the frame's size in pixels.
    """
    ux, uy = (a.x - b.x) * width, (a.y - b.y) * height
    vx, vy = (c.x - b.x) * width, (c.y - b.y) * height
    cross = ux * vy - uy * vx
    dot = ux * vx + uy * vy
    return math.degrees(math.atan2(cross, dot)) % 360

def interior(angle):
    """The unsigned 0–180 angle, if you don't need the direction."""
    return min(angle, 360 - angle)

# Left knee: hip (23), knee (25), ankle (27)
p = result.pose_landmarks[0]
knee = joint_angle(p[23], p[25], p[27], frame_width, frame_height)

type Point = { x: number; y: number };

/** Angle at b, swept from a to c, in degrees 0–360. Points are normalized; w and h are pixels. */
export function jointAngle(a: Point, b: Point, c: Point, w: number, h: number): number {
  const ux = (a.x - b.x) * w, uy = (a.y - b.y) * h;
  const vx = (c.x - b.x) * w, vy = (c.y - b.y) * h;
  const deg = (Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy) * 180) / Math.PI;
  return deg < 0 ? deg + 360 : deg;
}

/** The unsigned 0–180 angle, if you don't need the direction. */
export const interior = (angle: number) => Math.min(angle, 360 - angle);

// Left knee: hip (23), knee (25), ankle (27)
const knee = jointAngle(p[23], p[25], p[27], video.videoWidth, video.videoHeight);

MediaPipe's x and y are fractions of the frame's width and height. Those are different numbers unless the frame is square, so a segment that is really at 45° comes out at some other angle in normalized coordinates. Multiply x by the width and y by the height before taking any angle.

The unsigned angle — 0 to 180° — says how bent a joint is but not which way. For a knee that is usually enough. For a shoulder, an arm 40° in front of the body and 40° behind it read the same. A directed sweep from one segment to the other, on a 0–360° scale, keeps them apart: one reads 40° and the other 320°.

Markerless reports every angle as a clockwise sweep on that 0–360° scale, so a straight limb reads 180°. Two consequences are worth knowing before you compare numbers:

• Direction depends on the side facing the camera. The same posture filmed from the other side reads as its complement: 150° becomes 210°.
• Image y points down. Engines with y pointing up — Apple Vision among them — reverse every sweep. Flip y (1 − y) before using the formula, or the left and right of everything swap.

Clinical measurements use yet another convention, with 0° at the neutral position. A knee bent 40° from straight is 40° of flexion to a physiotherapist and 140° here. Range of motion by joint gives the conversion for each joint.

• Check visibility first. An angle is only as good as its worst point. Skip frames where any of the three has low visibility rather than computing an angle from a guess.
• Expect jitter. Landmarks move by a few pixels from frame to frame even when the body does not, and short segments such as the hand and foot turn that into degrees quickly.
• Smooth the angle series, not the decision. A low-pass filter over the angles removes jitter without delaying a peak, if it runs forwards and backwards — see the Butterworth filter and the other four.
• Film square-on. Everything above measures the angle as the camera sees it. A limb moving towards the lens reads short, and no formula recovers that.

The definitions and the formula above are the ones Markerless runs. Computed from a clip's landmarks and compared with the QuickPose engine's own output for the same clip, all eight engine-measured joints agree to within 0.1° on every frame — the engine's own rounding. That says the maths is the same; it says nothing about how close the landmarks are to the true joint centres, which is a property of the pose model.

If you would rather not maintain this yourself, range of motion gives all fourteen angles on every frame of an uploaded clip, and a rep counter export ships the same maths ready-made in Swift, Kotlin, TypeScript and Python.