opensportslib 0.0.1.dev2__py3-none-any.whl

opensportslib/__init__.py

@@ -0,0 +1,18 @@
+import importlib
+# from . import apis as model
+# from . import metrics
+# from . import datasets
+# from . import core
+
+def __getattr__(name):
+    if name == "model":
+        return importlib.import_module("opensportslib.apis")
+    if name == "metrics":
+        return importlib.import_module("opensportslib.metrics")
+    if name == "datasets":
+        return importlib.import_module("opensportslib.datasets")
+    if name == "core":
+        return importlib.import_module("opensportslib.core")
+    raise AttributeError(f"module 'opensportslib' has no attribute '{name}'")
+
+__all__ = ["model", "metrics", "datasets", "core"]

opensportslib/apis/__init__.py

@@ -0,0 +1,21 @@
+# opensportslib/apis/__init__.py
+
+# Import task APIs
+from opensportslib.apis.classification import ClassificationAPI
+from opensportslib.apis.localization import LocalizationAPI
+import warnings
+warnings.filterwarnings("ignore")
+
+# Factory functions for user-facing calls
+def classification(config=None, data_dir=None, save_dir=None):#, pretrained_model=None):
+    return ClassificationAPI(config=config, data_dir=data_dir, save_dir=save_dir)#,pretrained_model=pretrained_model)
+
+def localization(config=None, data_dir=None, save_dir=None):#, pretrained_model=None):
+    return LocalizationAPI(config=config, data_dir=data_dir, save_dir=save_dir)#,pretrained_model=pretrained_model)
+
+
+# Expose only these
+__all__ = [
+    "classification",
+    "localization",
+]

opensportslib/apis/classification.py

