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.

An OCR Pipeline for Text That Isn't Latin Script

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.

The OCR pipeline, in the order a scan actually travels
The OCR pipeline, in the order a scan actually travels

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_single

The 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.