https://github.com/mockba1501/pose-match

A motion-matching system that compares a user’s live camera pose against a static reference pose and computes similarity metrics.
https://github.com/mockba1501/pose-match

computer-vision mediapipe nextjs pose-detection typescript

Last synced: about 1 month ago
JSON representation

A motion-matching system that compares a user’s live camera pose against a static reference pose and computes similarity metrics.

• Host: GitHub
• URL: https://github.com/mockba1501/pose-match
• Owner: mockba1501
• Created: 2025-12-13T19:29:24.000Z (6 months ago)
• Default Branch: master
• Last Pushed: 2025-12-21T20:24:13.000Z (6 months ago)
• Last Synced: 2025-12-23T08:49:05.486Z (6 months ago)
• Topics: computer-vision, mediapipe, nextjs, pose-detection, typescript
• Language: TypeScript
• Homepage:
• Size: 8.47 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# PoseMatch – Real-time Pose Similarity System

**A pure geometric motion-matching system that compares a user’s live camera pose against a static reference pose.**

![Tech Stack](https://img.shields.io/badge/Stack-Next.js_16_App_Router-black) ![Style](https://img.shields.io/badge/Style-Tailwind_CSS_v4-38bdf8) ![Vision](https://img.shields.io/badge/Vision-MediaPipe-orange)

## 🚨 Critical Disclaimer

This system provides **geometric similarity metrics only**. It is **NOT** a medical or fitness tool. It does not evaluate safety, correctness, or health.

---

## 🚀 Features

### ✅ Implemented

- **Reference Pose Visualization**: Select and view reference poses with skeleton overlays.

- **Real-time Camera Detection**:

    - High-performance webcam integration using `requestAnimationFrame` loop.

    - Zero-latency overlay rendering using direct Canvas operations.

    - Robust permission handling and stream management.

- **Pose Normalization**: Geometric normalization (mid-hip centering, torso scaling) ready for comparison logic.

    - NOTE: Angle-based comparison does not require pose normalization.

    - Normalization is kept for future distance-based metrics.

- **Dual-Pipeline**: Separate state management for Reference (Static) and User (Dynamic) poses.

- **Similarity Scoring**:

    - **Joint Angle Analysis**: Computes specific joint angles (shoulders, elbows, hips, knees).

    - **Tolerance Checking**: Compares user angles against reference with configurable tolerance (e.g., ±5°).

- **Visual Feedback**:

    - **Real-time Skeleton Coloring**: Joints change color based on match status (Gray=Idle, Green=Match, Yellow=Close, Red=Miss).

### 🚧 In Progress (Next Steps)

- **Advanced Metrics**: Vector-based cosine similarity for overall body alignment.

- **Textual Feedback UI**: Instructions like "Raise Left Arm" or "Widening Stance".

## 🛠️ Architecture

- **Frontend**: Next.js 16 (App Router), React 19

- **Styling**: Tailwind CSS v4

- **Vision**: Google MediaPipe (GPU-accelerated)

- **State Management**:

    - **Ref-based Loop**: The detection loop runs outside React's render cycle for performance.

    - **Throttled State**: Only significant pose updates trigger React re-renders.

## 📦 Getting Started

1. **Install dependencies**:

   ```bash

   npm install

   ```

2. **Run development server**:

   ```bash

   npm run dev

   ```

3. **Open**: [http://localhost:3000](http://localhost:3000)

## 🗺️ Roadmap

- [x] **Phase 1**: Webcam setup & Static Reference Visualization

- [x] **Phase 2**: Real-time MediaPipe Integration (Video Mode)

- [x] **Phase 3**: Similarity Scoring Engine (Vector Math & Joint Angles)

- [x] **Phase 4**: User Feedback System (Visual State Feedback)