Tablesoccer Analysis

I have started to build a tablesoccer Video analysis with openCV, Python and a Basler camera. For now, I have realized the basic structure for the analysis, ball tracking, field detection, goal counting and ball speed calculation.



Table Soccer Video Analysis with OpenCV in Python - Basler dart / pulse Camera connected with PyPylon

During my own websearch couple of weeks ago I found some impressive demonstrations of video analysis setups for table soccer matches. But sadly none of those mostly university groups have published their code.

So not that long ago I began coding an OpenCV based ball-detection as a first step realizing the project. It became clear pretty fast that I won't be able to do all of the coding by myself, so I decided to release the project to all of you already although there still is a lot of work to be done before the project could somehow be called as "finished".

This is my setup.

I’m using a Basler pulse camera positioned about 1.5 meters on top of the soccer field for filming the field area of the table. I had to crop the sensors image to increase the framerate. The downside of that is that I now need a vocal length of about 4mm.


On the script side I decided to use Python for some straight forward results combined with the OpenCV library for image recognition.

To get the raw camera image I’m using a Python wrapper for Baslers C++ API, which allows me to configure all advanced camera settings within the code.


I focused a lot on writing the project code in a as modular way as possible so it will be easy to adapt new awesome features you might want to add to it.

So here's what I've done for now

  • Basic structure with clear separation between

    • camera interaction
    • several analyzing classes
    • a universal output class
  • Ball tracking with automatic color calibration

  • Field detection (orientation, scale, goal line, etc.)

  • Goal detection and counting

  • ball speed calculation in m/s

  • Heatmap generation when a match is finished

Currently there are two main classes. One is detecting the field with its orientation, size and goal area position. It also creates a pixel per inch ratio for things like speed calculation. The second is responsible for the calibration and detection of the ball. It can detect most ball colors. The color just has to be different than the field colors.


Obviously there is plenty of work to do and probably you have even more  great  ideas what can be done for a great user experience. Here I some ideas which I would like to implement if I have enough time in the future.

  • ball prediction for a faster ball detection
  • Web-based user interface with a responsive design to be usable on any device with Bluetooth or wifi

TableSoccerCV is hopefully just the beginning of some great Open Source table soccer video analysis projects. I hope you find my code useful! Cheers, StudentCV


0.1 - PreRelease


You will need the following packages for python to get the code working:

  • Python 3.4
  • OpenCV 3.0
  • PyPylon 1.0.5 Get it here
  • NumPy
  • Matplotlib


Want to contribute? Great!

The code itself is documented within the source code as much as possible. I'll also provide a short coding manual asap.

Feel free to add some great functionalities!


GitHub Repository


pushed dcead6a3b53f959a2264a4f7372b3a9b6904b476
2016-08-19 10:59:33 UTC
pushed aca6942d760c06c5325cadc3dc657a5927786db6
Updated PyPylon link
2016-07-15 07:59:55 UTC
Pries, Dennis
pushed 76cb94f0a8626cc8e6b13303615d18ecc348ca7d
Corrected spelling mistakes.
2016-05-20 14:17:43 UTC
pushed 83f7ed409212fa940c97f99339aaf12dab56dd71
Video Bypass fixed
2016-04-14 10:12:07 UTC
pushed fd0f00825ef4efbfa82ab8213cf34f2d55acbb9b
Readme Fix
2016-04-07 09:01:44 UTC
pushed 1f115ae49b015876298ef005003ea62b69257ea2
Readme fix
2016-04-07 08:06:38 UTC
pushed 22ee4fa92380d204840af761204921ced6ea9147
First Commit - PreRelease 0.1
2016-04-07 07:59:26 UTC
pushed 39cf666485dcbae56032648cbe188b31cca42464
:neckbeard: Added .gitattributes
2016-04-07 07:17:02 UTC
Title Description Format
Camera Stand Schematics for the construction of a customized camera stand pdf
Title Description Format
Sample video A sample video of a foosball game .avi

Project State

Public Project Participation wanted


Software Licence: Project has no software
Hardware Licence: Solderpad 0.51

Project Tags




Does this project pique your interest?

Login or register to join or follow this project.

sven-verpoort report abuse
Is there a PyPylon version for Python 3.6 ? We urgently need a working solution for cp36 on Win 32bit and we would highly appreciate if someone could help us.
aerotow report abuse
here we go
sarveshwarge report abuse
I get the Following ValueError: PS I:\TableSoccerCV> python Session started 192.9516106247902 Please put the ball an the center spot! Calibration starts - 5 seconds for positioning... 1.059940684013998 Calibration succeeded 6.306161969713371 Traceback (most recent call last): File "", line 140, in DetectBall.detect_ball_position(Image) File "I:\TableSoccerCV\", line 110, in detect_ball_position im2, contours, hierarchy = cv2.findContours(mask, cv2.RETR_TREE, cv2.CHAIN_APPROX_NONE) ValueError: not enough values to unpack (expected 3, got 2) I am willing to contribute more to this project, but for now I badly want a quick fix.
samperid report abuse
Hello, what reference did you use to figure how to use the PyPylon functions. There is very little documentation posted on the PyPylon repo regarding how to use the api.
aerotow report abuse
Hi @samperid PyPylon function calls are very similar to the calls in the other API languages. Give the Docs a try to find the names of functions and always basically just ask yourself "whats the pythonic" way of doing this. Usually that way you get the ball rollling.
aerotow report abuse
@sarveshwarge did you modify the code in any way so far?
sarveshwarge report abuse
No, just downloaded it from GitHub and ran it. Got the above output.
aerotow report abuse
Are you using the provided test video or a camera? For a live setup you probably have to manipulate the code for your excact szenario. The code is quite unflexible for different settings so far if I remember correctly
Back to top

Ready to join the project?

You'd like to participate ... Show more