DOI: 10.5281/zenodo.17540917
title: PoseBasketNet

description: # PoseBasketNet

A pose-aware temporal attention framework for basketball motion analysis and skill recognition.

 

## OverviewThis repository implements a research-style scaffold for PoseBasketNet, a model thatcombines pose-guided spatial modeling with temporal attention to recognize and assessbasketball skills in video sequences. It focuses on interpretability, robustness, and practicalsports analytics workflows.

## Key Ideas1) Pose-aware temporal attention to highlight salient frames and body configurations.2) Graph-based spatial modeling to encode anatomical dependencies between joints.3) A unified optimization strategy with pose-guided regularization and domain-specific priors.4) End-to-end training with a classification head for skill labels and hooks for analysis.

## Architecture Summary- Pose Encoder: extracts features from keypoints across frames.- Temporal Attention Module: computes attention weights to focus on informative moments.- Spatial Graph Block: models joint relationships with graph operations.- Classification Head: outputs skill probabilities.- Pose-Aware Optimization: adds temporal smoothness and pose consistency constraints.

## Figures Referenced (from the source document)- Figure on page 5: high-level PoseBasketNet pipeline with multi-scale transformer and dual attention.- Figure on page 6: pose-aware feature encoding with forward and backward heads plus attention blocks.- Figure on page 7: optimization strategy with hierarchical temporal modeling and attention gates.

## Results Snapshot (from the source document)- Page 9 tables show higher accuracy and robustness across multiple datasets compared to baselines.- Ablations indicate each module (pose features, temporal attention, hierarchical modeling) improves performance.

## Suggested Directory Layoutposebasketnet/  src/    data/               dataset adapters and loaders    models/             encoder, attention, graph, classifier    training/           loops, schedulers, logging    evaluation/         metrics and reporting    utils/              helpers for geometry, io, viz  configs/              YAML configs for experiments  scripts/              train, eval, export  tests/                unit tests and smoke checks  README.md

## Installationpython -m venv .venvsource .venv/bin/activate    # or .venv\Scripts\activate on Windowspip install --upgrade pippip install -r requirements.txt    # create this file with torch, torchvision, pytorch-lightning, numpy, scipy, opencv-python, networkx, pyyaml

## Minimal Requirements (suggested)- Python 3.10+- PyTorch 2.x- CUDA-capable GPU (optional but recommended)- ffmpeg for video decoding

## Datasets (as referenced)- Basketball Player Pose Dataset: keypoint-annotated images and videos for basketball actions.- Temporal Motion Analysis Dataset: temporal labels and motion trajectories for sports actions.- Skill Performance Tracking Dataset: individualized drills with performance metrics.- Basketball Training Optimization Dataset: multimodal training sessions and physiology data.

Note: this repository provides adapters for these dataset schemas but does not redistribute data.Prepare data according to the original licenses and place paths in a config file under configs/.

## Quickstart# example: train a classification modelpython -m scripts.train --config configs/baseline.yaml

# example: evaluate a checkpointpython -m scripts.eval --ckpt runs/exp01/checkpoints/last.ckpt --split val

# example: export attention maps for inspectionpython -m scripts.export_attention --ckpt runs/exp01/checkpoints/best.ckpt --video sample.mp4

## Configuration- Training parameters (optimizer, scheduler, batch size) live in YAML under configs/.- Model hyperparameters include pose feature dimension, attention depth, and graph topology.- Toggle pose-guided regularization and smoothing priors via the optimization section.

## Model Components- PoseEncoder: maps raw keypoints to embeddings with invariances for scale and rotation.- TemporalAttention: attends over time using a learnable query and compatibility function.- SpatialGraph: applies graph convolutions over joints to capture kinematic constraints.- Fusion: multiplies temporal context with joint features to derive discriminative signals.- Classifier: projects fused representation to class logits.

## Optimization Strategy- Pose-guided regularization encourages predicted poses to align with realistic trajectories.- Temporal smoothness prior promotes continuity across frames for actions like dribbling.- Hierarchical attention captures short and long temporal dependencies.

## Metrics- Top-1 and Top-5 accuracy- Precision, Recall, and F1- ROC-AUC (optional)- Throughput and latency for deployment settings

## Reproducibility- Fix random seeds, log configs, and archive checkpoints.- Record versions of CUDA, cuDNN, and dependencies.- Include exact dataset splits and hashes when applicable.

## Evaluation Protocol (example)1) Split data into train, val, and test (e.g., 80/10/10).2) Train with cosine scheduler and weight decay.3) Perform multiple runs with different seeds and report mean and standard deviation.4) Track learning curves, confusion matrices, and attention visualizations.

## Visualization- Save per-frame attention weights and overlay them on the video timeline.- Plot joint heatmaps for high-attention moments.- Export qualitative clips for successful and failure cases.

## Limitations- Performance depends on pose estimation quality under occlusion, blur, and low resolution.- Domain priors are basketball-specific and may not transfer without adaptation.- Additional modalities such as optical flow and trajectories may improve robustness.

## Responsible Use- Ensure you have rights to the data and respect privacy expectations in sports recordings.- Follow licenses of datasets and third-party libraries.

## Roadmap- Add lightweight variants for mobile inference.- Support mixed-modal training that combines pose, RGB, and optical flow.- Integrate quantization-aware training and pruning for deployment.

## How to CitePlease cite the original paper or this repository when using the ideas or codebase in academic or product work.

## LicenseThis project is released under a permissive license such as Apache-2.0 or MIT. Add your preferred license file.

## Maintainers- Primary contact: add your name and email here.- Issues and pull requests are welcome; please include minimal repro scripts and logs.

## AcknowledgmentsThanks to prior work on pose estimation, temporal attention, and sports analytics for inspiring this scaffold.