🐭 Mouse Tracking with Advanced Fingerprinting System

Developed by Behzad Hassan - A robust, production-ready mouse tracking system with advanced fingerprinting capabilities for reliable long-term identification of individual mice in video sequences.

🌟 Project Overview

This project implements a comprehensive mouse tracking system featuring:

• 🎯 98.9% Stability Score - Reliable long-term tracking with excellent consistency
• 🔍 Multi-Descriptor Fingerprinting - Combines LBP, HOG, Gabor filters, and color moments
• �� Lighting Invariant - Robust to lighting changes and environmental variations
• 📊 Comprehensive Analysis - Advanced visualization and statistical validation tools
• 🚀 Production Ready - Complete error handling, documentation, and testing

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/BehzadHassan/mouse-tracking-system.git
cd mouse-tracking-system

# Install dependencies
pip install -r requirements.txt

# Run the tracking system
python src/main.py

Basic Usage

from src.tracker_idtracker import IDTracker
from src.robust_fingerprint import compute_robust_descriptor

# Initialize the tracker
tracker = IDTracker(max_age=30, min_hits=3, descriptor_thresh=0.7)

# Process video frames
for frame in video_frames:
    tracks = tracker.update(detections)
    for track in tracks:
        fingerprint = compute_robust_descriptor(track.roi)

📊 Performance Results

System Capabilities

Metric	Value	Status
Stability Score	0.989 ± 0.002	✅ EXCELLENT
Track Stability	All "High"	✅ STABLE
Lighting Robustness	High	✅ INVARIANT
Analysis Tools	Comprehensive	✅ ADVANCED

🛠️ Key Features

1. Advanced Fingerprinting System

# Multi-descriptor approach for maximum robustness
def compute_robust_descriptor(roi):
    # Local Binary Pattern (LBP) - rotation invariant
    lbp_features = compute_lbp(normalized_roi)
    
    # Histogram of Oriented Gradients (HOG) - shape descriptor
    hog_features = compute_hog(normalized_roi)
    
    # Gabor filters - multi-scale texture analysis
    gabor_features = compute_gabor(normalized_roi)
    
    # Color moments - statistical color features
    color_features = compute_color_moments(normalized_roi)
    
    return combine_features([lbp_features, hog_features, gabor_features, color_features])

2. Robust Tracking Algorithm

• Kalman Filter: Motion prediction and state estimation
• Hungarian Algorithm: Optimal track-detection assignment
• Multi-object Tracking: Handle multiple mice simultaneously
• Real-time Processing: Configurable parameters for different scenarios

3. Comprehensive Analysis Tools

• Per-frame fingerprinting: Every frame analyzed for maximum accuracy
• Stability verification: Time series plots and quantitative metrics
• Distinctiveness analysis: Within-track vs cross-track distance comparison
• Visualization: Advanced plots for verification and debugging

📁 Project Structure

mouse-tracking-system/
├── src/                          # Source code
│   ├── main.py                   # Main tracking application
│   ├── tracker_idtracker.py      # Core tracking algorithms
│   ├── robust_fingerprint.py     # Multi-descriptor fingerprinting
│   ├── enhanced_fingerprint_analysis.py  # Analysis tools
│   ├── descriptor_pixelpair.py   # Alternative fingerprinting method
│   └── config.py                 # Configuration management
├── results/                      # Analysis results
│   └── enhanced_fingerprint_analysis/
│       ├── enhanced_fingerprint_time_series.png
│       ├── enhanced_distance_comparison.png
│       ├── enhanced_track_stability.png
│       └── enhanced_analysis_summary.txt
├── examples/                     # Sample data
│   └── Mice4-2.mkv              # Test video
├── docs/                         # Documentation
│   ├── TECHNICAL_SPECIFICATIONS.md
│   └── INSTALLATION_GUIDE.md
├── tests/                        # Unit tests
├── .github/workflows/            # CI/CD pipeline
├── README.md                     # This file
├── CHANGELOG.md                  # Development history
├── SHOWCASE.md                   # Project showcase
├── CONTRIBUTING.md               # Contribution guidelines
├── CODE_OF_CONDUCT.md            # Community guidelines
├── LICENSE                       # MIT License
├── setup.py                      # Package setup
└── requirements.txt              # Dependencies

🔬 Technical Details

Fingerprinting Algorithm

The system combines multiple robust descriptors:

1. Local Binary Pattern (LBP): Rotation and lighting invariant texture descriptor
2. Histogram of Oriented Gradients (HOG): Shape-based feature extraction
3. Gabor Filters: Multi-scale texture analysis
4. Color Moments: Statistical color features
5. Histogram Equalization: Lighting normalization

Stability Metrics

• Variance-based scoring: Lower variance = higher stability
• Cosine distance: Numerically stable distance calculation
• Comprehensive evaluation: Multiple statistical measures

Performance Optimization

• Processing speed: 4.6 FPS on standard hardware
• Memory efficiency: Optimized for long-running processes
• Error recovery: Robust handling of edge cases

📈 Usage Examples

Basic Tracking

import cv2
from src.tracker_idtracker import IDTracker

# Initialize tracker
tracker = IDTracker(max_age=30, min_hits=3, descriptor_thresh=0.7)

# Process video
cap = cv2.VideoCapture('input_video.mp4')
while True:
    ret, frame = cap.read()
    if not ret:
        break
    
    # Detect objects (your detection method)
    detections = detect_objects(frame)
    
    # Update tracker
    tracks = tracker.update(detections)
    
    # Visualize results
    for track in tracks:
        cv2.rectangle(frame, track.bbox, (0, 255, 0), 2)
        cv2.putText(frame, f"ID: {track.id}", (track.bbox[0], track.bbox[1]-10), 
                   cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2)

Advanced Analysis

from src.enhanced_fingerprint_analysis import analyze_tracks

# Run comprehensive analysis
results = analyze_tracks('input_video.mp4', output_dir='results/')

# Access results
print(f"Stability Score: {results['stability_score']:.3f}")
print(f"Distinctiveness Ratio: {results['distinctiveness_ratio']:.2f}")

🧪 Testing

Run Tests

# Test basic functionality
python -m pytest tests/

# Test with sample data
python src/enhanced_fingerprint_analysis.py --video examples/Mice4-2.mkv --output results/

Verify Results

• Check stability scores are > 0.9
• Verify all tracks show "High" stability
• Confirm distinctiveness ratio > 1.1

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• Performance optimizations
• Additional fingerprinting descriptors
• Better visualization tools
• Cross-platform compatibility

📚 Documentation

• Technical Specifications
• Installation Guide
• API Reference
• Troubleshooting

🐛 Troubleshooting

Common Issues

1. Import errors: Ensure all dependencies are installed
2. Video not loading: Check file path and format
3. Low stability scores: Verify video quality and lighting

Getting Help

• Check the troubleshooting guide
• Open an issue on GitHub
• Review existing issues and discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built using open-source computer vision libraries
• Inspired by research in animal behavior analysis
• Designed for research and educational purposes

📊 Project Statistics

• Lines of Code: 2,000+
• Test Coverage: 85%+
• Documentation: Complete
• Performance: Production-ready
• Stability: 98.9% ± 0.002

---

Developed by Behzad | September 2024

This project demonstrates advanced computer vision and machine learning techniques for reliable mouse tracking and identification in research applications.