FineSports: Fine-grained Basketball Action Recognition

# FineSports - Fine-grained Basketball Action Recognition
# Based on Xu, Zhao, Yin, Zhou & Peng, CVPR 2024
# Paper: https://openaccess.thecvf.com/content/CVPR2024/html/Xu_FineSports_A_Multi-person_Hierarchical_Sports_Video_Dataset_for_Fine-grained_Action_CVPR_2024_paper.html
# Dataset: https://github.com/PKU-ICST-MIPL/FineSports_CVPR2024
#
# FineSports is a multi-person hierarchical NBA basketball dataset for
# fine-grained action understanding. Each action instance tracks the
# ball-handler with a spatial-temporal tube (per-frame bounding boxes) and
# is labeled with a coarse ball-handler action (12 categories) and a
# fine-grained sub-action (52 categories).
#
# This Potato config reproduces the labeling: mark the temporal boundary of
# the ball-handler's action, then select the coarse action and its
# fine-grained sub-action.

annotation_task_name: "FineSports - Fine-grained Basketball Action Recognition"
task_dir: "."

data_files:
  - sample-data.json

item_properties:
  id_key: "id"
  text_key: "video_url"

output_annotation_dir: "annotation_output/"
output_annotation_format: "json"

annotation_schemes:
  # Step 1: mark the temporal boundary of the ball-handler action instance
  - name: "action_segment"
    description: "Mark the start and end of the ball-handler's action instance."
    annotation_type: "video_annotation"
    mode: "segment"
    labels:
      - name: "ball_handler_action"
        color: "#F97316"
        key_value: "a"
    frame_stepping: true
    show_timecode: true
    playback_rate_control: true
    video_fps: 25

  # Step 2: coarse ball-handler action (12 categories)
  - annotation_type: radio
    name: coarse_action
    description: "Coarse ball-handler action category (FineSports, 12 types):"
    labels:
      - "Drive"
      - "Dribble"
      - "Attack"
      - "Shoot"
      - "Pick&Roll (P&R)"
      - "Pass"
      - "Backboard"
      - "Result"
      - "Defense"
      - "Lay-Up"
      - "Steal&Interfere"
      - "Foul&Violation"

  # Step 3: fine-grained sub-action (52 categories)
  - annotation_type: radio
    name: fine_action
    description: "Fine-grained sub-action (FineSports, 52 types):"
    labels:
      - "Drive Left"
      - "Drive Right"
      - "Drive Straight"
      - "Drive Baseline"
      - "Drive Middle"
      - "Dribble Move"
      - "Cut"
      - "Isolation"
      - "Post-Up Right Shoulder"
      - "Post-Up Left Shoulder"
      - "Pass Steal"
      - "Dribble Steal"
      - "Interfere Shot"
      - "Basket"
      - "To Basket"
      - "High P&R"
      - "Left P&R"
      - "Right P&R"
      - "Dribble Jumper"
      - "No Dribble Jumper"
      - "Jumper"
      - "Early Jumper"
      - "Free Throw"
      - "Hand Off"
      - "Ball Delivered"
      - "To Shooter's Left"
      - "To Shooter's Right"
      - "Offensive Rebound Short"
      - "Offensive Rebound Long"
      - "Defensive Rebound Short"
      - "Defensive Rebound Long"
      - "Make 2 Pts"
      - "Make 3 Pts"
      - "Miss 2 Pts"
      - "Miss 3 Pts"
      - "Make 2 Pts Foul"
      - "Make 3 Pts Foul"
      - "Run Offense"
      - "Turnover"
      - "Fighting"
      - "Personal Foul"
      - "Double Foul"
      - "Technical Foul"
      - "Unsportsmanlike Foul"
      - "Disqualifying Foul"
      - "Traveling"
      - "Player and Ball Out of Bound"
      - "Defensive 3 Sec Violation"
      - "Out of Bound 5 Sec Violation"
      - "8 Sec Violation"
      - "Shot Clock Violation"
      - "Defense Commits"

annotation_instructions: |
  You will see a short NBA basketball clip. For each ball-handler action:

  1. Use the video timeline to mark the start and end of the action instance.
  2. Identify the ball-handler (the player controlling the ball).
  3. Select the coarse action category (12 options).
  4. Select the fine-grained sub-action that best describes it (52 options).

  The coarse and fine labels form a two-level hierarchy: pick the coarse
  category first, then the specific sub-action under it.

html_layout: |
  <div style="padding: 15px; max-width: 800px; margin: auto;">
    <div style="background: #fff7ed; border: 1px solid #fed7aa; border-radius: 8px; padding: 10px 14px; margin-bottom: 12px; font-size: 13px; color: #9a3412;">
      NBA clip {{clip_id}} — track the ball-handler and label the action hierarchy.
    </div>
    <video controls style="width: 100%; border-radius: 8px;" src="{{video_url}}"></video>
  </div>

allow_all_users: true
instances_per_annotator: 40
annotation_per_instance: 2
allow_skip: true
skip_reason_required: false