sportslabkit.camera.calibrate

Overview

Function

detect_corners(camera, scale, fps, num_corners_x, num_corners_y)	Detects the corners in a set of images.
select_images(imgpoints, objpoints, points_to_use)	Select a subset of images based on their location in the image plane.
calibrate_camera_zhang(objpoints, imgpoints, dim)	Compute camera matrix and distortion coefficients using Zhang’s method.
calibrate_camera_fisheye(objpoints, imgpoints, dim, balance)	Compute camera matrix and distortion coefficients using fisheye method.
find_intrinsic_camera_parameters(media_path, fps, scale, save_path, draw_on_save, points_to_use, calibration_method, return_mappings)	Calculate the intrinsic parameters of a camera from a video of a checkerboard pattern.
calibrate_video_from_mappings(media_path, mapx, mapy, save_path, stabilize)	Calibrates a video using provided mapping parameters.

Functions

sportslabkit.camera.calibrate.detect_corners(camera, scale: float, fps: float, num_corners_x: int = 5, num_corners_y: int = 9)

Detects the corners in a set of images.

This function detects the corners in a set of images using the cv2.findChessboardCorners function. The input images are downsampled using the scale parameter to increase processing speed. The function returns a tuple of two lists, objpoints and imgpoints, containing 3D points in real world space and 2D points in the image plane, respectively.

Parameters:

• camera (Camera) – A Camera object representing the camera from which the images were captured.

• scale (float) – The scale to resize the images for faster detection. Must be greater than 0.

• fps (float) – The frames per second to process. Must be greater than 0.

• num_corners_x (int, optional) – The number of corners along the x-axis in the checkerboard pattern. Defaults to 5.

• num_corners_y (int, optional) – The number of corners along the y-axis in the checkerboard pattern. Defaults to 9.

Returns:

A tuple containing two lists, objpoints and imgpoints. objpoints is a list of 3D points in real world space, and imgpoints is a list of 2D points in the image plane.

Return type:

tuple

Raises:

• ValueError – If scale or fps is less than or equal to 0.

• AssertionError – If no images are found in the video.

sportslabkit.camera.calibrate.select_images(imgpoints, objpoints, points_to_use: int)

Select a subset of images based on their location in the image plane.

This function selects a subset of images based on the location of the corners in the image plane. The images are sorted by their distance to the origin and a specified number of images is selected to use.

Parameters:

• imgpoints (list) – A list of 2D points in the image plane.

• objpoints (list) – A list of 3D points in real world space.

• points_to_use (int) – The number of images to use. Must be greater than 0.

Returns:

A tuple containing two lists, objpoints and imgpoints. objpoints is a list of 3D points in real world space, and imgpoints is a list of 2D points in the image plane.

Return type:

tuple

Raises:

ValueError – If points_to_use is less than or equal to 0.

sportslabkit.camera.calibrate.calibrate_camera_zhang(objpoints, imgpoints, dim)

Compute camera matrix and distortion coefficients using Zhang’s method.

Parameters:

• objpoints (list) – A list of 3D points in real world space.

• imgpoints (list) – A list of 2D points in the image plane.

• dim (tuple) – The image dimensions.

Returns:

A tuple containing the camera matrix, distortion coefficients, rotation vectors, and translation vectors.

Return type:

tuple

sportslabkit.camera.calibrate.calibrate_camera_fisheye(objpoints, imgpoints, dim, balance=1)

Compute camera matrix and distortion coefficients using fisheye method.

Parameters:

• objpoints (list) – A list of 3D points in real world space.

• imgpoints (list) – A list of 2D points in the image plane.

• dim (tuple) – The image dimensions.

• balance (float) – The balance factor. Must be between 0 and 1. Larger values wil

Returns:

A tuple containing the camera matrix, distortion coefficients, rotation vectors, and translation vectors.

Return type:

tuple

sportslabkit.camera.calibrate.find_intrinsic_camera_parameters(media_path: sportslabkit.types.types.PathLike, fps: int = 1, scale: int = 4, save_path: PathLike | None = None, draw_on_save: bool = False, points_to_use: int = 50, calibration_method: str = 'zhang', return_mappings: bool = True) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Calculate the intrinsic parameters of a camera from a video of a checkerboard pattern.

This function takes a video file containing a checkerboard pattern and calculates the intrinsic parameters of the camera. The video is first processed to locate the corners of the checkerboard in each frame. These corners are then used to compute the intrinsic parameters of the camera.

Parameters:

• media_path (Union[str, Path]) – Path to the video file or a list of video files containing the checkerboard pattern. Wildcards are supported.

• fps (int, optional) – Frames per second to use when processing the video. Defaults to 1.

• scale (int, optional) – Scale factor to use when processing the video. Defaults to 4.

• save_path (Optional[Union[str, Path]], optional) – Path to save the computed intrinsic parameters. If not specified, the parameters are not saved. Defaults to None.

• draw_on_save (bool, optional) – If True, the corners of the checkerboard are drawn on the frames and saved with the intrinsic parameters. Defaults to False.

• points_to_use (int, optional) – Number of frames to use when calculating the intrinsic parameters. If more frames are found than this number, a subset of frames is selected based on their location in the image plane. Defaults to 50.

• calibration_method (str, optional) – Calibration method to use. Must be either “zhang” or “fisheye”. Defaults to “zhang”.

• return_mappings (bool, optional) – If True, the function returns the computed mapping functions along with the intrinsic parameters. Defaults to True.

Returns:

A tuple containing the camera matrix, distortion coefficients, and mapping functions (if return_mappings is True).

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

Raises:

ValueError – If the calibration_method is not “zhang” or “fisheye”.

sportslabkit.camera.calibrate.calibrate_video_from_mappings(media_path: sportslabkit.types.types.PathLike, mapx: numpy.typing.NDArray, mapy: numpy.typing.NDArray, save_path: sportslabkit.types.types.PathLike, stabilize: bool = True)

Calibrates a video using provided mapping parameters.

Args: media_path (str): The path to the input video file. mapx (NDArray): The mapping array for x-axis. mapy (NDArray): The mapping array for y-axis. save_path (str): The path to save the calibrated video. stabilize (bool, optional): Whether to stabilize the video or not. Default is True.

Returns: None