@@ -0,0 +1,361 @@
+# opensportslib/apis/classification.py
+
+"""public API for classification tasks.
+
+supports three dataset/task combinations:
+    - MVFoul (video-based foul classification)
+    - SN-GAR with video modality
+    - SN-GAR with tracking modality
+
+handles single-GPU and multi-GPU (DDP) training and inference,
+delegating heavy lifting to Trainer_Classification.
+"""
+
+import os
+import logging
+from opensportslib.core.utils.config import expand 
+
+
+class ClassificationAPI:
+    """top-level entry point for classification training and inference.
+
+    loads a YAML config, resolves paths, and exposes train() / 
+    infer() methods that transparently handle single-GPU and
+    DDP execution.
+
+    Args:
+        config: path to the YAML configuration file.
+        data_dir: override for DATA.data_dir in the config.
+            if None, the value from the config is used.
+        save_dir: override for the checkpoint output directory.
+            falls back to SYSTEM.save_dir, then "./checkpoints".
+    """
+
+    def __init__(self, config=None, data_dir=None, save_dir=None):
+        from opensportslib.core.utils.config import (
+            load_config_omega
+        )
+        import uuid
+
+        if config is None:
+            raise ValueError("config path is required")
+
+        config_path = expand(config)
+        self.config = load_config_omega(config_path)
+
+        # let the caller override the dataset root directory.
+        self.config.DATA.data_dir = expand(
+            data_dir or self.config.DATA.data_dir
+        )
+
+        # checkpoint output directory; never derived from BASE_DIR so the
+        # user always has explicit control over where weights are written.
+        self.run_id = os.environ.get("RUN_ID") or str(uuid.uuid4())[:8]
+        os.environ["RUN_ID"] = self.run_id
+
+        self.save_dir = expand(
+            save_dir or self.config.SYSTEM.save_dir or "./checkpoints"
+        )
+        save_filename = os.path.join(self.config.MODEL.backbone.type, self.run_id)
+        self.config.SYSTEM.save_dir = os.path.join(self.save_dir, save_filename)
+        os.makedirs(self.config.SYSTEM.save_dir, exist_ok=True)
+
+        # DDP rank; used for logging and checkpointing.
+        rank = int(os.environ.get("RANK", 0))
+        self.trainer=None
+        self.best_checkpoint=None
+
+        log_dir = expand(self.config.SYSTEM.log_dir or "./log_dir")
+        os.makedirs(os.path.join(self.config.SYSTEM.save_dir, log_dir), exist_ok=True)
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s | %(levelname)s | %(message)s",
+            handlers=[
+                logging.FileHandler(os.path.join(log_dir, "train.log")),
+                logging.StreamHandler(),
+            ],
+            force=True,
+        )
+        if rank == 0:
+            logging.info(f"DATA DIR     : {self.config.DATA.data_dir}")
+            logging.info(f"MODEL SAVEDIR: {self.config.SYSTEM.save_dir}")
+
+    # -----------------------------------------------------------------
+    # internal DDP worker
+    # -----------------------------------------------------------------
+    @staticmethod
+    def _worker_ddp(
+        rank, 
+        world_size, 
+        mode, 
+        config,
+        return_queue=None, 
+        train_set=None, 
+        valid_set=None, 
+        test_set=None, 
+        pretrained=None,
+        use_wandb=False
+    ):
+        """execute a single training or inference job on one GPU.
+
+        spawned once per GPU by train() / infer(). Each process gets 
+        its own Trainer_Classification instance so that no mutable
+        state is shared across ranks.
+
+        Args:
+            rank: GPU rank (0-indexed).
+            world_size: total number of participating GPUs.
+            mode: "train" or "infer".
+            return_queue: multiprocessing.Queue used by rank-0 to
+                return metrics to the calling process (inference only).
+            train_set: path to the training set annotations file.
+            valid_set: path to the validation set annotations file.
+            test_set: path to the test set annotations file.
+            pretrained: path to a saved checkpoint for warm-starting
+                or inference.
+        """
+        import torch
+        from opensportslib.core.trainer.classification_trainer import Trainer_Classification
+        from opensportslib.core.utils.ddp import ddp_setup, ddp_cleanup
+        from opensportslib.core.utils.wandb import init_wandb
+        from opensportslib.core.utils.seed import set_reproducibility
+        from opensportslib.datasets.builder import build_dataset
+        from opensportslib.models.builder import build_model
+        import logging
+
+        # configure logging for each spawned process
+        logging.basicConfig(
+            level=logging.INFO,
+            format=f"[RANK {rank}] %(asctime)s | %(levelname)s | %(message)s",
+            force=True,
+        )
+        # silence non-rank0 processes
+        if rank != 0:
+            logging.getLogger().setLevel(logging.ERROR)
+
+        if rank == 0:
+            init_wandb(config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
+
+        # reproducibility: 
+        # we default to reproducible training, but allow the user to
+        # disable this via SYSTEM.use_seed=False in the config.
+        if getattr(config.SYSTEM, "use_seed", False):
+            set_reproducibility(config.SYSTEM.seed)
+
+        is_ddp = world_size > 1
+        if is_ddp:
+            torch.cuda.set_device(rank)
+            ddp_setup(rank, world_size)
+            device = torch.device(f"cuda:{rank}")
+        else:
+            from opensportslib.core.utils.config import select_device
+            device = select_device(config.SYSTEM)
+        
+        # each process creates a fresh trainer to avoid shared mutable state.
+        trainer = Trainer_Classification(config)
+        trainer.device = device
+
+        # build or restore the model.
+        if pretrained:
+            model, processor, scheduler, epoch = trainer.load(pretrained)
+        else:
+            model, processor = build_model(config, device)
+
+        trainer.model = model
+
+        if mode == "train":
+            train_data = build_dataset(
+                config, train_set, processor, split="train"
+            )
+            valid_data = build_dataset(
+                config, valid_set, processor, split="valid"
+            )
+            best_ckpt = trainer.train(
+                model, train_data, valid_data, 
+                rank=rank, world_size=world_size
+            )
+            # SEND BACK CHECKPOINT FROM RANK 0
+            if rank == 0 and return_queue is not None:
+                best_ckpt = getattr(trainer.trainer, "best_checkpoint_path", None)
+                return_queue.put(best_ckpt)
+
+        elif mode == "infer":
+            test_data = build_dataset(
+                config, test_set, processor, split="test"
+            )
+
+            metrics = trainer.infer(
+                test_data, rank=rank, world_size=world_size
+            )
+
+            if rank == 0 and return_queue is not None:
+                return_queue.put(metrics)
+
+        if is_ddp:
+            ddp_cleanup()
+
+    # -----------------------------------------------------------------
+    # public training interface
+    # -----------------------------------------------------------------
+
+    def train(
+        self, 
+        train_set=None, 
+        valid_set=None, 
+        test_set=None, 
+        pretrained=None, 
+        use_ddp=False,
+        use_wandb=True
+    ):
+        """run a full training loop.
+
+        Args:
+            train_set: path to training annotationns. defaults to the
+                value in the loaded config.
+            valid_set: path to validation annotations.
+            test_set: currently unused.
+            pretrained: optional checkpoint path for warm-starting.
+            use_ddp: if True and more than one GPU is visible,
+                spawn one process per GPU via torch.multiprocessing.spawn.
+        """
+        import torch
+        import torch.multiprocessing as mp
+        from opensportslib.core.utils.config import (
+            resolve_config_omega
+        )
+
+        train_set = expand(train_set or self.config.DATA.annotations.train)
+        valid_set = expand(valid_set or self.config.DATA.annotations.valid)
+
+        self.config = resolve_config_omega(self.config)
+        logging.info("Configuration:")
+        logging.info(self.config)
+
+        world_size = torch.cuda.device_count() or self.config.SYSTEM.GPU
+        use_ddp = use_ddp and world_size > 1
+
+        ctx = mp.get_context("spawn")
+        queue = ctx.Queue()
+
+        if use_ddp:
+            logging.info(f"Launching DDP on {world_size} GPUs")
+            mp.spawn(
+                ClassificationAPI._worker_ddp,
+                args=(
+                    world_size, "train", self.config, queue, 
+                    train_set, valid_set, None, pretrained, use_wandb
+                ),
+                nprocs=world_size,
+            )
+        else:
+            logging.info("Single GPU training")
+            ClassificationAPI._worker_ddp(
+                rank=0,
+                world_size=1,
+                mode="train",
+                config=self.config,
+                return_queue=queue,
+                train_set=train_set,
+                valid_set=valid_set,
+                pretrained=pretrained,
+                use_wandb=use_wandb
+            )
+        
+        self.best_checkpoint = queue.get()
+        return self.best_checkpoint
+
+
+    def infer(
+        self, 
+        test_set=None, 
+        pretrained=None, 
+        predictions=None, 
+        use_ddp=False, 
+        use_wandb=True
+    ):
+        """run inference or evaluate saved predictions.
+        
+        when "predictions" is None, the model runs a forward pass
+        over the test set and returns live metrics. when "predictions"
+        points to a saved prediction file, only the evaluation step runs
+        (no GPU needed).
+
+        Args:
+            test_set: path to test annotations.
+            pretrained: checkpoint path (required when running live inference).
+            predictions: path to a previously saved prediction file.
+                if provided, evaluation is run offline without a model.
+            use_ddp: if True, distribute inference across all visible GPUs.
+
+        Returns:
+            a metrics dictionary produced by the trainer.
+        """
+        import torch
+        import torch.multiprocessing as mp
+        from opensportslib.core.utils.config import (
+            resolve_config_omega
+        )
+
+        test_set = expand(test_set or self.config.DATA.annotations.test)
+
+        self.config = resolve_config_omega(self.config)
+        logging.info("Configuration:")
+        logging.info(self.config)
+
+        if pretrained is None and predictions is None:
+            if hasattr(self, "best_checkpoint"):
+                pretrained = self.best_checkpoint
+                logging.info(f"Using last trained checkpoint: {pretrained}")
+            else:
+                raise ValueError("No pretrained checkpoint provided and no training run found.")
+
+        if not predictions:
+            # live inference: run the model on test data.
+            world_size = torch.cuda.device_count()
+            use_ddp = use_ddp and world_size > 1
+
+            ctx = mp.get_context("spawn")
+            queue = ctx.Queue()
+            
+            if use_ddp:
+                mp.spawn(
+                    ClassificationAPI._worker_ddp,
+                    args=(
+                        world_size, "infer", self.config, queue, 
+                        None, None, test_set, pretrained, use_wandb
+                    ),
+                    nprocs=world_size,
+                )
+            else:
+                ClassificationAPI._worker_ddp(
+                    rank=0,
+                    world_size=1,
+                    mode="infer",
+                    config=self.config,
+                    return_queue=queue,
+                    test_set=test_set,
+                    pretrained=pretrained,
+                    use_wandb=use_wandb
+                )
+            
+            # rank-0 pushes metrics into the queue; retrieve them here.
+            metrics = queue.get()
+        else:
+            # offline evaluation from a saved prediction file.
+            from opensportslib.datasets.builder import build_dataset
+            from opensportslib.core.trainer.classification_trainer import Trainer_Classification
+
+            self.trainer = Trainer_Classification(self.config)
+            test_data = build_dataset(
+                self.config, test_set, None, split="test"
+            )
+            metrics = self.trainer.evaluate(
+                pred_path=predictions, 
+                gt_path=test_set, 
+                class_names=test_data.label_map, 
+                exclude_labels=test_data.exclude_labels
+            )
+
+        logging.info(f"TEST METRICS : {metrics}")
+            
+        return metrics

opensportslib/apis/localization.py

@@ -0,0 +1,228 @@
+from opensportslib.core.utils.config import expand 
+import os
+import logging
+import time
+ 
+class LocalizationAPI:
+    def __init__(self, config=None, data_dir=None, save_dir=None):
+        from opensportslib.core.utils.config import load_config_omega
+        #from ..core.trainer import Trainer
+        import uuid
+
+        if config is None:
+            raise ValueError("config path is required")
+
+        # 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)
+        # User must control dataset folder
+        self.config.DATA.data_dir = expand(data_dir or self.config.DATA.data_dir)
+        print(self.config.DATA.classes)
+        # User controls model saving location (never use BASE_DIR)
+
+        self.run_id = os.environ.get("RUN_ID") or str(uuid.uuid4())[:8]
+        os.environ["RUN_ID"] = self.run_id
+
+        self.save_dir = expand(
+            save_dir or self.config.SYSTEM.save_dir or "./checkpoints"
+        )
+        save_filename = os.path.join(self.config.MODEL.backbone.type, self.run_id)
+        self.config.SYSTEM.save_dir = os.path.join(self.save_dir, save_filename)
+        os.makedirs(self.config.SYSTEM.save_dir, exist_ok=True)
+
+        log_dir = expand(self.config.SYSTEM.log_dir or "./log_dir")
+        os.makedirs(os.path.join(self.config.SYSTEM.save_dir, log_dir), exist_ok=True)
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s | %(levelname)s | %(message)s",
+            handlers=[
+                logging.FileHandler(os.path.join(log_dir, "train.log")),
+                logging.StreamHandler(),  # still prints to console
+            ],
+        )
+
+        self.best_checkpoint=None
+
+        logger = logging.getLogger(__name__)
+
+        print("CONFIG PATH  :", config_path)
+        print("DATA DIR     :", self.config.DATA.data_dir)
+        print("SAVEDIR:", self.config.SYSTEM.save_dir)
+        print("Classes :", self.config.DATA.classes)
+
+        #self.trainer = Trainer(self.config)
+
+
+    def train(self, train_set=None, valid_set=None, pretrained=None, use_ddp=False, use_wandb=True):
+        from opensportslib.datasets.builder import build_dataset
+        from opensportslib.models.builder import build_model
+        from opensportslib.core.trainer.localization_trainer import build_trainer
+        from opensportslib.core.utils.default_args import get_default_args_trainer, get_default_args_train
+        from opensportslib.core.utils.config import select_device, resolve_config_omega
+        from opensportslib.core.utils.load_annotations import check_config
+        from opensportslib.core.utils.wandb import init_wandb
+        import random
+        import numpy as np
+        import torch
+        # # Load model
+        # if pretrained:
+        #     self.model, self.processor, _ = self.trainer.load(expand(pretrained))
+        # else:
+        #     self.model, self.processor = build_model(self.config, self.trainer.device)
+        # Expand annotation paths (user or config)
+        self.config.DATA.train.path = expand(train_set or self.config.DATA.train.path)
+        self.config.DATA.valid.path = expand(valid_set or self.config.DATA.valid.path)
+
+        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)
+        logging.info("Configuration:")
+        logging.info(self.config)
+        #print(self.config)
+
+        def set_seed(seed):
+            random.seed(seed)  # Python random module
+            np.random.seed(seed)  # NumPy
+            torch.manual_seed(seed)  # PyTorch
+            torch.cuda.manual_seed(seed)  # PyTorch CUDA
+            torch.cuda.manual_seed_all(seed)  # Multi-GPU training
+
+            # Ensures deterministic behavior
+            torch.backends.cudnn.deterministic = True  
+            torch.backends.cudnn.benchmark = False  
+
+            # Ensures deterministic behavior for CUDA operations
+            torch.use_deterministic_algorithms(True, warn_only=True)
+
+        set_seed(self.config.SYSTEM.seed)
+        # Start Timing
+        start = time.time()
+
+        device = select_device(self.config.SYSTEM)
+        self.model = build_model(self.config, device=device)
+        print(self.model)
+
+
+        # Datasets
+        # Train
+        data_obj_train = build_dataset(self.config, split="train")
+        dataset_Train = data_obj_train.building_dataset(
+            cfg=data_obj_train.cfg,
+            gpu=self.config.SYSTEM.GPU,
+            default_args=data_obj_train.default_args,
+        )
+        train_loader = data_obj_train.building_dataloader(dataset_Train, cfg=data_obj_train.cfg.dataloader, gpu=self.config.SYSTEM.GPU, dali=True)
+        print(len(train_loader))
+        # Valid
+        data_obj_valid = build_dataset(self.config,split="valid")
+        dataset_Valid = data_obj_valid.building_dataset(
+            cfg=data_obj_valid.cfg,
+            gpu= self.config.SYSTEM.GPU,
+            default_args=data_obj_valid.default_args,
+        )
+        valid_loader = data_obj_valid.building_dataloader(dataset_Valid, cfg=data_obj_valid.cfg.dataloader, gpu=self.config.SYSTEM.GPU, dali=True)
+        print(len(valid_loader))
+
+        # Trainer
+        trainer = build_trainer(
+            cfg=self.config,
+            model=self.model,
+            default_args=get_default_args_trainer(self.config, len(train_loader)),
+            resume_from = pretrained
+        )
+        # Start training`
+        logging.info("Start training")
+
+        trainer.train(
+            **get_default_args_train(
+                self.model,
+                train_loader,
+                valid_loader,
+                self.config.DATA.classes,
+                self.config.TRAIN.type,
+            )
+        )
+        self.best_checkpoint = trainer.best_checkpoint_path
+
+        logging.info(f"Total Execution Time is {time.time()-start} seconds")
+        return self.best_checkpoint
+  
+
+    def infer(self, test_set=None, pretrained=None, predictions=None, use_ddp=False, use_wandb=True):
+        from opensportslib.datasets.builder import build_dataset
+        from opensportslib.models.builder import build_model
+        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.wandb import init_wandb
+        import time
+
+        self.config.DATA.test.path = expand(test_set or self.config.DATA.test.path)
+        self.config.MODEL.multi_gpu = False
+        self.config = resolve_config_omega(self.config)
+        check_config(self.config, split="test")
+        init_wandb(self.config, run_id=os.environ["RUN_ID"], use_wandb=use_wandb)
+        logging.info("Configuration:")
+        logging.info(self.config)
+        # Start Timing
+        start = time.time()
+        if pretrained is None and predictions is None:
+            if hasattr(self, "best_checkpoint"):
+                pretrained = self.best_checkpoint
+                print(f"Using last trained checkpoint: {pretrained}")
+            else:
+                raise ValueError("No pretrained checkpoint provided and no training run found.")
+            
+        if not predictions:
+            logging.info("No predictions provided, running inference.")
+            device = select_device(self.config.SYSTEM)
+            self.model = build_model(self.config, device=device)
+            print("Model type:", type(self.model))
+            print("Torch model type:", type(self.model._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,
+                                            path=pretrained,
+                                            device=device,
+                                            key_remap_fn=localization_remap)
+
+            # Datasets
+            # Test
+            data_obj_test = build_dataset(self.config, split="test")
+            dataset_Test = data_obj_test.building_dataset(
+                cfg=data_obj_test.cfg,
+                gpu=self.config.SYSTEM.GPU,
+                default_args=data_obj_test.default_args,
+            )
+            test_loader = data_obj_test.building_dataloader(dataset_Test, cfg=data_obj_test.cfg.dataloader, gpu=self.config.SYSTEM.GPU, dali=True)
+            print(len(test_loader))
+
+            # # Inference
+            inferer = build_inferer(cfg=self.config.MODEL,
+                                    model=self.model)
+            json_gz_file = inferer.infer(cfg=self.config, data=test_loader)
+
+        #json_gz_file = self.config.DATA.test.results + ".recall.json.gz"
+        json_gz_file = predictions if predictions else json_gz_file
+
+        metrics = None
+
+        if has_localization_events(self.config.DATA.test.path):
+            logging.info("Ground truth labels detected → running evaluation")
+
+            evaluator = build_evaluator(cfg=self.config)
+            metrics = evaluator.evaluate(
+                cfg_testset=self.config.DATA.test,
+                json_gz_file=json_gz_file
+            )
+        else:
+            logging.info("No labels found in annotation file → skipping evaluation")
+
+        logging.info(f"Total Execution Time is {time.time()-start} seconds")
+        return metrics