opensportslib 0.2.0.dev3__tar.gz → 0.2.0.dev5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.2.0.dev3
+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
@@ -324,8 +325,8 @@ backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
 For X-VARS, `feature_source: indexed_or_raw_clip` prefers indexed CLIP features
 when available and falls back to extracting CLIP features from raw video during
 `infer()`. Pre-extracted features remain the preferred path for parity, speed,
-and reproducibility. See [docs/xvars_integration_phases.md](docs/xvars_integration_phases.md)
-for the full X-VARS setup workflow.
+and reproducibility. See [docs/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
 
 
 ---

{opensportslib-0.2.0.dev3 → opensportslib-0.2.0.dev5}/README.md

@@ -289,8 +289,8 @@ backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
 For X-VARS, `feature_source: indexed_or_raw_clip` prefers indexed CLIP features
 when available and falls back to extracting CLIP features from raw video during
 `infer()`. Pre-extracted features remain the preferred path for parity, speed,
-and reproducibility. See [docs/xvars_integration_phases.md](docs/xvars_integration_phases.md)
-for the full X-VARS setup workflow.
+and reproducibility. See [docs/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
 
 
 ---

opensportslib-0.2.0.dev5/examples/quickstart/basic_vqa.py

@@ -0,0 +1,37 @@
+from opensportslib.apis import VQAModel
+
+
+def main():
+    """
+    Minimal VQA example.
+    Update config, question, and dataset paths before running.
+    """
+
+    my_model = VQAModel(
+        config="examples/configs/vqa_qwen.yaml",
+        weights=None,  # optional: path or Hugging Face model ID
+    )
+
+    predictions = my_model.infer(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(predictions)
+
+    single_prediction = my_model.infer(
+        video_path="/path/to/video.mp4",
+        question="What card would you give? Why?",
+    )
+
+    print(single_prediction)
+
+    metrics = my_model.evaluate(
+        test_set="/path/to/test_annotations.json",
+        predictions=predictions,
+    )
+
+    print(metrics)
+
+
+if __name__ == "__main__":
+    main()

{opensportslib-0.2.0.dev3 → 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.dev3 → 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