An OCR Pipeline for Text That Isn't Latin Script
pytesseract.image_to_string() is one line. Getting clean Arabic verse out of a 1000px scan takes upscaling, two competing page-segmentation modes, and a scoring function that can tell a good transcript from a confident wrong one.
Tesseract will happily return text for an image that has almost nothing legible left in it. That's the core difficulty in core/tasks.py and core/ocr_tool.py: OCR doesn't fail loudly. It fails by returning plausible garbage, and for Arabic script, plausible garbage looks a lot like real words to anyone who doesn't read the language fluently.
Five sources feed one pipeline: upscale, sharpen, OCR twice, score, keep the better pass.
Preparing the image before OCR sees it
The scans in this library run around 1000px on the long edge — thin for Tesseract, which does noticeably better on higher-resolution input. Every scan goes through the same preparation before recognition:
def _prepare_scan(image):
"""Upscale and sharpen a scan so Tesseract has more to work with."""
grey = ImageOps.grayscale(image.convert('RGB'))
larger = grey.resize(
(grey.width * SCAN_OCR_UPSCALE, grey.height * SCAN_OCR_UPSCALE), Image.LANCZOS)
return larger.filter(SCAN_OCR_SHARPEN)SCAN_OCR_UPSCALE = 2, a Lanczos resize, then an UnsharpMask(radius=2, percent=140). Measured against text the source also published as plain copy, this lifted recovered Arabic by roughly half again — a comment left in the code rather than a number I'm asserting from memory, because it was measured once and is worth keeping honest.
Two segmentation modes, because neither wins outright
Tesseract's page-segmentation mode (--psm) matters more for these layouts than for ordinary prose, because the pages are bilingual — Arabic verse next to a transliteration or a footnote — and column layout varies source to source. The pipeline tries both --psm 6 (one uniform block) and --psm 4 (columns of text) and keeps whichever scores better:
OCR_CONFIGS = ('--psm 6', '--psm 4')
OCR_LANGS = 'ara+eng'"Scores better" is not a confidence number Tesseract hands back — it's a property of the text itself, described next.
Telling a good transcript from a shattered one
Arabic words run three to six letters. If a transcript comes back mostly single-letter tokens, or full of stray tatweel runs, something upstream broke — usually a layout Tesseract misread as one big justified line. That's measured directly:
def _text_shatter_score(text):
"""Fraction of Arabic tokens that are a single letter, plus the tatweel ratio."""
tokens = [t for t in re.split(r'\s+', text or '') if ARABIC_RE.search(t)]
if not tokens:
return 1.0, 1.0, 0
singles = sum(1 for t in tokens if len(t.strip('ـ')) <= 1)
tatweel = (text.count('ـ') / len(text)) if text else 1.0
return singles / len(tokens), tatweel, len(tokens)And acceptance is stricter than "did OCR produce something." A candidate transcript only replaces the stored text if it recovers at least 60% of the original's Arabic letters (OCR_MIN_COVERAGE = 0.6) — counted in letters, not words, because shattering splits one word into several tokens and a token-level comparison would flatter an OCR mode that simply recognized less — and stays under 25% Latin/digit noise (OCR_MAX_NOISE = 0.25):
def _ocr_is_improvement(transcript, original):
if not transcript:
return False
original_single, _, _ = _text_shatter_score(original)
single, _, tokens = _text_shatter_score(transcript)
if tokens < 20:
return False
original_letters = _arabic_len(original)
if original_letters and _arabic_len(transcript) < OCR_MIN_COVERAGE * original_letters:
return False
if _ocr_noise_ratio(transcript) > OCR_MAX_NOISE:
return False
return single < original_singleThe rule reads almost defensively, and it should: an OCR pass that "improves" a text by discarding the hard parts of it is worse than doing nothing, and it will happily do that if you let a single metric decide.
Cleaning what survives
Even an accepted transcript carries Latin/digit debris around the Arabic — page numbers, watermark text, viewer chrome. A line only counts as verse if at least 35% of its characters are Arabic (SCAN_LINE_ARABIC_SHARE = 0.35) and it has at least two Arabic characters; everything else is dropped.
The same pipeline is exposed to editors directly, through an admin OCR bench (core/ocr_tool.py) that accepts a PDF or screenshot upload and runs identical preprocessing, so what an editor sees when hand-correcting a record matches what the automated crawl already tried. That consistency matters more than it sounds: without it, an editor "fixing" a record could introduce a discrepancy the automated pass would have avoided on its own.
Series: Qasida App.