README.md

---
language: en
license: mit
tags:
  - court-detection
  - keypoint-detection
  - sports-analysis
  - badminton
  - tennis
  - pytorch
  - computer-vision
  - octave-convolution
  - geometric-constraints
  - polar-transform
datasets:
  - adithyanraj03/CourtKeyNet-Dataset
metrics:
  - pck
  - iou
pipeline_tag: keypoint-detection
library_name: pytorch
model-index:
  - name: CourtKeyNet
    results:
      - task:
          type: keypoint-detection
          name: Court Keypoint Detection
        dataset:
          name: CourtKeyNet Badminton Court Dataset
          type: custom
        metrics:
          - name: PCK
            type: pck
            value: 99.99
          - name: IoU
            type: iou
            value: 99.67
---

<div align="center">
  <img src="assets/teasser.png" alt="CourtKeyNet Banner" width="100%">

# CourtKeyNet: A Novel Octave-Based Architecture for Precision Court Detection

**Adithya N Raj** 

[![Paper](https://img.shields.io/static/v1?label=Paper&message=ScienceDirect&color=red&logo=elsevier&logoColor=white)](https://www.sciencedirect.com/science/article/pii/S2666827026000496)
[![GitHub](https://img.shields.io/static/v1?label=Code&message=GitHub&color=black&logo=github)](https://github.com/adithyanraj03/CourtKeyNet)
[![Dataset](https://img.shields.io/badge/%F0%9F%93%81%20Dataset-GitHub-blue)](https://github.com/adithyanraj03/Paper_09_Data-Set_CourtKeyNet)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![SafeTensors](https://img.shields.io/badge/Format-SafeTensors-8A2BE2)](https://huggingface.co/docs/safetensors)

</div>

---

## Model Summary

**CourtKeyNet** is a lightweight deep learning architecture for precision court keypoint detection in sports videos. It detects 4 corner keypoints of badminton and tennis courts from a single image, enabling downstream applications like court homography estimation, match statistics generation, and automated broadcasting systems.

Published in [Machine Learning with Applications (Elsevier)](https://www.sciencedirect.com/science/article/pii/S2666827026000496), 2026.

### Key Features

- 🎯 **99.99% PCK** and **99.67% IoU** on the fine-tuned model
- ⚡ **Lightweight and fast** — efficient architecture for real-time use
- 🔬 **Octave Feature Extractor** — Multi-frequency feature decomposition for capturing fine court details and global structural context
- 🎱 **Polar Transform Attention** — Boundary detection in polar coordinates for precise court line localization
- 📐 **Geometric Consistency Loss** — Ensures structurally valid quadrilateral outputs
- 🏸 Supports both **badminton** and **tennis** court detection

---

## Model Variants

| Variant | File | Format | Val Loss | PCK (%) | IoU (%) | Description |
|---------|------|--------|----------|---------|---------|-------------|
| **CourtKeyNet-Base** | `pretrained/courtkeynet_base.safetensors` | SafeTensors | 0.0977 | 99.09 | 94.33 | Pre-trained on 140k+ images from scratch |
| **CourtKeyNet-Finetuned** ⭐ | `finetuned/courtkeynet_finetuned.safetensors` | SafeTensors | 0.0013 | 99.99 | 99.67 | Fine-tuned on 7k+ clean annotated images |

> **Recommendation:** Use the **fine-tuned** variant for best results. The pre-trained base model is provided for researchers who wish to fine-tune on their own custom court datasets.

---

## Quick Start

### 1. Download Weights

```bash
# Install huggingface CLI
pip install "huggingface_hub[cli]"

# Download the full repository
huggingface-cli download Cracked-ANJ/CourtKeyNet --local-dir ./courtkeynet-weights

# Or download only the fine-tuned model (recommended)
huggingface-cli download Cracked-ANJ/CourtKeyNet finetuned/courtkeynet_finetuned.safetensors --local-dir ./courtkeynet-weights
```

### 2. Run Inference

For inference, training, and fine-tuning scripts, use the full source code from the **[GitHub Repository](https://github.com/adithyanraj03/CourtKeyNet)**:

```bash
# Clone the source code
git clone https://github.com/adithyanraj03/CourtKeyNet.git
cd CourtKeyNet

# Install dependencies
pip install -r requirements.txt

# Run Inference Studio (GUI)
cd courtkeynet
python inference.py
```

> The Inference Studio provides a complete GUI with image/video/webcam support, confidence scoring, and real-time visualization.

---

## Architecture

<div align="center">
  <img src="assets/architecture.png" alt="CourtKeyNet Architecture" width="80%">
</div>



<details>
<summary style="font-size: 1.2em; font-weight: bold; cursor: pointer;">🔍 How Confidence Detection Works (Visual Explanation)</summary>

### How Confidence Detection Works

The model (`CourtKeyNet`) works like this:

![Architecture](assets/data_1.png)

**Problem**: It has no "court detector" — it assumes every image IS a court!

---

#### What the Model Actually Outputs Internally

When you run `model(image)`, it returns a dictionary with these components:

```python
outputs = {
    'heatmaps': Tensor[B, 4, 160, 160],      # 4 gaussian peaks (one per corner)
    'kpts_init': Tensor[B, 4, 2],            # Initial keypoints from heatmaps
    'kpts_refined': Tensor[B, 4, 2],         # Final refined keypoints
    'features': Tensor[B, 256, 20, 20]       # Feature maps (optional)
}
```

#### Visualization of Heatmap Output

For a **real court image**:
```text
Heatmap for Corner 0 (Top-Left):
```
![Heatmap](assets/data_2.png)

For a **non-court image** (e.g., random person):
```text
Heatmap for Corner 0:
```
![Heatmap](assets/data_3.png)

---

#### 3 Confidence Metrics

##### 1️⃣ **Heatmap Peak Confidence** (Primary Signal)

**What it measures**: How "peaky" the heatmap is

```python
max_values = heatmaps.max(dim=(2,3))  # Find highest value in each heatmap
conf_heatmap = max_values.mean()      # Average across 4 corners
```

**Visual comparison**:

![Comparison](assets/data_4.png)

---

##### 2️⃣ **Heatmap Entropy** (Uncertainty)

**What it measures**: How "spread out" the probability is

```python
# Entropy = -Σ(p * log(p))
# Low entropy = focused (good)
# High entropy = random noise (bad)
```

**Visual comparison**:

![Entropy_Comparison](assets/data_5.png)

---

##### 3️⃣ **Geometric Validity** (Shape Check)

**What it checks**: Does the quad look like a real court?

```text
Checklist:
✓ Are corners in correct positions? (TL upper-left, BR lower-right)
✓ Is the quad convex? (no crossed lines)
✓ Is the area reasonable? (not too tiny, not entire image)
✓ Is aspect ratio court-like? (not a thin line)
```

**Visual examples**:

![Visual_Example](assets/data_6.png)

</details>

---

## Training Details

### Pre-training (from scratch)

| Parameter | Value |
|-----------|-------|
| **Dataset** | 140,000+ badminton & tennis court images |
| **Epochs** | 158 (early stopping, patience=20) |
| **Best Epoch** | 138 |
| **Optimizer** | AdamW |
| **Learning Rate** | 5e-5 (cosine schedule) |
| **Batch Size** | 47 |
| **Image Size** | 640×640 |
| **Mixed Precision** | ✓ FP16 |
| **Hardware** | NVIDIA RTX 5090 (32GB) |

### Fine-tuning

| Parameter | Value |
|-----------|-------|
| **Base Model** | Pre-trained CourtKeyNet-Base (epoch 138) |
| **Dataset** | 7,000+ precisely annotated clean images |
| **Epochs** | 79 (early stopping, patience=20) |
| **Best Epoch** | 59 |
| **Learning Rate** | 1e-4 |
| **Batch Size** | 48 |
| **Geometric Loss** | Enabled (edge + diagonal + angle constraints) |

---

## Evaluation Results

### Fine-tuned Model (Recommended)

| Metric | Score |
|--------|-------|
| **PCK** (Percentage of Correct Keypoints) | **99.99%** |
| **IoU** (Intersection over Union) | **99.67%** |
| **Validation Loss** | **0.0013** |

### Pre-trained Base Model

| Metric | Score |
|--------|-------|
| **PCK** | 99.09% |
| **IoU** | 94.33% |
| **Validation Loss** | 0.0977 |

### Training Metrics

<div align="center">
  <img src="assets/training_metrics.png" alt="Training Metrics" width="100%">
  <p><em>Pre-training metrics across 158 epochs showing loss convergence and PCK/IoU progression</em></p>
</div>

<div align="center">
  <img src="assets/finetune_detail.png" alt="Fine-tuning Detail" width="100%">
  <p><em>Fine-tuning convergence: rapid loss decrease with PCK reaching 99.99% and IoU reaching 99.67%</em></p>
</div>

### Validation Samples

<div align="center">
  <table>
    <tr>
      <td align="center"><strong>Epoch 1 (Early Fine-tuning)</strong></td>
      <td align="center"><strong>Epoch 79 (Final)</strong></td>
    </tr>
    <tr>
      <td><img src="assets/val_sample_early.jpg" alt="Early Validation" width="100%"></td>
      <td><img src="assets/val_sample_final.jpg" alt="Final Validation" width="100%"></td>
    </tr>
  </table>
  <p><em>Red = Predicted court boundary | Green = Ground truth | Yellow dots = Keypoints</em></p>
</div>

---

## Fine-tuning on Custom Data

To fine-tune CourtKeyNet on your own court dataset (any sport):

```bash
# 1. Clone the source code
git clone https://github.com/adithyanraj03/CourtKeyNet.git
cd CourtKeyNet

# 2. Download weights
huggingface-cli download Cracked-ANJ/CourtKeyNet pretrained/courtkeynet_base.pt --local-dir ./weights

# 3. Fine-tune
cd courtkeynet
python finetune.py
```

> **Note:** Fine-tuning requires only **5,000–7,000** clean annotated images. Training from scratch requires **140,000+** images.

---

## Intended Use

### ✅ Appropriate Uses
- Badminton and tennis court detection in sports videos
- Court homography estimation for tactical analysis
- Generating match statistics from broadcast footage
- Automated camera calibration for sports broadcasting
- Academic research in sports video analysis

### ⚠️ Limitations
- Trained specifically on badminton and tennis courts; other court types may require fine-tuning
- Expects single-court images; multi-court scenes are not supported
- Performance may degrade on heavily occluded courts or extreme camera angles
- The model detects 4 outer corners only (not inner court lines)

---

## Citation

If you use CourtKeyNet in your research, please cite:

**Paper:** [CourtKeyNet: A novel octave-based architecture for precision badminton court detection with geometric constraints](https://www.sciencedirect.com/science/article/pii/S2666827026000496)  
**DOI:** [10.1016/j.mlwa.2026.100884](https://doi.org/10.1016/j.mlwa.2026.100884)

```bibtex
@article{NRAJ2026100884,
  title     = {CourtKeyNet: A novel octave-based architecture for precision badminton court detection with geometric constraints},
  journal   = {Machine Learning with Applications},
  volume    = {24},
  pages     = {100884},
  year      = {2026},
  issn      = {2666-8270},
  doi       = {https://doi.org/10.1016/j.mlwa.2026.100884},
  url       = {https://www.sciencedirect.com/science/article/pii/S2666827026000496},
  author    = {Adithya N Raj and Prethija G.}
}
```

---

## License

This project is released under the [MIT License](LICENSE), suitable for both academic and commercial use.

## Contact

For questions or collaboration opportunities: **adithyanraj03@gmail.com**