Metadata-Version: 2.4
Name: mk8dx_table_reader
Version: 0.6.5
Summary: A package to extract player names and scores from MK8DX tables using YOLO and ONNX-based EasyOCR.
Home-page: https://github.com/mk8dx-table-reader/mk8dx-table-reader
Author: Julien ABADIE
Author-email: julien.abadie@etu.uca.fr
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pillow
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: setuptools
Requires-Dist: onnxruntime
Requires-Dist: torchfree-ocr
Requires-Dist: ultralytics
Provides-Extra: pytorch-ocr
Requires-Dist: easyocr; extra == "pytorch-ocr"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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