opensportslib 0.0.1.dev15__tar.gz → 0.0.1.dev17__tar.gz

{opensportslib-0.0.1.dev15/opensportslib.egg-info → opensportslib-0.0.1.dev17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.0.1.dev15
+Version: 0.0.1.dev17
 Summary: OpenSportsLib is the professional library, designed for advanced video understanding in sports. It provides state-of-the-art tools for action recognition, spotting, retrieval, and captioning, making it ideal for researchers, analysts, and developers working with sports video data.
 Author: Jeet Vora
 Requires-Python: >=3.12
@@ -21,6 +21,7 @@ Requires-Dist: wandb
 Requires-Dist: opencv-python
 Requires-Dist: omegaconf
 Requires-Dist: timm
+Requires-Dist: seaborn
 Provides-Extra: localization
 Requires-Dist: nvidia-dali-cuda120; extra == "localization"
 Requires-Dist: cupy-cuda12x; extra == "localization"

{opensportslib-0.0.1.dev15 → opensportslib-0.0.1.dev17}/opensportslib/apis/localization.py

@@ -101,7 +101,7 @@ class LocalizationAPI:
 
         device = select_device(self.config.SYSTEM)
         self.model = build_model(self.config, device=device)
-        print(self.model)
+        print(f"model: {self.model}")
 
 
         # Datasets
@@ -155,7 +155,7 @@ class LocalizationAPI:
         from opensportslib.core.trainer.localization_trainer import build_inferer, build_evaluator
         from opensportslib.core.utils.config import select_device, resolve_config_omega, is_local_path
         from opensportslib.core.utils.checkpoint import load_checkpoint, localization_remap
-        from opensportslib.core.utils.load_annotations import check_config, has_localization_events
+        from opensportslib.core.utils.load_annotations import check_config, has_localization_events, whether_infer_split
         from opensportslib.core.utils.wandb import init_wandb
         import time
 
@@ -163,6 +163,7 @@ class LocalizationAPI:
         self.config.MODEL.multi_gpu = False
         self.config = resolve_config_omega(self.config)
         check_config(self.config, split="test")
+        self.config.infer_split = whether_infer_split(self.config.DATA.test)
         init_wandb(self.config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
         logging.info("Configuration:")
         logging.info(self.config)
@@ -179,19 +180,29 @@ class LocalizationAPI:
             logging.info("No predictions provided, running inference.")
             device = select_device(self.config.SYSTEM)
             self.model = build_model(self.config, device=device)
+            inner_model = getattr(self.model, "_model", None)
+            if inner_model is None:
+                inner_model = getattr(self.model, "model", self.model)
             print("Model type:", type(self.model))
-            print("Torch model type:", type(self.model._model))
+            print("Torch model type:", type(inner_model))
             # Load model
             if pretrained:
                 #pretrained = expand(pretrained)
                 if is_local_path(pretrained):
                     self.config.SYSTEM.work_dir = os.path.dirname(os.path.abspath(pretrained))
                 
-                self.model._model, _, _, epoch = load_checkpoint(model=self.model._model,
+                inner_model, _, _, epoch = load_checkpoint(model=inner_model,
                                             path=pretrained,
                                             device=device,
                                             key_remap_fn=localization_remap)
 
+                if hasattr(self.model, "_model"):
+                    self.model._model = inner_model
+                elif hasattr(self.model, "model"):
+                    self.model.model = inner_model
+                else:
+                    self.model = inner_model
+
             # Datasets
             # Test
             data_obj_test = build_dataset(self.config, split="test")
@@ -206,7 +217,7 @@ class LocalizationAPI:
             # # Inference
             inferer = build_inferer(cfg=self.config.MODEL,
                                     model=self.model)
-            json_gz_file = inferer.infer(cfg=self.config, data=dataset_Test)
+            json_gz_file = inferer.infer(cfg=self.config, data=dataset_Test, dataloader=test_loader)
 
         #json_gz_file = self.config.DATA.test.results + ".recall.json.gz"
         json_gz_file = predictions if predictions else json_gz_file
@@ -219,7 +230,7 @@ class LocalizationAPI:
             evaluator = build_evaluator(cfg=self.config)
             metrics = evaluator.evaluate(
                 cfg_testset=self.config.DATA.test,
-                json_gz_file=json_gz_file
+                json_gz_file=self.config.DATA.test.results if isinstance(json_gz_file, dict) else json_gz_file
             )
         else:
             logging.info("No labels found in annotation file → skipping evaluation")

opensportslib-0.0.1.dev17/opensportslib/config/localization-json_netvlad++_resnetpca512.yaml

@@ -0,0 +1,145 @@
+TASK: localization
+
+dali: false
+
+DATA:
+  dataset_name: SoccerNet
+  data_dir: /home/vorajv/opensportslib/SoccerNet/
+  classes:
+    - Penalty
+    - Kick-off
+    - Goal
+    - Substitution
+    - Offside
+    - Shots on target
+    - Shots off target
+    - Clearance
+    - Ball out of play
+    - Throw-in
+    - Foul
+    - Indirect free-kick
+    - Direct free-kick
+    - Corner
+    - Yellow card
+    - Red card
+    - Yellow->red card
+    
+  epoch_num_frames: 500000
+  mixup: true
+  modality: rgb
+  crop_dim: -1
+  dilate_len: 0        # Dilate ground truth labels
+  clip_len: 100
+  input_fps: 25
+  extract_fps: 2
+  imagenet_mean: [0.485, 0.456, 0.406]
+  imagenet_std: [0.229, 0.224, 0.225]
+  target_height: 224
+  target_width: 398
+
+  train:
+    type: FeatureClipsfromJSON
+    classes: ${DATA.classes}
+    output_map: [data, label]
+    video_path: ${DATA.data_dir}
+    path: ${DATA.train.video_path}/annotations-2024-224p-train.json
+    framerate: 2
+    window_size: 20
+    dataloader:
+      batch_size: 256
+      shuffle: true
+      num_workers: 4
+      pin_memory: true
+
+  valid:
+    type: FeatureClipsfromJSON
+    classes: ${DATA.classes}
+    output_map: [data, label]
+    video_path: ${DATA.data_dir}
+    path: ${DATA.valid.video_path}/annotations-2024-224p-valid.json
+    framerate: 2
+    window_size: 20
+    dataloader:
+      batch_size: 256
+      shuffle: true
+      num_workers: 4
+      pin_memory: true
+
+  test:
+    type: FeatureVideosfromJSON
+    classes: ${DATA.classes}
+    output_map: [data, label]
+    video_path: ${DATA.data_dir}
+    path: ${DATA.test.video_path}/annotations-2024-224p-test.json
+    results: results_spotting_test_netvlad++_resnetpca512
+    framerate: 2
+    window_size: 20
+    metric: tight
+    dataloader:
+      batch_size: 1
+      shuffle: false
+      num_workers: 1
+      pin_memory: true
+
+MODEL:
+    type: LearnablePooling
+    runner:
+      type: runner_JSON
+    backbone:
+      type: PreExtactedFeatures
+      encoder: ResNET_TF2_PCA512
+      feature_dim: 512
+      output_dim: 512
+      framerate: 2
+      window_size: 20
+    neck:
+      type: NetVLAD++
+      input_dim: 512
+      output_dim: 32768 # 512 clusters * 64 vocab size
+      vocab_size: 64
+    head:
+      type: LinearLayer
+      input_dim: 32768
+      num_classes: 17
+    post_proc:
+      type: NMS
+      NMS_window: 30
+      NMS_threshold: 0.0
+    load_weights: null
+
+TRAIN:
+  type: trainer_pooling
+  max_epochs: 1000
+  evaluation_frequency: 1000
+  framerate: 2
+  batch_size: 256
+
+  criterion:
+    type: NLLLoss
+
+  optimizer:
+    type: Adam
+    lr: 0.001
+    betas: [0.9, 0.999]
+    eps: 1e-08
+    weight_decay: 0
+    amsgrad: false
+
+  scheduler:
+    type: ReduceLROnPlateau
+    mode: min
+    factor: 1e-03
+    min_lr: 1e-06
+    patience: 10
+    verbose: true
+
+
+SYSTEM:
+  log_dir: ./logs
+  save_dir: ./checkpoints
+  work_dir: ${SYSTEM.save_dir}
+  seed: 42
+  GPU: 4        # number of gpus to use
+  device: cuda   # auto | cuda | cpu
+  gpu_id: 0      # device id for single gpu training
+

opensportslib-0.0.1.dev15/opensportslib/config/sngar_frames.yaml → opensportslib-0.0.1.dev17/opensportslib/config/sngar-frames.yaml

@@ -1,29 +1,36 @@
 TASK: classification
+# this is the config for classification task on sngar-frames dataset.
+# this config is used for the main experiments reported in the paper:
+# "Pixels or Positions? Benchmarking Modalities in Group Activity Recognition"
+# https://arxiv.org/abs/2511.12606
+# videomaev2 - fully finetuned on the sngar-frames dataset.
+# it has all the hyperparameters value used to reproduce the results reported in the paper.
 
 DATA:
   dataset_name: sngar
   data_dir: /home/spark_user1/opensportslib/sngar-frames
   data_modality: frames_npy
-  max_samples: 100
+  # max_samples: 100 # only used for quick testing
   num_frames: 16
   frame_size: [224, 224]
   train:
     path: ${DATA.data_dir}/annotations_train.json
     dataloader:
-      batch_size: 64
+      batch_size: 8 # for frozen backbone, use 64
+      # for unfrozen backbone, use 32-16-8 depending on the memory available
       shuffle: true
       num_workers: 8
       pin_memory: true
   valid:
     path: ${DATA.data_dir}/annotations_valid.json
     dataloader:
-      batch_size: 64
+      batch_size: 8
       num_workers: 8
       shuffle: false
   test:
     path: ${DATA.data_dir}/annotations_test.json
     dataloader:
-      batch_size: 64
+      batch_size: 8
       num_workers: 8
       shuffle: false
   augmentations:
@@ -32,15 +39,18 @@ DATA:
     color_jitter: true
     jitter_prob: 0.5
     jitter_params: [0.2, 0.2, 0.2, 0.1]
+  data_slicing: # only used for data scaling experiments
+    enabled: false
+    training_matches: 45  # default: all 45 training matches
 
 MODEL:
   type: custom
   backbone:
-    type: dinov3                  # dinov3 | clip | videomae | videomae2
-    pretrained_model: facebook/dinov3-vitb16-pretrain-lvd1689m
-    # facebook/dinov3-vitb16-pretrain-lvd1689m | openai/clip-vit-base-patch16 | MCG-NJU/videomae-base | OpenGVLab/VideoMAEv2-Base
+    type: videomae2                  # dinov3 | videomae | videomae2
+    pretrained_model: OpenGVLab/VideoMAEv2-Base
+    # facebook/dinov3-vitb16-pretrain-lvd1689m | MCG-NJU/videomae-base | OpenGVLab/VideoMAEv2-Base
     hidden_dim: 768
-    freeze: true
+    freeze: false # true for frozen backbone, false for unfrozen backbone i.e. full-finetuning
     unfreeze_last_n_layers: 0     # 0 = frozen backbone, >0 = unfreeze last N layers
   neck:
     type: TemporalAggregation
@@ -56,12 +66,12 @@ MODEL:
     dropout: 0.1
 
 TRAIN:
-  monitor: balanced_accuracy
-  mode: max
+  monitor: loss # balanced_accuracy, loss
+  mode: min # max or min
   enabled: true
   use_amp: true
   mixup_alpha: 0.2
-  use_weighted_sampler: false
+  use_weighted_sampler: true
   samples_per_class: 4000
   use_weighted_loss: false
   epochs: 100
@@ -75,7 +85,7 @@ TRAIN:
 
   optimizer:
     type: AdamW
-    lr: 0.0001
+    lr: 0.00005 # tune lr based on the backbone
     betas: [0.9, 0.999]
     eps: 0.0000001
     weight_decay: 0.0001

opensportslib-0.0.1.dev15/opensportslib/config/classification_tracking.yaml → opensportslib-0.0.1.dev17/opensportslib/config/sngar-tracking.yaml

@@ -1,9 +1,15 @@
 TASK: classification
+# this is the config for classification task on sngar-tracking dataset.
+# this config is used for the main experiments reported in the paper:
+# "Pixels or Positions? Benchmarking Modalities in Group Activity Recognition"
+# https://arxiv.org/abs/2511.12606
+# this is used to train our baseline model that is GIN backbone + Maxpool temporal aggregation + positional edges.
+# it has all the hyperparameters value used to reproduce the results reported in the paper.
 
 DATA:
   dataset_name: sngar
   data_modality: tracking_parquet
-  data_dir: /home/karkid/opensportslib/sngar-tracking
+  data_dir: /home/karkid/opensportslib/tracking-dataset
   preload_data: false
   train: 
     type: annotations_train.json
@@ -43,12 +49,15 @@ DATA:
   pitch_half_width: 50.0
   max_displacement: 110.0
   max_ball_height: 30.0
+  data_slicing: # only used for data scaling experiments
+    enabled: false
+    training_matches: 45  # default: all 45 training matches
 
 MODEL:
   type: custom
   backbone:
     type: graph_conv
-    encoder: graphconv
+    encoder: gin
     hidden_dim: 64
     num_layers: 20
     dropout: 0.1
@@ -74,7 +83,7 @@ TRAIN:
   use_weighted_sampler: true
   use_weighted_loss: false
   samples_per_class: 4000
-  epochs: 10
+  epochs: 100
   patience: 10
   save_every: 20
   detailed_results: true

{opensportslib-0.0.1.dev15 → opensportslib-0.0.1.dev17}/opensportslib/core/trainer/classification_trainer.py

@@ -685,7 +685,7 @@ class FramesTrainerClassification(BaseTrainerClassification):
                 self.scaler.step(self.optimizer)
                 self.scaler.update()
 
-        return logits, labels, loss
+        return logits, labels, loss, True
 
 # --------------------------------------------------------------
 # unified trainer dispatcher 

{opensportslib-0.0.1.dev15 → opensportslib-0.0.1.dev17}/opensportslib/core/trainer/localization_trainer.py

@@ -164,11 +164,12 @@ class Trainer_pl(Trainer):
         self.work_dir = work_dir
         call = MyCallback()
         self.trainer = pl.Trainer(
-            max_epochs=cfg.max_epochs,
-            devices=[cfg.GPU],
+            max_epochs=cfg.TRAIN.max_epochs,
+            devices=cfg.SYSTEM.GPU,
             callbacks=[call, CustomProgressBar(refresh_rate=1)],
             num_sanity_val_steps=0,
         )
+        self.best_checkpoint_path = None
 
     def train(self, **kwargs):
         self.trainer.fit(**kwargs)
@@ -177,10 +178,12 @@ class Trainer_pl(Trainer):
 
         logging.info("Done training")
         logging.info("Best epoch: {}".format(best_model.get("epoch")))
-        torch.save(best_model, os.path.join(self.work_dir, "model.pth.tar"))
+        best_path = os.path.join(self.work_dir, "model.pth.tar")
+        self.best_checkpoint_path = best_path
+        torch.save(best_model, best_path)
 
         logging.info("Model saved")
-        logging.info(os.path.join(self.work_dir, "model.pth.tar"))
+        logging.info(best_path)
 
 
 class Trainer_e2e(Trainer):
@@ -496,24 +499,25 @@ class Inferer:
         self.model = model
         self.infer_Spotting=infer_Spotting
 
-    def infer(self, cfg, data):
+    def infer(self, cfg, data, dataloader=None):
         """Infer actions from data.
 
         Args:
             data : The data from which we will infer.
+            dataloader : The dataloader for the test data.
 
         Returns:
             Dict containing predictions
         """
         if self.infer_Spotting=="infer_JSON":
-            return self.infer_JSON(cfg, self.model, data)
+            return self.infer_JSON(cfg, self.model, data, dataloader)
         elif self.infer_Spotting=="infer_SN":    
-            return self.infer_SN(cfg, self.model, data)
+            return self.infer_SN(cfg, self.model, data, dataloader)
         elif self.infer_Spotting=="infer_E2E":
-            return self.infer_E2E(cfg, self.model, data)
+            return self.infer_E2E(cfg, self.model, data, dataloader)
 
 
-    def infer_common(self, cfg, model, data):
+    def infer_common(self, cfg, model, data, dataloader=None):
         """Infer actions from data using a given model.
 
         Args:
@@ -525,10 +529,21 @@ class Inferer:
             Dict containing predictions
         """
         # Run Inference on Dataset
-        pass
+        from opensportslib.core.utils.lightning import CustomProgressBar, MyCallback
+        import pytorch_lightning as pl
+
+        if cfg.SYSTEM.work_dir is not None and dataloader is not None:
+            
+            evaluator = pl.Trainer(
+                callbacks=[CustomProgressBar()],
+                devices=cfg.SYSTEM.GPU,
+                num_sanity_val_steps=0,
+            )
+            evaluator.predict(model, dataloader)
+            return model.json_data
 
 
-    def infer_JSON(self, cfg, model, data):
+    def infer_JSON(self, cfg, model, data, dataloader=None):
         """Infer actions from data using a given model for NetVlad/CALF methods
 
         Args:
@@ -539,10 +554,10 @@ class Inferer:
         Returns:
             Dict containing predictions
         """
-        return self.infer_common(cfg, model, data)
+        return self.infer_common(cfg, model, data, dataloader)
 
 
-    def infer_SN(self, cfg, model, data):
+    def infer_SN(self, cfg, model, data, dataloader=None):
         """Infer actions from data using a given model for the SNV2 data
 
         Args:
@@ -553,10 +568,10 @@ class Inferer:
         Returns:
             Dict containing predictions
         """
-        return self.infer_common(cfg, model, data)
+        return self.infer_common(cfg, model, data, dataloader)
 
 
-    def infer_E2E(self, cfg, model, data):
+    def infer_E2E(self, cfg, model, data, dataloader=None):
         """Infer actions from data using a given model for the e2espot method.
 
         Args:
@@ -735,7 +750,6 @@ class Evaluator:
     
       
     def evaluate_common_JSON(self, cfg, results, metric):
-
         if cfg.path is None:
             return
 
@@ -756,6 +770,7 @@ class Evaluator:
 
         # detect v2 prediction
         pred_is_v2 = isinstance(pred_data, dict) and pred_data is not None and "data" in pred_data
+        print("PRED V2 :", pred_is_v2)
         # --------------------------------------------------
         # CLASSES
         # --------------------------------------------------
@@ -800,10 +815,11 @@ class Evaluator:
 
             # ---------------- GT ----------------
             if gt_is_v2:
+                print("Game: ", game)
                 video_path = game["inputs"][0]["path"]
                 labels = [{"label": e.get("label"),  
                            "gameTime": e.get("gameTime"),
-                           "position": int(e.get("position_ms")),
+                           "position": int(e.get("position_ms", e.get("position"))),
                           } for e in game.get("events", [])]
             else:
                 video_path = game["path"]
@@ -825,7 +841,7 @@ class Evaluator:
                            "label": e.get("label"),  
                            "gameTime": e.get("gameTime"),
                            "confidence": e.get("confidence"),
-                           "position": int(e.get("position_ms")),
+                           "position": int(e.get("position_ms", e.get("position"))),
                            "frame": e.get("frame")
                         }
                         for e in item.get("events", [])
@@ -859,7 +875,7 @@ class Evaluator:
                            "label": e.get("label"),  
                            "gameTime": e.get("gameTime"),
                            "confidence": e.get("confidence"),
-                           "position": int(e.get("position_ms")),
+                           "position": int(e.get("position_ms", e.get("position"))),
                            "frame": e.get("frame")
                         }
                         for e in item.get("events", [])
@@ -997,7 +1013,8 @@ class Evaluator:
         Returns
             The different mAPs computed.
         """
-
+        from SoccerNet.Evaluation.utils import INVERSE_EVENT_DICTIONARY_V2
+        from SoccerNet.Evaluation.ActionSpotting import evaluate
         # challenge sets to be tested on EvalAI
         if "challenge" in cfg.split:
             print("Visit eval.ai to evaluate performances on Challenge set")

{opensportslib-0.0.1.dev15 → opensportslib-0.0.1.dev17}/opensportslib/core/utils/load_annotations.py

@@ -9,11 +9,51 @@ from opensportslib.core.utils.video_processing import get_stride, read_fps, get_
 from opensportslib.core.utils.config import load_json
 from collections import defaultdict
 
-def load_annotations(annotations_path, task_key="action", exclude_labels=[""], multiview=False, input_type="video", allow_missing_labels=False):
+def load_annotations(
+    annotations_path,
+    task_key="action",
+    exclude_labels=None,
+    multiview=False,
+    input_type="video",
+    allow_missing_labels=False,
+    max_games=None
+):
 
     with open(annotations_path, "r") as f:
         data = json.load(f)
 
+    # this is used for data slicing experiments.
+    # and doesn't affect the validation and test sets.
+    # if you haven't added "data_scaling" to the config, this will be ignored.
+    if max_games is not None:
+        all_game_ids = sorted(set(
+            item.get("metadata", {}).get("game_id", "")
+            for item in data["data"]
+        )) 
+
+        # remove empty string if any items lack game_id
+        all_game_ids = [g for g in all_game_ids if g]
+
+        # warn if any items lack game_id
+        items_without_game_id = sum(
+            1 for item in data["data"]
+            if not item.get("metadata", {}).get("game_id", "")
+        )
+        if items_without_game_id > 0:
+            print(f"warning: {items_without_game_id}/{len(data['data'])} items have "
+                  f"no game_id, these will not be affected by data slicing")
+
+        if max_games < len(all_game_ids):
+            keep_ids = set(all_game_ids[:max_games])
+            original_count = len(data["data"])
+            data["data"] = [
+                item for item in data["data"]
+                if item.get("metadata", {}).get("game_id", "") in keep_ids
+            ]
+            print(f"data slicing: {max_games}/{len(all_game_ids)} games, "
+                  f"{len(data['data'])}/{original_count} samples retained")
+    # ----- data slicing ends here -----
+
     exclude_labels = set(exclude_labels or [""])
 
     # Label list for the selected task
@@ -496,4 +536,34 @@ def check_config(cfg, split="train"):
             classes = cfg.DATA.classes
         
         #print(classes)
-        cfg.DATA.classes = load_classes(classes)
+        cfg.DATA.classes = load_classes(classes)
+
+
+def whether_infer_split(cfg):
+    """Given a config dict, check whether we want to infer a split or a single element (can be a game, video or feature file)/
+
+    Args:
+        cfg (dict): Config dict.
+
+    Returns:
+        bool : True if we infer split, false otherwise. Raises an error if the input is not expected.
+    """
+    if cfg.type == "SoccerNetGames" or cfg.type == "SoccerNetClipsTestingCALF":
+        if cfg.split == None:
+            return False
+        else:
+            return True
+    elif (
+        cfg.type == "FeatureVideosfromJSON" or cfg.type == "FeatureVideosChunksfromJson"
+    ):
+        if cfg.path.endswith(".json"):
+            return True
+        else:
+            return False
+    elif cfg.type == "VideoGameWithOpencvVideo" or cfg.type == "VideoGameWithDaliVideo":
+        if cfg.path.endswith(".json"):
+            return True
+        else:
+            return False
+    else:
+        raise ValueError(f"Unknown dataset type {cfg.type}")

{opensportslib-0.0.1.dev15 → opensportslib-0.0.1.dev17}/opensportslib/core/utils/wandb.py

@@ -2,6 +2,7 @@ import wandb
 import matplotlib.pyplot as plt
 import numpy as np
 import logging
+import os
 
 def init_wandb(cfg, run_id, use_wandb=False):
     """
@@ -24,6 +25,15 @@ def init_wandb(cfg, run_id, use_wandb=False):
         logging.warning("wandb not installed. Install with `pip install wandb`.")
         return None
 
+    # Prevent multiple processes from initializing wandb
+    rank = int(os.environ.get("RANK", os.environ.get("LOCAL_RANK", 0)))
+    if rank != 0:
+        return None
+
+    # Prevent re-initialization
+    if wandb.run is not None:
+        return wandb
+
     if getattr(cfg.DATA, "data_modality", None):
         run_name = f"{cfg.MODEL.backbone.type}_{cfg.DATA.data_modality}"
     else: