opensportslib 0.2.0.dev4__tar.gz → 0.2.0.dev5__tar.gz

{opensportslib-0.2.0.dev4/opensportslib.egg-info → opensportslib-0.2.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.2.0.dev4
+Version: 0.2.0.dev5
 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
@@ -26,6 +26,7 @@ Requires-Dist: tabulate
 Requires-Dist: pytorch-lightning
 Requires-Dist: pandas
 Requires-Dist: pyarrow
+Requires-Dist: h5py
 Requires-Dist: huggingface_hub
 Requires-Dist: easydict
 Provides-Extra: test

{opensportslib-0.2.0.dev4 → opensportslib-0.2.0.dev5}/opensportslib/apis/classification.py

@@ -17,6 +17,17 @@ from opensportslib.core.config.accessors import (
 )
 from opensportslib.core.utils.config import expand
 
+
+def _is_tracking_graph_modality(modality):
+    return str(modality).lower() in {
+        "tracking",
+        "tracking_parquet",
+        "tracking_h5",
+        "player_centroids_h5",
+        "player_joints_h5",
+    }
+
+
 class ClassificationModel(BaseTaskModel):
     """Top-level task wrapper for classification."""
 
@@ -100,7 +111,7 @@ class ClassificationModel(BaseTaskModel):
         trainer.model = model
 
         modality = get_data_modality(config)
-        use_tracking_collate = modality in {"tracking", "tracking_parquet"}
+        use_tracking_collate = _is_tracking_graph_modality(modality)
         logging.info(
             "Worker setup | mode=%s | modality=%s | tracking_collate=%s",
             mode,

{opensportslib-0.2.0.dev4 → opensportslib-0.2.0.dev5}/opensportslib/apis/localization.py

@@ -14,6 +14,7 @@ from opensportslib.core.config.accessors import (
     get_split_annotation_path,
     get_split_cfg,
     set_split_annotation_path,
+    get_model_family,
 )
 from opensportslib.core.utils.config import expand
 
@@ -170,6 +171,11 @@ class LocalizationModel(BaseTaskModel):
 
         del kwargs
 
+        if str(get_model_family(self.config)).lower() == "rulebased":
+            raise NotImplementedError(
+                "RuleBased localization models are inference-only; call infer() instead of train()."
+            )
+
         train_set = self._resolve_split_path("train", train_set)
         valid_set = self._resolve_split_path("valid", valid_set)
         self._set_split_path("train", train_set)

opensportslib-0.2.0.dev5/opensportslib/configs/localization/h5_header_distance.yaml

@@ -0,0 +1,93 @@
+TASK: localization
+VERSION: 2
+
+SYSTEM:
+  paths:
+    work_dir: ./outputs/header_spotting_distance
+  device: cpu
+  gpu:
+    count: 0
+
+DATA:
+  common:
+    dataset_name: h5_headers
+    data_root: ./data
+    classes:
+      - header
+    splits:
+      test:
+        type: H5OSLJsonSpotting
+        annotation_path: ./data/h5.json
+        source_path: ./data
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+  inputs:
+    tracking:
+      modality: player_joints_h5
+      representation: raw
+      source:
+        format: h5
+      sampling: {}
+      transform: {}
+      augmentations: {}
+      params: {}
+
+MODEL:
+  metadata:
+    family: RuleBased
+    runner:
+      type: runner_h5_header_rule
+  components:
+    rule:
+      kind: algorithm
+      source:
+        provider: opensportslib
+        registry: rule_based
+        name: h5_header_distance
+      params:
+        label: header
+        head_name: action
+        distance_threshold_m: 0.5
+        min_confidence: 0.5
+        confidence_mode: linear_inverse_distance
+        confidence_power: 1.0
+        nms_window_ms: 1000
+        nms_scope: sample
+        ball_tolerance_ms: 60
+        chunk_size: 100000
+        head_joints: [nose, neck, l_eye, r_eye, l_ear, r_ear]
+        required_input_type: player_joints_h5
+        ball_path_field: ball_path
+        timestamp_field: timestamp_utc
+        output_task: action_spotting
+        include_diagnostics: true
+        position_ms_origin: joint_h5_start
+        metadata_start_field: start_utc
+        metadata_end_field: end_utc
+        ball_coordinate_fields: [x, y, z]
+        joint_coordinate_suffixes: [x, y, z]
+        identity_fields: [player_id, jersey_number, team_id, is_home]
+        invalid_coordinate_values: [-200.0]
+        sideline_filter_enabled: true
+        pitch_half_width_m: 50.0
+        sideline_exclusion_m: 1.0
+        sideline_reference: ball_y
+        trajectory_filter_enabled: false
+        trajectory_change_mode: either_angle_or_speed
+        trajectory_pre_window_ms: 200
+        trajectory_post_window_ms: 200
+        trajectory_min_angle_deg: 25.0
+        trajectory_min_speed_delta_ratio: 0.25
+        trajectory_min_vector_norm_m: 0.05
+        trajectory_use_xy_only: false
+        confidence_output_key: confidence_score
+  topology: []
+
+TRAIN:
+  trainer:
+    type: trainer_rule_based
+  execution:
+    enabled: false

opensportslib-0.2.0.dev5/opensportslib/configs/localization/h5_header_distance_angle.yaml

@@ -0,0 +1,93 @@
+TASK: localization
+VERSION: 2
+
+SYSTEM:
+  paths:
+    work_dir: ./outputs/header_spotting_distance_angle
+  device: cpu
+  gpu:
+    count: 0
+
+DATA:
+  common:
+    dataset_name: h5_headers
+    data_root: ./data
+    classes:
+      - header
+    splits:
+      test:
+        type: H5OSLJsonSpotting
+        annotation_path: ./data/h5.json
+        source_path: ./data
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+  inputs:
+    tracking:
+      modality: player_joints_h5
+      representation: raw
+      source:
+        format: h5
+      sampling: {}
+      transform: {}
+      augmentations: {}
+      params: {}
+
+MODEL:
+  metadata:
+    family: RuleBased
+    runner:
+      type: runner_h5_header_rule
+  components:
+    rule:
+      kind: algorithm
+      source:
+        provider: opensportslib
+        registry: rule_based
+        name: h5_header_distance_angle
+      params:
+        label: header
+        head_name: action
+        distance_threshold_m: 0.5
+        min_confidence: 0.5
+        confidence_mode: linear_inverse_distance
+        confidence_power: 1.0
+        nms_window_ms: 1000
+        nms_scope: sample
+        ball_tolerance_ms: 60
+        chunk_size: 100000
+        head_joints: [nose, neck, l_eye, r_eye, l_ear, r_ear]
+        required_input_type: player_joints_h5
+        ball_path_field: ball_path
+        timestamp_field: timestamp_utc
+        output_task: action_spotting
+        include_diagnostics: true
+        position_ms_origin: joint_h5_start
+        metadata_start_field: start_utc
+        metadata_end_field: end_utc
+        ball_coordinate_fields: [x, y, z]
+        joint_coordinate_suffixes: [x, y, z]
+        identity_fields: [player_id, jersey_number, team_id, is_home]
+        invalid_coordinate_values: [-200.0]
+        sideline_filter_enabled: true
+        pitch_half_width_m: 50.0
+        sideline_exclusion_m: 1.0
+        sideline_reference: ball_y
+        trajectory_filter_enabled: true
+        trajectory_change_mode: angle
+        trajectory_pre_window_ms: 200
+        trajectory_post_window_ms: 200
+        trajectory_min_angle_deg: 25.0
+        trajectory_min_speed_delta_ratio: 0.25
+        trajectory_min_vector_norm_m: 0.05
+        trajectory_use_xy_only: false
+        confidence_output_key: confidence_score
+  topology: []
+
+TRAIN:
+  trainer:
+    type: trainer_rule_based
+  execution:
+    enabled: false

opensportslib-0.2.0.dev5/opensportslib/configs/localization/h5_header_distance_speed.yaml

@@ -0,0 +1,93 @@
+TASK: localization
+VERSION: 2
+
+SYSTEM:
+  paths:
+    work_dir: ./outputs/header_spotting_distance_speed
+  device: cpu
+  gpu:
+    count: 0
+
+DATA:
+  common:
+    dataset_name: h5_headers
+    data_root: ./data
+    classes:
+      - header
+    splits:
+      test:
+        type: H5OSLJsonSpotting
+        annotation_path: ./data/h5.json
+        source_path: ./data
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+  inputs:
+    tracking:
+      modality: player_joints_h5
+      representation: raw
+      source:
+        format: h5
+      sampling: {}
+      transform: {}
+      augmentations: {}
+      params: {}
+
+MODEL:
+  metadata:
+    family: RuleBased
+    runner:
+      type: runner_h5_header_rule
+  components:
+    rule:
+      kind: algorithm
+      source:
+        provider: opensportslib
+        registry: rule_based
+        name: h5_header_distance_speed
+      params:
+        label: header
+        head_name: action
+        distance_threshold_m: 0.5
+        min_confidence: 0.5
+        confidence_mode: linear_inverse_distance
+        confidence_power: 1.0
+        nms_window_ms: 1000
+        nms_scope: sample
+        ball_tolerance_ms: 60
+        chunk_size: 100000
+        head_joints: [nose, neck, l_eye, r_eye, l_ear, r_ear]
+        required_input_type: player_joints_h5
+        ball_path_field: ball_path
+        timestamp_field: timestamp_utc
+        output_task: action_spotting
+        include_diagnostics: true
+        position_ms_origin: joint_h5_start
+        metadata_start_field: start_utc
+        metadata_end_field: end_utc
+        ball_coordinate_fields: [x, y, z]
+        joint_coordinate_suffixes: [x, y, z]
+        identity_fields: [player_id, jersey_number, team_id, is_home]
+        invalid_coordinate_values: [-200.0]
+        sideline_filter_enabled: true
+        pitch_half_width_m: 50.0
+        sideline_exclusion_m: 1.0
+        sideline_reference: ball_y
+        trajectory_filter_enabled: true
+        trajectory_change_mode: speed
+        trajectory_pre_window_ms: 200
+        trajectory_post_window_ms: 200
+        trajectory_min_angle_deg: 25.0
+        trajectory_min_speed_delta_ratio: 0.25
+        trajectory_min_vector_norm_m: 0.05
+        trajectory_use_xy_only: false
+        confidence_output_key: confidence_score
+  topology: []
+
+TRAIN:
+  trainer:
+    type: trainer_rule_based
+  execution:
+    enabled: false

opensportslib-0.2.0.dev5/opensportslib/configs/localization/h5_header_distance_speed_angle.yaml

@@ -0,0 +1,93 @@
+TASK: localization
+VERSION: 2
+
+SYSTEM:
+  paths:
+    work_dir: ./outputs/header_spotting_distance_speed_angle
+  device: cpu
+  gpu:
+    count: 0
+
+DATA:
+  common:
+    dataset_name: h5_headers
+    data_root: ./data
+    classes:
+      - header
+    splits:
+      test:
+        type: H5OSLJsonSpotting
+        annotation_path: ./data/h5.json
+        source_path: ./data
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+  inputs:
+    tracking:
+      modality: player_joints_h5
+      representation: raw
+      source:
+        format: h5
+      sampling: {}
+      transform: {}
+      augmentations: {}
+      params: {}
+
+MODEL:
+  metadata:
+    family: RuleBased
+    runner:
+      type: runner_h5_header_rule
+  components:
+    rule:
+      kind: algorithm
+      source:
+        provider: opensportslib
+        registry: rule_based
+        name: h5_header_distance_speed_angle
+      params:
+        label: header
+        head_name: action
+        distance_threshold_m: 0.5
+        min_confidence: 0.5
+        confidence_mode: linear_inverse_distance
+        confidence_power: 1.0
+        nms_window_ms: 1000
+        nms_scope: sample
+        ball_tolerance_ms: 60
+        chunk_size: 100000
+        head_joints: [nose, neck, l_eye, r_eye, l_ear, r_ear]
+        required_input_type: player_joints_h5
+        ball_path_field: ball_path
+        timestamp_field: timestamp_utc
+        output_task: action_spotting
+        include_diagnostics: true
+        position_ms_origin: joint_h5_start
+        metadata_start_field: start_utc
+        metadata_end_field: end_utc
+        ball_coordinate_fields: [x, y, z]
+        joint_coordinate_suffixes: [x, y, z]
+        identity_fields: [player_id, jersey_number, team_id, is_home]
+        invalid_coordinate_values: [-200.0]
+        sideline_filter_enabled: true
+        pitch_half_width_m: 50.0
+        sideline_exclusion_m: 1.0
+        sideline_reference: ball_y
+        trajectory_filter_enabled: true
+        trajectory_change_mode: both_angle_and_speed
+        trajectory_pre_window_ms: 200
+        trajectory_post_window_ms: 200
+        trajectory_min_angle_deg: 25.0
+        trajectory_min_speed_delta_ratio: 0.25
+        trajectory_min_vector_norm_m: 0.05
+        trajectory_use_xy_only: false
+        confidence_output_key: confidence_score
+  topology: []
+
+TRAIN:
+  trainer:
+    type: trainer_rule_based
+  execution:
+    enabled: false

opensportslib-0.2.0.dev5/opensportslib/configs/localization/h5_header_rule.yaml

@@ -0,0 +1,99 @@
+TASK: localization
+VERSION: 2
+
+SYSTEM:
+  paths:
+    work_dir: ./outputs/header_spotting
+  device: cpu
+  gpu:
+    count: 0
+
+DATA:
+  common:
+    dataset_name: h5_headers
+    data_root: ./data
+    classes:
+      - header
+    splits:
+      test:
+        type: H5OSLJsonSpotting
+        annotation_path: ./data/h5.json
+        source_path: ./data
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+  inputs:
+    tracking:
+      modality: player_joints_h5
+      representation: raw
+      source:
+        format: h5
+      sampling: {}
+      transform: {}
+      augmentations: {}
+      params: {}
+
+MODEL:
+  metadata:
+    family: RuleBased
+    runner:
+      type: runner_h5_header_rule
+  components:
+    rule:
+      kind: algorithm
+      source:
+        provider: opensportslib
+        registry: rule_based
+        # Available models:
+        # - h5_header_distance
+        # - h5_header_distance_speed
+        # - h5_header_distance_angle
+        # - h5_header_distance_speed_angle
+        name: h5_header_distance_speed_angle
+      params:
+        label: header
+        head_name: action
+        distance_threshold_m: 0.20
+        min_confidence: 0.5
+        confidence_mode: linear_inverse_distance
+        confidence_power: 1.0
+        nms_window_ms: 1000
+        nms_scope: sample
+        ball_tolerance_ms: 60
+        chunk_size: 100000
+        head_joints: [nose, neck, l_eye, r_eye, l_ear, r_ear]
+        required_input_type: player_joints_h5
+        ball_path_field: ball_path
+        timestamp_field: timestamp_utc
+        output_task: action_spotting
+        include_diagnostics: true
+        created_by: h5_header_distance_speed_angle_rule
+        position_ms_origin: joint_h5_start
+        metadata_start_field: start_utc
+        metadata_end_field: end_utc
+        ball_coordinate_fields: [x, y, z]
+        joint_coordinate_suffixes: [x, y, z]
+        identity_fields: [player_id, jersey_number, team_id, is_home]
+        invalid_coordinate_values: [-200.0]
+        sideline_filter_enabled: true
+        pitch_half_width_m: 50.0
+        sideline_exclusion_m: 1.0
+        sideline_reference: ball_y
+        trajectory_filter_enabled: true
+        trajectory_change_mode: both_angle_and_speed
+        trajectory_pre_window_ms: 200
+        trajectory_post_window_ms: 200
+        trajectory_min_angle_deg: 25.0
+        trajectory_min_speed_delta_ratio: 0.25
+        trajectory_min_vector_norm_m: 0.05
+        trajectory_use_xy_only: false
+        confidence_output_key: confidence_score
+  topology: []
+
+TRAIN:
+  trainer:
+    type: trainer_rule_based
+  execution:
+    enabled: false

{opensportslib-0.2.0.dev4 → opensportslib-0.2.0.dev5}/opensportslib/core/config/accessors.py

@@ -6,10 +6,17 @@ import os
 from types import SimpleNamespace
 from typing import Any
 
+try:
+    from omegaconf import OmegaConf
+except Exception:  # pragma: no cover - omegaconf is a runtime dependency
+    OmegaConf = None
+
 
 def _to_plain(obj: Any) -> Any:
     if obj is None:
         return None
+    if OmegaConf is not None and OmegaConf.is_config(obj):
+        return OmegaConf.to_container(obj, resolve=True)
     if isinstance(obj, dict):
         return {k: _to_plain(v) for k, v in obj.items()}
     if isinstance(obj, list):
@@ -24,6 +31,9 @@ def _to_plain(obj: Any) -> Any:
 def _as_dict(obj: Any) -> dict[str, Any]:
     if obj is None:
         return {}
+    if OmegaConf is not None and OmegaConf.is_config(obj):
+        plain = OmegaConf.to_container(obj, resolve=True)
+        return plain if isinstance(plain, dict) else {}
     if isinstance(obj, dict):
         return {k: _to_plain(v) for k, v in obj.items()}
     if hasattr(obj, "__dict__"):

{opensportslib-0.2.0.dev4 → opensportslib-0.2.0.dev5}/opensportslib/core/trainer/classification_trainer.py

@@ -69,6 +69,16 @@ def _is_frames_npy_modality(config, modality=None):
     representation = str(input_cfg.get("representation", "")).lower()
     return source_format == "npy" or representation == "frames"
 
+
+def _is_tracking_graph_modality(modality):
+    return str(modality).lower() in {
+        "tracking",
+        "tracking_parquet",
+        "tracking_h5",
+        "player_centroids_h5",
+        "player_joints_h5",
+    }
+
 # -------------------------------------------------------------------
 # base classification trainer
 # -------------------------------------------------------------------
@@ -815,7 +825,7 @@ class Trainer_Classification:
 
         is_ddp = world_size > 1
         modality = get_data_modality(self.config)
-        is_tracking_modality = modality in {"tracking", "tracking_parquet"}
+        is_tracking_modality = _is_tracking_graph_modality(modality)
         is_frames_modality = _is_frames_npy_modality(self.config, modality)
         seed = get_system_seed(self.config)
 
@@ -1128,7 +1138,7 @@ class Trainer_Classification:
                 test_sampler = None
 
             modality = get_data_modality(self.config)
-            is_tracking_modality = modality in {"tracking", "tracking_parquet"}
+            is_tracking_modality = _is_tracking_graph_modality(modality)
             is_frames_modality = _is_frames_npy_modality(self.config, modality)
             collate_fn = tracking_collate_fn if is_tracking_modality else None
             test_dataloader_cfg = get_split_dataloader_cfg(self.config, "test")

{opensportslib-0.2.0.dev4 → opensportslib-0.2.0.dev5}/opensportslib/core/trainer/localization_trainer.py

@@ -510,6 +510,8 @@ def build_inferer(cfg, model, default_args=None):
         return Inferer(cfg=cfg, model=model, infer_Spotting="infer_SN")
     if runner_type == "runner_e2e":
         return Inferer(cfg=cfg, model=model, infer_Spotting="infer_E2E")
+    if runner_type == "runner_h5_header_rule":
+        return Inferer(cfg=cfg, model=model, infer_Spotting="infer_H5HeaderRule")
     raise ValueError(f"Unsupported localization runner type: {runner_type}")
 
 class Inferer:
@@ -542,7 +544,9 @@ class Inferer:
             return self.infer_SN(cfg, self.model, data, dataloader)
         elif self.infer_Spotting=="infer_E2E":
             return self.infer_E2E(cfg, self.model, data, dataloader)
-
+        elif self.infer_Spotting=="infer_H5HeaderRule":
+            return self.infer_H5HeaderRule(cfg, self.model, data, dataloader)
+        raise ValueError(f"Unsupported infer_Spotting method: {self.infer_Spotting}")
 
     def infer_common(self, cfg, model, data, dataloader=None):
         """Infer actions from data using a given model.
@@ -644,6 +648,11 @@ class Inferer:
 
         return predictions
 
+    def infer_H5HeaderRule(self, cfg, model, data, dataloader=None):
+        """Run rule-based H5 header spotting without Lightning or weights."""
+        del cfg, dataloader
+        return model.predict(data)
+
 
 def build_evaluator(cfg, default_args=None):
     """Build a evaluator from config dict.

{opensportslib-0.2.0.dev4 → opensportslib-0.2.0.dev5}/opensportslib/core/utils/load_annotations.py

@@ -66,7 +66,8 @@ def load_annotations(
     # Group by action id (without view suffix)
     grouped = defaultdict(lambda: {
         "video_paths": [],
-        "label": None
+        "label": None,
+        "inputs": [],
     })
 
     for item in data["data"]:
@@ -101,9 +102,14 @@ def load_annotations(
             continue
 
         grouped[group_id]["video_paths"].extend(clips)
+        grouped[group_id]["inputs"].extend(
+            dict(inp) for inp in item.get("inputs", [])
+            if inp.get("type") == input_type and "path" in inp
+        )
         if label_idx is not None:
             grouped[group_id]["label"] = label_idx
         grouped[group_id]["id"] = group_id
+        grouped[group_id].setdefault("metadata", dict(item.get("metadata", {}) or {}))
 
     return list(grouped.values()), label_map
 
@@ -587,5 +593,7 @@ def whether_infer_split(cfg):
             return True
         else:
             return False
+    elif split_type == "H5OSLJsonSpotting":
+        return bool(annotation_path and annotation_path.endswith(".json"))
     else:
         raise ValueError(f"Unknown dataset type {split_type}")