DEPLOYMENT.md

Hugging Face Deployment Guide

📋 Pre-Deployment Checklist

Before uploading to Hugging Face Spaces, ensure:

• All code files are plagiarism-free with original implementations
• Student attribution is present in all files
• README.md has HF metadata header
• requirements.txt includes all dependencies
• .gitattributes is configured for Git LFS
• LICENSE file is present
• Error handling is comprehensive
• Sample video is available (optional)

🚀 Deployment Steps

1. Create a New Space on Hugging Face

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: vehicle-speed-estimation (or your choice)
   • License: MIT
   • SDK: Gradio
   • Visibility: Public or Private

2. Upload Files

You can upload files via:

Option A: Web Interface

1. Navigate to your Space
2. Click "Files and versions"
3. Upload all files from the project directory:

   app.py
   main.py
   config.py
   requirements.txt
   README.md
   LICENSE
   CITATION.cff
   CONTRIBUTING.md
   .gitattributes
   src/
   ├── __init__.py
   ├── annotator.py
   ├── speed_estimator.py
   ├── view_transformer.py
   └── exceptions.py
   

Option B: Git Command Line

# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/vehicle-speed-estimation
cd vehicle-speed-estimation

# Copy all files from the project
cp -r /path/to/Vehicle-Speed-Estimation-and-Counting-YOLO-Supervision/* .

# Add and commit
git add .
git commit -m "Initial commit: Vehicle Speed Estimation System"

# Push to Hugging Face
git push

3. Configure Git LFS for Large Files

If you have model files or sample videos:

# Install Git LFS
git lfs install

# Track large files
git lfs track "*.pt"
git lfs track "*.mp4"

# Add .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS"
git push

4. Wait for Build

• Hugging Face will automatically build your Space
• Check the "Logs" tab for build progress
• Build typically takes 2-5 minutes

5. Test Your Space

Once built:

1. Upload a test video
2. Verify processing works
3. Check output video quality
4. Test error handling with invalid inputs

⚙️ Configuration Notes

Model Files

The YOLO model will be downloaded automatically on first run. If you want to include a pre-downloaded model:

1. Download the model (e.g., yolov8n.pt)
2. Create a models/ directory
3. Upload via Git LFS:

   git lfs track "models/*.pt"
   git add models/yolov8n.pt
   git commit -m "Add YOLO model"
   git push
   

Sample Videos

To include example videos:

1. Create a data/ directory
2. Add sample videos (keep under 100MB each)
3. Upload via Git LFS:

   git lfs track "data/*.mp4"
   git add data/vehicles.mp4
   git commit -m "Add sample video"
   git push
   

Environment Variables

If you need to set environment variables:

1. Go to Space Settings
2. Click "Variables and secrets"
3. Add any required variables

🐛 Troubleshooting

Build Fails

Issue: Dependencies fail to install

Solution:

• Check requirements.txt for version conflicts
• Ensure all packages are available on PyPI
• Try pinning specific versions

Out of Memory

Issue: Space runs out of memory during processing

Solution:

• Upgrade to a better hardware tier (Settings → Hardware)
• Reduce video resolution in preprocessing
• Use smaller YOLO model (yolov8n instead of yolov8l)

Slow Processing

Issue: Video processing is very slow

Solution:

• Upgrade to GPU hardware (Settings → Hardware)
• Use smaller model for faster inference
• Reduce input video resolution

Model Download Fails

Issue: YOLO model fails to download

Solution:

• Pre-download model and include in repository
• Check internet connectivity in Space
• Use alternative model source

📊 Hardware Recommendations

Video Resolution	Model Size	Recommended Hardware
720p	YOLOv8n	CPU Basic (Free)
1080p	YOLOv8n/s	CPU Upgrade
1080p	YOLOv8m/l	T4 Small (GPU)
4K	YOLOv8l	A10G Small (GPU)

🔒 Security Notes

• Never commit API keys or secrets to the repository
• Use Hugging Face Secrets for sensitive data
• Validate all user inputs
• Limit file upload sizes

📈 Monitoring

After deployment:

1. Monitor Space usage in Settings
2. Check error logs regularly
3. Review user feedback
4. Update dependencies periodically

🔄 Updating Your Space

To update after deployment:

# Make changes locally
# Test thoroughly

# Commit and push
git add .
git commit -m "Description of changes"
git push

# Space will automatically rebuild

📝 Post-Deployment

1. Test all functionality
2. Share Space link with team
3. Add Space to your profile
4. Consider writing a blog post about the project
5. Share on social media

🎓 Academic Use

For academic submissions:

1. Ensure all student names are visible in README
2. Include enrollment numbers
3. Add CITATION.cff for proper attribution
4. Document all external libraries used
5. Include technical documentation

✅ Final Verification

Before marking as complete:

• Space builds successfully
• Video upload works
• Processing completes without errors
• Output video is downloadable
• Statistics are displayed correctly
• Error messages are user-friendly
• All student names are visible
• README renders correctly
• License is visible

🎉 Success!

Your Vehicle Speed Estimation System is now live on Hugging Face Spaces!

Share your Space URL:

https://huggingface.co/spaces/YOUR_USERNAME/vehicle-speed-estimation

---

Developed by:

• Abhay Gupta (0205CC221005)
• Aditi Lakhera (0205CC221011)
• Balraj Patel (0205CC221049)
• Bhumika Patel (0205CC221050)