opensportslib 0.1.1__tar.gz → 0.1.1.dev2__tar.gz

{opensportslib-0.1.1/opensportslib.egg-info → opensportslib-0.1.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.1
+Version: 0.1.1.dev2
 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
@@ -33,6 +33,9 @@ Requires-Dist: torch-scatter; extra == "py-geometric"
 Requires-Dist: torch-sparse; extra == "py-geometric"
 Requires-Dist: torch-cluster; extra == "py-geometric"
 Requires-Dist: torch-spline-conv; extra == "py-geometric"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
 Dynamic: license-file
 
 # OpenSportsLib
@@ -192,6 +195,7 @@ Generate text descriptions for sports events and temporal segments.
 Use the README for the fast start, then go deeper through:
 
 - Full documentation: https://opensportslab.github.io/opensportslib/
+- Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
 - Example configs: [examples/configs/](examples/configs/)
 - Quickstart scripts: [examples/quickstart/](examples/quickstart/)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/README.md

@@ -155,6 +155,7 @@ Generate text descriptions for sports events and temporal segments.
 Use the README for the fast start, then go deeper through:
 
 - Full documentation: https://opensportslab.github.io/opensportslib/
+- Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
 - Example configs: [examples/configs/](examples/configs/)
 - Quickstart scripts: [examples/quickstart/](examples/quickstart/)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/apis/classification.py

@@ -40,8 +40,8 @@ class ClassificationAPI:
         if config is None:
             raise ValueError("config path is required")
 
-        config_path = expand(config)
-        self.config = load_config_omega(config_path)
+        self.config_path = expand(config)
+        self.config = load_config_omega(self.config_path)
 
         # let the caller override the dataset root directory.
         self.config.DATA.data_dir = expand(
@@ -88,6 +88,7 @@ class ClassificationAPI:
         rank, 
         world_size, 
         mode, 
+        config_path,
         config,
         return_queue=None, 
         train_set=None, 
@@ -134,7 +135,7 @@ class ClassificationAPI:
             logging.getLogger().setLevel(logging.ERROR)
 
         if rank == 0:
-            init_wandb(config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
+            init_wandb(config_path, config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
 
         # reproducibility: 
         # we default to reproducible training, but allow the user to
@@ -242,7 +243,7 @@ class ClassificationAPI:
             mp.spawn(
                 ClassificationAPI._worker_ddp,
                 args=(
-                    world_size, "train", self.config, queue, 
+                    world_size, "train", self.config_path, self.config, queue, 
                     train_set, valid_set, None, pretrained, use_wandb
                 ),
                 nprocs=world_size,
@@ -253,6 +254,7 @@ class ClassificationAPI:
                 rank=0,
                 world_size=1,
                 mode="train",
+                config_path=self.config_path,
                 config=self.config,
                 return_queue=queue,
                 train_set=train_set,
@@ -321,7 +323,7 @@ class ClassificationAPI:
                 mp.spawn(
                     ClassificationAPI._worker_ddp,
                     args=(
-                        world_size, "infer", self.config, queue, 
+                        world_size, "infer",self.config_path, self.config, queue, 
                         None, None, test_set, pretrained, use_wandb
                     ),
                     nprocs=world_size,
@@ -331,6 +333,7 @@ class ClassificationAPI:
                     rank=0,
                     world_size=1,
                     mode="infer",
+                    config_path=self.config_path,
                     config=self.config,
                     return_queue=queue,
                     test_set=test_set,

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/apis/localization.py

@@ -14,8 +14,8 @@ class LocalizationAPI:
 
         # Load config
         ### load data_dor first then do load config with omega to resolve $paths
-        config_path = expand(config)
-        self.config = load_config_omega(config_path)
+        self.config_path = expand(config)
+        self.config = load_config_omega(self.config_path)
         # User must control dataset folder
         self.config.DATA.data_dir = expand(data_dir or self.config.DATA.data_dir)
         print(self.config.DATA.classes)
@@ -46,7 +46,7 @@ class LocalizationAPI:
 
         logger = logging.getLogger(__name__)
 
-        print("CONFIG PATH  :", config_path)
+        print("CONFIG PATH  :", self.config_path)
         print("DATA DIR     :", self.config.DATA.data_dir)
         print("SAVEDIR:", self.config.SYSTEM.save_dir)
         print("Classes :", self.config.DATA.classes)
@@ -76,7 +76,7 @@ class LocalizationAPI:
 
         self.config = resolve_config_omega(self.config)
         check_config(self.config, split="train")
-        init_wandb(self.config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
+        init_wandb(self.config_path, self.config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
         logging.info("Configuration:")
         logging.info(self.config)
         #print(self.config)
@@ -164,7 +164,7 @@ class LocalizationAPI:
         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)
+        init_wandb(self.config_path, self.config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
         logging.info("Configuration:")
         logging.info(self.config)
         # Start Timing

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/core/trainer/classification_trainer.py

@@ -286,14 +286,15 @@ class BaseTrainerClassification:
 
             if self.rank == 0:
                 # ---------------- W&B LOG ----------------
-                wandb.log({
-                    "epoch": epoch + 1,
-                    "lr": current_lr,
-                    "train/loss": train_loss,
-                    "valid/loss": val_loss,
-                    **{f"train/{k}": v for k, v in train_metrics.items()},
-                    **{f"valid/{k}": v for k, v in val_metrics.items()},
-                })
+                if wandb.run is not None:
+                    wandb.log({
+                        "epoch": epoch + 1,
+                        "lr": current_lr,
+                        "train/loss": train_loss,
+                        "valid/loss": val_loss,
+                        **{f"train/{k}": v for k, v in train_metrics.items()},
+                        **{f"valid/{k}": v for k, v in val_metrics.items()},
+                    })
 
                 logging.info(f"Train Loss: {train_loss:.4f} | Train Bal Acc: {train_metric:.4f}")
                 logging.info(f"Val Loss: {val_loss:.4f} | Val Bal Acc: {val_metric:.4f}")
@@ -316,9 +317,10 @@ class BaseTrainerClassification:
                 best_path = self._save_checkpoint("best", epoch + 1, tag="best")
                 self.best_checkpoint_path = best_path
 
-                artifact = wandb.Artifact("model-checkpoint", type="model")
-                artifact.add_file(best_path)
-                wandb.log_artifact(artifact)
+                if wandb.run is not None:
+                    artifact = wandb.Artifact("model-checkpoint", type="model")
+                    artifact.add_file(best_path)
+                    wandb.log_artifact(artifact)
             
         if self.rank == 0:
             logging.info(f"Best checkpoint : {self.best_checkpoint_path}")
@@ -350,10 +352,11 @@ class BaseTrainerClassification:
         pbar.close()
 
         if self.rank==0:
-            wandb.log({
-                "test/loss": test_loss,
-                **{f"test/{k}": v for k, v in test_metrics.items()},
-            })
+            if wandb.run is not None:
+                wandb.log({
+                    "test/loss": test_loss,
+                    **{f"test/{k}": v for k, v in test_metrics.items()},
+                })
 
             if detailed_results:
                 from opensportslib.metrics.classification_metric import (
@@ -1128,4 +1131,4 @@ class Trainer_Classification:
             self.scheduler = scheduler
             self.epoch = epoch
             logging.info(f"Model loaded from {path}, epoch: {epoch}")
-            return self.model, self.optimizer, self.scheduler, self.epoch
+            return self.model, self.optimizer, self.scheduler, self.epoch

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/core/trainer/localization_trainer.py

@@ -403,15 +403,16 @@ class Trainer_e2e(Trainer):
             )
 
             # ---------------- W&B LOG ----------------
-            wandb.log({
-                "epoch": epoch + 1,
-                "train/loss": train_loss,
-                "valid/loss": valid_loss,
-                "valid/mAP": valid_mAP,
-                "lr": self.optimizer.param_groups[0]["lr"],
-                "best/mAP": self.best_criterion_valid if self.criterion_valid == "map" else None,
-                "best/loss": self.best_criterion_valid if self.criterion_valid == "loss" else None,
-            })
+            if wandb.run is not None:
+                wandb.log({
+                    "epoch": epoch + 1,
+                    "train/loss": train_loss,
+                    "valid/loss": valid_loss,
+                    "valid/mAP": valid_mAP,
+                    "lr": self.optimizer.param_groups[0]["lr"],
+                    "best/mAP": self.best_criterion_valid if self.criterion_valid == "map" else None,
+                    "best/loss": self.best_criterion_valid if self.criterion_valid == "loss" else None,
+                })
 
             if self.save_dir is not None:
                 os.makedirs(self.save_dir, exist_ok=True)
@@ -630,9 +631,10 @@ class Inferer:
                 cfg.DATA.test.dataloader,
                 return_pred=False,
             )
-            wandb.log({
-                "test/Avg_mAP": mAP,
-            })
+            if wandb.run is not None:
+                wandb.log({
+                    "test/Avg_mAP": mAP,
+                })
             pred_json_file = os.path.join(pred_file + ".json")
             pred_recall_file = os.path.join(pred_file + ".recall.json.gz")
             logging.info("Predictions saved")
@@ -1092,4 +1094,3 @@ class Evaluator:
 
         return results
 
-

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/core/utils/config.py

@@ -26,7 +26,22 @@ def dict_to_namespace(d, skip_keys=("classes",)):
         return d
 
 def namespace_to_dict(ns):
-    return {k: vars(v) if hasattr(v, "__dict__") else v for k, v in vars(ns).items()}
+    """
+    Recursively convert namespace/dict/list containers into plain Python types.
+    """
+    if ns is None or isinstance(ns, (str, int, float, bool)):
+        return ns
+
+    if isinstance(ns, dict):
+        return {str(k): namespace_to_dict(v) for k, v in ns.items()}
+
+    if isinstance(ns, (list, tuple, set)):
+        return [namespace_to_dict(v) for v in ns]
+
+    if hasattr(ns, "__dict__"):
+        return {str(k): namespace_to_dict(v) for k, v in vars(ns).items()}
+
+    return ns
 
 def namespace_to_omegaconf(ns):
     """
@@ -196,4 +211,4 @@ def is_local_path(p):
     return p and (
         os.path.exists(p) or
         p.endswith((".pt", ".pth", ".tar"))
-    )
+    )

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/core/utils/data.py

@@ -52,7 +52,16 @@ def tracking_collate_fn(batch):
     Custom collate function for tracking data.
     Uses PyG Batch.from_data_list for efficient C++ batching.
     """
-    from torch_geometric.data import Batch
+    try:
+        from torch_geometric.data import Batch
+    except ImportError as exc:
+        raise ImportError(
+            "torch-geometric is required for tracking_collate_fn. "
+            "Install with: pip install \"opensportslib[py-geometric]\" "
+            "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
+            "or (editable): pip install -e \".[py-geometric]\" "
+            "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+        ) from exc
     
     batch_size = len(batch)
     seq_len = batch[0]['seq_len']
@@ -82,4 +91,4 @@ def mixup_data(x, y, alpha=0.2):
     index = torch.randperm(x.size(0)).to(x.device)
     mixed_x = lam * x + (1 - lam) * x[index]
     return mixed_x, y, y[index], lam
-    
+    

opensportslib-0.1.1.dev2/opensportslib/core/utils/wandb.py

@@ -0,0 +1,280 @@
+import wandb
+import matplotlib.pyplot as plt
+import numpy as np
+import logging
+import os
+from opensportslib.core.utils.config import namespace_to_dict
+
+def build_wandb_config(cfg):
+    """
+    Extract minimal + useful config for W&B dashboard.
+    Returns a FLAT dict (ready for wandb.init(config=...))
+    """
+
+    from opensportslib.core.utils.config import namespace_to_dict
+
+    cfg_dict = namespace_to_dict(cfg)
+
+    def get(d, path, default=None):
+        """Safe nested get using dot notation"""
+        keys = path.split(".")
+        for k in keys:
+            if not isinstance(d, dict) or k not in d:
+                return default
+            d = d[k]
+        return d
+
+    def pick(paths):
+        """Pick only selected keys"""
+        out = {}
+        for p in paths:
+            v = get(cfg_dict, p)
+            if v is not None:
+                out[p] = v
+        return out
+
+    # -------------------------
+    # REQUIRED (core columns)
+    # -------------------------
+    REQUIRED_KEYS = [
+        "TASK",
+
+        "DATA.dataset_name",
+        "DATA.data_modality",
+
+        "MODEL.type",
+        "MODEL.backbone.type",
+        "MODEL.neck.type",
+        "MODEL.head.type",
+
+        "TRAIN.optimizer.type",
+        "TRAIN.optimizer.lr",
+        "TRAIN.scheduler.type",
+
+        "TRAIN.monitor",
+        "TRAIN.mode",
+
+        "SYSTEM.device",
+    ]
+
+    # -------------------------
+    # OPTIONAL (useful knobs)
+    # -------------------------
+    OPTIONAL_KEYS = [
+        # DATA
+        "DATA.num_frames",
+        "DATA.clip_len",
+        "DATA.input_fps",
+        "DATA.extract_fps",
+        "DATA.frame_size",
+        "DATA.view_type",
+        "DATA.num_classes",
+
+        # MODEL
+        "MODEL.backbone.encoder",
+        "MODEL.backbone.hidden_dim",
+        "MODEL.backbone.freeze",
+        "MODEL.unfreeze_last_n_layers",
+        "MODEL.neck.agr_type",
+        "MODEL.edge",
+
+        # TRAIN
+        "TRAIN.epochs",
+        "TRAIN.num_epochs",
+        "TRAIN.max_epochs",
+        "TRAIN.use_amp",
+        "TRAIN.use_weighted_loss",
+        "TRAIN.use_weighted_sampler",
+        "TRAIN.mixup",
+        "TRAIN.mixup_alpha",
+
+        # SYSTEM
+        "SYSTEM.GPU",
+        "SYSTEM.seed",
+    ]
+
+    config = {}
+
+    # pick required
+    config.update(pick(REQUIRED_KEYS))
+
+    # pick optional
+    config.update(pick(OPTIONAL_KEYS))
+
+    # -------------------------
+    # SPECIAL HANDLING
+    # -------------------------
+
+    # Normalize batch_size (from nested dataloader)
+    batch_size = get(cfg_dict, "DATA.train.dataloader.batch_size")
+    if batch_size is not None:
+        config["TRAIN.batch_size"] = batch_size
+
+    # Normalize epochs (different configs use different names)
+    epochs = (
+        get(cfg_dict, "TRAIN.epochs")
+        or get(cfg_dict, "TRAIN.num_epochs")
+        or get(cfg_dict, "TRAIN.max_epochs")
+    )
+    if epochs is not None:
+        config["TRAIN.total_epochs"] = epochs
+
+    return config
+
+def _flatten_config(data, parent_key="", sep="."):
+    """Flatten nested dict/list config for W&B table-friendly columns."""
+    items = {}
+
+    if isinstance(data, dict):
+        for k, v in data.items():
+            key = f"{parent_key}{sep}{k}" if parent_key else str(k)
+            items.update(_flatten_config(v, key, sep=sep))
+        return items
+
+    if isinstance(data, list):
+        for i, v in enumerate(data):
+            key = f"{parent_key}{sep}{i}" if parent_key else str(i)
+            items.update(_flatten_config(v, key, sep=sep))
+        return items
+
+    if parent_key:
+        items[parent_key] = data
+
+    return items
+
+
+def _wandb_ready():
+    return getattr(wandb, "run", None) is not None
+
+def init_wandb(cfg_path, cfg, run_id, use_wandb=False):
+    """
+    Initialize Weights & Biases if enabled.
+    
+    Args:
+        cfg_path: Path to the configuration file.
+        cfg: config object with attributes:
+             - use_wandb (bool)
+             - project_name (str)
+             - run_name (str)
+    """
+
+    if not use_wandb:
+        logging.info("W&B disabled.")
+        return None
+
+    try:
+        import wandb
+    except ImportError:
+        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:
+        run_name = f"{cfg.MODEL.backbone.type}"
+
+    config_flat = build_wandb_config(cfg)
+
+    wandb.init(
+        project=cfg.TASK,
+        name=run_name,
+        id=run_id,
+        resume="allow",
+        config=config_flat,
+    )
+
+    artifact = wandb.Artifact(
+        name=f"{cfg.TASK}-config",
+        type="config",
+        description="configuration (YAML)"
+    )
+
+    artifact.add_file(cfg_path)
+    wandb.log_artifact(artifact)
+
+    logging.info(f"Wandb initialised")
+    return wandb
+
+def log_table_wandb(name, rows, headers):
+    """
+    Log a table to Weights & Biases.
+
+    Args:
+        name (str): Name of the table in wandb.
+        rows (list[list]): Table rows.
+        headers (list[str]): Column headers.
+    """
+    if not _wandb_ready():
+        return
+
+    table = wandb.Table(columns=headers)
+
+    for row in rows:
+        table.add_data(*row)
+
+    wandb.log({name: table})
+
+def log_attention_wandb(attention, split_name):
+    if not _wandb_ready():
+        return
+
+    attn = attention.detach().cpu().numpy()
+
+    fig, ax = plt.subplots(figsize=(6, 3))
+    ax.imshow(attn, aspect="auto", cmap="viridis")
+    ax.set_title(f"{split_name} Attention Map")
+    ax.set_xlabel("Views / Time")
+    ax.set_ylabel("Batch")
+
+    wandb.log({
+        f"{split_name}/attention_map": wandb.Image(fig)
+    })
+
+    plt.close(fig)
+
+
+def log_sample_videos_wandb(mvclips, preds, labels, split_name, max_samples=2, fps=5):
+    if not _wandb_ready():
+        return
+
+
+    # mvclips: (B, V, C, T, H, W)
+    mvclips = mvclips.detach().cpu().numpy()
+
+    for i in range(min(len(mvclips), max_samples)):
+        views = mvclips[i]  # (V, C, T, H, W)
+
+        # Log each view separately
+        for v in range(views.shape[0]):
+            video = views[v].transpose(1, 2, 3, 0)  # (T, H, W, C)
+            video = (video * 255).astype(np.uint8) if video.max() <= 1.0 else video
+
+            wandb.log({
+                f"{split_name}/sample_{i}_view_{v}": wandb.Video(
+                    video,
+                    fps=fps,
+                    caption=f"Pred: {preds[i]}, GT: {labels[i]}"
+                )
+            })
+
+
+def log_confusion_matrix_wandb(y_true, y_pred, class_names, split_name):
+    if not _wandb_ready():
+        return
+    wandb.log({
+        f"{split_name}/confusion_matrix": wandb.plot.confusion_matrix(
+            probs=None,
+            y_true=y_true,
+            preds=y_pred,
+            class_names=class_names
+        )
+    })

{opensportslib-0.1.1 → opensportslib-0.1.1.dev2}/opensportslib/datasets/classification_dataset.py

@@ -496,7 +496,16 @@ class TrackingDataset(ClassificationDataset):
         a copy of the feature array is made before augmentation and 
         normalization so the cached data is never mutated.
         """
-        from torch_geometric.data import Data
+        try:
+            from torch_geometric.data import Data
+        except ImportError as exc:
+            raise ImportError(
+                "torch-geometric is required for tracking_parquet datasets. "
+                "Install with: pip install \"opensportslib[py-geometric]\" "
+                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
+                "or (editable): pip install -e \".[py-geometric]\" "
+                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+            ) from exc
 
         from opensportslib.datasets.utils.tracking import normalize_features
         
@@ -533,7 +542,16 @@ class TrackingDataset(ClassificationDataset):
 
     def _getitem_on_the_fly(self, idx):
         """load, parse, and process a single sample from disk."""
-        from torch_geometric.data import Data
+        try:
+            from torch_geometric.data import Data
+        except ImportError as exc:
+            raise ImportError(
+                "torch-geometric is required for tracking_parquet datasets. "
+                "Install with: pip install \"opensportslib[py-geometric]\" "
+                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html "
+                "or (editable): pip install -e \".[py-geometric]\" "
+                "-f https://pytorch-geometric.com/whl/torch-2.10.0+cu128.html"
+            ) from exc
         
         from opensportslib.datasets.utils.tracking import (
             compute_deltas,
@@ -600,4 +618,4 @@ class TrackingDataset(ClassificationDataset):
         if label is not None:
             out["label"] = label
         return out
-        
+