Quick Start Guide

Quick Start Guide

Get started with the production gesture control system in 5 minutes.

---

Option 1: Test Without Hardware (Recommended First)

Test the production system without requiring phone or video setup.

Step 1: Install Dependencies

pip install numpy

Step 2: Run Test Suite

cd studio/dj_agent/gesture_control
python test_production_system.py

Expected Output:

TEST SUMMARY
══════════════════════════════════════════════════════════════════════

   Database             ✅ PASSED
   Recognizer           ✅ PASSED
   Export/Import        ✅ PASSED
   Recovery             ✅ PASSED

Total: 4/4 tests passed (100%)

🎉 All tests passed! Production system is working correctly.

What This Tests:
- ✅ Database creation and loading
- ✅ Sample recording (15 samples with variations)
- ✅ Template training with cross-validation
- ✅ Gesture recognition with caching
- ✅ Template export/import
- ✅ Automatic backups
- ✅ Data integrity (checksums)

---

Option 2: Full Training System (Requires Hardware)

Run the complete training system with phone sensor streaming.

Step 1: Install Dependencies

pip install numpy websockets opencv-python google-genai

Step 2: Setup Gemini API (Optional)

Get API key from [Google AI Studio](https://aistudio.google.com/):

export GEMINI_API_KEY="your-api-key-here"

Or create `.env` file:

echo "GEMINI_API_KEY=your-api-key-here" >> .env

Step 3: Setup Phone

Install Sensor Logger app:
- iOS: https://apps.apple.com/app/sensor-logger/id1531582925
- Android: https://play.google.com/store/apps/details?id=com.kelvin.sensorapp

Step 4: Run Training System

cd studio/dj_agent/gesture_control
python run_training_system.py

The script will display your computer's IP address. Configure phone app with:
- Protocol: WebSocket
- Host: `<displayed IP address>`
- Port: 8765

Step 5: Start Streaming

Start streaming from phone app. You'll see:

✅ Phone connected

Step 6: Use Training UI

Navigate through the menu:
1. Recording Mode - Capture training samples
2. Practice Mode - Test your gestures
3. Review Mode - View statistics
4. Manage Templates - Configure shortcuts
5. Performance Dashboard - Monitor metrics

---

Quick Training Workflow

1. Record Samples (3 minutes)

Select mode: 1

Enter gesture name: swipe_right

Press ENTER when ready...
3... 2... 1... 🔴 GO!

✅ Sample 1/15 recorded

Repeat 15 times.

2. Train Template (< 1 second)

🎉 Enough samples collected!
Train template now? (y/n): y

✅ Trained template for swipe_right (15 samples, acc=92%)

3. Practice (2 minutes)

Select mode: 2

Select gesture: 1

Press ENTER when ready...
3... 2... 1... 🔴 GO!

Overall Match: ████████████████████████████░░░░░░  85%
Confidence:    ███████████████████████████████░░░  90%

Feedback:
  • Good horizontal speed
  • Timing slightly off

Suggestions:
  • Match the template's timing more closely

Practice until average score >85

---

File Locations

After running, you'll find:

studio/dj_agent/gesture_control/
├── gesture_database/           # Training data
│   ├── templates.json          # Trained templates
│   ├── samples/                # Training samples
│   └── backups/                # Auto-backups
├── training_session.json       # Session persistence
└── recording_sessions/         # Recovery data

---

Troubleshooting

"Phone not connecting"

1. Check phone and computer on same WiFi
2. Verify IP address in phone app
3. Check firewall allows port 8765
4. Try: `telnet <computer-ip> 8765`

"No templates available"

Record samples first (Option 1 in menu).

"Low recognition accuracy"

1. Record more samples (15+ recommended)
2. Use Practice Mode to identify weak features
3. Check Training System Guide for tips

---

What's Next?

Learn More

• [Training System Guide](./TRAINING_SYSTEM_GUIDE.md) - Complete training guide
• [Production Deployment Guide](./PRODUCTION_DEPLOYMENT_GUIDE.md) - Configuration & monitoring
• [Production Migration Guide](./PRODUCTION_MIGRATION_GUIDE.md) - Upgrade from prototype

Performance Monitoring

Access dashboard in Training UI → Option 5:

PERFORMANCE DASHBOARD

🏥 Database Health:
  State: healthy
  Backups: 5

🎯 Recognition Performance:
  Success rate: 92%
  Avg latency: 23.4ms
  Cache hit rate: 87%

Configuration

Edit in Python:

# Adjust recognition threshold
recognizer.set_confidence_threshold(0.6)  # Lower = more permissive

# Adjust feature weights
recognizer.feature_weights['gyro_direction'] = 3.0  # Increase importance

# Change target samples
progress.target_samples = 20  # More samples = better accuracy

---

Production Ready ✅

The system includes:
- Auto-reconnection (network failures)
- Auto-save (crash recovery)
- Auto-backup (every 5 minutes)
- Template caching (50
- Cross-validation (accuracy measurement)
- Performance monitoring

No configuration needed - works out of the box!

---

Support

### Documentation
- [TRAINING_SYSTEM_GUIDE.md](./TRAINING_SYSTEM_GUIDE.md)
- [PRODUCTION_DEPLOYMENT_GUIDE.md](./PRODUCTION_DEPLOYMENT_GUIDE.md)
- [PRODUCTION_SUMMARY.md](./PRODUCTION_SUMMARY.md)

### Example Code
Each production file has a `main()` function with runnable examples.

Logs

# View errors
grep "ERROR" gesture_control.log

# Monitor in real-time
tail -f gesture_control.log

---

Ready to train gestures! 🎯📱

Quick Start Guide - Version 1.0
Author: Computational Choreography