README.md

metadata

title: Football Player Re-identification
emoji: ⚽
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false

Football Player Re-identification in a Single Feed (Hugging Face Gradio App)

This project implements a basic real-time player re-identification and tracking system for a single video feed, deployed as a Gradio web application on Hugging Face Spaces. It uses a pre-trained YOLOv11 model for object detection and employs IoU-based tracking with a feature-based re-identification mechanism to maintain player identities even when they temporarily leave the frame.

Objective

Given a 15-second video, the goal is to:

1. Detect all players throughout the clip.
2. Assign unique IDs to players based on their initial appearance.
3. Maintain the same ID for players who go out of frame and re-appear later in the video (e.g., near a goal event).
4. Simulate real-time re-identification and player tracking, outputting a video with identified players.

How to Deploy and Use on Hugging Face Spaces

This application is designed to be easily deployed on Hugging Face Spaces.

1. Project Structure for Hugging Face Space

Your project directory should look like this before pushing to Hugging Face:

player-re-identification/ ├── app.py # The Gradio interface definition ├── reid_processor.py # The core re-identification logic ├── requirements.txt # All Python dependencies └── .gitignore # Specifies files to ignore (e.g., model, videos)

Important Notes for Hugging Face:

• Model (yolov11_model.pt): The model file is not included directly in the repository due to its size. reid_processor.py is configured to automatically download it from Google Drive using gdown when the Gradio app starts for the first time on the Space.
• Input Video (15sec_input_720p.mp4): The input video is provided by the user directly through the Gradio web interface. Do not include it in the repository.
• Output Video (reidentified_output.mp4): The output video is generated dynamically by the app and displayed in the Gradio interface; it's not committed to the repository.

2. Deployment Steps on Hugging Face

1. Sign up/Log in to Hugging Face: Go to huggingface.co/spaces and create an account or log in.
2. Create a New Space:
   • Click on "Create new Space".
   • Space name: Choose a unique name (e.g., football-player-reid).
   • Owner: Your Hugging Face username.
   • Space type: Select "Public" or "Private" as per your preference.
   • SDK: Select Gradio.
   • Docker Template: Select "Blank".
   • Hardware: For testing, you can start with "CPU basic (Free)". However, for real-time video processing with YOLO, a GPU runtime is highly recommended for better performance. If you have a paid Hugging Face account or a grant, you can choose a GPU (e.g., Nvidia T4 - small). You can upgrade this later as well.
   • Click "Create Space".
3. Upload Your Files:
   • After creating the Space, you'll be redirected to its page. Click on the "Files" tab.
   • The easiest way to fix the README.md is directly on the Hugging Face website:
     • Click on README.md in the file list.
     • Click the "Edit this file" (pencil) icon.
     • Replace the entire content with the new README.md provided in this response (including the --- blocks at the top).
     • Add a commit message like "Add Space configuration to README" and click "Commit changes".
   • If you're using Git:

     # Make sure you are in your cloned Hugging Face Space directory
     # (e.g., cd YOUR_SPACE_NAME)
     # Edit the README.md file locally, pasting the new content
     git add README.md
     git commit -m "Add Space configuration to README"
     git push
     

4. Monitor Deployment:
   • Go back to your Hugging Face Space page. The Space will automatically start building. You can check the "Logs" tab for progress and any errors during installation of dependencies or model download.
   • The first build might take a few minutes as it downloads ultralytics dependencies and the YOLOv11 model.

3. How to Use the Deployed App

1. Once the Space is built and running (status will show "Running"), navigate to its main page.
2. You will see the Gradio interface.
3. Click the "Upload a 15-second football video" box to upload your video file.
4. Click "Submit" (or the equivalent button) to start the re-identification process.
5. After processing, the "Processed Video with Re-identified Players" will appear in the output section.

Local Development (Optional)

If you wish to run the Gradio app locally before deploying:

1. Follow the "Prerequisites" and "1. Project Setup" steps above (including downloading the YOLOv11 model and placing it).
2. Follow "2. Environment Setup" and "3. Install Dependencies" (ensure gradio and gdown are in your requirements.txt and installed).
3. Run:

   python app.py
   

   This will launch the Gradio interface in your web browser, typically at http://127.0.0.1:7860.

Dependencies / Environment Requirements

• Python: 3.8+
• Libraries (from requirements.txt):
  • opencv-python
  • numpy
  • ultralytics
  • gradio