Ryuzakii-001/Lucid

👤 Person Re-Identification System

Complete AI-powered person tracking and matching across multiple videos

---

🎯 What This Does

This system can:

• ✅ Track people in videos with unique IDs
• ✅ Match individuals across different cameras/videos
• ✅ Search for specific people across all footage
• ✅ Extract video clips of person appearances
• ✅ Web interface for easy interaction

---

🚀 Quick Start

Option 1: Web Application (Recommended)

# Start the webapp
streamlit run reid_webapp.py
# or
./start_webapp.sh

Then open http://localhost:8501 in your browser!

Option 2: Command Line

# Simple tracking (single video)
python person_tracker.py

# Advanced ReID (cross-video matching)
python reid_system.py

# Quick demo
python quick_reid_demo.py

---

📦 Installation

# Install dependencies
pip install -r requirements_webapp.txt

# Or minimal install
pip install opencv-python torch numpy ultralytics streamlit
pip install deep-sort-realtime torchreid gdown

---

📁 Project Structure

Main Applications

File	Description	Use When
reid_webapp.py	Web interface (Streamlit)	You want a GUI
reid_system.py	Full CLI system	Advanced features needed
person_tracker.py	Simple tracker	Just need basic tracking
quick_reid_demo.py	Quick demo script	Testing the system

Documentation

File	Content
WEBAPP_GUIDE.md	Complete webapp tutorial
GETTING_STARTED.md	Installation & setup guide
SYSTEM_SUMMARY.md	Technical overview
README_REID.md	ReID system details

Helper Files

• start_webapp.sh - Launch webapp
• requirements_webapp.txt - All dependencies
• simple_reid_demo.py - Batch video processing
• test_detection.py - Verify YOLO installation

---

🎨 Features

1. Gallery Building

• Upload reference video
• Automatic person detection
• Feature extraction (512-d embeddings)
• Quality analysis

2. Cross-Video Matching

• Match people across cameras
• Confidence scoring
• Green boxes = matched
• Red boxes = unknown

3. Person Search

• Search by person ID
• Timeline generation
• All appearances listed
• Downloadable reports

4. Clip Extraction

• Extract 3-second clips
• Centered on appearances
• Organized by person
• Bulk download

5. Analytics

• Person statistics
• Detection counts
• Visual charts
• System metrics

---

💻 System Requirements

Minimum

• Python 3.10+
• 8GB RAM
• macOS / Linux / Windows
• ~500MB disk space

Recommended

• Python 3.10+
• 16GB RAM
• CUDA-capable GPU
• ~2GB disk space

---

📊 Performance

Task	CPU	GPU
Model Loading	5s	3s
Gallery Building	2-5 min/1000 frames	30s-1min/1000 frames
Video Matching	3-8 min/1000 frames	1-2 min/1000 frames
Clip Extraction	Instant	Instant

---

🎓 Usage Examples

Web Interface

1. Start webapp: streamlit run reid_webapp.py
2. Load models: Click button in sidebar
3. Build gallery: Upload video in Tab 1
4. Match videos: Upload queries in Tab 2
5. Search person: Use Tab 4

Command Line

# Track single video
python person_tracker.py
> Enter path: /path/to/video.mp4

# Full ReID system
python reid_system.py
> Gallery video: /path/to/ref.mp4
> Query videos: /path/to/cam1.mp4, /path/to/cam2.mp4

# Quick demo (edit paths in file first)
python quick_reid_demo.py

---

🛠️ Technology Stack

• Detection: YOLOv8 (Ultralytics)
• Tracking: DeepSORT
• ReID: OSNet (torchreid)
• UI: Streamlit
• Backend: PyTorch, OpenCV
• Analysis: NumPy, SciPy

---

📈 Workflow

1. Build Gallery
   └─> Reference video → Detect people → Extract features → Save gallery

2. Match Videos
   └─> Query video → Detect people → Compare with gallery → Annotate output

3. Extract Clips
   └─> Select person → Find appearances → Extract segments → Save clips

4. Search Person
   └─> Enter ID → Search all videos → Generate report → Display results

---

🎯 Use Cases

Security & Surveillance

• Track suspects across multiple cameras
• Generate movement timelines
• Extract incident clips
• Identify unauthorized access

Retail Analytics

• Customer journey mapping
• Visit frequency analysis
• Dwell time calculation
• VIP customer tracking

Sports Analytics

• Player tracking across angles
• Performance highlight extraction
• Movement pattern analysis
• Multi-camera coverage

Event Management

• Attendee tracking
• VIP monitoring
• Crowd flow analysis
• Security coordination

---

📊 Output Files

webapp_output/
├── gallery.pkl                    # Person database
├── matched_*.mp4                  # Annotated videos
├── matched_*_detections.json      # Detection logs
└── clips/
    └── person_*/
        └── clip_*.mp4             # Extracted clips

Detection Log Format (JSON)

{
  "frame": 145,
  "timestamp": "0:00:06",
  "person_id": "1",
  "bbox": [320, 150, 480, 450],
  "similarity": 0.847
}

---

🔧 Configuration

Edit settings in reid_system.py:

SIMILARITY_THRESHOLD = 0.6  # Matching strictness (0-1)
CLIP_DURATION = 3           # Clip length (seconds)
MIN_DETECTION_AREA = 3000   # Min bounding box size
YOLO_CONF = 0.35           # Detection confidence

Or use webapp sidebar sliders for real-time adjustment!

---

🐛 Troubleshooting

Models won't load

# Reinstall with correct TensorFlow version
pip uninstall tensorflow tensorflow-macos -y
pip install tensorflow-macos==2.13.0 tensorboard==2.13.0

Slow processing

• Use GPU if available
• Reduce video resolution
• Increase detection confidence threshold
• Process shorter segments

No matches found

• Lower similarity threshold
• Check video quality/lighting
• Ensure person in gallery video
• Verify correct video uploaded

Import errors

pip install -r requirements_webapp.txt

---

📝 Testing

Your system was successfully tested with:

• ✅ Cam1.mp4: 24 unique persons tracked
• ✅ Cam2.mp4: Cross-video matching working
• ✅ Gallery: 6 persons, 937 embeddings
• ✅ Webapp: Fully functional

---

🤝 Contributing

Feel free to:

• Report bugs
• Suggest features
• Submit improvements
• Share use cases

---

📄 License

This project uses:

• YOLOv8 (AGPL-3.0)
• DeepSORT (GPL-3.0)
• OSNet (MIT)
• Other open-source libraries

---

🎉 Success!

You now have a complete person re-identification system with both web and command-line interfaces!

Get started now:

streamlit run reid_webapp.py

Then open http://localhost:8501

---

📞 Quick Links

• 📖 Webapp Guide - Complete UI tutorial
• 📖 Getting Started - Installation help
• 📖 System Summary - Technical details
• 📖 ReID Docs - Advanced features

---

Built with ❤️ using AI and Computer Vision

Last updated: 2025

Lucid

Lucid

Lucid