Ball Tracker → Robotic Goalkeeper (OpenCV + Tkinter)

Production-oriented, low-latency ball detection + trajectory prediction with angle output for Arduino control.

Project structure

• camera.py capture thread (low latency)
• roi.py 4-point ROI + perspective warp (save/load)
• mask.py HSV masking + color pick helper
• detection.py contour filtering (area + circularity)
• tracking.py constant-velocity Kalman tracker + trajectory history
• prediction.py linear lookahead prediction
• geometry.py angle calculation
• serial_out.py non-blocking Arduino serial output
• ui.py Tkinter UI + vision worker thread
• main.py entry point

Setup (Windows)

1. Activate your venv (recommended):
   • venv\\Scripts\\activate
2. Install dependencies:
   • pip install -r requirements.txt
3. (Optional) Setup config:
   • Copy config.example.json to config.json to start with default values.
4. Run:
   • python main.py

Build distributable (Windows EXE)

Builds a portable folder you can copy to another laptop.

.\build.ps1

Output:

• dist\BallTracker\BallTracker.exe

Copy to another PC:

• Copy the whole dist\BallTracker\ folder (not only the .exe).

UI Usage

1) ROI calibration (4-point)

1. Click Reset ROI (click 4 points).
2. Click 4 corners of the playfield / goal plane in the camera view.
3. The app switches to Tracking mode and processes only the warped ROI output.

2) Color masking (HSV)

Two options:

• Manual sliders: adjust H/S/V min/max until the ball is isolated in the mask thumbnail.
• Pick color on click: enable, then click on the ball in the tracking view to auto-set HSV.

3) Reference point (goal center)

• Enable Set reference point on click, then click the desired point in the tracking view.
• Or press Center reference to use the ROI center.

4) Serial output (Arduino)

• Select COM port + baud → Connect
• The app sends: A:<angle>\\n (integer degrees)

Configuration

Settings are stored in config.json (auto-saved on exit):

• Camera settings
• ROI points
• HSV range
• Detection thresholds
• Prediction lookahead
• Reference point
• Serial port + baud

Example config.json keys:

• camera.index, camera.width, camera.height
• hsv.h_min ... hsv.v_max
• detection.min_area, detection.max_area, detection.min_circularity
• prediction.enabled, prediction.lookahead_s
• reference_point (in ROI output coordinates)
• roi.points (4 points in camera image coordinates)

Calibration guidance

• Choose ROI corners on a planar surface that matches the robot’s control frame.
• Use a stable camera mount; avoid wide-angle distortion if possible.
• Keep lighting stable; if lighting changes, re-pick HSV.

Practical tips:

• Pick ROI points on a rectangle that corresponds to the goal plane / field plane.
• ROI clicks can be in any order (the code orders them internally).
• If your camera feed is mirrored/rotated by drivers, fix that first (OpenCV capture), then calibrate ROI.

Arduino integration

The app sends ASCII lines like:

• A:45\\n

Minimal Arduino sketch (reads one line and parses the angle):

String line;

void setup() {
  Serial.begin(115200);
}

void loop() {
  while (Serial.available()) {
    char c = (char)Serial.read();
    if (c == '\\n') {
      if (line.startsWith("A:")) {
        int angle = line.substring(2).toInt();
        // TODO: map angle -> servo/motor command
      }
      line = "";
    } else if (c != '\\r') {
      line += c;
    }
  }
}

Troubleshooting

• Black UI / no video: ensure camera index is correct (edit config.json → camera.index).
• Low FPS: reduce camera resolution in config.json (e.g. 640x480).
• Ball not detected:
  • Use Pick mode and click the ball
  • Increase detection.min_area or relax detection.min_circularity
• Serial connect fails:
  • Install driver (CH340/CP210x depending on your board)
  • Ensure no other app is using the COM port