TryFormAI Analysis Worker

Open‑source video analysis engine for golf swing evaluation. It processes side and rear view videos to compute biomechanics, consistency, tempo metrics, visual annotations, and handicap‑aware scores with dynamic scaling.

Quick Start

• Install dependencies (see Requirements), then run tests to validate your environment.
• Use the Side View analyzer for face‑on swings; Rear View for down‑the‑line swings.

Example (Side View, deterministic processing):

from worker.analysis.analyzers.side_view.analyzer import SideViewAnalyzer
from worker.analysis.processors.deterministic_video_processor import create_deterministic_video_processor

# Pose processor is created by the analyzer's processor in run_analysis; you can supply your own if needed.
pose_processor = None
analyzer = SideViewAnalyzer(pose_processor)

manual_timestamps = {
    'start': 0.5,
    'mid_backswing': 1.1,
    'top': 1.5,
    'mid_downswing': 1.8,
    'impact': 2.0,
    'mid_follow_through': 2.4,
    'follow_through': 2.8,
    'finish': 3.1,
}
user_profile = { 'handedness': 'right', 'handicap': 12 }

results = analyzer.run_analysis(
    video_path='path/to/video.mp4',
    manual_timestamps=manual_timestamps,
    user_profile=user_profile,
    job_id='job-1234',  # required for deterministic pipeline
)

print(results['handicap_scoring'])

Requirements

• Python 3.10+
• ffmpeg (for video I/O)
• Optional: GPU drivers compatible with your environment

Setup

pip install -U pip
pip install -r worker/requirements.txt
pip install -r dev-requirements.txt  # if present in your environment

Choosing a Processor Mode

• Deterministic (recommended for production reproducibility):
  • worker/analysis/processors/deterministic_video_processor.py
  • Requires job_id to anchor reproducibility across runs.
• Performance optimized (throughput‑oriented):
  • worker/analysis/processors/performance_optimized_processor.py
  • Use where speed matters and non‑bit‑exact reproducibility is acceptable.
• Frame sampling helpers:
  • worker/analysis/processors/smart_frame_sampler.py

Running Tests

• Core unit tests (fast):

pytest -q

• Focused scoring tests (no MediaPipe needed):

pytest -q tests/worker/analysis/test_centralized_scoring.py

• If your environment lacks MediaPipe, you can skip heavy suites using markers or by running only the above file.

Features

• Deterministic processing (job‑anchored) for reproducible results
• Dynamic handicap scaling (continuous thresholds per exact handicap)
• Centralized scoring and recommendations
• Modular analyzers for side/rear views
• Config‑first parameters with validation and migration utilities

Key Modules

• Centralized scoring: worker/analysis/core/centralized_handicap_scoring.py
• Dynamic thresholds: worker/analysis/core/dynamic_handicap_scaling.py
• Handicap thresholds (fallback): worker/analysis/core/handicap_thresholds.py
• Coordinate system (canonical): worker/analysis/core/coordinate_system.py
• Scoring integration helper: worker/analysis/core/scoring_integration.py
• Processors: worker/analysis/processors/
• Analyzers: worker/analysis/analyzers/

Codebase Structure

• worker/analysis/ — Core engine
  • core/ — Scoring, dynamic scaling, coordinate system, metrics core
  • processors/ — Video IO, deterministic/performance processors, MediaPipe pools
  • analyzers/ — View pipelines (frame processing, calculators, annotations, reports)
  • config/ — Modular configuration (domains, presets, core)
  • validation/ — Landmark/result validation
  • monitoring/ — Health monitoring glue
• worker/core/ — Job orchestration and concurrency utilities
• tests/ — Unit, integration, e2e, load/perf

Conventions & Boundaries

• View terminology: "Side View (face‑on)" and "Rear View (down‑the‑line)". Use consistently in code and docs.
• Keep core/ view‑agnostic; place per‑view logic under analyzers/<view>/.
• Prefer dependency injection for stateful utilities (e.g., coordinate system manager). The global coordinate_manager is for legacy convenience.
• Avoid heavy imports at module import time in utils/ and processors/; lazy‑import inside functions/methods.

Configuration Quickstart

• Entrypoint: worker/analysis/config/__init__.py
• Initialize system once at startup if your app needs domain validation/presets:

from worker.analysis.config import initialize_config_system, get_config_manager
config_manager = initialize_config_system()
biomech = config_manager.biomechanics

• Infrastructure config for environment/platform knobs:

from worker.analysis.config import get_infrastructure_config
infra = get_infrastructure_config()
print(infra.enable_pose_estimation, infra.cache_ttl_seconds)

Tips

• Import submodules directly (avoid importing worker.analysis.core package to keep imports light in tests).
• Deterministic processing requires a job_id; see analyzers for usage patterns.
• For performance issues, prefer performance_optimized_processor.py where appropriate.

Documentation

• Docs index: docs/README.md
• Architecture: docs/ARCHITECTURE.md
• Contributing: docs/CONTRIBUTING.md
• Audit Report: docs/AUDIT_REPORT.md

Troubleshooting

• Missing mediapipe: install the appropriate version for your Python and OS.
• Local path issues during tests: ensure the repo root is on sys.path (see tests/worker/conftest.py).

Contributing

We welcome issues and PRs! Please read docs/CONTRIBUTING.md before submitting changes.