sportslabkit.dataframe.bboxdataframe#

Overview#

Classes#
`BBoxDataFrame`	Bounding box data frame.

Function#
`add_bbox_to_frame`(image, left, top, right, bottom, label, color)	Add bounding box and label to image.
`add_frame_id_to_frame`(image, frame_id)	Add frame id to image.

Attributes#
`X_INDEX`	-
`Y_INDEX`	-
`W_INDEX`	-
`H_INDEX`	-
`CONFIDENCE_INDEX`	-
`CLASS_ID_INDEX`	-
`IMAGE_NAME_INDEX`	-
`OBJECT_ID_INDEX`	-

Classes#

class sportslabkit.dataframe.bboxdataframe.BBoxDataFrame[source]#

Bases: sportslabkit.dataframe.base.BaseSLKDataFrame

Bounding box data frame.

Parameters:: pd.DataFrame (pd.DataFrame) – Pandas DataFrame object.
Returns:: Bounding box data frame.
Return type:: BBoxDataFrame

Note

The bounding box data frame is a pandas DataFrame object with the following MultiIndex structure: Level 0: Team ID(str) Level 1: Player ID(str) Level 2: Attribute

and the following attributes:: frame (float): Frame ID. bb_left (float): Bounding box left coordinate. bb_top (float): Bounding box top coordinate. bb_width (float): Bounding box width. bb_height (float): Bounding box height. conf (float): Confidence of the bounding box.

Since SoccerTrack basically only handles ball and person classes, class_id, etc. are not included in the BBoxDataframe for simplicity. However, they are needed for visualization and calculation of evaluation indicators, so they are generated as needed in additional attributes.

Overview

Methods#
`visualize_frame`(frame_idx, frame, draw_frame_id)	Visualize the bounding box of the specified frame.
`visualize_frames`(video_path, save_path, **kwargs)	Visualize bounding boxes on a video.
`to_yolo_format`()	abc Convert a dataframe to the YOLO format.
`to_yolov5_format`(mapping, na_class, h, w, save_dir)	Convert a dataframe to the YOLOv5 format.
`to_mot_format`()	Convert a dataframe to the MOT format.
`to_labelbox_segment`()	Convert a dataframe to the Labelbox segment format.
`to_labelbox_data`(data_row, schema_lookup)	Convert a dataframe to the Labelbox format.
`to_list_of_tuples_format`(mapping, na_class)	Convert a dataframe to a list of tuples.
`to_codf`(H, method)	Converts bounding box dataframe to a new coordinate dataframe using a given homography matrix.
`preprocess_for_mot_eval`()	Preprocess a dataframe for evaluation using the MOT metrics.
`from_dict`(d, attributes)	static Create a BBoxDataFrame from a nested dictionary contating the coordinates of the players and the ball.

Members

visualize_frame(frame_idx: int, frame: numpy.ndarray, draw_frame_id: bool = False) → numpy.ndarray[source]#

Visualize the bounding box of the specified frame.

Parameters:

self (BBoxDataFrame) – BBoxDataFrame object.
frame_idx (int) – Frame ID.
frame (np.ndarray) – Frame image.
draw_frame_id (bool, optional) – Whether to draw the frame ID. Defaults to False.

Returns:

Frame image with bounding box.

Return type:

frame(np.ndarray)

visualize_frames(video_path: str, save_path: str, **kwargs) → None[source]#

Visualize bounding boxes on a video.

Parameters:: video_path (str) – Path to the video file.
Returns:: None

abstract to_yolo_format()[source]#

Convert a dataframe to the YOLO format.

Returns:: Dataframe in YOLO format.
Return type:: pd.DataFrame

to_yolov5_format(mapping: dict[dict[Any, Any], dict[Any, Any]] | None = None, na_class: int = 0, h: int | None = None, w: int | None = None, save_dir: str | None = None)[source]#

Convert a dataframe to the YOLOv5 format.

Converts a dataframe to the YOLOv5 format. The specification for each line is as follows: <class_id> <x_center> <y_center> <width> <height>

One row per object
Each row is class x_center y_center width height format.
Box coordinates must be normalized by the dimensions of the image (i.e. have values between 0 and 1)
Class numbers are zero-indexed (start from 0).

Parameters:

mapping (dict, optional) – Mappings from team_id and player_id to class_id. Should contain one or two nested dictionaries like {‘TeamID’:{0:1}, ‘PlayerID’:{0:1}}. Defaults to None. If None,the class_id will be inferred from the team_id and player_id and set such that players=0 and ball=1.
na_class (int, optional) – Class ID for NaN values. Defaults to 0.
h (int, optional) – Height of the image. Unnecessary if the dataframe has height metadata. Defaults to None.
w (int, optional) – Width of the image. Unnecessary if the dataframe has width metadata. Defaults to None.
save_dir (str, optional) – If specified, saves a text file for each frame in the specified directory. Defaults to None.

Returns:

list of shape (N, M, 5) in YOLOv5 format. Where N is the number of frames, M is the number of objects in the frame, and 5 is the number of attributes (class_id, x_center, y_center, width, height).

Return type:

list

to_mot_format()[source]#

Convert a dataframe to the MOT format.

Returns:: Dataframe in MOT format.
Return type:: pd.DataFrame

to_labelbox_segment() → dict[source]#

Convert a dataframe to the Labelbox segment format.

