efootball-ocr 1.0.0

OCR-based match result reader for eFootball screenshots — extracts winner, score, usernames and phase.

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

brew install tesseract

Ubuntu / Debian

sudo apt-get install tesseract-ocr

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

2. Install Python packages

pip install -r efootball_ocr/requirements.txt

---

Quick start

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

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

for r in results:
    print(r)

Force a specific screen type

# 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

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.