Golf Feedback System

A comprehensive golf swing analysis application with real-time feedback, featuring a React frontend and FastAPI backend powered by computer vision and pose estimation.

Project Structure

golf-feedback-system/
├── frontend/
│   └── swing-better/     # React application
├── src/
│   ├── app/              # Backend FastAPI application
│   └── s3_NAM_model/     # S3 NAM model package
├── requirements.txt      # Python dependencies
└── README.md

Prerequisites

• Python 3.8 or higher
• Node.js 16.x or higher
• npm or yarn package manager

Backend Setup

1. Create Virtual Environment

Navigate to your project root directory and create a virtual environment:

python -m venv venv

Or if you're using Python 3 specifically:

python3 -m venv venv

2. Activate Virtual Environment

Activate the virtual environment based on your operating system:

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

You should see (venv) appear at the beginning of your command line prompt, indicating the virtual environment is active.

3. Install Python Dependencies

With the virtual environment activated, install the required packages:

pip install -r requirements.txt

4. Install S3 NAM Model Package

Navigate to the S3 NAM model directory and install it in editable mode:

cd src/s3_NAM_model
pip install -e .
cd ../..

The -e flag installs the package in editable/development mode, which means changes to the source code will be reflected without reinstalling.

5. Download Required Models

Before running the application, you need to download the required model files:

Download Link: Model Files on Google Drive

Installation Instructions:

1. Download the models folder from the Google Drive link
2. Place the downloaded models folder in the root directory
3. Download the golfpose-checkpoints folder from the Google Drive link
4. Place the downloaded golfpose-checkpoints folder in the src/golfpose/ directory
   • Final path should be: src/golfpose/golfpose-checkpoints/

Your directory structure should look like this after downloading:

models/   # Downloaded model files
src/
├── app/
├── golfpose/
│   └── golfpose-checkpoints/  # Downloaded checkpoint files
├── s3_NAM_model/  # S3 NAM model package
└── ...

6. Run the Backend

Development Mode (with auto-reload):

uvicorn src.app.main:app --reload

Production Mode:

uvicorn src.app.main:app --host 0.0.0.0 --port 8000

The backend API will be available at http://localhost:8000

Frontend Setup

1. Navigate to Frontend Directory

cd frontend/swing-better

2. Install Node Dependencies

npm install

Or if you're using yarn:

yarn install

3. Run the Frontend

Development Mode:

npm run dev

Or with yarn:

yarn dev

Production Build:

npm run build

Or with yarn:

yarn build

The frontend application will typically be available at http://localhost:3000 (or the port specified in your configuration).

Running the Complete Application

To run both frontend and backend simultaneously:

1. Terminal 1 - Backend:

   # From project root
   source venv/bin/activate  # or venv\Scripts\activate on Windows
   uvicorn src.app.main:app --reload

2. Terminal 2 - Frontend:

   # From project root
   cd frontend/swing-better
   npm run dev

Quick Setup Summary

For a quick setup from scratch:

# 1. Setup backend
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cd src/s3_NAM_model && pip install -e . && cd ../..

# 2. Download models from Google Drive and place them correctly

# 3. Setup frontend
cd frontend/swing-better
npm install
cd ../..

# 4. Run backend (Terminal 1)
uvicorn src.app.main:app --reload

# 5. Run frontend (Terminal 2)
cd frontend/swing-better && npm run dev

Research References

This project is based on the following research papers:

1. ArXiv Paper 2508.20491v1
2. ICPR 2024 GolfPose Paper
3. ArXiv Paper 1903.06528