The Problem

Athletes and coaches need quick, visual feedback on form and performance without building custom pipelines. Existing libraries provide models, but not end‑to‑end demos that ingest raw video, run pose‑segmentation, and output actionable metrics.

What This Does

vision-demos bundles five self‑contained Python demos, each targeting a different exercise. Each demo lives in its own folder (e.g., chin_ups/, dance_sync/) and contains a main.py that orchestrates the pipeline. Key files across demos:

  • main.py – CLI entry point.
  • src/env.py – loads environment variables from .env.example.
  • src/pose.py – runs the vitpose-plus-large model.
  • src/skeleton.py – constructs the skeletal graph.
  • src/render.py – overlays pose and metrics on the video.
  • src/panel.py – renders a side‑panel UI (textual or graphical) with metrics.

How It Is Wired

Entry point: chin_ups/main.py (analogous for other demos).

  1. main.py imports config, env, and video.
  2. video.VideoProcessor reads the input clip, splits it into frames, and calls the pose pipeline.
  3. pose.run_pose forwards frames to the remote VLM Run endpoint for vitpose-plus-large.
  4. skeleton.build turns raw keypoints into a graph, feeding it to reps.RepCounter or similarity.SimilarityMetric depending on the demo.
  5. panel.Panel aggregates metrics and uses render.draw_overlay to create the final video.
  6. Output is written to output/ in the demo folder.

The control flow is linear with a single hub (main.py). Functions that touch external services are pose.run_pose and skeleton.build. All other modules are pure CPU side and write only to the local filesystem. No database or network writes occur beyond the VLM Run API calls.

How To Use It

  1. Clone ``bash git clone https://github.com/moses-y/vision-demos cd vision-demos ``
  2. Create environment (each demo provides environment.yml) ``bash conda env create -f chin_ups/environment.yml conda activate vision-demos ``
  3. Load credentials – copy .env.example to .env and fill in VLM_RUN_API_KEY.
  4. Run a demo (example: chin‑ups) ``bash cd chin_ups python main.py --video path/to/video.mp4 ` The script outputs output/chin_ups_demo.mp4. For other demos, substitute the folder name and main.py`.

The README in each folder contains additional flags (e.g., --panel, --verbose). No Dockerfile or CI configuration is present; local execution is required.

Real‑World Use

A sports analytics service can embed the chin_ups/main.py as a micro‑service. Example workflow:

import subprocess, json

def analyze_video(video_path):
    cmd = f"python chin_ups/main.py --video {video_path}"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    # parse rendered panel or parse metadata written alongside video
    return json.loads(result.stdout)

The returned JSON includes rep_count, peak_times, and ascent_duration for downstream dashboards.

Code Health & Issues

  • Medium (SDLC) – No test files across the repo.
  • Medium (SDLC) – No CI/CD configuration (.github/ or similar).
  • Low (Documentation) – Minimal inline comments; most logic lives in src/*.py.
  • Low (Configuration) – Environment variables rely on manual copy of .env.example.

No license file is missing; Apache‑2.0 is declared in LICENSE. The repository contains 85 Python files but lacks automated quality gates.

The Bottom Line

vision-demos delivers functional, ready‑to‑run computer‑vision demos for a handful of sports scenarios. The code is straightforward, with a single entry point per demo and clear separation between pose inference and metric computation. The lack of tests and CI limits confidence for production use, but the repo is a solid starting point for rapid prototyping or educational demonstrations.