"""Chakkhu ចក្ខុ demo + API: Khmer + English OCR. Upload a photo (street sign, shop front, poster), a page of printed text, or one text line. For photos a text detector (scene.py) finds the text first; for pages the line finder (lines.py) cuts them into lines. Chakkhu reads each line with both heads and gives every line a confidence (how sure it is). "auto" tries both and keeps the reading Chakkhu is surer about. Two models to choose from: pytorch Chakkhu-OCR-Khmer (PyTorch): best quality, fastest with a GPU onnx Chakkhu-OCR-Khmer-ONNX (int8, ONNX Runtime only): small, made for CPUs, phones and apps API (no account needed): from gradio_client import Client, handle_file c = Client("muyleanging/Chakkhu-OCR-Demo") c.predict(handle_file("photo.jpg"), "auto", "pytorch", api_name="/read") # mode: auto/photo/page/line · or "onnx" → {"text": "...", "lines": [{"text", "confidence", "box": [x, y, w, h]}], "ms": 812, "model": "pytorch"} """ import os import sys import time import gradio as gr import numpy as np import torch from PIL import Image, ImageDraw, ImageOps from huggingface_hub import snapshot_download from chakkhu import load, read from lines import find_lines from scene import photo_rows, vote torch.set_num_threads(2) # local folders can be given for a test before publishing (CHAKKHU_MODEL_DIR, CHAKKHU_ONNX_DIR) MODEL, TOK = load(os.environ.get("CHAKKHU_MODEL_DIR", "muyleanging/Chakkhu-OCR-Khmer")) # the ONNX version: only the int8 graphs + its small reader (numpy + onnxruntime) ONNX_DIR = os.environ.get("CHAKKHU_ONNX_DIR") or snapshot_download("muyleanging/Chakkhu-OCR-Khmer-ONNX", allow_patterns=["*.int8.onnx", "*.py", "*.json"]) sys.path.insert(0, ONNX_DIR) from chakkhu_onnx import Chakkhu as ChakkhuONNX # noqa: E402 ONNX = ChakkhuONNX(ONNX_DIR, int8=True, threads=2) MODELS = {"pytorch": "Chakkhu PyTorch (best quality)", "onnx": "Chakkhu ONNX int8 (small, for CPU)"} MAX_SIDE = 2400 def prepare(img): img = ImageOps.exif_transpose(img).convert("RGB") if max(img.size) > MAX_SIDE: img.thumbnail((MAX_SIDE, MAX_SIDE)) return img def rows(boxes) -> int: """How many text rows the boxes make: boxes that overlap vertically by half their height are one row (the line finder can cut one line into pieces at a wide gap between words).""" out = [] for x, y, w, h in sorted(boxes, key=lambda b: b[1] + b[3] / 2): for r in out: if min(y + h, r[1]) - max(y, r[0]) > 0.5 * min(h, r[1] - r[0]): r[0], r[1] = min(r[0], y), max(r[1], y + h) break else: out.append([y, y + h]) return len(out) def join_rows(boxes): """Join the line finder's pieces that belong to one text row: pieces side by side (signs often have big gaps between words) and small subscript / vowel pieces just above or below a row. Returns one box per row.""" rows = [] for x, y, w, h in sorted(boxes, key=lambda b: b[3], reverse=True): # tall pieces first cy = y + h / 2 for r in rows: rx0, ry0, rx1, ry1 = r rh = ry1 - ry0 same = min(y + h, ry1) - max(y, ry0) > 0.5 * min(h, rh) and max(x - rx1, rx0 - (x + w)) < 8 * rh mark = h < 0.6 * rh and w < 1.5 * rh and ry0 - 0.3 * rh < cy < ry1 + 0.3 * rh and rx0 <= x and x + w <= rx1 # narrow, close if same or mark: r[:] = [min(rx0, x), min(ry0, y), max(rx1, x + w), max(ry1, y + h)] break else: rows.append([x, y, x + w, y + h]) return [(x0, y0, x1 - x0, y1 - y0) for x0, y0, x1, y1 in sorted(rows, key=lambda r: (r[1] + r[3]) / 2)] def read_crops(crops, model): if not crops: return [] return ONNX.read(crops, confidence=True) if model == "onnx" else read(MODEL, TOK, crops, confidence=True) def read_boxes(img, boxes, model, as_page): crops = [img.crop((x, y, x + w, y + h)) for x, y, w, h in boxes] got = read_crops(crops, model) # on a page, drop tiny unsure bits (specks, lines cut by the finder); one line is always shown return [{"text": tx, "confidence": c, "box": [int(v) for v in b]} for (tx, c), b in zip(got, boxes) if tx.strip() and not (as_page and len(tx.strip()) <= 2 and c < 0.5)] def sure(lines) -> float: """How sure Chakkhu is about a reading: confidence weighted by text length (0 if nothing was read).""" n = sum(len(l["text"]) for l in lines) return sum(l["confidence"] * len(l["text"]) for l in lines) / n if n else 0.0 def read_photo(img, model): """Photo mode: find the text with the detector, cut every row out several ways, keep the surest reading.""" rows, cands = photo_rows(img) got = read_crops([c for cs in cands for c, _ in cs], model) lines, k = [], 0 for cs in cands: g = got[k:k + len(cs)] k += len(cs) if not g: continue tx, c = vote(g) # word by word across all crops of this row j = max(range(len(g)), key=lambda i: g[i][1]) poly = cs[j][1] xs, ys = [p[0] for p in poly], [p[1] for p in poly] if tx.strip() and not (len(tx.strip()) <= 2 and c < 0.6): lines.append({"text": tx, "confidence": c, "box": [int(min(xs)), int(min(ys)), int(max(xs) - min(xs)), int(max(ys) - min(ys))], "poly": [[round(x), round(y)] for x, y in poly]}) return lines def run(img: Image.Image, mode: str, model: str = "pytorch") -> dict: """Read a photo, a page or one line. "auto": read it as a photo (text detector) and as a page / line, keep the reading Chakkhu is surer about. Page / line: when the picture could be either (the line finder sees several rows, but a line crop can also show bits of the lines around it), read it both ways and keep the surer reading.""" img = prepare(img) t = time.time() if mode in ("photo", "auto"): photo = read_photo(img, model) if mode == "photo" or (photo and sure(photo) >= 0.8): ms = round(1000 * (time.time() - t)) return {"text": "\n".join(l["text"] for l in photo), "lines": photo, "ms": ms, "model": model, "note": "", "how": "photo"} other = run(img, "page", model) if photo and sure(photo) >= sure(other["lines"]): other.update(text="\n".join(l["text"] for l in photo), lines=photo, how="photo") other["ms"] = round(1000 * (time.time() - t)) return other whole = [(0, 0, img.width, img.height)] found = find_lines(np.asarray(img)) if img.width / max(1, img.height) <= 8 or mode == "line" else [] found = join_rows(found) n, note = rows(found), "" if n < 2: # one row of text (the finder can cut a line into pieces): read the whole picture lines = read_boxes(img, whole, model, as_page=False) else: page = read_boxes(img, found, model, as_page=True) if mode == "page" and sure(page) >= 0.85: lines = page else: line = read_boxes(img, whole, model, as_page=False) if mode == "line": lines = page if sure(page) > sure(line) + 0.15 else line if lines is page: note = f"found {n} lines, so it was read as a page" else: lines = line if sure(line) > sure(page) + 0.1 else page ms = round(1000 * (time.time() - t)) return {"text": "\n".join(l["text"] for l in lines), "lines": lines, "ms": ms, "model": model, "note": note, "how": "line" if len(lines) == 1 and lines[0]["box"][:2] == [0, 0] else "page"} def read_api(image: Image.Image, mode: str = "page", model: str = "pytorch") -> dict: """OCR API. mode = "auto" (photo or page, whichever reads surer), "photo" (find the text in a photo first), "page" (find the lines first) or "line" (the picture is one text line). model = "pytorch" (Chakkhu-OCR-Khmer, best quality) or "onnx" (Chakkhu-OCR-Khmer-ONNX, int8). Returns {"text", "lines": [{"text", "confidence" (0–1), "box": [x, y, w, h]}], "ms", "model"} (photo lines also have "poly": the four corners of a tilted line).""" model = "onnx" if str(model).lower().startswith("onnx") else "pytorch" if image is None: return {"text": "", "lines": [], "ms": 0, "model": model} if isinstance(image, dict): # the API hands over a file: {"path": ..., "url": ...} image = Image.open(image.get("path") or image["name"]) elif isinstance(image, str): image = Image.open(image) mode = str(mode).lower() mode = mode if mode in ("auto", "photo", "page", "line") else "page" return run(image, mode, model) def draw(img, lines): """The picture with a box around every line it read: green = sure, orange = check it, red = unsure.""" img = prepare(img).copy() d = ImageDraw.Draw(img) w = max(2, round(max(img.size) / 350)) for l in lines: col = (22, 163, 74) if l["confidence"] >= 0.9 else (234, 138, 0) if l["confidence"] >= 0.6 else (220, 38, 38) if "poly" in l: d.polygon([tuple(p) for p in l["poly"]], outline=col, width=w) else: x, y, bw, bh = l["box"] d.rectangle((x, y, x + bw, y + bh), outline=col, width=w) return img MODES = {"Auto (photo or page)": "auto", "Photo / street sign": "photo", "Page / several lines": "page", "One line": "line"} def ui(img, mode, model): if img is None: return "", "", None, None key = "onnx" if model == MODELS["onnx"] else "pytorch" r = run(img, MODES.get(mode, "auto"), key) unsure = [l for l in r["lines"] if l["confidence"] < 0.9] if not r["lines"]: return "", ("Nothing could be read. Check that the picture shows printed Khmer or English text; " "for one cropped text line choose **One line**."), None, None how = {"photo": "read as a photo (text found first)", "page": "read as a page", "line": "read as one line"}.get(r.get("how"), "") info = (f"⚠️ {r['note']} · " if r["note"] else "") + f"{len(r['lines'])} line(s) · {how} · {r['ms']} ms on CPU · {MODELS[key]}" + (f" · ⚠️ {len(unsure)} unsure (confidence < 0.9)" if unsure else " · all sure ✅") table = [[i + 1, l["text"], l["confidence"]] for i, l in enumerate(r["lines"])] return r["text"], info, table, draw(img, r["lines"]) P, O = MODELS["pytorch"], MODELS["onnx"] AUTO, PHOTO, PAGE, LINE = "Auto (photo or page)", "Photo / street sign", "Page / several lines", "One line" # real pictures from the KHOB benchmark (MIT): sign boards and hard signs first, then a document page EXAMPLES = [["examples/photo_red_cross.jpg", AUTO, P], # whole street photo: the text is found first ["examples/photo_loan_sign.jpg", AUTO, O], # tilted sign on a wall ["examples/photo_hanoi_corner.jpg", AUTO, P], # hanging shop sign ["examples/photo_fire_hose.jpg", AUTO, O], ["examples/photo_restaurant.jpg", AUTO, P], # small sign far away ["examples/night_quote.jpg", PAGE, P], # night photo, 3 lines ["examples/sign_mixed.jpg", PAGE, O], # Khmer + English ["examples/sign_no_parking.jpg", PAGE, P], # "no parking / entrance" ["examples/sign_wc.jpg", PAGE, O], ["examples/sign_street_400.jpg", LINE, P], # street name with Khmer digits ["examples/night_bold.jpg", LINE, O], # bold two-colour letters at night ["examples/night_decorative.jpg", LINE, P], # decorative font at night ["examples/label_bicarbonate.jpg", LINE, O], # product label, Khmer + English ["examples/sign_security_camera.jpg", LINE, P], ["examples/night_pagoda.jpg", PAGE, O], # small night sign ["examples/notice_lights.jpg", PAGE, P], ["examples/sign_phone.jpg", PAGE, O], # hard: Chakkhu says it is unsure (confidence 0.58) ["examples/block.png", PAGE, P]] # a printed decree, 4 lines with gr.Blocks(title="Chakkhu ចក្ខុ: Khmer OCR") as demo: gr.Markdown( "# Chakkhu ចក្ខុ: Khmer + English OCR\n" "Upload a **photo** (street sign, shop front, poster), a **page** of printed Khmer or one **text line**: in **Auto** mode Chakkhu finds the text by itself. Pick a model: " "[Chakkhu-OCR-Khmer](https://huggingface.co/muyleanging/Chakkhu-OCR-Khmer) (PyTorch, best quality, fastest with a GPU) or " "[Chakkhu-OCR-Khmer-ONNX](https://huggingface.co/muyleanging/Chakkhu-OCR-Khmer-ONNX) (int8, small, for CPUs and apps). 18.6M parameters, " "**4.06% character errors** on the full KHOB benchmark (4,018 real lines; Netra-OCR 5.87%). " "Every line gets a **confidence**: Chakkhu tells you when it is unsure. By Ing Muyleang · " "🌐 [Website: results, how it works, code](https://muyleanging.github.io/chakkhu-web/) · " "📚 [Training data](https://huggingface.co/datasets/muyleanging/Chakkhu-OCR-Khmer-Data)") with gr.Row(): with gr.Column(): image = gr.Image(type="pil", label="Picture") mode = gr.Radio(list(MODES), value=AUTO, label="Picture holds") model = gr.Radio([P, O], value=P, label="Model") btn = gr.Button("Read", variant="primary") with gr.Column(): text = gr.Textbox(label="Text", lines=8, buttons=["copy"]) info = gr.Markdown() table = gr.Dataframe(headers=["#", "line", "confidence"], label="Lines", wrap=True) found = gr.Image(type="pil", label="Found text (green = sure, orange = check, red = unsure)") btn.click(ui, [image, mode, model], [text, info, table, found], api_visibility="private") gr.Examples(EXAMPLES, [image, mode, model], [text, info, table, found], fn=ui, cache_examples=False, examples_per_page=18, label="Examples: whole street photos, signs and pages from the KHOB benchmark (click one)") gr.api(read_api, api_name="read") gr.Markdown( "**API** (free, no account):\n```python\nfrom gradio_client import Client, handle_file\n" "c = Client(\"muyleanging/Chakkhu-OCR-Demo\")\n" "c.predict(handle_file(\"photo.jpg\"), \"auto\", \"pytorch\", api_name=\"/read\") # \"photo\" · \"page\" · \"line\" · \"onnx\"\n" "# → {'text': ..., 'lines': [{'text', 'confidence', 'box': [x, y, w, h]}], 'ms': ..., 'model': ...}\n```\n" "Works best on printed text: documents, old decrees, scans, screenshots, chat pictures, and now better on " "street signs and English. Weaker on night photos and curved or vertical text. Pages with several columns: " "crop one column first. This free demo runs on a CPU, so both models run on the CPU here.") demo.launch()