CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Running the Application

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server
uvicorn app:app --host 0.0.0.0 --port 7860

# Alternative development server with reload
uvicorn app:app --reload

Docker Deployment

# Build the Docker image
docker build -t sportsai .

# Run the container
docker run -p 7860:7860 sportsai

Environment Setup

• Create .env file with required environment variables:
  • API_URL: External API endpoint URL
  • API_KEY: Authentication key for external API
  • AI_API_TOKEN: Token for authenticating incoming requests

Architecture Overview

Core Components

FastAPI Application (app.py)

• Main web server with two primary endpoints:
  • /upload: General video processing with pose estimation
  • /exercise/salto_alto: Specialized high jump exercise analysis
• Uses background tasks for asynchronous video processing
• Handles file uploads and API authentication

Pose Estimation (vitpose.py)

• Wraps the rt-pose library with VitPose model
• Provides pose estimation pipeline with CUDA/CPU support
• Handles video-to-frames conversion and frame annotation
• Automatically rotates landscape videos to portrait orientation

Video Analysis (tasks.py)

• Contains process_salto_alto() function for high jump analysis
• Implements comprehensive jump metrics calculation:
  • Jump height detection using pose keypoints
  • Sayer power estimation
  • Repetition counting
  • Metrics visualization overlay
• Sends results to external API endpoints via webhooks

Configuration (config.py)

• Manages environment variables and API credentials
• Uses python-dotenv for environment file loading

Key Features

High Jump Analysis Pipeline:

1. Video upload and pose estimation using VitPose
2. Calibration using person height in first frame
3. Jump detection based on ankle movement thresholds
4. Real-time metrics calculation and overlay visualization
5. Results packaging and webhook delivery

Pose Estimation:

• Uses PekingU/rtdetr object detection + usyd-community/vitpose-plus-small
• Supports both CUDA and CPU inference
• Model compilation enabled for performance optimization

Video Processing:

• Automatic landscape-to-portrait rotation
• Skeleton visualization with keypoint connections
• Metrics overlay with rounded rectangles and real-time updates

Dependencies

• FastAPI: Web framework for API endpoints
• rt-pose: Pose estimation pipeline
• OpenCV: Video processing and computer vision
• Supervision: Keypoint visualization utilities
• PyTorch: Deep learning framework for pose models

File Structure

• app.py: Main FastAPI application
• vitpose.py: VitPose wrapper class
• tasks.py: Video processing and analysis functions
• config.py: Environment configuration
• requirements.txt: Python dependencies
• Dockerfile: Container deployment configuration
• static/: Directory for processed video outputs (git-ignored)

API Authentication

All endpoints require token-based authentication via header or body parameters. Unauthorized requests return 401 status codes.