Parameters:: self (BBoxDataFrame) – BBoxDataFrame object.
Returns:: Dictionary in Labelbox segment format.
Return type:: segment

Notes

The Labelbox segment format is a dictionary with the following structure: {feature_name:

{keyframes:

{frame:

{bbox:
{top: XX, left: XX, height: XX, width: XX},

label: label }

}, {frame: …

}

}

}

to_labelbox_data(data_row: object, schema_lookup: dict) → list[source]#

Convert a dataframe to the Labelbox format.

Parameters:

self (BBoxDataFrame) – BBoxDataFrame object.
data_row (DataRow) – DataRow object.
schema_lookup (dict) – Dictionary of label names and label ids.

Returns:

List of dictionaries in Labelbox format.

Return type:

uploads(list)

to_list_of_tuples_format(mapping: dict[dict[Any, Any], dict[Any, Any]] | None = None, na_class: int | str = 'player')[source]#

Convert a dataframe to a list of tuples.

Converts a dataframe to a list of tuples necessary for calculating object detection metrics such as mAP and AP scores. The specification for each list element is as follows: (x, y, w, h, confidence, class_id, image_name, object_id)

Returns:: List of tuples.
Return type:: list

to_codf(H: numpy.ndarray, method: str = 'bottom_middle') → sportslabkit.dataframe.coordinatesdataframe.CoordinatesDataFrame[source]#

Converts bounding box dataframe to a new coordinate dataframe using a given homography matrix.

This function takes a dataframe of bounding boxes and applies a perspective transformation to a specified point within each bounding box (e.g., center, bottom middle, top middle) into a new coordinate frame (e.g., a pitch coordinate frame). The result is returned as a CoordinatesDataFrame.

Parameters:

self (BBoxDataFrame) – A dataframe containing bounding box coordinates.
H (np.ndarray) – A 3x3 homography matrix used for the perspective transformation.
method (str) – Method to determine the point within the bounding box to transform. Options include ‘center’, ‘bottom_middle’, ‘top_middle’.

Returns:

A dataframe containing the transformed coordinates.

Return type:

CoordinatesDataFrame

Example

H = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]) bbox_data = BBoxDataFrame(…) codf = bbox_data.to_codf(H, method=’bottom_middle’)

preprocess_for_mot_eval()[source]#

Preprocess a dataframe for evaluation using the MOT metrics.

Parameters:: self (BBoxDataFrame) – BBoxDataFrame object.
Returns:: List of lists of object ids for each frame. dets (list): A list of arrays of detections in the format (x, y, w, h) for each frame.
Return type:: ids (list)

static from_dict(d: dict, attributes: Iterable[str] | None = ('bb_left', 'bb_top', 'bb_width', 'bb_height'))[source]#

Create a BBoxDataFrame from a nested dictionary contating the coordinates of the players and the ball.

The input dictionary should be of the form: {

home_team_key: {
PlayerID: {frame: [x, y], …}, PlayerID: {frame: [x, y], …}, …

}, away_team_key: {

PlayerID: {frame: [x, y], …}, PlayerID: {frame: [x, y], …}, …

}, ball_key: {

frame: [x, y], frame: [x, y], …

}

} The PlayerID can be any unique identifier for the player, e.g. their jersey number or name. The PlayerID for the ball can be omitted, as it will be set to “0”. frame must be an integer identifier for the frame number.

Parameters:

dict (dict) – Nested dictionary containing the coordinates of the players and the ball.
attributes (Optional[Iterable[str]], optional) – Attributes to use for the coordinates. Defaults to (“x”, “y”).

Returns:

CoordinatesDataFrame.

Return type:

CoordinatesDataFrame

Functions#

sportslabkit.dataframe.bboxdataframe.add_bbox_to_frame(image: numpy.ndarray, left: int, top: int, right: int, bottom: int, label: str | None = None, color: str | None = None) → numpy.ndarray[source]#

Add bounding box and label to image.

Parameters:

img (np.ndarray) – Image.
left (int) – Bounding box left coordinate.
top (int) – Bounding box top coordinate.
right (int) – Bounding box right coordinate.
bottom (int) – Bounding box bottom coordinate.
label (str) – Label.
color (str) – Color.

Returns:

Image with bounding box and label.

Return type:

img (np.ndarray)

sportslabkit.dataframe.bboxdataframe.add_frame_id_to_frame(image: numpy.ndarray, frame_id: int) → numpy.ndarray[source]#

Add frame id to image.

Parameters:

img (np.ndarray) – Image.
frame_id (int) – Frame id.

Returns:

Image with frame id.

Return type:

img (np.ndarray)

Attributes#

sportslabkit.dataframe.bboxdataframe.X_INDEX = 0[source]#

sportslabkit.dataframe.bboxdataframe.Y_INDEX = 1[source]#

sportslabkit.dataframe.bboxdataframe.W_INDEX = 2[source]#

sportslabkit.dataframe.bboxdataframe.H_INDEX = 3[source]#

sportslabkit.dataframe.bboxdataframe.CONFIDENCE_INDEX = 4[source]#

sportslabkit.dataframe.bboxdataframe.CLASS_ID_INDEX = 5[source]#

sportslabkit.dataframe.bboxdataframe.IMAGE_NAME_INDEX = 6[source]#

sportslabkit.dataframe.bboxdataframe.OBJECT_ID_INDEX = 7[source]#