Cracked-ANJ/CourtKeyNet

<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

    

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

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](https://github.com/adithyanraj03/CourtKeyNet):

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

[image]

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

[image]

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

Heatmap for Corner 0:

[image]

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:

[image]

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:

[image]

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:

[image]

</details>

Training Details

Pre-training (from scratch)

Fine-tuning

Evaluation Results

Fine-tuned Model (Recommended)

Pre-trained Base Model

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/valsampleearly.jpg" alt="Early Validation" width="100%"></td> <td><img src="assets/valsamplefinal.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):

# 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