DanceIR: Dance Information Retrieval Toolbox

A modular Python toolbox for dance motion analysis, feature extraction, and tempo estimation from 2D keypoint data.

This toolbox implements a kinematic anchor–based framework for estimating musical tempo from dance movement, as described in the following manuscript currently under review:

Estimating Music Tempo from Dance Movement Using Kinematic Rhythmic Anchors (under review)

Features

• Multi-anchor dance tempo estimation: Robust dance tempo estimation using multiple body segments (hands, feet, torso)
• COCO-format keypoint support: Load and process standard 2D keypoint formats
• Feature extraction: Center of mass, anchor detection, and energy-based features
• Signal preprocessing: Detrending, normalization, and filtering utilities
• Evaluation metrics: Octave-invariant metric for dance tempo estimation evaluation

Installation

From PyPI

pip install danceir

From source

git clone https://github.com/sagar0dutta/danceir.git
cd danceir
pip install -e .

Optional dependencies

For demo notebooks and video processing:

pip install danceir[demo]

For development:

pip install danceir[dev]

Quick Start

Basic Tempo Estimation

import numpy as np
from danceir.io import KeypointLoader
from danceir.pipelines import estimate_tempo_from_keypoints

# Load keypoint data (COCO format)
loader = KeypointLoader()
keypoints_data = loader.load_keypoints_pickle("keypoints.pkl")
keypoints_2d = loader.extract_all_keypoints_2d(keypoints_data)
# Shape: (num_frames, num_joints, 2) where last dim is [x, y]

# Estimate tempo
result = estimate_tempo_from_keypoints(
    keypoints_2d,
    marker_groups=[(9, 10), (15, 16)],  # both hands, both feet
    axis='y',
    use_com=True,  # Include torso center of mass
    fps=60.0
)

# Get results
tempo_info = result['combined_anchors']
print(f"Estimated tempo: {tempo_info['gtempo']} BPM")
print(f"Best segment: {tempo_info['best_segment']}")

Evaluation

from danceir.evaluation import dance_tempo_evaluation

# Compare estimated tempo with reference
ref_tempo = 120.0  # Ground truth BPM
est_tempo = tempo_info['gtempo']

eval_result = dance_tempo_evaluation(ref_tempo, est_tempo)
print(f"Accuracy: {eval_result.accuracy}%")
print(f"Mean DTS: {eval_result.mean_dts:.3f}")

Keypoint Format

DanceIR expects COCO-format 2D keypoints:

• Input shape: (num_persons, num_frames, num_joints, 3)
• Last dimension: [x, y, confidence]
• Joint indices: 0=nose, 1=left_eye, ..., 9=left_wrist, 10=right_wrist, ..., 15=left_ankle, 16=right_ankle

API Overview

Main Pipeline

• estimate_tempo_from_keypoints(): High-level tempo estimation from keypoints

I/O

• KeypointLoader: Load COCO-format keypoint data from pickle files
• AnchorIO: Save/load anchor sequences
• PathManager: Manage data paths

Features

• compute_com_variants(): Compute center of mass (hips, shoulders, torso)
• detect_segment_anchor(): Detect anchors from motion signals
• AnchorExtractor: High-level anchor extraction interface
• EnergyExtractor: Energy-based feature extraction

Analysis

• estimate_dance_tempo(): Multi-anchor tempo estimation
• compute_tempogram(): Compute tempogram from anchor signals
• compute_alignment(): Align signals with sinusoidal templates

Evaluation

• dance_tempo_evaluation(): Compute Octave-invariant metrics

Requirements

• Python >= 3.8
• numpy >= 1.20.0
• scipy >= 1.7.0
• librosa >= 0.9.0

Documentation

Full documentation:

Examples

See the demo/ directory for Jupyter notebook examples:

• Demo.ipynb: Complete tutorial with tempo estimation from keypoint files and video processing with MediaPipe pose estimation
• Basic tempo estimation from keypoint files
• Video processing with MediaPipe pose estimation

The demo notebook demonstrates:

1. Loading COCO-format keypoint data
2. Extracting multi-anchor features (hands, feet, torso)
3. Running tempo estimation pipeline
4. Evaluating results with reference tempos
5. Processing videos with MediaPipe for pose estimation

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

Report bugs or request features on GitHub Issues.

Author

Sagar Dutta - sagar0dutta@gmail.com

---