Real-Time_Tennis_Analytics_System_Using_Computer_Vision

KO | EN

gitlite — search

#javascript #react #golang #go #machine-learning #rust #deep-learning #linux #docker #nodejs #awesome #security #pytorch #ios

Real-Time_Tennis_Analytics_System_Using_Computer_Vision

(★ 15)

Tennis Detection & Mini-Court Visualization using YOLOv8

Real-Time_Tennis_Analytics_System_Using_Computer_Vision 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Real-Time Tennis Analytics

A computer-vision system for tennis video analysis built with Ultralytics YOLO and OpenCV. It supports tennis ball and player detection, short-term trajectory prediction, court perspective mapping, ground-projected speed estimation, and mini-court visualization.

> The repository includes the labeled training dataset, a demonstration video, an example output video, and the default trained checkpoint.

## Demo

The demo shows player and ball detection, the smoothed ball trajectory, ground-projected speed, and the mini-court view running on the same rally.

## Before and After

<table>
  <tr>
    <th width="50%">Original video</th>
    <th width="50%">Analytics output</th>
  </tr>
  <tr>
    <td><img src="docs/assets/comparison_before.webp" alt="Original tennis video frame"></td>
    <td><img src="docs/assets/comparison_after.webp" alt="Analyzed tennis video frame with detections, trajectory, speed, and mini-court"></td>
  </tr>
</table>

## Features

- Detects `tennisball` and `tennisplayer` objects.
- Selects the ball candidate using its predicted position, candidate distance, and detection confidence to reject obvious jumps.
- Predicts the ball position for up to three consecutive missed frames.
- Automatically reacquires the ball after tracking is lost.
- Applies exponential smoothing to reduce ball-position jitter.
- Selects the two primary players and maps their foot positions onto the court.
- Uses a JSON calibration file to calculate the video-to-court homography.
- Estimates median-smoothed ground-projected speed using the actual elapsed frame interval.
- Renders detection boxes, trajectories, player positions, speed, and a mini-court into an output video.
- Supports image detection, basic video detection, full video analysis, calibration, and model training.

## Project Structure

```text
.
├── run.py                      # Recommended project entry point
├── src/tennis_analytics/
│   ├── config.py              # Paths, parameters, data structures, and validation
│   ├── detector.py            # Ultralytics YOLO detection
│   ├── tracker.py             # Ball tracking, player selection, and speed estimation
│   ├── mini_court.py          # Calibration, coordinate mapping, and mini-court rendering
│   ├── pipeline.py            # Video processing, basic inference, and model training
│   └── cli.py                 # Unified command-line interface
├── tests/                     # Tracking, speed, and CLI tests
├── configs/court_points.json  # Doubles-court calibration for the demonstration video
├── datasets/tennis/           # YOLO-format training and validation dataset
├── docs/assets/               # README demo GIF and comparison images
├── models/                    # Optional location for a preferred best.pt checkpoint
├── outputs/                   # Default output directory and example result
├── runs/detect/train2/
│   └── weights/best.pt        # Default tennis detection model
├── demonstration_video/       # Demonstration input video
├── pyproject.toml             # Package and CLI configuration
├── requirements.txt
└── ultralytics-main/          # Upstream source snapshot and legacy compatibility scripts
```

The old scripts in `ultralytics-main/train.py`, `imagesdemo.py`, `vediodemo.py`, and `mini_court/` are retained as compatibility entry points. The application logic now lives in `src/tennis_analytics`. The package installs a pinned Ultralytics version through `pyproject.toml` instead of depending on changes to the upstream source tree.

## Processing Pipeline

```text
Video frame
  → YOLO detection
  → Motion-constrained candidate selection / short-term prediction / reacquisition
  → Exponential smoothing of the ball position
  → Selection of the two primary players
  → Court homography
  → Ground-projected speed estimation
  → Original-frame and mini-court rendering
  → Output MP4
```

The modules communicate through small data structures such as `Detection`, `TrackSample`, and two-dimensional coordinates. This keeps the code easy to follow without splitting a project of this size into too many files.

## Installation

Python 3.8 or later is required. Create a virtual environment from the repository root:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

On Windows, activate the environment with:

```powershell
.venv\Scripts\activate
```

Installing the package also provides the unified command:

```bash
tennis-analytics --help
```

## Model Setup

The application automatically searches for a model in this order:

```text
1. runs/detect/train2/weights/best.pt
2. runs/detect/train4/weights/best.pt
```

