Datasetpublic

muyu111/basketball

SHOT: Group Intention Forecasting Dataset Paper · arXiv · Project Page · Code · Dataset SHOT is a basketball video dataset for Group Intention Forecasting (GIF). By observing players and their interactions in the early part of a clip, the task is to predict when a shot will occur. SHOT includes five camera-view categories, video frames, keyframe labels, player tracks, body poses, gaze estimates, and head-pose estimates. Introduced in: Beyond the Individual: Introducing Group… See the full description on the dataset page: https://huggingface.co/datasets/muyu111/basketball.

sourceHugging Facecc-by-nc-4.0updated 3d agoView on Hugging Face

1likes2.6kdownloads

Dataset Card

SHOT: Group Intention Forecasting Dataset

Paper · arXiv · Project Page · Code · Dataset

SHOT is a basketball video dataset for Group Intention Forecasting (GIF). By observing players and their interactions in the early part of a clip, the task is to predict when a shot will occur. SHOT includes five camera-view categories, video frames, keyframe labels, player tracks, body poses, gaze estimates, and head-pose estimates.

Introduced in: Beyond the Individual: Introducing Group Intention Forecasting with SHOT Dataset, ACM Multimedia 2025 (MM ’25).

Quick Start

The data is stored on the shotdatasets branch. Use huggingface_hub to download it:

bash

pip install -U huggingface_hub

Download one sample

Start with one sample to explore the files and annotations:

python

from huggingface_hub import snapshot_download

sample_path = "view1/Drive_Dunk/ATLvsNJ-10-view1-3"

snapshot_download(
    repo_id="muyu111/basketball",
    repo_type="dataset",
    revision="shotdatasets",
    allow_patterns=[f"{sample_path}/**"],
    local_dir="./SHOT",
)

Download all data

python

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="muyu111/basketball",
    repo_type="dataset",
    revision="shotdatasets",
    local_dir="./SHOT",
)

To download a single view, add allow_patterns=["view1/**"] to the call above.

File Structure

Samples are organized by view → tactic → sample ID. Each sample contains its video and associated annotations. <sample_id> below refers to the sample folder name, such as ATLvsNJ-10-view1-3.

text

SHOT/
├── view1/
│   └── Drive_Dunk/
│       └── ATLvsNJ-10-view1-3/
│           ├── <sample_id>.mp4
│           ├── frames/
│           ├── keyframes/
│           ├── labels/
│           ├── <sample_id>-track.txt
│           ├── <sample_id>-track_with_gt.txt
│           ├── <sample_id>-pose.json
│           ├── <sample_id>-gaze.txt
│           └── <sample_id>-headpose.txt
├── view2/
├── view3/
├── view4/
└── view5/

File	Contents
`*.mp4`	Basketball video clip
`frames/`	Extracted video frames (JPG)
`keyframes/`	Selected keyframe images (JPG)
`labels/`	Keyframe bounding boxes, player IDs, and roles (XML)
`*-track.txt`	Player tracking output
`*-track_with_gt.txt`	Tracking output with player ID alignment to keyframe annotations
`*-pose.json`	Body keypoints and confidence scores
`*-gaze.txt`	Gaze estimates
`*-headpose.txt`	Head-pose estimates

Tactic names combine passing, screening, driving, and shot type. For example, One-Pass_One-Screen_Drive_Layup indicates one pass, one screen, a drive, and a layup.

Read the Annotations

The examples below use the sample downloaded in Quick Start. Run them from the directory containing SHOT/.

Keyframe labels

XML files store bounding boxes as (xmin, ymin, xmax, ymax). Object names combine a role and player ID: standing-1 means player 1 is standing. The annotation protocol assigns IDs 1–5 to offensive players and 6–10 to defensive players.

python

from pathlib import Path
import xml.etree.ElementTree as ET

sample_dir = Path("SHOT/view1/Drive_Dunk/ATLvsNJ-10-view1-3")
xml_path = sample_dir / "labels/ATLvsNJ-10-view1_frame_0.xml"

