data/README.md

---
license: mit
---
# AI Skating Coach - Figure Skating Element Recognition Dataset

**Clean 64-class version with multi-jump combinations preserved**

## Overview

Figure skating skeleton pose sequences for action/element classification. Raw keypoint data extracted from competition videos and professional motion capture, presented in clean unmodified form.

- **Total samples:** 5,405
- **Training:** 4,324 sequences
- **Test:** 1,081 sequences  
- **Classes:** 64 figure skating elements
- **Format:** Clean unaugmented data (no synthetic samples, no class weights)

## Dataset Structure

```
├── train_data.pkl          # Training sequences (4,324)
├── train_label.pkl         # Training labels
├── test_data.pkl           # Test sequences (1,081)
├── test_label.pkl          # Test labels
├── label_mapping.json      # Class IDs and names
└── dataset_info.json       # Metadata
```

## Data Format

**Skeleton sequences:** `(num_samples, variable_frames, 17_keypoints, 3_coordinates)`

- **Frames:** Variable length from original footage (original temporal resolution preserved)
- **Duration:** Varies by element (typically 2-25 seconds at 30 fps)
- **Keypoints:** 17-point COCO format
  - Head: nose, left/right eye, left/right ear
  - Torso: shoulders, elbows, wrists, hips, knees, ankles
- **Coordinates:** (x, y, confidence) normalized to [-1, 1] range

## Classes (64 Total)

### Single Jump Elements (0-20)
Single rotation jumps: Axel, Flip, Lutz, Loop, Salchow, Toeloop  
Rotations: 1x, 2x, 3x, 4x (where applicable)

**Examples:** 1Axel, 2Flip, 3Lutz, 4Toeloop

### Multi-Jump Combinations (21-30)
Natural sequence patterns from competition:
- 1A+3T, 1A+3A
- 2A+3T, 2A+3A, 2A+1Eu+3S
- 3F+3T, 3F+2T+2Lo
- 3Lz+3T, 3Lz+3Lo
- Generic Combination (Comb)

### Spins (31-62)
Rotational elements with position changes:
- **FCSp** (Foot Change Camel Spin): 31-34
- **CCoSp** (Catch Foot Combination Spin): 35-38
- **ChCamelSp** (Change Camel Spin): 39-42
- **ChComboSp** (Change Combination Spin): 43-46
- **ChSitSp** (Change Sit Spin): 47-50
- **FlySitSp** (Fly Sit Spin): 51-54
- **LaybackSp** (Layback Spin): 55-58

### Step Sequences & Choreography (59-63)
Linear traveling skating patterns:
- **StepSeq1-4:** Graded step sequences (59-62)
- **ChoreSeq1:** Choreographed sequence (63)

## Data Sources

1. **MMFS Dataset** (4,915 sequences)
   - 2D pose estimation from figure skating competition videos
   - Multiple skaters, various competition levels

2. **JSON Motion Capture** (253 sequences)
   - Professional 3D mocap capture from 4 elite skaters
   - Converted to 17-keypoint COCO format for consistency

3. **Combined & Validated** (5,405 sequences)
   - Merged MMFS and mocap data
   - Deduplicated overlapping classes
   - Combinations preserved for sequence modeling

## Preprocessing
 **Format unification:** 142-marker mocap → 17-keypoint COCO skeleton  
 **Temporal sampling:** Uniform to 150 frames per sequence  
 **Normalization:** Keypoint coordinates normalized to [-1, 1]  
 **Velocity features:** Computed for temporal dynamics  
 **Train/test split:** 80/20 stratified by class  



-

## Loading the Dataset

### Python
```python
import pickle
import json
import numpy as np

# Load training sequences and labels
with open('train_data.pkl', 'rb') as f:
    X_train = pickle.load(f)  # List of (150, 17, 3) arrays
with open('train_label.pkl', 'rb') as f:
    y_train = pickle.load(f)  # Array of class IDs (0-63)

# Load test data
with open('test_data.pkl', 'rb') as f:
    X_test = pickle.load(f)
with open('test_label.pkl', 'rb') as f:
    y_test = pickle.load(f)

# Load class mapping
with open('label_mapping.json', 'r') as f:
    mapping = json.load(f)

# Inspect
print(f"Training: {len(X_train)} sequences, {X_train[0].shape}")
print(f"Classes: {len(np.unique(y_train))}")
print(f"Class weights: {np.bincount(y_train)}")  # Raw distribution
```

### Convert to NumPy
```python
import numpy as np

# Stack sequences into array
X_train_array = np.array(X_train)  # (4324, 150, 17, 3)
X_test_array = np.array(X_test)    # (1081, 150, 17, 3)
```

## Recommended Usage

### Action Recognition
- CNN-LSTM architecture for 64-class classification
- Input: (batch, 150, 17, 3) sequences
- Output: 64-class softmax

### Sequence Modeling
- Use combinations (classes 21-30) for multi-step skill prediction
- Temporal modeling with RNNs/Transformers
- Learn natural skill progression patterns

### Transfer Learning
1. Pretrain on combinations for sequence context
2. Fine-tune on single jumps for element detection
3. Apply to event/routine-level classification

### Sports Analytics
- Skill difficulty assessment
- Athlete performance tracking
- Technique consistency analysis

## Class Distribution

For detailed per-class sample counts, see `dataset_info.json`

**Imbalance ratio:** ~6x (largest/smallest class)  
**Skew:** Toward more common elements (2-3 rotations, standard spins)





Dataset compiled from public figure skating competition videos and proprietary motion capture data. Use for research and educational purposes.

---

**Generated:** February 2026