PiTrac Auto-Calibration

This document describes how to set up and use PiTrac’s new (May 2025) auto-calibration feature.

PiTrac auto-calibration automatically determines the focal length and camera angles of the system. Previously, these values had to be determined and set manually using a tape measure and an Excel spreadsheet. PiTrac will use these values to calculate ball locations and–ultimately–final values like ball speed and HSA/VSA.

Auto-calibration determines the focal length and camera angles empirically. A physical “calibration rig” is used to position golf balls at known, fixed distances and angles from PiTrac. The calibration process is then told where those test balls are in space, and the process uses that knowledge to determine the focal length and angles. The resulting values are written to the current .json configuration file, and are then used when PiTrac operates in its normal launch monitor mode.

The values that are generated by auto-calibration in the .json file are the following:

   "cameras": {  
        "kCamera1FocalLength": "6.4030723439413677",  
        "kCamera2FocalLength": "6.11",  
        "kCamera1Angles": \[  
            "48.587453708172063",  
            "-20.597432130360897"  
        \],  
        "kCamera2Angles": \[  
            "0",  
            "6.77"  
        \],

Note that prior to performing auto-calibration, PiTrac’s cameras must be correctly focused and the de-distortion matrices should already have been calculated and entered into the configuration .json file. See the original calibration document here. This newer auto-calibration process just removes all the measuring and math that used to have to be done manually after the focusing/de-distortion steps. Auto-calibration won’t work well if those steps have not already been performed.

Finally, the current calibration rig assumes that the tee-off camera that watches for a ball hit (Camera 1) is pointed off at an angle. We hope that will not be required sometime in the future. If both cameras can be pointed straight ahead, we will likely only use only the single calibration ball that sits straight out in front of the monitor.

Physical Setup:

First thing to do is to get your calibration rig printed. The rig provides an easy way to precisely position two golf balls in front of the launch monitor. Of course, you could make your own rig – you would just need to make measurements of where the ball(s) are relative to the cameras and inform PiTrac of that through the configuration file.

  1. Print the rig using the files here in the github repo. The rig is in the version 2 enclosure file area, but can be used with either version of the enclosure. The main difference in using the rig for the Version 1 and 2 enclosures is just the measurement values that describe the distances from where the cameras are to the golf balls positioned on the rig. The rig looks like the following on the print bed:

    Picture 1_0 - AutoCalibration Instuctions (Picture 1_0)

    1. Printing Notes:
      1. The rig only needs support structure in the green area shown below on the part that positions Ball 1 on the floor. Otherwise, whatever standard print settings your system uses (e.g., 15% infill) should be fine. We did not need any print plate glue.
      2. The rig takes less than 100 grams of filament. PETG is probably best to reduce any warping, but PLA works fine, too.
    2. If you make your own rig, consider modelling it in FreeCad or Fusion or so that you can use the 3D modelling tools to determine precise measurements. See the image of the rig with the 1.0 version of the enclosure, along with estimated distances, second picture, below.

  2. Assemble the parts so that the resulting rig looks like:

    Picture 2_0 - Calibration Rig with PiTrac Ver 1 0 (Picture 2_0)

    1. (NOTE - the measurements to the balls above are not quite right. They should terminate in the center of the ball, and they don’t start exactly in the center of the camera lens. Just having a problem figuring out how to do that in FreeCAD).
    2. Make sure the pieces are completely pushed together snuggly (they can be a little tight) so that the dimensions are correct.
    3. The right-most ball in the image above will be referred to as Ball 1 because that ball is the one camera 1 points to (at least in the current version of PITrac). The Camera 2 ball that is positioned in mid-air is Ball 2.
  3. Rig Alignment
    1. Placement:
      1. Version 2.0 enclosure:
        1. The 2.0 enclosure has a small square hole in the middle of the bottom front side into which the tab of the rig is inserted for alignment. You’ll still need to make sure the rest of the rig is square to the monitor.
          Picture 4_1 - PiTrac - Ver 2 Enclosure Rig Positioning (Picture 4_1)
      2. Version 1.0 enclosure:
        1. The original 1.0 enclosure did not have a mounting/alignment hole for the rig. Instead, make sure that the tab of the rig closest to the LM is centered underneath the lowest camera. Place the tab on the diagonal part of the enclosure so that the end edge of the wider part of the rearmost part of the rig is aligned with the outside of the lower part of the enclosure:
          Picture 4_2 - PiTrac - Ver 1 Enclosure Rig Positioning (Picture 4_2)
    2. For a more precise calibration, use a carpenter’s square (or similar) to make sure that the rig is at right angles to everything on the launch monitor:

    Picture 3_0 - PiTrac Calibration Rig w Square (Picture 3_0)

    1. Note that the parts can sometimes print with a bit of a warp.
  4. Aim/align the cameras:
    1. If not already done as part of the focusing operation, ensure that Camera 1 is pointing directly at Ball 1 and that Camera 2 is pointing slightly below Ball 2, but otherwise straight out from the monitor. Just do your best – They do not have to be in exact positions, but the calibration accuracy will be better if the cameras are close to pointing directly at the ball. The whole point of auto-calibration is that it will figure out what the exact angles are.
    2. Double-check that the two cameras are roughly pointing in the appropriate directions. Note that the flight Camera 2 is expected to point a little below the Ball 2.
    3. Ensure the camera screws are tightened down to prevent any future movement of the cameras after calibration.

Software Setup:

  1. First, PiTrac needs to be told exactly where each ball will be with respect to the corresponding camera. This is done by setting the x, y, and z offsets from the center of the camera lens to the center of the golf ball. Those values must be put into the .json configuration file in the “calibration” section.

  2. For the Version 1.0 Enclosure and the standard calibration rig, these values are shown below:

       "calibration": {

        "Looking out from cameras, positive X distance is to the right, positive y is up, and positive Z is outward": "0",

        "kAutoCalibrationBallPositionFromCamera1Meters": \[

            "-0.525",

            "-0.275",

            "0.45"

        \],

        "kAutoCalibrationBallPositionFromCamera2Meters": \[

            "0.0",

            "0.095",

            "0.435"

        \],

        "kNumberPicturesForFocalLengthAverage": "6",

        "kTestAutoCalibrationFileName": "M:\\\\Dev\\\\PiTrac\\\\Software\\\\LMSourceCode\\\\Images\\\\autocalibrate\_cam1\_still\_picture\_1.png"
    1. You should also sanity check the above values by using a tape measure.
  3. As mentioned above, the two sets of measurements shown above are for the Version 1 enclosure and the pre-built calibration rig. These values were derived by using the measurement tool in FreeCad as shown below:

Picture 2_0 - Calibration Rig with PiTrac Ver 1 0 (Picture 2_0)

  1. We also have the following measurements for the Version 2.0 enclosure, but these haven’t been tested:

            "kAutoCalibrationBallPositionFromCamera1Meters": \[

            "-0.504",

            "-0.234",

            "0.491"

        \],

        "kAutoCalibrationBallPositionFromCamera2Meters": \[

            "0.0",

            "0.088",

            "0.466"
    1. The above numbers were calculated similarly, from this 3D model:
      Picture 6_0 - Calibration Rig with PiTrac Ver 2 0 (Picture 6_0)
  2. Next, as a sanity check, we will take a test picture from each camera to its associated ball.
    1. For camera 1, use the runCam1Still.sh to see how close the ball is to the visual center of the image frame. That script will output a file named cam1_still_picture.png in whatever directory is specified in the environment variable $PITRAC_BASE_IMAGE_LOGGING_DIR. (e.g., /home/pictrac/LM_Shares/WebShare)
      1. You’ll need to ensure sufficient lighting (PiTrac LEDs on) for this picture to work well.
    2. For Camera 2, you will need to run runCam2Still.sh on Pi 1 as well as runCam2ForAutoCalibration.sh on Pi 2. This arrangement is required because (for now), Pi 2 is still the only executable environment that can access Camera 2. This process will take longer, but should also output a file cam2_still_picture.png as the camera 1 process does.

    3. Ensure that the focus is good for both pictures. Examples of good camera 1 and 2 pictures are shown below:
      Picture 7_0 - Cam 1 - cam1_still_picture Picture 8_0 - Cam 2 Base Autocalibration Image

      (Picture 7_0 and Picture 8_0)

    4. Note that currently the Camera 2 picture tends to be over-saturated from all the strobe pulses hitting the ball in the same place and will probably not look as focused.
  3. Running the Auto-Calibration process
    1. The Auto-Calibration process works similarly for cameras 1 and 2, though the second Pi (Pi 2) is required as well as Pi 1 for calibrating Camera 2.
    2. PRIOR to running any calibration, make sure you store a copy of your current golf_sim_config.json file in a safe place. Although the original file’s settings should be preserved (except for focal length and camera angles), you never know if some bug could trash your original file.
    3. Camera 1
    4. Make sure there is a ball on the rig’s positioning pad that is on the floor and in the view of camera 1 looking down on that ball.
    5. Run the runAutoCalibrateCam1.sh
    6. The script will first take a series of pictures to find an average focal length. Next, it will use the last picture taken to calculate the camera’s angles with respect to axes that are orthogonal to the launch monitor.
      1. Look for a line like the following in the logging file output:
      2. [2025-05-05 15:57:30.892196] (0x00007fff0f7d8040) [info] Calibrated focal length for distance 0.744144 and Radius: 53.111847 mm is 6.460002.[
    7. The original golf_sim_config.json will be saved in a file named in a pattern like: golf_sim_config.json_BACKUP_2025-May-01_21.02.20.json.
    8. The current golf_sim_config.json will be updated with the new focal length and the x, y angles for Camera 1 (or 2).

    9. To make sure things are working, the system will save copies of the pictures it took along with a green circle identifying where PiTrac decided the ball was. Check to make sure the circle is tightly around the ball. Decent example pictures are shown below:

      Picture 12_0 - Cam 1 - kCameraXBallLocation_2 Picture 10_0 - Cam 2 - Focal_Length_Autocalibration_Image_3

      (Picture 12_0, Picture 10_0)

    10. Next, as a sanity check, leave the ball where it is and run the script called runCam1BallLocation.sh. If everything is working, the x, y, z distances to the ball should be very close to the values provided in the golf_sim_config.json in the kAutoCalibrationBallPositionFromCamera1Meters parameter.

         "calibration": {

        "Looking out from cameras, positive X distance is to the right, positive y is up, and positive Z is outward": "0",

        "kAutoCalibrationBallPositionFromCamera1Meters": \[

            "-0.525",

            "-0.275",

            "0.45"

        \],
    11. Camera 2
      1. To perform auto-calibration for Camera 2, you do basically the same things as above for Camera 1. But, you will need to run the PiTrac script named runCam2ForAutoCalibration.sh on Pi 2 prior to starting the auto-calibration on Pi 1. And of course, runAutoCalibrateCam2.sh instead of the version for Camera 1.
        1. Because the Camera 2 calibration process relies on the second Pi and camera, it will run much slower than the Camera 1 calibration. This can be shortened if necessary by reducing the number of picture samples that will be taken to find an average focal length. That value is stored in “calibration.kNumberPicturesForFocalLengthAverage”.
        2. The runCam2ForAutoCalibration.sh is currently not shutting down by itself at the end of the process, so you will have to Ctrl-C it or otherwise kill the process.