The included `runs/detect/train2/weights/best.pt` checkpoint is selected automatically. Its recorded best results are 0.7766 mAP50 and 0.3701 mAP50-95, which are better than the `train4` run. Use `--model` to select a different checkpoint.

The model must contain the following class names:

```yaml
names:
  0: tennisball
  1: tennisplayer
```

## 1. Court Calibration

Each fixed-camera video requires four court corner points in this order: top-left, top-right, bottom-right, and bottom-left.

The default calibration command assumes the 10.97-meter width of a doubles court:

```bash
tennis-analytics calibrate \
  --video "demonstration_video/oringinal vedio.mp4" \
  --output configs/court_points.json
```

If the selected points follow the singles sidelines, specify the 8.23-meter width:

```bash
tennis-analytics calibrate \
  --video /path/to/video.mp4 \
  --court-width-m 8.23
```

The calibration file records both the video resolution and the real court dimensions. Recalibrate videos with a different resolution to avoid incorrect coordinate scaling.

## 2. Full Video Analysis

The simplest way to run the project is to execute the entry point from the repository root:

```bash
.venv/bin/python run.py
```

With no arguments, `run.py` processes the default demonstration video using the automatically discovered model and the bundled calibration file. It also relaunches itself with the project `.venv` interpreter when an IDE uses the wrong Python interpreter. Preview is disabled by default, and the result is written to `outputs/output_with_minicourt.mp4`.

Arguments can be passed directly to the entry point:

```bash
.venv/bin/python run.py \
  --output outputs/result.mp4 \
  --show
```

The equivalent unified CLI command is:

```bash
tennis-analytics process \
  --video "demonstration_video/oringinal vedio.mp4" \
  --calibration configs/court_points.json \
  --output outputs/result.mp4
```

Add `--show` for a live preview:

```bash
tennis-analytics process --show
```

Common options:

```text
--conf 0.20                Detection confidence threshold
--max-prediction-gap 3     Maximum number of consecutive frames to predict
--max-players 2            Number of players mapped onto the mini-court
--show                     Show the processing window; press q to stop early
```

## 3. Basic Detection

Detect objects in a video without rendering the mini-court:

```bash
tennis-analytics detect-video \
  --video /path/to/video.mp4 \
  --model models/best.pt \
  --output outputs/detection.mp4
```

Detect objects in a single image:

```bash
tennis-analytics detect-image \
  --image /path/to/image.jpg \
  --model models/best.pt \
  --output outputs/image_result.jpg
```

## 4. Training

The included YOLO-format dataset contains 110 training images and 90 validation images. Train with:

```bash
tennis-analytics train \
  --data datasets/tennis/tennisball.yaml \
  --model yolov8n.pt \
  --epochs 250 \
  --imgsz 640
```

The default training output directory is:

```text
runs/detect/tennis_detector/
```

After training, copy `weights/best.pt` to `models/best.pt`, or pass its existing path with `--model`.

## Tests

Run the test suite after installing the project:

```bash
python -m unittest discover -s tests -v
```

The current tests cover:

- Updating the ball track only once per frame.
- Rejecting a distant, high-confidence false detection using the predicted path.
- Predicting through a limited number of missed frames.
- Reacquiring the ball after the prediction window expires.
- Smoothing observed ball positions.
- Selecting the two strongest player detections.
- Using the actual elapsed time after missed frames.
- Excluding predicted points from speed estimation.
- Rejecting implausible speeds.
- Parsing CLI commands and arguments.

## Known Limitations

1. The system uses a monocular ground-plane homography. A flying tennis ball has height, so the reported value is ground-projected speed rather than true three-dimensional radar-gun speed.
2. The two players are currently selected by detection confidence. Umpires, ball kids, or spectators may be selected incorrectly; court-region filtering and persistent multi-object tracking IDs would improve this behavior.
3. Linear prediction is intended only for short visual gaps and does not replace long-term track association.
4. A fixed homography requires a stationary camera. Videos with camera movement, zoom, or significant shake require dynamic court keypoints and camera-motion compensation.
5. The best recorded experiment results are 0.7766 mAP50 and 0.3701 mAP50-95. Reproducing them may still vary with the Ultralytics version, hardware, random seed, and training configuration.

## License

The bundled Ultralytics source code is licensed under AGPL-3.0. Review the applicable license obligations before publishing or deploying the project.

Real-Time_Tennis_Analytics_System_Using_Computer_Vision

Real-Time_Tennis_Analytics_System_Using_Computer_Vision 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Real-Time_Tennis_Analytics_System_Using_Computer_Vision

Real-Time_Tennis_Analytics_System_Using_Computer_Vision 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README