# MK8DX Table Reader

A Python package to extract player names and scores from Mario Kart 8 Deluxe end-game tables using YOLO object detection and ONNX-based EasyOCR.

## Installation

### Option 1: Lightweight ONNX Version (Recommended)

```bash
# Install the package (without heavy PyTorch dependencies)
pip install mk8dx-table-reader

# Download ONNX EasyOCR models (~17 MB)
python download_easyocr_models.py
```

**Total size:** ~50 MB

### Option 2: PyTorch Version (Fallback)

```bash
# Install with PyTorch-based EasyOCR
pip install mk8dx-table-reader[pytorch-ocr]
```

**Total size:** ~2 GB

## Features

- Extract player names from MK8DX end-game screenshots
- Read scores and positions from tables
- Uses YOLO for object detection
- **NEW**: ONNX-based EasyOCR for lightweight inference (3-4x faster, 97% smaller)
- Fallback to PyTorch EasyOCR if ONNX models not available
- OCR powered by optimized ONNX models and Keras models

## Requirements

### Core Requirements
- Python >= 3.11.11
- OpenCV
- ONNXRuntime
- Ultralytics YOLO
- NumPy
- Pillow

### Optional Requirements
- EasyOCR (PyTorch-based, only if not using ONNX models)

## Usage

```python
from mk8dx_table_reader import Fullreader
import PIL

# Initialize reader (automatically uses ONNX if models are available)
reader = Fullreader()

# Load an image
img = PIL.Image.open("screenshot.png")

# Extract player names and scores
names, scores = reader.fullOCR(img)

print("Players:", names)
print("Scores:", scores)
```

## ONNX EasyOCR Benefits

| Feature | PyTorch EasyOCR | ONNX EasyOCR |
|---------|----------------|--------------|
| **Package Size** | ~2 GB | ~17 MB |
| **Inference Speed** | Baseline | 3-4x faster |
| **Memory Usage** | ~2 GB RAM | ~50 MB RAM |
| **Accuracy** | 100% | >95% |

See [EASYOCR_ONNX_GUIDE.md](EASYOCR_ONNX_GUIDE.md) for more details.

## License

See LICENSE.md for details.

## Author

Julien ABADIE - julien.abadie@etu.uca.fr

## GitHub

[https://github.com/PrizeWhipser/shortcat.tips](https://github.com/PrizeWhipser/shortcat.tips)
