rowing_stats/CLAUDE.md

CLAUDE.md

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

Project Overview

A computer vision + LLM pipeline that extracts rowing machine workout data from photos of Concept 2 PM5 displays. Photos go through screen detection, classification, and OCR-via-LLM to produce structured workout metrics.

Pipeline

photos/ → crop_to_screen.py → screen_classifier.py → extract_rowing_data.py → rowing_results.csv

1. crop_to_screen.py — Detects and perspective-corrects the LCD screen region using OpenCV edge detection, contour filtering, and morphological operations. Scores candidates by edge_density × area × rectangularity.
2. screen_classifier.py — Binary classifier (rowing display vs. not). Two modes: a rule-based feature scorer (no training needed) and a 4-layer CNN with batch norm (requires training on train/ data).
3. extract_rowing_data.py — Sends cropped images to Claude Haiku vision API, extracts time/distance, validates against sanity bounds (pace, distance, duration), computes derived metrics (pace/500m, calories), and reads EXIF date.
4. optimize_crop.py — Optuna-based hyperparameter tuner for crop_to_screen.py detection parameters (12 params). Evaluates trials by counting CNN-classified rowing displays.

Commands

# Crop screens from photos
python crop_to_screen.py photos/ cropped/

# Classify images (feature-based or CNN)
python screen_classifier.py predict --dir cropped/
python screen_classifier.py predict --image path/to/img.jpg --mode cnn

# Train the CNN classifier
python screen_classifier.py train --data-dir train/

# Extract rowing data (requires ANTHROPIC_API_KEY)
python extract_rowing_data.py --dir photos/
python extract_rowing_data.py --image path/to/img.jpg

# Optimize crop parameters
python optimize_crop.py --n-trials 300 --photos-dir photos/

Dependencies

No requirements.txt exists. Key packages: anthropic, torch, torchvision, opencv-python (cv2), Pillow, numpy, optuna.

Key Details

• The Claude API call in extract_rowing_data.py uses claude-haiku-4-5-20251001 for cost efficiency on a structured extraction task.
• Validation bounds in extract_rowing_data.py mirror those from a Go handler (handle_rowing.go): distance 100–100k meters, time 30s–2hrs, pace 1:20–2:30 /500m.
• Training data lives in train/0/ (non-rowing, 80 samples) and train/1/ (rowing displays, 48 samples).
• The trained CNN model is saved as screen_classifier_model.pth.
• .env contains API keys — it is gitignored and must not be committed.