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

Adithya N Raj

---

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), 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

# 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:

# 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

🔍 How Confidence Detection Works (Visual Explanation)

How Confidence Detection Works

The model (CourtKeyNet) works like this:

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:

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:

Heatmap for Corner 0 (Top-Left):

For a non-court image (e.g., random person):

Heatmap for Corner 0:

---

3 Confidence Metrics

1️⃣ Heatmap Peak Confidence (Primary Signal)

What it measures: How "peaky" the heatmap is

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

Visual comparison:

---

2️⃣ Heatmap Entropy (Uncertainty)

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

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

Visual comparison:

---

3️⃣ Geometric Validity (Shape Check)

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

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:

---

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

Pre-training metrics across 158 epochs showing loss convergence and PCK/IoU progression

Fine-tuning convergence: rapid loss decrease with PCK reaching 99.99% and IoU reaching 99.67%

Validation Samples

Epoch 1 (Early Fine-tuning)	Epoch 79 (Final)

Red = Predicted court boundary | Green = Ground truth | Yellow dots = Keypoints

---

Fine-tuning on Custom Data

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

# 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
DOI: 10.1016/j.mlwa.2026.100884

@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, suitable for both academic and commercial use.

Contact

For questions or collaboration opportunities: adithyanraj03@gmail.com