You need to agree to share your Hugging Face information to access this model

This repository is publicly accessible, but you have to accept the conditions to access its files and content.

Log in or Sign Up to review the conditions and access this model content.

YAML Metadata Warning:empty or missing yaml metadata in repo card

Check out the documentation for more information.

πŸ‘€ Person Re-Identification System

Complete AI-powered person tracking and matching across multiple videos

Python 3.10+ YOLOv8 OSNet Streamlit


🎯 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


Built with ❀️ using AI and Computer Vision

Last updated: 2025

Lucid

Lucid

Lucid

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. πŸ™‹ Ask for provider support