foosball-ai

This software is designed to take a camera feed or a video file as an input of a match played on a foosball table (🇦🇹 Wuzzler), track the ball and count goals.

Features

• Support for different streaming backends (imutils/opencv, VidGear) for capturing
• Preprocessing
  • arUco marker detection for roi estimation and cropping to improve performance
  • goal detection build on top of arUco detection (done every other second to compensate table movement)
• Ball tracking
  • frame-by-frame analysis of rgb/bgr stream
  • ball detection by color masking (can be calibrated for different ball colors)
  • ball track (adjustable length) to analyze later on
• Analyze
  • detect goals on either side
  • TBD: detect middle goals (they won't count in 🇦🇹 tavern rules)
  • TBD: estimate ball speed
• Hooks
  • playsound providing support for playing a sound on 📢 goal 🎉
  • webhook support for triggering something different (or counting goals on a separate system)
• Rendering
  • optional, since headless mode is also supported
  • show detected goals, basic stats, ball track, current score
  • add VidGear streaming support to live stream

Prerequisites

• python3
• pip
• opencv

Install

0. Prerequisites

• Mac OS (suggestion)

  brew install pyenv pyenv-virtualenv
  pyenv install 3.11
  pyenv exec pip install
  brew install opencv
  

• Linux
  • Ubuntu sudo apt-get install python3 python3-pip python3-opencv
  • Arch pacman -S python python-pip opencv

1. Setup a venv

   python3 -m venv ./venv  
   

2. Activate venv

   . ./venv/bin/activate  
   

3. Install requirements

   pip install -r requirements.txt  
   

Run

0. (optional) Download video
   • demo video (w/ yellow ball)
   • (optional) calibration video for camera calibration (w/ yellow ball)
1. Activate venv (if not already done in the Install step)

   . ./venv/bin/activate  
   

2. Run camera calibration (optional for demo)

   You can skip this step if you chose to download above demo video, since the provided calibration.yaml is already tailored to the recorded video's camera

   python3 -m foosball -c cam -cv <path-to-calibration-video>.mp4
   

3. Run

   python3 -m foosball -f <path-to-file>.mp4
   

Misc

Calibration

Color

Color calibration is needed for the ball (or the goals) to be detected. There are 2 preconfigured ball profiles and 1 goal profile available, accessible by a cli option. For individual options please refer to the calibration mode where you can select the color range to be detected and stored in a color profile accordingly.

ball/goal calibration mode

python3 -m foosball -f ./demo.mp4 -c [ball|goal]

camera (aruco)

1. Generate Aruco Board

   python3 -m foosball -a
   

2. Print it in DIN A4 format (aruco.png)
3. In order to automatically detected the aruco markers and thus improve performance and accuracy, for each camera an initial calibration has to be done. Once run this application with calibration mode cam and present the printed out version of the generated aruco board to the camera by

• waving it sturdily in different angles in front of the camera,
• provide the path to a pre-recorded version of it
• or provide a path to a set of pre-recoded images of it

cam calibration mode

python3 -m foosball -c cam -cs 50

License

This software is licensed under CC-BY-NC-SA