# Handle UTF-8 and Chinese legacy encoding
raw = xml_path.read_bytes()
try:
    xml_text = raw.decode("utf-8-sig")
except UnicodeDecodeError:
    xml_text = raw.decode("gb18030")

root = ET.fromstring(xml_text)
players = []
for obj in root.findall("object"):
    role, player_id = obj.findtext("name").rsplit("-", 1)
    box = obj.find("bndbox")
    players.append({
        "player_id": int(player_id),
        "role": role,
        "bbox_xyxy": [
            float(box.findtext(k))
            for k in ("xmin", "ymin", "xmax", "ymax")
        ],
    })

print(players[0])

Output:

text

{'player_id': 1, 'role': 'standing', 'bbox_xyxy': [0.0, 599.0, 168.0, 952.0]}

Body poses

Pose JSON files contain meta_info for the 17 COCO keypoint definitions and instance_info for the per-frame estimates.

python

import json
from pathlib import Path

sample_dir = Path("SHOT/view1/Drive_Dunk/ATLvsNJ-10-view1-3")
pose_path = sample_dir / f"{sample_dir.name}-pose.json"
pose = json.loads(pose_path.read_text(encoding="utf-8"))

frame = pose["instance_info"][0]
print("Frame ID:", frame["frame_id"])
for person in frame["instances"]:
    print("Keypoints:", person["keypoints"])
    print("Scores:", person["keypoint_scores"])

Player tracks

Tracking TXT files use comma-separated MOT-style rows:

text

frame_id, player_id, left, top, width, height, confidence, -1, -1, -1

Use *-track_with_gt.txt when working with the annotated player IDs. In *-track.txt, the second column is the raw tracker ID.

python

import csv
from pathlib import Path

sample_dir = Path("SHOT/view1/Drive_Dunk/ATLvsNJ-10-view1-3")
track_path = sample_dir / f"{sample_dir.name}-track_with_gt.txt"

with track_path.open(encoding="utf-8", newline="") as f:
    for row in csv.reader(f):
        if not row:
            continue
        frame_id, player_id = int(row[0]), int(row[1])
        bbox_xywh = [float(value) for value in row[2:6]]
        print(frame_id, player_id, bbox_xywh)
        break

Working with multiple annotations

—Frame alignment: In the example above, image and pose indices start at 0, while tracking and gaze indices start at 1. Align frame indices before combining features, and sort images by their numeric frame suffix.
—Player alignment: Pose instances contain bounding boxes but no explicit player IDs. Match them to player tracks when building features for each player.
—Velocity: Compute velocity from changes in player position over the corresponding time interval.

Dataset Size

The number of cases in each view is listed below. Each case corresponds to one sample directory.

View	Cases
`view1`	373
`view2`	551
`view3`	72
`view4`	394
`view5`	471
Total	1,861

Citation

If you find our work helpful for your research, please consider citing our work:

bibtex

@inproceedings{DBLP:conf/mm/ZhangWHM0XZ025,
  author       = {Ruixu Zhang and
                  Yuran Wang and
                  Xinyi Hu and
                  Chaoyu Mai and
                  Wenxuan Liu and
                  Danni Xu and
                  Xian Zhong and
                  Zheng Wang},
  title        = {Beyond the Individual: Introducing Group Intention Forecasting with
                  {SHOT} Dataset},
  booktitle    = {{ACM} Multimedia},
  pages        = {13002--13008},
  publisher    = {{ACM}},
  year         = {2025}
}

License

The original annotations and documentation are licensed under CC BY-NC 4.0, covering the rights held by the SHOT contributors. This license permits noncommercial sharing and adaptation with appropriate credit, a license link, and an indication of any changes. See LICENSE for the full terms.

Third-party basketball footage and extracted frames are excluded from this license and remain subject to their respective rights holders' terms and applicable law.