Pose Module

Advanced human pose estimation and analysis capabilities

Overview

The Pose module provides powerful capabilities for human pose estimation and analysis using YOLOv8. It enables accurate keypoint detection, angle measurements, distance calculations, and pose visualization.

Keypoint Detection

17-point keypoint detection for comprehensive human pose analysis

Angle Analysis

Calculate angles between joints and body segments

Distance Measurement

Measure distances between any two keypoints

Pose Visualization

Draw pose skeletons with automatic connection handling

Installation

pip install yolozone

Initialization

from yolozone import PoseDetector

# Initialize with default model
detector = PoseDetector()

# Initialize with custom model
detector = PoseDetector(model="path/to/custom/model.pt")

Keypoint Reference

ID Keypoint ID Keypoint
0 Nose 9 Left Wrist
1 Left Eye 10 Right Wrist
2 Right Eye 11 Left Hip
3 Left Ear 12 Right Hip
4 Right Ear 13 Left Knee
5 Left Shoulder 14 Right Knee
6 Right Shoulder 15 Left Ankle
7 Left Elbow 16 Right Ankle
8 Right Elbow

Methods

__init__(model="yolov8s-pose.pt")

Initialize the pose detector with a YOLO model

Parameters

  • model (str): Path to YOLO pose model weights (default: "yolov8s-pose.pt")

find_keypoints(img, device="cpu")

Detect human pose keypoints in an image

Parameters

  • img (numpy.ndarray): Input image
  • device (str): Device to run inference on ('cpu', 'cuda', 'mps')

Returns

  • numpy.ndarray: Array of detected keypoints

Example

keypoints = detector.find_keypoints(
    image,
    device="cuda"
)

angle_between_3_points(keypoints, point1, point2, point3, subject_index=0)

Calculate the angle between three keypoints

Parameters

  • keypoints: Detected keypoints from find_keypoints()
  • point1 (int): First keypoint ID
  • point2 (int): Second keypoint ID (vertex)
  • point3 (int): Third keypoint ID
  • subject_index (int): Index of the person in multi-person detection

Returns

  • tuple: (angle in degrees, formatted text, text position)

Example

# Calculate elbow angle (shoulder-elbow-wrist)
angle, text, pos = detector.angle_between_3_points(
    keypoints, 5, 7, 9  # Left shoulder, elbow, wrist
)

distance_between_2_points(keypoints, point1, point2, subject_index=0)

Calculate the distance between two keypoints

Parameters

  • keypoints: Detected keypoints from find_keypoints()
  • point1 (int): First keypoint ID
  • point2 (int): Second keypoint ID
  • subject_index (int): Index of the person in multi-person detection

Returns

  • tuple: (distance, formatted text, text position, point1 coords, point2 coords)

Example

# Measure arm length (shoulder to wrist)
dist, text, pos, p1, p2 = detector.distance_between_2_points(
    keypoints, 5, 9  # Left shoulder to left wrist
)

angle_between_2_lines(keypoints, point1, point2, point3, point4, subject_index=0)

Calculate the angle between two lines defined by four points

Parameters

  • keypoints: Detected keypoints from find_keypoints()
  • point1, point2 (int): Points defining first line
  • point3, point4 (int): Points defining second line
  • subject_index (int): Index of the person in multi-person detection

Returns

  • tuple: (angle in degrees, formatted text, text position)

Example

# Calculate angle between arms
angle, text, pos = detector.angle_between_2_lines(
    keypoints, 5, 9, 6, 10  # Left arm vs right arm
)

draw_pose(keypoints, subject_index=0)

Generate points and lines for drawing the pose skeleton

Parameters

  • keypoints: Detected keypoints from find_keypoints()
  • subject_index (int): Index of the person in multi-person detection

Returns

  • tuple: (array of points, array of line pairs)

Example

points, lines = detector.draw_pose(keypoints)

# Draw points
for point in points:
    cv2.circle(image, point, 5, (255, 255, 255), 2)

# Draw lines
for line in lines:
    cv2.line(image, line[0], line[1], (255, 255, 255), 2)

Complete Examples

Basic Pose Detection

from yolozone import PoseDetector
import cv2

# Initialize detector
detector = PoseDetector()

# Read image
image = cv2.imread('person.jpg')

# Detect keypoints
keypoints = detector.find_keypoints(image)

# Draw pose
points, lines = detector.draw_pose(keypoints)

# Visualize
for point in points:
    cv2.circle(image, point, 5, (255, 255, 255), 2)
for line in lines:
    cv2.line(image, line[0], line[1], (255, 255, 255), 2)

cv2.imshow('Pose Detection', image)
cv2.waitKey(0)

Real-time Pose Analysis

import cv2

detector = PoseDetector()
cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break
        
    # Detect pose
    keypoints = detector.find_keypoints(frame)
    
    # Draw skeleton
    points, lines = detector.draw_pose(keypoints)
    for point in points:
        cv2.circle(frame, point, 5, (255, 255, 255), 2)
    for line in lines:
        cv2.line(frame, line[0], line[1], (255, 255, 255), 2)
    
    # Calculate and display angles
    angle, text, pos = detector.angle_between_3_points(
        keypoints, 5, 7, 9  # Left arm angle
    )
    cv2.putText(frame, text, pos, cv2.FONT_HERSHEY_SIMPLEX, 
                1, (0, 255, 0), 2)
    
    cv2.imshow('Real-time Pose', frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Advanced Measurements

# Detect pose
keypoints = detector.find_keypoints(image)

# Measure arm angles
left_arm, text1, pos1 = detector.angle_between_3_points(
    keypoints, 5, 7, 9  # Left shoulder-elbow-wrist
)
right_arm, text2, pos2 = detector.angle_between_3_points(
    keypoints, 6, 8, 10  # Right shoulder-elbow-wrist
)

# Measure distances
torso_length, text3, pos3, p1, p2 = detector.distance_between_2_points(
    keypoints, 5, 11  # Shoulder to hip
)

# Calculate angle between arms
arms_angle, text4, pos4 = detector.angle_between_2_lines(
    keypoints, 5, 9, 6, 10  # Left vs right arm
)

# Draw measurements on image
cv2.putText(image, text1, pos1, cv2.FONT_HERSHEY_SIMPLEX, 1, (0,255,0), 2)
cv2.putText(image, text2, pos2, cv2.FONT_HERSHEY_SIMPLEX, 1, (0,255,0), 2)
cv2.putText(image, text3, pos3, cv2.FONT_HERSHEY_SIMPLEX, 1, (255,0,0), 2)
cv2.putText(image, text4, pos4, cv2.FONT_HERSHEY_SIMPLEX, 1, (0,0,255), 2)