### Install via pip Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/installation.ipynb Standard installation command for the library. ```bash pip install sportslabkit ``` -------------------------------- ### Build and Serve Documentation Locally Source: https://github.com/atomscott/sportslabkit/blob/develop/contributing.md Commands to generate the documentation and start a local server for previewing changes. ```bash make html ``` ```bash make serve ``` -------------------------------- ### Install from development branch Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/installation.ipynb Install the latest features directly from the development branch on GitHub. ```bash pip install git+https://github.com/atomscott/sportslabkit.git@develop#egg=sportslabkit ``` -------------------------------- ### Loading Dataset and Camera Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/motion_model.ipynb Setup the environment by loading dataset paths and initializing the camera object for video processing. ```python import soccertrack as st dataset_path = st.datasets.get_path("wide_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] root = st.utils.get_git_root() cam = st.Camera(path_to_mp4) # let's load the first frame of the video frame = cam.get_frame(0) ``` -------------------------------- ### Setup development environment with Conda and Poetry Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/installation.ipynb Commands to create a conda environment and install dependencies using Poetry. ```bash conda env create --file dev_environment.yaml --name sportslabkit_dev_env ``` ```bash conda activate sportslabkit_dev_env poetry install ``` -------------------------------- ### Execute Player Tracking Workflow Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Example workflow for extracting a quadrilateral from a hull and visualizing it on a frame. ```python hull = FLD(frames[2]) print(hull.shape) quadrilateral = hull_to_quadrilateral(hull) image_with_quadrilateral = draw_quadrilateral_on_image(frames[0], quadrilateral) slk.utils.cv2pil(image_with_quadrilateral, convert_bgr2rgb=False) ``` -------------------------------- ### Install SportsLabKit and dependencies Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/kaggle_notebook_soccertrack.ipynb Install the required libraries for tracking and image embeddings in a Jupyter environment. ```python %pip install sportslabkit --quiet %pip install git+https://github.com/KaiyangZhou/deep-person-reid.git --quiet ``` -------------------------------- ### Install SportsLabKit via pip Source: https://github.com/atomscott/sportslabkit/blob/develop/README.md Use this command to install the package in your Python environment. ```bash pip install SportsLabKit ``` -------------------------------- ### Define Camera Ranges in YAML Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/camera.ipynb Example configuration for defining spatial coverage areas for multiple cameras in a YAML file. ```yaml - label: Blue Cam x_range: - 0 - 52.5 y_range: - 0 - 68 - label: Red Cam x_range: - 52.5 - 105 y_range: - 0 - 68 ``` -------------------------------- ### Initialize Camera Objects Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/camera.ipynb Demonstrates the instantiation of Camera objects using a configuration dictionary. Ensure the configuration file path is correctly specified before loading. ```python # from sportslabkit.camera import load_cameras # cameras = load_cameras(cfg['cameras']) # print(f"Loaded {len(cameras)} cameras") # WIP ``` -------------------------------- ### Initialize Camera Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/single_object_tracker.ipynb Set up the Camera object using dataset paths. ```python import sportslabkit as slk dataset_path = slk.datasets.get_path("wide_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] root = slk.utils.get_git_root() cam = slk.Camera(path_to_mp4) ``` -------------------------------- ### Initialize and run tracking pipeline Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/introduction_to_sportslabkit.ipynb Configure detection and motion models to track objects, then execute the tracker on a video segment. ```python from sportslabkit.utils import get_git_root from sportslabkit.mot import SORTTracker root = get_git_root() cam = slk.Camera(path_to_mp4) det_model = slk.detection_model.load('YOLOv8x', imgsz=640) motion_model = slk.motion_model.load('KalmanFilter', dt=1/30, process_noise=10000, measurement_noise=10) tracker = SORTTracker(detection_model=det_model, motion_model=motion_model) tracker.track(cam[:100]) res = tracker.to_bbdf() ``` -------------------------------- ### Assigning Team IDs to Tracklets Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Example of iterating through tracklets to assign a predicted team ID. ```python predit_teamid def f(all_tracklets): for tracklet in all_tracklets: prediction_id = predit_teamid(tracklet) tracklet.teamid = xxx return all_tracklets f(all_tracklets) ``` -------------------------------- ### Run object tracking Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/kaggle_notebook_soccertrack.ipynb Initialize detection and motion models, then execute the SORT tracker. ```python from sportslabkit.mot import SORTTracker det_model = slk.detection_model.load('YOLOv8x', imgsz=640) motion_model = slk.motion_model.load('KalmanFilter', dt=1/30, process_noise=10000, measurement_noise=10) tracker = SORTTracker(detection_model=det_model, motion_model=motion_model) res = tracker.track(cam) ``` -------------------------------- ### Initialize Camera and Read Frames Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/camera.ipynb Demonstrates how to initialize a Camera object with a video path and access specific frames. ```python import sportslabkit as slk # Get a video dataset_path = slk.datasets.get_path("wide_view") path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] cam = slk.Camera(path_to_mp4) frame = cam[0] # Get the first frame print(frame.shape) ``` ```text Output: (1000, 6500, 3) ``` -------------------------------- ### Prepare Dataset and Camera Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/05_tracking_the_ball.ipynb Initialize the dataset paths and camera object for processing. ```python import sportslabkit as slk root = slk.utils.get_git_root() dataset_path = slk.datasets.get_path('top_view') path_to_csv = sorted(dataset_path.glob('annotations/*.csv'))[-1] path_to_mp4 = sorted(dataset_path.glob('videos/*.mp4'))[-1] bbdf_gt = slk.load_df(path_to_csv) # We will use this as ground truth cam = slk.Camera(path_to_mp4) # Camera object will be used to load frames n_frames = 100 # Let's reduce the number of frames to 100 for now ``` -------------------------------- ### Initialize KaggleDownloader Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/00_dataset_preparation.ipynb Initialize the downloader class to begin the authentication process with Kaggle. ```python import sportslabkit as slk dl = slk.datasets.KaggleDownloader() ``` -------------------------------- ### Overlay DataFrame information on images Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/02_dataframe_visualization.ipynb Defines a function to iterate through a DataFrame and draw text on an image using OpenCV, with an example of integrating it into a video generation pipeline. ```python import cv2 import pandas as pd def write_dataframe_on_image(df, image, start_pos=(10, 10), font_scale=0.5, color=(255, 255, 255)): # Define the starting position x, y = start_pos # Loop through DataFrame and write text on the image counter = 1 for index, row in df.iterrows(): TeamID = index[1] PlayerID = index[2] text = f"TID: {TeamID} PID: {PlayerID}, x: {row['bb_top']:.2f}, y: {row['bb_left']:.2f}, w: {row['bb_width']:.2f}, h: {row['bb_height']:.2f}" cv2.putText(image, text, (x, int(y + counter * 30 * font_scale * 1.3)), cv2.FONT_HERSHEY_SIMPLEX, font_scale, color, 2) counter += 1 return image # Example usage: # for i, frame in enumerate(cam.iter_frames()): # frame = plot_frame(i+1, frame[:,:,::-1]) # Ensure plot_frame is defined # frame_df = df[df.index == i+1].to_long_df() # Ensure to_long_df is defined # image = write_dataframe_on_image(frame_df, frame, start_pos=(50, 50), font_scale=1, color=(20,255,83)) def f(i, frame): frame = plot_frame(i+1, frame[:,:,::-1]) # Ensure plot_frame is defined frame_df = df[df.index == i+1].to_long_df() # Ensure to_long_df is defined image = write_dataframe_on_image(frame_df, frame, start_pos=(1000, 50), font_scale=1, color=(20,255,83)) return image cam = slk.Camera(wide_view_mp4) slk.utils.make_video((f(i, frame) for i, frame in enumerate(cam.iter_frames())), "video.mp4", input_framerate=25) ``` -------------------------------- ### Run Tracking and Visualize Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/single_object_tracker.ipynb Execute the tracking process and save the output video. ```python tracklet = tracker.track(frames) bbdf = tracklet.to_bbdf() save_path = "assets/meanshift_tracking_results.mp4" bbdf.visualize_frames(cam.video_path, save_path) Video(save_path) ``` -------------------------------- ### Initialize Video Path Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/02_dataframe_visualization.ipynb Verify the existence of a video file path using pathlib. ```python from pathlib import Path path_to_mp4 = Path('/Users/atom/Downloads') / 'A031C0024_20230211201927_0005.mp4' path_to_mp4.exists() ``` -------------------------------- ### Initialize MeanShiftTracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/single_object_tracker.ipynb Set up the tracker using an initial bounding box from detection results. ```python from sportslabkit.sot import MeanShiftTracker from IPython.display import Video # Define the initial target object using a bounding box (x, y, width, height) initial_target = det_result.preds[0, :4].astype(int) # Use the first ground truth position as the initial target initial_frame = frame # Use the first frame as the initial frame target = {"box": initial_target} # Create and initialize the MeanShiftTracker tracker = MeanShiftTracker(target=target, initial_frame=initial_frame) # Track the target object in the sequence of frames frames = cam[:30] # get the first 25 frames ``` -------------------------------- ### Initialize and Run Tracker with Tuned Parameters Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/04_tuning_the_trackers.ipynb Configures detection, motion, and matching models using optimized parameters and executes tracking. ```python det_model = slk.detection_model.load( model_name='yolov8', model=root/'models/yolov8/soccer_top_view-model=yolov8x-imgsz=2048.pt', conf=best_params['conf'], iou=best_params['iou'], imgsz=2048, device=0, classes=0, augment=True, max_det=best_params['max_det'], ) motion_model = slk.motion_model.load( model_name='kalmanfilter', dt=1/30, process_noise=best_params['process_noise'], measurement_noise=best_params['measurement_noise'], confidence_scaler=best_params['confidence_scaler'], ) matching_fn = slk.matching.SimpleMatchingFunction( metric=slk.metrics.EuclideanCMM(use_pred_box=True), gate=best_params['gate'], ) tracker = SORTTracker( detection_model=det_model, motion_model=motion_model, matching_fn=matching_fn, max_staleness=best_params['max_staleness'], min_length=best_params['min_length'], ) bbdf = tracker.track(frames) score = hota_score(bboxes_track=bbdf, bboxes_gt=bbdf_gt)["HOTA"] print(f'HOTA score: {score:.2f}') bbdf.visualize_frames(cam.video_path, root/'notebooks/02_user_guide/assets/sort_tuned.mp4') ``` -------------------------------- ### Initialize Image and Motion Models Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/05_tracking_the_ball.ipynb Loads the OSNet image model and KalmanFilter motion model for tracking. ```python image_model = slk.image_model.load('OSNet_ibn_x1_0') motion_model = slk.motion_model.load('KalmanFilter') ``` -------------------------------- ### Configure and Run TeamTracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/tracking_with_bells_and_whistles.ipynb Initializes the tracking pipeline with detection, motion, calibration, and matching models, then executes tracking on a video segment. ```python from sportslabkit.utils import get_git_root from sportslabkit.mot import TeamTracker from sportslabkit.mot.callbacks import TeamClassificationCallback root = get_git_root() cam = slk.Camera(path_to_mp4) det_model = slk.detection_model.load('YOLOv8x', model=root / 'models/yolov8/soccer_top_view_best.pt', imgsz=1280) motion_model = slk.motion_model.load('GCLinear') calibration_model = slk.calibration_model.load('LineBasedCalibrator', min_line_length=50, line_distance_threshold=50, line_thickness=15, morph_size=15) image_model = slk.image_model.load('resnet50') first_matching_fn = slk.matching.MotionVisualMatchingFunction( motion_metric=slk.metrics.EuclideanCMM2D(use_pred_pt=True), motion_metric_gate=0.9, visual_metric=slk.metrics.CosineCMM(), visual_metric_gate=0.5, beta=0.9, ) second_matching_fn = slk.matching.SimpleMatchingFunction( metric=slk.metrics.EuclideanCMM2D(use_pred_pt=True), gate=0.5, ) vector_model = slk.vector_model.load('sklearnvectormodel', model_path='https://drive.google.com/file/d/1d6SskM1VFc_kIjFbQqEKgnMrmVnDRwWZ/view') callbacks = [TeamClassificationCallback(vector_model)] tracker = TeamTracker( detection_model=det_model, image_model=image_model, motion_model=motion_model, calibration_model=calibration_model, first_matching_fn=first_matching_fn, second_matching_fn=second_matching_fn, detection_score_threshold=0.5, max_staleness=3, min_length=5, callbacks=callbacks, ) res = tracker.track(cam[:10]) ``` -------------------------------- ### Initialize Environment and Project Variables Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/05_dev/labelbox_intergration.ipynb Loads environment variables and defines project-specific identifiers for Labelbox integration. ```python from dotenv import load_dotenv import os from soccertrack.utils import get_git_root load_dotenv() LABELBOX_PROJECT_ID = "cldmd6hrx08ej07yt2rydfine" # This is the project ID for the top-view dataset LABELBOX_PROJECT_NAME = "F_Soccer_Tsukuba3" # This is the project name for the wide-view LABELBOX_DATASET_NAME = "Dataset_Fisheye_Soccer_Tsukuba3" # This is the dataset name for the wide-view LABELBOX_API_KEY = os.getenv("LABELBOX_API_KEY") root = get_git_root() INPUT_BBDF_DIR = root / "soccertrack"/"datasets"/"wide_view"/"annotations" ``` -------------------------------- ### Initialize Detection Environment Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/detection_model.ipynb Loads the dataset paths and initializes the camera object for video processing. ```python import sportslabkit as slk dataset_path = slk.datasets.get_path("wide_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] root = slk.utils.get_git_root() cam = slk.Camera(path_to_mp4) # let's load the first frame of the video frame = cam.get_frame(0) ``` -------------------------------- ### Initialize TeamTracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Configure the detection, image, motion, and calibration models, along with matching functions and callbacks, to instantiate the TeamTracker. ```python from sportslabkit.mot import TeamTracker import numpy as np slk.logger.set_log_level('INFO') det_model = slk.detection_model.load( model_name='yolov8', model=root/'models/yolov8/Soccer_SideView.pt', conf=0.25, iou=0.6, imgsz=640, device='mps', classes=0, augment=True, max_det=35 ) image_model = slk.image_model.load( model_name='mobilenetv2_x1_0', image_size=(32,32), device='mps' ) motion_model = slk.motion_model.load( model_name='SingleTargetLinear', ) # motion_model = slk.motion_model.load( # model_name='SingleTargetLSTM', # model='/Users/atom/Github/SoccerTrack/models/teamtrack/LSTM-F_Soccer_Tsukuba3-epoch=79-val_nll_loss=-2.74.ckpt', # ) keypoint_json = root / 'notebooks/02_user_guide/assets/soccer_keypoints.json' cam.source_keypoints, cam.target_keypoints = slk.utils.load_keypoints(keypoint_json) # calibration model return a 3x3 homography matrix for each frame calibration_model = slk.calibration_model.load( model_name='DummyCalibrationModel', homographies=cam.H, mode='constant' ) first_matching_fn = slk.matching.MotionVisualMatchingFunction( motion_metric=slk.metrics.EuclideanCMM2D(use_pred_pt=True), motion_metric_gate=0.2, visual_metric=slk.metrics.CosineCMM(), visual_metric_gate=0.2, beta=0.9, ) second_matching_fn = slk.matching.SimpleMatchingFunction( metric=slk.metrics.EuclideanCMM2D(use_pred_pt=True), gate=0.9, ) # team_detection_callback = slk.callbacks.TeamDetectionCallback(classication_model=TeamClassifier()) class PrintingCallback(slk.callbacks.Callback): def on_track_sequence_start(self, tracker): tracklets = tracker.alive_tracklets + tracker.dead_tracklets print(f"Tracking started with {len(tracklets)} tracklets") def on_track_sequence_end(self, tracker): tracklets = tracker.alive_tracklets + tracker.dead_tracklets print(f"Tracking ended with {len(tracklets)} tracklets") callbacks = [PrintingCallback()] tracker = TeamTracker( detection_model=det_model, image_model=image_model, motion_model=motion_model, calibration_model=calibration_model, first_matching_fn=first_matching_fn, second_matching_fn=second_matching_fn, detection_score_threshold=0.6, max_staleness=2, min_length=2, callbacks=callbacks, ) ``` -------------------------------- ### Configure and Run Multi-Object Tracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Sets up the tracker with specific model specifications and executes the tracking loop over video frames. ```python import numpy as np import soccertrack from soccertrack import Camera, detection_model from soccertrack.utils import get_git_root from soccertrack.logger import show_df, tqdm, set_log_level from soccertrack.detection_model.base import Detection from soccertrack.tracking_model.tracker import MultiObjectTracker from soccertrack.tracking_model.matching import EuclideanDistance from soccertrack.metrics import mota_score, hota_score, identity_score model_spec = { "dt": 1 / 25, "order_pos": 1, "dim_pos": 2, "order_size": 0, "dim_size": 2, "q_var_pos": best_params["q_var_pos"], "r_var_pos": best_params["r_var_pos"], "q_var_size": best_params["q_var_size"], "r_var_size": best_params["r_var_size"], "p_cov_p0": best_params["p_cov_p0"], } tracker_kwargs = { "max_staleness": best_params["max_staleness"], "smooth_feature_gamma":best_params["smooth_feature_gamma"], "smooth_score_gamma": best_params["smooth_score_gamma"], } gate = best_params["gate"] tracker = MultiObjectTracker( dt = 1/25, model_spec=model_spec, tracker_kwargs=tracker_kwargs, matching_fn=EuclideanDistance(gate), ) def track(cam, tracker): for frame in (pbar := tqdm(cam.iter_frames())): # detect objects using the detection model detections = det_model(frame, augment=True).to_list() # check if detections are withing pich contour # contour = FLD(frame) # detections = filter(lambda x: cv2.pointPolygonTest(contour, (x.box[0], x.box[1]), False) > 0, detections) # use top 22 detections detections = sorted(detections, key=lambda x: x.score, reverse=True)[:22] detections = list(filter(lambda x: x.class_id == 0, detections)) # update the state of the multi-object-tracker tracker # with the list of bounding boxes tracker.step(detections=detections) return tracker root = get_git_root() model_name = "yolov5" model_repo = root / "external" / "yolov5" model_ckpt = root / "models" / "yolov5" / "yolov5x6.pt" det_model = detection_model.load(model_name, model_repo, model_ckpt) det_model.model.conf = 0.01 det_model.model.size = 6000 # dataset_path = soccertrack.datasets.get_path("top-view") csv_paths = sorted(dataset_path.glob("*.csv"))[:1] mp4_paths = sorted(dataset_path.glob("*.mp4"))[:1] scores = [] for path_to_csv, path_to_mp4 in zip(csv_paths, mp4_paths): bbdf = soccertrack.load_df(path_to_csv) # We will use this as ground truth cam = Camera(path_to_mp4) # Camera object will be used to load frames tracker = MultiObjectTracker( dt = 1/25, model_spec=model_spec, tracker_kwargs=tracker_kwargs, matching_fn=EuclideanDistance(gate), ) bbdf_pred_ft = track(cam, tracker).to_bbdf() bbdf_pred_ft.sort_index(inplace=True) bbdf = bbdf[bbdf.index>=1] mota = mota_score(bboxes_gt=bbdf, bboxes_track=bbdf_pred_ft) hota = hota_score(bboxes_gt=bbdf, bboxes_track=bbdf_pred_ft) id = identity_score(bboxes_gt=bbdf, bboxes_track=bbdf_pred_ft) scores.append({ 'MOTA': mota['MOTA'], 'HOTA': hota['HOTA'], 'DetA': hota['DetA'], 'AssA': hota['AssA'], 'IDF1': id['IDF1'], }) print(f'{path_to_mp4.name} MOTA: {mota["MOTA"]:.2f} HOTA: {hota["HOTA"]:.2f}') ``` -------------------------------- ### Initialize and Run SORT Tracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/07_tracking_method_comparison.ipynb Configures the detection model, motion model, and matching function before executing the tracker on the prepared frames. ```python from sportslabkit.mot import SORTTracker det_model = slk.detection_model.load( model_name='yolov8', model=root/'models/yolov8/soccer_top_view-model=yolov8x-imgsz=2048.pt', conf=0.25, iou=0.6, imgsz=960, device='mps', classes=0, augment=True, max_det=35 ) motion_model = slk.motion_model.load( model_name='kalmanfilter', dt=1/30, process_noise=500, measurement_noise=10, confidence_scaler=1 ) matching_fn = slk.matching.SimpleMatchingFunction( metric=slk.metrics.IoUCMM(use_pred_box=True), gate=0.9 ) tracker = SORTTracker( detection_model=det_model, motion_model=motion_model, matching_fn=matching_fn, max_staleness=2, min_length=2 ) bbdf_pred = tracker.track(frames) hota = slk.metrics.hota_score(bbdf_gt, bbdf_pred)["HOTA"] print(f"HOTA Score before Tuning (SORTTracker): {hota:.3f}") ``` -------------------------------- ### Run Tracking Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Execute the tracking process on the prepared frames. ```python tracker.track(frames) ``` -------------------------------- ### Prepare Dataset for Tracking Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/07_tracking_method_comparison.ipynb Loads video and annotation data from the dataset path and selects the first 10 frames for processing. ```python import sportslabkit as slk from sportslabkit.logger import set_log_level dataset_path = slk.datasets.get_path("top_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] root = slk.utils.get_git_root() cam = slk.Camera(path_to_mp4) # For the sake of speed, we'll only use the first 10 frames n_frames = 10 frames = cam[:n_frames] bbdf_gt = slk.load_df(path_to_csv) # TODO: Hopefully we can get rid of this if bbdf_gt.index[0] == 0: bbdf_gt.index += 1 bbdf_gt = bbdf_gt[:n_frames] ``` -------------------------------- ### Load and inspect camera configuration Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/camera.ipynb Loads a YAML configuration file and logs the camera settings for verification. ```python import sportslabkit as slk cfg = slk.utils.load_config('./assets/config.yml') slk.logger.inspect(cfg) ``` -------------------------------- ### Load Dataset and Prepare Dataframes Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/03_evaluation_metrics.ipynb Loads a sample dataset and prepares ground truth and prediction dataframes for metric evaluation. ```python import sportslabkit as slk dataset_path = slk.datasets.get_path('top_view') path_to_csv = sorted(dataset_path.glob('annotations/*.csv'))[0] bbdf = slk.load_df(path_to_csv) # We will use this as ground truth gt_bbdf = bbdf[:5] pred_bbdf = bbdf[1:5] ``` -------------------------------- ### Initialize SORT Tracker with custom configurations Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/04_tuning_the_trackers.ipynb Configures the detection model, motion model, and matching function before initializing the SORTTracker. ```python from sportslabkit.mot import SORTTracker slk.logger.set_log_level('INFO') det_model = slk.detection_model.load( model_name='yolov8', model=root/'models/yolov8/soccer_top_view-model=yolov8x-imgsz=2048.pt', conf=0.25, iou=0.6, imgsz=960, device='mps', classes=0, augment=True, max_det=35 ) motion_model = slk.motion_model.load( model_name='kalmanfilter', dt=1/30, process_noise=500, measurement_noise=10, confidence_scaler=1 ) matching_fn = slk.matching.SimpleMatchingFunction( metric=slk.metrics.EuclideanCMM(use_pred_box=True), gate=0.5 ) tracker = SORTTracker( detection_model=det_model, motion_model=motion_model, matching_fn=matching_fn, max_staleness=2, min_length=2 ) ``` -------------------------------- ### BYTETracker Configuration and Execution Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/07_tracking_method_comparison.ipynb Configures detection, image, and motion models along with matching functions to initialize and run the BYTETracker. ```python from sportslabkit.mot import BYTETracker slk.logger.set_log_level('INFO') det_model = slk.detection_model.load( model_name='yolov8', model=root/'models/yolov8/soccer_top_view-model=yolov8x-imgsz=2048.pt', conf=0.25, iou=0.6, imgsz=960, device='mps', classes=0, augment=True, max_det=35 ) image_model = slk.image_model.load( model_name='mobilenetv2_x1_0', image_size=(32,32), device='mps' ) motion_model = slk.motion_model.load( model_name='kalmanfilter', dt=1/30, process_noise=500, measurement_noise=10, confidence_scaler=1 ) first_matching_fn = slk.matching.MotionVisualMatchingFunction( motion_metric=slk.metrics.IoUCMM(use_pred_box=True), motion_metric_gate=0.2, visual_metric=slk.metrics.CosineCMM(), visual_metric_gate=0.2, beta=0.9, ) second_matching_fn = slk.matching.SimpleMatchingFunction( metric=slk.metrics.IoUCMM(use_pred_box=True), gate=0.9, ) tracker = BYTETracker( detection_model=det_model, image_model=image_model, motion_model=motion_model, first_matching_fn=first_matching_fn, second_matching_fn=second_matching_fn, detection_score_threshold=0.6, max_staleness=2, min_length=2 ) bbdf_pred = tracker.track(frames) hota = slk.metrics.hota_score(bbdf_gt, bbdf_pred)["HOTA"] print(f"HOTA Score before Tuning (BYTETracker): {hota:.3f}") ``` -------------------------------- ### Initialize and Run Motion Model Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Loads a motion model and updates a tracklet with observations to predict movement. ```python import sportslabkit as slk import numpy as np motion_model = slk.motion_model.load( model_name='SingleTargetLSTM', model='/Users/atom/Github/SoccerTrack/models/teamtrack/LSTM-F_Soccer_Tsukuba3-epoch=79-val_nll_loss=-2.74.ckpt', ) tracklet = slk.Tracklet() tracklet.register_observation_types(['pt']) tracklet.update_observation('pt', np.array([105, 65])) motion_model(tracklet) ``` ```text Output: LSTM( (lstm): LSTM(2, 64, num_layers=2, batch_first=True, dropout=0.2, bidirectional=True) (fc0): Linear(in_features=128, out_features=18, bias=True) ) ``` ```text Result: tensor([[105.0209, 65.0018]]) ``` -------------------------------- ### Load model with custom configuration Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/image_model.ipynb Initializes a model with specific overrides, such as changing the input image size. ```python model_config = {"image_size": (32, 32)} resnet = slk.image_model.load("resnet50", model_config=model_config) ``` -------------------------------- ### Inspect model and inference configurations Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/image_model.ipynb Displays the available parameters for model instantiation and inference settings. ```python resnet.show_model_config() resnet.show_inference_config() ``` -------------------------------- ### Define file paths for the demo Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/kaggle_notebook_soccertrack.ipynb Set paths for the annotation CSV, video file, and keypoints JSON. ```python path_to_csv = dataset_root / 'wide_view/annotations/F_20200220_1_0000_0030.csv' path_to_mp4 = dataset_root / 'kaggle/input/soccertrack/wide_view/videos/F_20200220_1_0000_0030.mp4' path_to_kps = dataset_root / 'kaggle/input/soccertrack/fisheye_keypoints.json' ``` -------------------------------- ### Visualize Preprocessing Steps Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/calibration_model.ipynb Debug the calibration process by visualizing contours, hulls, and quadrilaterals on the preprocessed image. ```python def show_preprocess(image, model, thickness=7): contour = model._get_largest_contour(image) hull = model._approximate_hull(contour) quadrilateral = model.order_points(model._approximate_quad(hull)) contour_reshaped = contour.squeeze().astype(np.int32) hull_reshaped = hull.squeeze().astype(np.int32) quad_reshaped = quadrilateral.squeeze().astype(np.int32) r = (255, 0, 0) g = (0, 255, 0) b = (0, 0, 255) preproc_im = model._preprocess_image(image) imc = cv2.cvtColor(preproc_im, cv2.COLOR_GRAY2RGB) cv2.drawContours(imc, [contour_reshaped], 0, r, thickness) cv2.drawContours(imc, [hull_reshaped], 0, g, thickness) cv2.drawContours(imc, [quad_reshaped], 0, b, thickness) return imc res = show_preprocess(frame, calibration_model) slk.utils.cv2pil(res, False) ``` -------------------------------- ### Load Dataset and Frames Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Prepare the video and annotation data for processing. ```python import sportslabkit as slk from sportslabkit.logger import set_log_level dataset_path = slk.datasets.get_path("wide_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] root = slk.utils.get_git_root() cam = slk.Camera(path_to_mp4) # For the sake of speed, we'll only use the first 10 frames n_frames = 2 frames = cam[:n_frames] bbdf_gt = slk.load_df(path_to_csv) # TODO: Hopefully we can get rid of this if bbdf_gt.index[0] == 0: bbdf_gt.index += 1 bbdf_gt = bbdf_gt[:n_frames] ``` -------------------------------- ### Configuring Log Levels Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/05_dev/logging-demo.ipynb Shows how to change the global log level using set_log_level. Case-insensitive strings are accepted. ```python from soccertrack.logger import set_log_level # set the log level to DEBUG set_log_level('DEBUG') logger.debug("That's it, beautiful and simple logging!") # set the log level to CRITICAL set_log_level('critical') # <- using lower case is OK logger.debug("That's it, beautiful and simple logging!") logger.critical("Fire in the hole!") ``` ```text Output: IPython:0005 🐛| That's it, beautiful and simple logging!  IPython:0010 🔥| Fire in the hole!  ``` -------------------------------- ### Implementing a Minimum Cost Flow Tracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/single_object_tracker.ipynb Initializes and runs a MinimumCostFlowTracker with specified detection, image, and motion models. ```python from sportslabkit.logger import set_log_level from sportslabkit.matching import SimpleBatchMatchingFunction from sportslabkit.sot import MinimumCostFlowTracker set_log_level("INFO") matching_fn = SimpleBatchMatchingFunction() # define the player detection model model_config = {"size": 960, "conf":0.1} # make this smaller to speed up inference det_model = slk.detection_model.load(model_name, inference_config=inference_config) image_model = slk.image_model.load("resnet50", {"image_size": 224}) motion_model = None tracker = MinimumCostFlowTracker( target=target, initial_frame=initial_frame, detection_model=det_model, window_size=30, image_model=image_model, motion_model=motion_model, matching_fn=matching_fn, ) tracklet = tracker.track(frames[:30]) bbdf = tracklet.to_bbdf() save_path = "tracking_results-xxx.mp4" bbdf.visualize_frames(cam.video_path, save_path) Video(save_path) ``` -------------------------------- ### Makefile development commands Source: https://github.com/atomscott/sportslabkit/blob/develop/contributing.md Standard Makefile targets for formatting, linting, and testing the project. ```makefile ## format python source code format: poetry run docformatter --in-place -r $(i) poetry run black $(i) poetry run isort $(i) ## Lint using flake8 lint: poetry run docformatter --in-place -r $(i) poetry run black $(i) poetry run isort $(i) poetry run prospector --profile profile.prospector.yaml $(i) ## Run tests using pytest tests: poetry run pytest --cov=./ --cov-report xml /bin/deepsource report --analyzer test-coverage --key python --value-file ./coverage.xml ``` -------------------------------- ### Load Dataset and View Data Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/introduction_to_sportslabkit.ipynb Retrieves a sample dataset path and loads it into a BBoxDataFrame for inspection. ```python import sportslabkit as slk from sportslabkit.logger import show_df # This just makes the df viewable in the notebook. dataset_path = slk.datasets.get_path("wide_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] bbdf = slk.load_df(path_to_csv) bbdf.head() ``` -------------------------------- ### Load Appearance Model Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/06_tracking_the_players.ipynb Initializes the ImageEmbedder using a pre-trained checkpoint file. ```python from soccertrack.image_model import ImageEmbedder dirpath = root / "models" / "resnet18" ckpt_path = list(dirpath.glob('*.ckpt'))[-1] image_model = ImageEmbedder.load_from_checkpoint(ckpt_path, num_classes=2) ``` -------------------------------- ### Load and inspect an image model Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/motion_model.ipynb Instantiates a model by name and displays its inference and model configurations. ```python im_model = st.image_model.load(model_name="ResNet50_fc512") # You can check the current configuration with the following methods: im_model.show_inference_config() im_model.show_model_config() ``` -------------------------------- ### Import SportsLabKit Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/kaggle_notebook_soccertrack.ipynb Import the main library package. ```python import sportslabkit as slk ``` -------------------------------- ### Load video data Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/kaggle_notebook_soccertrack.ipynb Initialize the camera object and extract a frame for visualization. ```python cam = slk.Camera(path_to_mp4) # Camera object will be used to load frames frame = cam[0] # When indexed like this cam will return a numpy array slk.utils.cv2pil(frame, convert_bgr2rgb=False) # Utility function in SportsLabKit to show images ``` -------------------------------- ### Configure and Run DeepSORT Tracker Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/07_tracking_method_comparison.ipynb Initializes detection, image, and motion models before running the tracker on frames to calculate the HOTA score. ```python from sportslabkit.mot import DeepSORTTracker slk.logger.set_log_level('INFO') det_model = slk.detection_model.load( model_name='yolov8', model=root/'models/yolov8/soccer_top_view-model=yolov8x-imgsz=2048.pt', conf=0.25, iou=0.6, imgsz=960, device='mps', classes=0, augment=True, max_det=35 ) image_model = slk.image_model.load( model_name='mobilenetv2_x1_0', image_size=(32,32), device='mps' ) motion_model = slk.motion_model.load( model_name='kalmanfilter', dt=1/30, process_noise=500, measurement_noise=10, confidence_scaler=1 ) matching_fn = slk.matching.MotionVisualMatchingFunction( motion_metric=slk.metrics.IoUCMM(use_pred_box=True), motion_metric_gate=0.2, visual_metric=slk.metrics.CosineCMM(), visual_metric_gate=0.2, beta=0.9, ) tracker = DeepSORTTracker( detection_model=det_model, image_model=image_model, motion_model=motion_model, matching_fn=matching_fn, max_staleness=2, min_length=2 ) bbdf_pred = tracker.track(frames) hota = slk.metrics.hota_score(bbdf_gt, bbdf_pred)["HOTA"] print(f"HOTA Score before Tuning (DeepSORTTracker): {hota:.3f}") ``` -------------------------------- ### Applying Tuned Parameters to Tracklets Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/multi_object_tracker.ipynb Initialize a motion model with tuned parameters and evaluate tracking performance using IoU scores. ```python kf_model = KalmanFilterMotionModel(best_params) predictions = [] tracklet = Tracklet() tracklet.register_observation_types(['box', 'score']) for det in detections: obs = convert_det_to_obs(det) tracklet.update_observations(obs) prediction = kf_model(tracklet) predictions.append(prediction) score = iou_scores(ground_truth_positions, predictions, xywh=True) print(f"Average IoU score: {score:.2f}") display_tracking_animation(detections, ground_truth_positions, predictions=predictions) ``` -------------------------------- ### Applying Hyperparameters Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/04_tuning_the_trackers.ipynb Applies the first set of trial parameters to the tracker instance. ```python tracker.apply_hyperparameters(tracker.trial_params[0]) ``` -------------------------------- ### st.image_model.show_available_models() Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/motion_model.ipynb Lists all available image models that can be loaded. ```APIDOC ## st.image_model.show_available_models() ### Description Returns a list of strings representing the names of all available image models. ### Returns - **list** (string) - A list of available model class names. ``` -------------------------------- ### Generate visualization video Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/introduction_to_sportslabkit.ipynb Create a video file showing bounding box tracking results over a sequence of frames. ```python save_path = 'assets/visualize_frames.mp4' bbdf_short = bbdf.iloc[:100].copy() bbdf_short.visualize_frames(path_to_mp4, save_path) ``` -------------------------------- ### Simulate and display moving object Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/motion_model.ipynb Initializes a simulation of a moving object and displays the tracking animation. ```python from soccertrack.notebook_utils import simulate_moving_object, display_tracking_animation num_frames = 50 detections, ground_truth_positions = simulate_moving_object(num_frames) display_tracking_animation(detections, ground_truth_positions) print("detections@t=0:", detections[0]) print("ground_truth_positions@t=0:", ground_truth_positions[0]) ``` -------------------------------- ### Compare EMA gamma values for tracking Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/multi_object_tracker.ipynb Demonstrates how varying the gamma parameter in ExponentialMovingAverage affects tracking responsiveness. ```python gamma=0.2 ema = ExponentialMovingAverage({'gamma':gamma}) predictions = [] tracklet = Tracklet() tracklet.register_observation_types(['box', 'score']) for det in detections: obs = convert_det_to_obs(det) tracklet.update_observations(obs) prediction = ema(tracklet) predictions.append(prediction) display_tracking_animation(detections, ground_truth_positions, predictions=predictions) ``` ```python gamma=0.8 # try working with different gamma to see how it affects the prediction ema = ExponentialMovingAverage({'gamma':gamma}) predictions = [] tracklet = Tracklet() tracklet.register_observation_types(['box', 'score']) for det in detections: obs = convert_det_to_obs(det) tracklet.update_observations(obs) prediction = ema(tracklet) predictions.append(prediction) display_tracking_animation(detections, ground_truth_positions, predictions=predictions) ``` -------------------------------- ### Visualize preprocessing Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/calibration_model.ipynb Displays the result of the preprocessing steps applied by the calibration model. ```python res = show_preprocess(im, calibration_model) slk.utils.cv2pil(res, False) ``` -------------------------------- ### Load ResNet50 model Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/image_model.ipynb Instantiates a ResNet50 model using the default configuration. ```python resnet = slk.image_model.load("resnet50") ``` -------------------------------- ### Load and Run Detection Model Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/05_tracking_the_ball.ipynb Initializes a YOLOv8 detection model and performs inference on a frame. ```python frame = cam[0] det_model = slk.detection_model.load( 'yolov8', model=root / 'models/yolov8/soccer_top_view-model=yolov8x-imgsz=2048.pt', # path to the checkpoint file classes=[1], # class index of ball to be detected imgsz=2560, device='cuda' ) det_result = det_model(frame)[0] print(det_result.to_df()) im = det_result.show(width=5) im.resize((im.width//4, im.height//4)) ``` -------------------------------- ### Load video and bounding box data Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/01_dataframe_manipulation.ipynb Initialize a Camera object and load annotations from a CSV file using the sportslabkit library. ```python import sportslabkit as slk from sportslabkit.logger import show_df dataset_path = slk.datasets.get_path("wide_view") path_to_csv = sorted(dataset_path.glob("annotations/*.csv"))[0] path_to_mp4 = sorted(dataset_path.glob("videos/*.mp4"))[0] cam = slk.Camera(path_to_mp4) # Camera object will be used to load frames bbdf = slk.load_df(path_to_csv) # We will use this as ground truth bbdf.head() ``` -------------------------------- ### Run Makefile commands Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/01_get_started/installation.ipynb Common tasks for project maintenance and testing using the Makefile. ```bash make clean ``` ```bash make lint ``` ```bash make tests ``` -------------------------------- ### Configure annotators for detections Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/02_user_guide/02_dataframe_visualization.ipynb Initializes color schemes and annotator objects for players, goalkeepers, and the ball. ```python # Colors are in BGR format # Orange BALL_COLOR_HEX = "#005AFF" BALL_COLOR = Color.from_hex_string(BALL_COLOR_HEX) # red GOALKEEPER_1_COLOR_HEX = "#0000FF" GOALKEEPER_COLOR_1 = Color.from_hex_string(GOALKEEPER_1_COLOR_HEX) # yellow GOALKEEPER_2_COLOR_HEX = "#00FFFF" GOALKEEPER_COLOR_2 = Color.from_hex_string(GOALKEEPER_2_COLOR_HEX) # Sky Blue PLAYER_1_COLOR_HEX = "#C0C0C0" PLAYER_COLOR_1 = Color.from_hex_string(PLAYER_1_COLOR_HEX) # Silver PLAYER_2_COLOR_HEX = "#FFFF00" PLAYER_COLOR_2 = Color.from_hex_string(PLAYER_2_COLOR_HEX) COLORS = [ BALL_COLOR, GOALKEEPER_COLOR_1, GOALKEEPER_COLOR_2, PLAYER_COLOR_1, PLAYER_COLOR_2, ] THICKNESS = 4 CLASS_BALL = 0 CLASS_GOALKEEPER_1 = 1 CLASS_GOALKEEPER_2 = 2 CLASS_PLAYER_1 = 3 CLASS_PLAYER_2= 4 # initiate annotators annotator = BaseAnnotator( colors=COLORS, thickness=THICKNESS) text_annotator = TextAnnotator(background_color=Color(255, 255, 255), text_color=Color(0, 0, 0), text_thickness=2) ball_marker_annotator = MarkerAnntator(color=BALL_COLOR) # player_marker_annotator = MarkerAnntator(color=PLAYER_MARKER_FILL_COLOR) ``` -------------------------------- ### Initialize SimpleContourCalibrator Source: https://github.com/atomscott/sportslabkit/blob/develop/notebooks/03_core_components/calibration_model.ipynb Load the calibration model with specific morphological parameters. ```python calibration_model = slk.calibration_model.load('SimpleContourCalibrator', morph_open_size=2, morph_close_size=15, morph_dilate_size=15, morph_erode_size=1, morph_iters=1) ```