Metadata-Version: 2.4
Name: efootball-ocr
Version: 1.0.0
Summary: OCR-based match result reader for eFootball screenshots — extracts winner, score, usernames and phase.
Author: Hazzi
License: MIT
Project-URL: Homepage, https://github.com/hazzi/efootball-ocr
Project-URL: Repository, https://github.com/hazzi/efootball-ocr
Keywords: efootball,ocr,football,gaming,screenshot,tesseract
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: Pillow>=10.0.0
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy>=1.24.0
Dynamic: license-file

# efootball_ocr

A Python module that reads **eFootball** match result screenshots and extracts:

| Field | Example |
|---|---|
| Home username | `hazziboss` |
| Away username | `MEMPHISDPAY` |
| Home team name | `Hazzi Fc` |
| Away team name | `MEMPHISDEPAY` |
| Score line | `4 – 0` |
| Winner | `hazziboss` |
| Match phase | `Full Time` / `After Extra Time` |
| Match date | `2026-04-28 10:18` |

---

## Supported screenshot types

### 1. Result screen  (dark background)
The post-match screen that shows the final score in large yellow text with
the two club badges and usernames beneath them.

```
[Left badge]    Full Time    [Right badge]
[Left badge]    0  –  6      [Right badge]
 hotboykolz                   Hazzi Fc
```

### 2. Stats screen  (yellow/blue chevron background)
The in-game statistics panel that shows the score in its header row
and lists possession, shots, passes, etc.

Standard:
```
HUNTER  0  =  0  Hazzi Fc
              Full Time
Possession     35%  |  65%
...
```

Penalty shootout variant — an extra `X PK Y` line appears between the score and the phase label:
```
HUNTER  0  =  0  Hazzi Fc
              4 PK 3
              Full Time
Possession     35%  |  65%
...
```

### 3. Match history card  (compact dark banner)
The compact match history card shown in match lists / replays.

```
          28/04/2026 10:18
[badge]  Hazzi Fc  4 - 0  MEMPHISDEPAY  [badge]
          hazziboss     MEMPHISDPAY
```

---

## Installation

### 1. Install Tesseract-OCR (system dependency)

**macOS**
```bash
brew install tesseract
```

**Ubuntu / Debian**
```bash
sudo apt-get install tesseract-ocr
```

**Windows**
Download the installer from https://github.com/UB-Mannheim/tesseract/wiki

### 2. Install Python packages

```bash
pip install -r efootball_ocr/requirements.txt
```

---

## Quick start

```python
from efootball_ocr import EFootballResultReader

reader = EFootballResultReader()

# Works with all three screenshot types automatically
result = reader.read("screenshot.png")

print(result.winner)        # "hazziboss"
print(result.score_line)    # "4 – 0"
print(result.home_username) # "hazziboss"
print(result.away_username) # "MEMPHISDPAY"
print(result.match_date)    # "2026-04-28 10:18"  (card format only)
print(result)               # full one-line summary
```

### Process multiple screenshots at once

```python
paths = ["match1.png", "match2.png", "match3.png"]
results = reader.read_batch(paths)

for r in results:
    print(r)
```

### Force a specific screen type

```python
# Skip auto-detection
reader = EFootballResultReader(force_screen_type="card")
result = reader.read("history_card.png")
```

---

## MatchResult fields

| Field | Type | Description |
|---|---|---|
| `home_username` | `str` | Home player's account/login name (smaller text) |
| `away_username` | `str` | Away player's account/login name (smaller text) |
| `home_team` | `str` | Home club display name (larger bold text) |
| `away_team` | `str` | Away club display name (larger bold text) |
| `home_score` | `int` | Regular / AET goals scored by home (`-1` if undetected) |
| `away_score` | `int` | Regular / AET goals scored by away (`-1` if undetected) |
| `home_pen_score` | `int` | Penalty shootout goals by home (`-1` if no penalties) |
| `away_pen_score` | `int` | Penalty shootout goals by away (`-1` if no penalties) |
| `winner` | `str \| None` | Winning username (uses penalty score if regular scores tied), or `None` for a draw |
| `score_line` | `str` | Human-readable score, e.g. `"0 – 0  (PK 4 – 3)"` when penalties |
| `penalty_score_line` | `str` | Just the penalty score `"4 – 3"`, or `""` if no penalties |
| `phase` | `str` | `"Full Time"`, `"After Extra Time"`, `"Penalties"`, or `"Unknown"` |
| `match_date` | `str` | ISO date string `"YYYY-MM-DD HH:MM"` when present (card format) |
| `screen_type` | `str` | `"result"`, `"stats"`, `"card"`, or `"Unknown"` |
| `confidence` | `float` | 0–1 estimate of parse quality |
| `raw_text` | `str` | Full OCR dump — useful for debugging |

---

## Auto-detection logic

| Condition | Detected type |
|---|---|
| Image width / height > 2.5  (wide banner) | `card` |
| Yellow dominates top third of image | `stats` |
| Dark background, no dominant yellow | `result` |
| None of the above | tries all three, picks highest confidence |

---

## Demo

```bash
python efootball_ocr/demo.py
```

Expected output:

```
=== Post-match result screen  (IMG_3276) ===
  Screen type   : result
  Phase         : Full Time
  Home team     : hotboykolz
  Home username : hotboykolz
  Away team     : Hazzi Fc
  Away username : Hazzi Fc
  Score         : 0 – 6
  Winner        : Hazzi Fc
  Confidence    : 100%

=== Match history card  (image_1777750058365) ===
  Screen type   : card
  Phase         : Full Time
  Date          : 2026-04-28 10:18
  Home team     : Hazzi Fc
  Home username : hazziboss
  Away team     : MEMPHISDEPAY
  Away username : MEMPHISDPAY
  Score         : 4 – 0
  Winner        : hazziboss
  Confidence    : 100%
```

---

## Tips for best accuracy

- Use **full-resolution** screenshots — don't crop or resize before passing in.
- If `result.confidence` is below 0.75, check `result.raw_text` to see what Tesseract actually read.
- For non-Latin usernames, install the matching Tesseract language pack.
- The card parser detects the format by aspect ratio (width/height > 2.5) — if your card is cropped square, pass `force_screen_type="card"` explicitly.
