README.md

---
title: AAI 521 - ASL Hand Detection
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
license: mit
---

# AAI 521 - ASL Hand Detection System

American Sign Language hand gesture detection using MediaPipe, Gradio and CNN (TBD).

## Project Overview

This application detects and classifies basic static ASL gestures using MediaPipe Hands for hand landmark detection and a rule-based classifier for gesture recognition.

Features:
- Three input modes: Webcam snapshot, Image upload, and Live streaming
- Real-time hand landmark visualization
- Support for 5 ASL gestures (A, V, B, 1, W)
- Production logging for debugging

## Setup
```bash
# Install UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv sync

# Run the application
uv run python app.py # (Kill with Ctrl+C to shutdown gracefully in linux environment)
```

## Technical Stack

- **Hand Detection**: MediaPipe Hands (v0.10.9)
- **Classification**: Rule-based finger extension analysis
- **Frontend**: Gradio (with tabbed interface)
- **Image Processing**: OpenCV, NumPy, CNN (TBD)
- **Package Management**: UV for reproducible builds
- **Logging**: Production-ready [INFO]/[WARN] logging
---

## Collab Setup (Use Your Own Branch)

```bash
# 1. Clone the repository
git clone git@github.com:denjcodes/AAI_521_Final_Project.git
cd AAI_521_Final_Project

# 2. Add HuggingFace Space as a remote
git remote add hf git@hf.co:spaces/d2j666/AAI_521_Final_Project

# 3. Verify remotes
git remote -v

# Create and switch to your branch
git checkout -b <your-branch>

# Pull latest from main
git pull origin main

# Make changes
git add .
git commit -m "Message"

# Push your branch to GitHub
git push origin <your-branch>

# Deploy your branch to HF main (only when ready)
git push hf <your-branch>:main
```

---
### SSH Prerequisites
Before cloning or pushing via SSH:
- GitHub ->  Settings -> SSH and GPG Keys -> New SSH Key
- HuggingFace -> Settings -> SSH Keys -> Add SSH Key
---