opensportslib 0.3.1.dev18__tar.gz → 0.3.1.dev20__tar.gz

{opensportslib-0.3.1.dev18/opensportslib.egg-info → opensportslib-0.3.1.dev20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev18
+Version: 0.3.1.dev20
 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
@@ -28,6 +28,7 @@ Requires-Dist: pandas
 Requires-Dist: pyarrow
 Requires-Dist: h5py==3.16.0
 Requires-Dist: huggingface_hub
+Requires-Dist: datasets<6,>=5.0.0
 Requires-Dist: easydict
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
@@ -437,6 +438,44 @@ VQA setup workflow.
 
 OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
 
+For SN-GAR tracking classification, `sngar_tracking_hf.yaml` loads split metadata
+through `datasets` and caches every referenced TAR shard before using each split.
+It preserves the weighted replacement sampler without extracting individual clips. Install
+with `python -m pip install -e .`, authenticate with `hf auth login`,
+and see [SN-GAR-README.md](SN-GAR-README.md) for the training command and cache layout.
+
+For SN-GAR video action spotting, `sngar_spotting_video_hf.yaml` uses
+`DATA.inputs.video.source.format: hf_json` to stage OSL JSON manifests and MP4s
+from the `multimodal` branch of `OpenSportsLab/SNGAR-Action-Spotting`. It reads
+the JSON manifests and downloads only their selected video inputs, leaving the
+tracking Parquet files alone. Run
+`LocalizationModel(config="sngar_spotting_video_hf.yaml").train(use_wandb=False)`
+after `hf auth login` and dataset access approval. The first train/validation
+stage downloads all videos in those splits; subsequent runs reuse the cache.
+If a cached video is missing, staging downloads it again before training starts.
+The example keeps the 300-frame window but uses one clip per step, limited
+DataLoader prefetch, and four gradient accumulation steps to control memory.
+For the OpenCV loader, accumulation combines successive batches, so batch size
+one with four accumulation steps is valid.
+The 29.97-fps videos are sampled every sixth source frame for approximately
+5 fps and a 60-second window. Restart training after a sampling change so
+decoded clips and event labels use the same frame rate.
+
+For tracking action spotting, use
+`LocalizationModel(config="sngar_spotting_tracking_hf.yaml").train(use_wandb=False)`.
+This config selects `tracking_parquet` from the same `multimodal` JSON manifests,
+downloads only the whole-game tracking tables in the requested splits,
+and passes them to the tracking graph dataset. The staged manifest keeps the
+`tracking_parquet` input type. Tracking files are cached under
+`/home/giancos/OSLdata/sngar/hf_json_tracking_cache`; video MP4s are skipped.
+
+To run the five example baselines sequentially with their full epoch settings,
+see [tools/train/weekend_train.sh](tools/train/weekend_train.sh). Run it with
+`bash tools/train/weekend_train.sh` after `hf auth login`. Each algorithm and
+dataset has its own section in the script. Video spotting alone was measured at
+about 10 days for 100 epochs on one user's machine, so the complete sequence
+will extend beyond a weekend on similar hardware.
+
 ### Python API
 
 ```python
@@ -583,6 +622,10 @@ opensportslib setup --vqa_qwen
 
 We welcome contributions to OpenSportsLib.
 
+All PRs must target `dev`. Before a PR can merge, every GitHub-linked commit
+author must accept the [Individual Contributor License Agreement](.github/CLA.md)
+when prompted by the `CLA check`.
+
 Please check:
 
 - [CONTRIBUTING.md](CONTRIBUTING.md)

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/README.md

@@ -399,6 +399,44 @@ VQA setup workflow.
 
 OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
 
+For SN-GAR tracking classification, `sngar_tracking_hf.yaml` loads split metadata
+through `datasets` and caches every referenced TAR shard before using each split.
+It preserves the weighted replacement sampler without extracting individual clips. Install
+with `python -m pip install -e .`, authenticate with `hf auth login`,
+and see [SN-GAR-README.md](SN-GAR-README.md) for the training command and cache layout.
+
+For SN-GAR video action spotting, `sngar_spotting_video_hf.yaml` uses
+`DATA.inputs.video.source.format: hf_json` to stage OSL JSON manifests and MP4s
+from the `multimodal` branch of `OpenSportsLab/SNGAR-Action-Spotting`. It reads
+the JSON manifests and downloads only their selected video inputs, leaving the
+tracking Parquet files alone. Run
+`LocalizationModel(config="sngar_spotting_video_hf.yaml").train(use_wandb=False)`
+after `hf auth login` and dataset access approval. The first train/validation
+stage downloads all videos in those splits; subsequent runs reuse the cache.
+If a cached video is missing, staging downloads it again before training starts.
+The example keeps the 300-frame window but uses one clip per step, limited
+DataLoader prefetch, and four gradient accumulation steps to control memory.
+For the OpenCV loader, accumulation combines successive batches, so batch size
+one with four accumulation steps is valid.
+The 29.97-fps videos are sampled every sixth source frame for approximately
+5 fps and a 60-second window. Restart training after a sampling change so
+decoded clips and event labels use the same frame rate.
+
+For tracking action spotting, use
+`LocalizationModel(config="sngar_spotting_tracking_hf.yaml").train(use_wandb=False)`.
+This config selects `tracking_parquet` from the same `multimodal` JSON manifests,
+downloads only the whole-game tracking tables in the requested splits,
+and passes them to the tracking graph dataset. The staged manifest keeps the
+`tracking_parquet` input type. Tracking files are cached under
+`/home/giancos/OSLdata/sngar/hf_json_tracking_cache`; video MP4s are skipped.
+
+To run the five example baselines sequentially with their full epoch settings,
+see [tools/train/weekend_train.sh](tools/train/weekend_train.sh). Run it with
+`bash tools/train/weekend_train.sh` after `hf auth login`. Each algorithm and
+dataset has its own section in the script. Video spotting alone was measured at
+about 10 days for 100 epochs on one user's machine, so the complete sequence
+will extend beyond a weekend on similar hardware.
+
 ### Python API
 
 ```python
@@ -545,6 +583,10 @@ opensportslib setup --vqa_qwen
 
 We welcome contributions to OpenSportsLib.
 
+All PRs must target `dev`. Before a PR can merge, every GitHub-linked commit
+author must accept the [Individual Contributor License Agreement](.github/CLA.md)
+when prompted by the `CLA check`.
+
 Please check:
 
 - [CONTRIBUTING.md](CONTRIBUTING.md)

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/opensportslib/apis/classification.py

@@ -33,6 +33,19 @@ class ClassificationModel(BaseTaskModel):
     """Top-level task wrapper for classification."""
 
     def _resolve_split_path(self, split: str, override: str | None = None) -> str:
+        if not self.is_remote:
+            from opensportslib.datasets.hf_tracking import (
+                hf_tracking_source,
+                prepare_hf_tracking_split,
+            )
+
+            if hf_tracking_source(self.config):
+                if override is not None:
+                    raise ValueError(
+                        "hf_webdataset uses its configured Hub splits; "
+                        "train_set, valid_set, and test_set overrides are unsupported."
+                    )
+                return str(prepare_hf_tracking_split(self.config, split).annotations_path)
         if override is not None:
             return expand(override)
 

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/opensportslib/apis/localization.py

@@ -16,6 +16,7 @@ from opensportslib.core.config.accessors import (
     get_split_annotation_path,
     get_split_cfg,
     set_split_annotation_path,
+    set_split_source_path,
     set_loader_backend,
     get_model_family,
 )
@@ -49,6 +50,15 @@ class LocalizationModel(BaseTaskModel):
         if override is not None:
             return expand(override)
 
+        from opensportslib.datasets.hf_json import hf_json_source, prepare_hf_json_split
+
+        if hf_json_source(self.config):
+            prepared = prepare_hf_json_split(self.config, split)
+            set_split_source_path(self.config, split, str(prepared.source_path))
+            if split == "valid":
+                set_split_source_path(self.config, "valid_data_frames", str(prepared.source_path))
+            return str(prepared.annotation_path)
+
         path = get_split_annotation_path(self.config, split)
         if path:
             return expand(path)

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/opensportslib/core/config/accessors.py

@@ -182,6 +182,20 @@ def get_split_source_path(cfg: Any, split: str) -> str | None:
     return getattr(split_cfg, "source_path", None)
 
 
+def set_split_source_path(cfg: Any, split: str, path: str) -> None:
+    data = getattr(cfg, "DATA", None)
+    if data is None:
+        data = SimpleNamespace()
+        setattr(cfg, "DATA", data)
+    common = _ensure_child(data, "common")
+    splits = _ensure_child(common, "splits")
+    split_cfg = _ensure_child(splits, split)
+    if isinstance(split_cfg, dict):
+        split_cfg["source_path"] = path
+    else:
+        setattr(split_cfg, "source_path", path)
+
+
 def classes_to_ordered_list(classes: Any) -> list[str]:
     """Normalise a classes spec to a list ordered by class index.
 

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/opensportslib/core/utils/load_annotations.py

@@ -860,9 +860,16 @@ def check_config(cfg, split="train"):
         ]
         head_type = get_component_name_by_kind(cfg, "head")
         assert head_type in ["", "gru", "deeper_gru", "mstcn", "asformer"]
-        # assert cfg.dataset.batch_size % cfg.training.acc_grad_iter == 0
         train_bs = cfg.DATA.common.splits.train.dataloader.batch_size
-        assert train_bs % cfg.TRAIN.execution.acc_grad_iter == 0
+        acc_grad_iter = cfg.TRAIN.execution.acc_grad_iter
+        if acc_grad_iter < 1:
+            raise ValueError("TRAIN.execution.acc_grad_iter must be at least 1")
+        # DALI divides its configured batch into accumulation microbatches.
+        # OpenCV accumulates gradients across independent DataLoader batches.
+        if get_loader_backend(cfg) == "dali" and train_bs % acc_grad_iter != 0:
+            raise ValueError(
+                "DALI train batch_size must be divisible by TRAIN.execution.acc_grad_iter"
+            )
         assert cfg.TRAIN.execution.criterion_valid in ["map", "loss"]
         assert get_train_epochs(cfg) == cfg.TRAIN.scheduler.num_epochs
         assert cfg.TRAIN.execution.acc_grad_iter == cfg.TRAIN.scheduler.acc_grad_iter

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/opensportslib/core/utils/video_processing.py

@@ -99,6 +99,13 @@ def get_stride(src_fps, sample_fps):
     if sample_fps <= 0:
         stride = 1
     else:
+        # MP4s commonly report 30000/1001 rather than the nominal 30 fps.
+        # Truncating 29.97 / 5 gives 5, which samples at almost 6 fps.
+        nominal_fps = round(src_fps)
+        if nominal_fps > 0 and math.isclose(
+            src_fps, nominal_fps, rel_tol=0.0011
+        ):
+            src_fps = nominal_fps
         stride = int(src_fps / sample_fps)
     return stride
 

{opensportslib-0.3.1.dev18 → opensportslib-0.3.1.dev20}/opensportslib/datasets/classification_dataset.py

@@ -65,6 +65,10 @@ def build(config, annotations_path, processor=None, split="train"):
     modality = get_data_modality(config).lower()
 
     if modality in ("tracking", "tracking_parquet"):
+        from opensportslib.datasets.hf_tracking import hf_tracking_source
+
+        if hf_tracking_source(config):
+            return HFTrackingDataset(config, split=split)
         return TrackingDataset(config, annotations_path, split)
     elif modality in H5_TRACKING_MODALITIES:
         return H5TrackingDataset(config, annotations_path, split)
@@ -749,6 +753,22 @@ class TrackingDataset(ClassificationDataset):
         return out
         
 
+class HFTrackingDataset(TrackingDataset):
+    """Tracking graphs backed by indexed Hugging Face WebDataset TAR shards."""
+
+    def __init__(self, config, split="train"):
+        from opensportslib.datasets.hf_tracking import HFTarTrackingReader, prepare_hf_tracking_split
+
+        if get_data_params(config).get("preload_data", False):
+            raise ValueError("hf_webdataset requires DATA.inputs.tracking.params.preload_data=false")
+        prepared = prepare_hf_tracking_split(config, split)
+        self._hf_reader = HFTarTrackingReader(prepared)
+        super().__init__(config, str(prepared.annotations_path), split)
+
+    def _load_tracking_clip(self, path):
+        return self._hf_reader.read_parquet(path)
+
+
 class H5TrackingDataset(ClassificationDataset):
     """Graph-based classification dataset for UTC-indexed player/ball H5 files."""
 

opensportslib-0.3.1.dev20/opensportslib/datasets/hf_json.py

@@ -0,0 +1,169 @@
+"""Stage OSL JSON manifests and their selected media from a Hugging Face dataset."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import re
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from opensportslib.core.config.accessors import get_input_cfg
+
+
+@dataclass(frozen=True)
+class PreparedHFJsonSplit:
+    annotation_path: Path
+    source_path: Path
+    revision: str
+
+
+def hf_json_source(config) -> dict:
+    source = get_input_cfg(config).get("source") or {}
+    return source if str(source.get("format", "")).lower() == "hf_json" else {}
+
+
+def _safe_path(value: str) -> str:
+    path = PurePosixPath(value)
+    if not value or path.is_absolute() or ".." in path.parts or "\\" in value:
+        raise ValueError(f"Unsafe path in Hugging Face JSON manifest: {value!r}")
+    return path.as_posix()
+
+
+def _set_resolved_revision(config, revision: str) -> None:
+    inputs = config.DATA.inputs
+    values = inputs.values() if isinstance(inputs, dict) else vars(inputs).values()
+    for input_cfg in values:
+        source = input_cfg.get("source") if isinstance(input_cfg, dict) else input_cfg.source
+        if str(source.get("format") if isinstance(source, dict) else source.format).lower() == "hf_json":
+            if isinstance(source, dict):
+                source["resolved_revision"] = revision
+            else:
+                source.resolved_revision = revision
+            return
+
+
+def prepare_hf_json_split(config, split: str) -> PreparedHFJsonSplit:
+    """Download one split's selected media, then publish its local manifest.
+
+    The localization video and tracking loaders inspect each file during
+    construction. Stage only the configured input type while keeping its
+    manifest type and other metadata intact. Hub blobs are linked into a
+    small split directory.
+    """
+    source = hf_json_source(config)
+    if not source:
+        raise ValueError("Source format must be 'hf_json'.")
+    if split not in {"train", "valid", "test"}:
+        raise ValueError(f"Unsupported Hugging Face JSON split: {split!r}")
+
+    repo_id = str(source.get("repo_id") or "").strip()
+    branch = str(source.get("revision") or "main").strip()
+    cache_dir = Path(str(source.get("cache_dir") or "~/.cache/opensportslib/hf_json")).expanduser()
+    media_type = str(source.get("input_type") or "video_mp4")
+    if not repo_id or not branch:
+        raise ValueError("hf_json requires source.repo_id and source.revision.")
+
+    try:
+        from huggingface_hub import HfApi, hf_hub_download
+
+        revision = str(source.get("resolved_revision") or "").strip()
+        if not revision:
+            revision = HfApi(token=True).repo_info(
+                repo_id=repo_id, repo_type="dataset", revision=branch
+            ).sha
+        if not revision:
+            raise ValueError("The Hub did not return a commit SHA.")
+    except Exception as exc:
+        raise RuntimeError(
+            f"Cannot access Hugging Face dataset {repo_id!r} at {branch!r}. "
+            "Request access and run `hf auth login`."
+        ) from exc
+
+    _set_resolved_revision(config, revision)
+    safe_repo = re.sub(r"[^A-Za-z0-9_.-]+", "--", repo_id)
+    root = cache_dir / safe_repo / revision
+    root.mkdir(parents=True, exist_ok=True)
+    manifest_name = _safe_path(str(source.get("annotation_pattern") or "annotations_{split}.json").format(split=split))
+    annotation_path = root / f"selected_{media_type}_{split}.json"
+    prepared = PreparedHFJsonSplit(annotation_path, root, revision)
+    hub_cache = cache_dir / "hub"
+
+    with (root / f".{split}.lock").open("w") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        try:
+            cached_manifest = annotation_path.is_file()
+            if cached_manifest:
+                payload = json.loads(annotation_path.read_text(encoding="utf-8"))
+                # Older caches could contain an input relabeled to ``video``.
+                # Refresh those manifests so the selected source type is kept.
+                valid_cache = isinstance(payload, dict) and isinstance(payload.get("data"), list)
+                if valid_cache:
+                    valid_cache = all(
+                        isinstance(sample, dict)
+                        and len([
+                            item for item in sample.get("inputs", [])
+                            if isinstance(item, dict) and item.get("type") == media_type
+                        ]) == 1
+                        for sample in payload["data"]
+                    )
+                if not valid_cache:
+                    cached_manifest = False
+            if not cached_manifest:
+                remote_manifest = hf_hub_download(
+                    repo_id=repo_id, filename=manifest_name, repo_type="dataset",
+                    revision=revision, token=True, cache_dir=str(hub_cache),
+                )
+                payload = json.loads(Path(remote_manifest).read_text(encoding="utf-8"))
+            if not isinstance(payload, dict) or not isinstance(payload.get("data"), list):
+                raise ValueError(f"{manifest_name} is not an OSL JSON manifest")
+            if not payload["data"]:
+                raise ValueError(f"{manifest_name} contains no samples")
+
+            filenames = set()
+            for sample in payload["data"]:
+                selected = [item for item in sample.get("inputs", []) if item.get("type") == media_type]
+                if len(selected) != 1:
+                    raise ValueError(
+                        f"Expected one {media_type!r} input for sample {sample.get('game_id', sample.get('id'))!r}"
+                    )
+                item = dict(selected[0])
+                filename = _safe_path(str(item.get("path") or ""))
+                if not filename.startswith(f"{split}/"):
+                    raise ValueError(f"Media path {filename!r} is outside split {split!r}")
+                filenames.add(filename)
+                sample["inputs"] = [item]
+
+            def stage_media(filename: str) -> None:
+                destination = root / filename
+                if destination.is_file():
+                    return
+                downloaded = Path(hf_hub_download(
+                    repo_id=repo_id, filename=filename, repo_type="dataset",
+                    revision=revision, token=True, cache_dir=str(hub_cache),
+                ))
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                temporary = destination.with_name(f".{destination.name}.{os.getpid()}.tmp")
+                try:
+                    temporary.symlink_to(downloaded)
+                    os.replace(temporary, destination)
+                finally:
+                    temporary.unlink(missing_ok=True)
+
+            with ThreadPoolExecutor(max_workers=min(4, len(filenames))) as executor:
+                list(executor.map(stage_media, sorted(filenames)))
+
+            if not cached_manifest:
+                temporary = annotation_path.with_name(f".{annotation_path.name}.{os.getpid()}.tmp")
+                try:
+                    temporary.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+                    os.replace(temporary, annotation_path)
+                finally:
+                    temporary.unlink(missing_ok=True)
+        except Exception as exc:
+            raise RuntimeError(
+                f"Failed to stage {split!r} from {repo_id}@{revision}: {exc}"
+            ) from exc
+    return prepared