Initial Morocco BO region classification pipeline demo

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/pages/page_005.png filter=lfs diff=lfs merge=lfs -text
+examples/pages/page_012.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,30 @@
 ---
-title: Morocco Bo Region Classification Demo
-emoji: 😻
-colorFrom: indigo
-colorTo: pink
+title: Morocco BO Region Classification
+emoji: 🏷️
+colorFrom: purple
+colorTo: blue
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+sdk_version: 5.49.1
 app_file: app.py
-pinned: false
+python_version: "3.11"
+startup_duration_timeout: 1h
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Morocco BO Region Classification Demo
+
+End-to-end demo for Moroccan Bulletin Officiel layout analysis:
+
+1. **Region proposal** — fine-tuned [PP-DocLayout-L](https://huggingface.co/AvoCahDoe/region-proposal-pp-doclayout-l-bo) detects layout boxes
+2. **OCR** — PP-OCRv3 line detection + [Latin recognizer](https://huggingface.co/AvoCahDoe/morocco-bo-ocr-latin-v3-finetuned) extracts words inside each box
+3. **Classification** — fine-tuned [LayoutLMv3](https://huggingface.co/AvoCahDoe/layoutlmv3-bo-segments) assigns one of 14 BO classes per region (ARTICLE, TITLE, TABLE, FOOTER, SOMMAIRE, etc.)
+
+Upload a full French BO page (PNG/JPG) and click **Detect & classify**.
+
+**Note:** First run downloads models (~300 MB total) and may take 1–3 minutes on CPU. Word boxes are approximated from line OCR (proportional split); best results on French BO pages similar to training data.
+
+## Links
+
+- **Proposal model:** [AvoCahDoe/region-proposal-pp-doclayout-l-bo](https://huggingface.co/AvoCahDoe/region-proposal-pp-doclayout-l-bo)
+- **Classification model:** [AvoCahDoe/layoutlmv3-bo-segments](https://huggingface.co/AvoCahDoe/layoutlmv3-bo-segments)
+- **OCR model:** [AvoCahDoe/morocco-bo-ocr-latin-v3-finetuned](https://huggingface.co/AvoCahDoe/morocco-bo-ocr-latin-v3-finetuned)

app.py

@@ -0,0 +1,520 @@
+from __future__ import annotations
+
+import os
+import tempfile
+
+os.environ.setdefault("FLAGS_use_mkldnn", "0")
+os.environ.setdefault("FLAGS_enable_pir_api", "0")
+os.environ.setdefault("PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK", "True")
+os.environ.setdefault("OMP_NUM_THREADS", "1")
+
+from pathlib import Path
+
+import cv2
+import gradio as gr
+import numpy as np
+import pandas as pd
+import torch
+import yaml
+from huggingface_hub import snapshot_download
+from PIL import Image, ImageDraw, ImageFont
+from transformers import LayoutLMv3ForSequenceClassification, LayoutLMv3Processor
+
+PROPOSAL_REPO = "AvoCahDoe/region-proposal-pp-doclayout-l-bo"
+PROPOSAL_MODEL_NAME = "PP-DocLayout-L"
+OCR_REPO = "AvoCahDoe/morocco-bo-ocr-latin-v3-finetuned"
+OCR_MODEL_NAME = "latin_PP-OCRv3_mobile_rec"
+CLASSIFIER_REPO = "AvoCahDoe/layoutlmv3-bo-segments"
+
+MAX_IMAGE_SIDE = 2400
+WORD_COVERAGE_THRESHOLD = 0.5
+CLASSIFY_BATCH_SIZE = 4
+
+PP_COLORS = {
+    "text": "#3B8BD4",
+    "paragraph_title": "#D85A30",
+    "doc_title": "#D85A30",
+    "header": "#888780",
+    "footer": "#6b7280",
+    "table": "#1D9E75",
+    "image": "#ec4899",
+    "reference": "#14b8a6",
+}
+
+BO_COLORS = {
+    "ARTICLE": "#3B8BD4",
+    "PREAMBLE": "#14b8a6",
+    "TITLE": "#D85A30",
+    "FOOTER": "#888780",
+    "TABLE": "#1D9E75",
+    "FIGURE": "#ec4899",
+    "ANNEXE_TITLE": "#f59e0b",
+    "ANNEXE_TEXT": "#3b82f6",
+    "SOMMAIRE": "#ef4444",
+    "CHAPTER_CONTENT": "#06b6d4",
+    "ANNEXE_LEVEL": "#8b5cf6",
+    "CHAPTER_TITLE": "#7F77DD",
+    "FORM": "#84cc16",
+    "SECTION": "#ec4899",
+}
+
+_proposal_infer_dir = None
+_ocr_infer_dir = None
+_layout_detector = None
+_text_detector = None
+_text_recognizer = None
+_classifier_processor = None
+_classifier_model = None
+
+
+def _hf_token() -> str | None:
+    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+
+
+def _get_proposal_infer_dir() -> Path:
+    global _proposal_infer_dir
+    if _proposal_infer_dir is None:
+        root = snapshot_download(PROPOSAL_REPO, allow_patterns=["inference/*"])
+        _proposal_infer_dir = Path(root) / "inference"
+    return _proposal_infer_dir
+
+
+def _get_ocr_infer_dir() -> Path:
+    global _ocr_infer_dir
+    if _ocr_infer_dir is None:
+        root = snapshot_download(OCR_REPO, allow_patterns=["inference/*"])
+        _ocr_infer_dir = Path(root) / "inference"
+        _ensure_ocr_config(_ocr_infer_dir)
+    return _ocr_infer_dir
+
+
+def _ensure_ocr_config(infer_dir: Path) -> None:
+    yml_path = infer_dir / "inference.yml"
+    if not yml_path.exists():
+        return
+    data = yaml.safe_load(yml_path.read_text(encoding="utf-8")) or {}
+    global_cfg = data.setdefault("Global", {})
+    if global_cfg.get("model_name") != OCR_MODEL_NAME:
+        global_cfg["model_name"] = OCR_MODEL_NAME
+        yml_path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+
+
+def get_layout_detector():
+    global _layout_detector
+    if _layout_detector is None:
+        from paddleocr import LayoutDetection
+
+        _layout_detector = LayoutDetection(
+            model_dir=str(_get_proposal_infer_dir()),
+            model_name=PROPOSAL_MODEL_NAME,
+            enable_mkldnn=False,
+        )
+    return _layout_detector
+
+
+def get_text_detector():
+    global _text_detector
+    if _text_detector is None:
+        from paddleocr import TextDetection
+
+        _text_detector = TextDetection(
+            model_name="PP-OCRv3_mobile_det",
+            enable_mkldnn=False,
+            limit_side_len=1920,
+        )
+    return _text_detector
+
+
+def get_text_recognizer():
+    global _text_recognizer
+    if _text_recognizer is None:
+        from paddleocr import TextRecognition
+
+        _text_recognizer = TextRecognition(
+            model_dir=str(_get_ocr_infer_dir()),
+            model_name=OCR_MODEL_NAME,
+            enable_mkldnn=False,
+        )
+    return _text_recognizer
+
+
+def get_classifier():
+    global _classifier_processor, _classifier_model
+    if _classifier_processor is None or _classifier_model is None:
+        token = _hf_token()
+        _classifier_processor = LayoutLMv3Processor.from_pretrained(
+            CLASSIFIER_REPO,
+            apply_ocr=False,
+            token=token,
+        )
+        _classifier_model = LayoutLMv3ForSequenceClassification.from_pretrained(
+            CLASSIFIER_REPO,
+            token=token,
+        )
+        _classifier_model.eval()
+    return _classifier_processor, _classifier_model
+
+
+def _image_path(image) -> str | None:
+    if image is None:
+        return None
+    return image if isinstance(image, str) else getattr(image, "name", str(image))
+
+
+def _font(size: int = 10):
+    for name in ("DejaVuSans.ttf", "arial.ttf"):
+        try:
+            return ImageFont.truetype(name, size)
+        except OSError:
+            continue
+    return ImageFont.load_default()
+
+
+def _maybe_resize(image_path: str) -> str:
+    img = Image.open(image_path).convert("RGB")
+    w, h = img.size
+    max_side = max(w, h)
+    if max_side <= MAX_IMAGE_SIDE:
+        return image_path
+    scale = MAX_IMAGE_SIDE / max_side
+    resized = img.resize((int(w * scale), int(h * scale)), Image.Resampling.LANCZOS)
+    out = Path(image_path).with_name(f"{Path(image_path).stem}_resized.png")
+    resized.save(out)
+    return str(out)
+
+
+def parse_proposal_boxes(result) -> list[dict]:
+    data = result.json if hasattr(result, "json") else {}
+    inner = data.get("res", data)
+    regions = []
+    for box in inner.get("boxes", []):
+        coord = box.get("coordinate", box.get("bbox", []))
+        if len(coord) < 4:
+            continue
+        regions.append({
+            "pp_label": str(box.get("label", "unknown")).lower(),
+            "proposal_score": float(box.get("score", 0.0)),
+            "x0": float(coord[0]),
+            "y0": float(coord[1]),
+            "x1": float(coord[2]),
+            "y1": float(coord[3]),
+        })
+    return regions
+
+
+def run_proposals(image_path: str, threshold: float) -> list[dict]:
+    output = get_layout_detector().predict(
+        image_path,
+        batch_size=1,
+        layout_nms=True,
+        threshold=float(threshold),
+    )
+    regions: list[dict] = []
+    for res in output:
+        regions.extend(parse_proposal_boxes(res))
+    regions.sort(key=lambda r: (r["y0"], r["x0"]))
+    return regions
+
+
+def _parse_rec_result(result) -> tuple[str, float]:
+    if not result:
+        return "", 0.0
+    item = result[0] if isinstance(result, list) else result
+    if isinstance(item, dict):
+        text = str(item.get("rec_text") or item.get("text") or "")
+        score = item.get("rec_score") or item.get("score")
+        return text, float(score) if score is not None else 1.0
+    return str(item), 1.0
+
+
+def line_to_words(text: str, x0: float, y0: float, x1: float, y1: float) -> list[dict]:
+    tokens = text.split()
+    if not tokens:
+        return []
+    line_w = max(1.0, x1 - x0)
+    char_counts = [max(1, len(t)) for t in tokens]
+    total_chars = sum(char_counts)
+    words = []
+    cursor = x0
+    for token, n_chars in zip(tokens, char_counts):
+        w = line_w * (n_chars / total_chars)
+        words.append({
+            "text": token,
+            "bbox_px": [cursor, y0, cursor + w, y1],
+        })
+        cursor += w
+    return words
+
+
+def extract_page_words(image_path: str) -> list[dict]:
+    img = cv2.imread(image_path)
+    if img is None:
+        return []
+
+    det_result = get_text_detector().predict(image_path)
+    if not det_result:
+        return []
+
+    item = det_result[0]
+    polys = item.get("dt_polys") or []
+    det_scores = item.get("dt_scores") or [1.0] * len(polys)
+    recognizer = get_text_recognizer()
+    all_words: list[dict] = []
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp = Path(tmpdir)
+        for i, poly in enumerate(polys):
+            if i < len(det_scores) and float(det_scores[i]) < 0.5:
+                continue
+            arr = np.asarray(poly)
+            if arr.size == 0:
+                continue
+            x0, y0 = float(arr[:, 0].min()), float(arr[:, 1].min())
+            x1, y1 = float(arr[:, 0].max()), float(arr[:, 1].max())
+            crop = img[int(y0) : int(y1), int(x0) : int(x1)]
+            if crop.size == 0 or crop.shape[0] < 3 or crop.shape[1] < 3:
+                continue
+            crop_path = tmp / f"line_{i}.png"
+            cv2.imwrite(str(crop_path), crop)
+            text, score = _parse_rec_result(recognizer.predict(str(crop_path)))
+            text = text.strip()
+            if not text or score < 0.5:
+                continue
+            all_words.extend(line_to_words(text, x0, y0, x1, y1))
+
+    return all_words
+
+
+def word_region_coverage(word_bbox: list[float], region_bbox: list[float]) -> float:
+    wx0, wy0, wx1, wy1 = word_bbox
+    rx0, ry0, rx1, ry1 = region_bbox
+    ix0, iy0 = max(wx0, rx0), max(wy0, ry0)
+    ix1, iy1 = min(wx1, rx1), min(wy1, ry1)
+    inter = max(0.0, ix1 - ix0) * max(0.0, iy1 - iy0)
+    word_area = max(1.0, (wx1 - wx0) * (wy1 - wy0))
+    return inter / word_area
+
+
+def words_in_region(
+    words: list[dict],
+    region_bbox: list[float],
+    threshold: float = WORD_COVERAGE_THRESHOLD,
+) -> list[dict]:
+    inside = []
+    for w in words:
+        if word_region_coverage(w["bbox_px"], region_bbox) >= threshold:
+            inside.append(w)
+    inside.sort(key=lambda w: (w["bbox_px"][1], w["bbox_px"][0]))
+    return inside
+
+
+def normalize_bbox(bbox_px: list[float], width: int, height: int) -> list[int]:
+    x0, y0, x1, y1 = bbox_px
+    return [
+        int(x0 / width * 1000),
+        int(y0 / height * 1000),
+        int(x1 / width * 1000),
+        int(y1 / height * 1000),
+    ]
+
+
+def build_segments(
+    proposals: list[dict],
+    words: list[dict],
+    image_path: str,
+) -> tuple[list[dict], int]:
+    img = Image.open(image_path)
+    w, h = img.size
+    segments: list[dict] = []
+    skipped = 0
+    for reg in proposals:
+        bbox = [reg["x0"], reg["y0"], reg["x1"], reg["y1"]]
+        inside = words_in_region(words, bbox)
+        if not inside:
+            skipped += 1
+            continue
+        segments.append({
+            "proposal_score": reg["proposal_score"],
+            "pp_label": reg["pp_label"],
+            "x0": reg["x0"],
+            "y0": reg["y0"],
+            "x1": reg["x1"],
+            "y1": reg["y1"],
+            "words": [x["text"] for x in inside],
+            "word_boxes_norm": [normalize_bbox(x["bbox_px"], w, h) for x in inside],
+            "word_count": len(inside),
+        })
+    return segments, skipped
+
+
+@torch.no_grad()
+def classify_segments(segments: list[dict], image_path: str) -> list[dict]:
+    if not segments:
+        return []
+    processor, model = get_classifier()
+    id2label = model.config.id2label
+    results: list[dict] = []
+
+    for i in range(0, len(segments), CLASSIFY_BATCH_SIZE):
+        batch = segments[i : i + CLASSIFY_BATCH_SIZE]
+        images = [Image.open(image_path).convert("RGB") for _ in batch]
+        enc = processor(
+            images,
+            [s["words"] for s in batch],
+            boxes=[s["word_boxes_norm"] for s in batch],
+            truncation=True,
+            padding=True,
+            max_length=512,
+            return_tensors="pt",
+        )
+        outputs = model(**enc)
+        probs = torch.softmax(outputs.logits, dim=-1).cpu().numpy()
+        for seg, prob_row in zip(batch, probs):
+            pred_id = int(prob_row.argmax())
+            label = id2label[pred_id] if isinstance(id2label, dict) else id2label[str(pred_id)]
+            results.append({
+                **seg,
+                "bo_class": label,
+                "confidence": round(float(prob_row[pred_id]), 4),
+            })
+    return results
+
+
+def _scale_preview(img: Image.Image, max_w: int = 1200) -> Image.Image:
+    if img.width <= max_w:
+        return img
+    scale = max_w / img.width
+    return img.resize((max_w, int(img.height * scale)), Image.Resampling.LANCZOS)
+
+
+def draw_proposal_overlay(img: Image.Image, proposals: list[dict]) -> Image.Image:
+    out = img.copy()
+    draw = ImageDraw.Draw(out)
+    font = _font(9)
+    for reg in proposals:
+        label = reg.get("pp_label", "?")
+        color = PP_COLORS.get(label, "#999999")
+        x0, y0, x1, y1 = int(reg["x0"]), int(reg["y0"]), int(reg["x1"]), int(reg["y1"])
+        draw.rectangle([x0, y0, x1, y1], outline=color, width=2)
+        draw.text(
+            (x0 + 2, max(0, y0 - 12)),
+            f"{label} {reg.get('proposal_score', 0):.2f}",
+            fill=color,
+            font=font,
+        )
+    return _scale_preview(out)
+
+
+def draw_classification_overlay(img: Image.Image, classified: list[dict]) -> Image.Image:
+    out = img.copy()
+    draw = ImageDraw.Draw(out)
+    font = _font(9)
+    used: set[str] = set()
+    for reg in classified:
+        label = reg.get("bo_class", "?")
+        used.add(label)
+        color = BO_COLORS.get(label, "#999999")
+        x0, y0, x1, y1 = int(reg["x0"]), int(reg["y0"]), int(reg["x1"]), int(reg["y1"])
+        draw.rectangle([x0, y0, x1, y1], outline=color, width=3)
+        draw.text(
+            (x0 + 2, max(0, y0 - 14)),
+            f"{label} {reg.get('confidence', 0):.2f}",
+            fill=color,
+            font=font,
+        )
+
+    legend_w = 220
+    canvas = Image.new("RGB", (out.width + legend_w, out.height), "#fafafa")
+    canvas.paste(out, (0, 0))
+    ld = ImageDraw.Draw(canvas)
+    x0 = out.width + 10
+    ld.text((x0, 8), "BO class (LayoutLMv3)", fill="#111", font=_font(11))
+    y = 32
+    for cls in sorted(used):
+        c = BO_COLORS.get(cls, "#999")
+        ld.rectangle([x0, y, x0 + 14, y + 12], outline=c, fill=c)
+        ld.text((x0 + 20, y), cls, fill="#222", font=_font(9))
+        y += 16
+    return _scale_preview(canvas)
+
+
+def detect_and_classify(
+    image,
+    threshold: float,
+) -> tuple[Image.Image | None, Image.Image | None, pd.DataFrame, str, str]:
+    empty_df = pd.DataFrame(
+        columns=["bo_class", "confidence", "proposal_score", "word_count", "x0", "y0", "x1", "y1"]
+    )
+    image_path = _image_path(image)
+    if not image_path:
+        return None, None, empty_df, "0", "0 skipped (no words)"
+
+    image_path = _maybe_resize(image_path)
+    base_img = Image.open(image_path).convert("RGB")
+
+    proposals = run_proposals(image_path, threshold)
+    proposal_preview = draw_proposal_overlay(base_img, proposals) if proposals else _scale_preview(base_img)
+
+    if not proposals:
+        return _scale_preview(base_img), proposal_preview, empty_df, "0", "0 skipped (no words)"
+
+    words = extract_page_words(image_path)
+    segments, skipped = build_segments(proposals, words, image_path)
+    classified = classify_segments(segments, image_path)
+
+    if not classified:
+        return _scale_preview(base_img), proposal_preview, empty_df, "0", f"{skipped} skipped (no words)"
+
+    class_preview = draw_classification_overlay(base_img, classified)
+    df = pd.DataFrame(classified)[
+        ["bo_class", "confidence", "proposal_score", "word_count", "x0", "y0", "x1", "y1"]
+    ]
+    skip_msg = f"{skipped} skipped (no words)" if skipped else "0 skipped"
+    return class_preview, proposal_preview, df, str(len(classified)), skip_msg
+
+
+DESCRIPTION = """
+Upload a **full French Bulletin Officiel page** (PNG/JPG) to run the full pipeline:
+
+1. **Region proposal** — fine-tuned PP-DocLayout-L finds layout boxes
+2. **OCR** — Latin PP-OCRv3 extracts words inside each box
+3. **Classification** — LayoutLMv3 assigns one of 14 BO classes per region
+
+**Note:** First run downloads models (~300 MB) and may take 1–3 minutes on CPU.
+"""
+
+EXAMPLES = [
+    ["examples/pages/page_005.png", 0.5],
+    ["examples/pages/page_012.png", 0.5],
+]
+
+with gr.Blocks(title="Morocco BO Region Classification") as demo:
+    gr.Markdown("# Morocco BO Region Classification")
+    gr.Markdown(DESCRIPTION)
+    with gr.Row():
+        with gr.Column():
+            page_image = gr.Image(type="filepath", label="Page image")
+            threshold = gr.Slider(0.1, 0.95, value=0.5, step=0.05, label="Proposal threshold")
+            run_btn = gr.Button("Detect & classify", variant="primary")
+        with gr.Column():
+            class_preview = gr.Image(label="BO classification overlay", type="pil")
+            proposal_preview = gr.Image(label="Proposal overlay (PP-DocLayout-L)", type="pil")
+            count_out = gr.Textbox(label="Regions classified", lines=1)
+            skip_out = gr.Textbox(label="Skipped regions", lines=1)
+            table_out = gr.Dataframe(
+                label="Classification results",
+                headers=["bo_class", "confidence", "proposal_score", "word_count", "x0", "y0", "x1", "y1"],
+                interactive=False,
+            )
+    run_btn.click(
+        detect_and_classify,
+        inputs=[page_image, threshold],
+        outputs=[class_preview, proposal_preview, table_out, count_out, skip_out],
+    )
+    gr.Examples(examples=EXAMPLES, inputs=[page_image, threshold])
+
+demo.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    ssr_mode=False,
+)

requirements.txt

@@ -0,0 +1,9 @@
+paddlepaddle==3.2.2
+paddleocr>=2.10.0
+transformers>=4.40.0
+accelerate>=0.30.0
+Pillow
+pandas
+numpy
+opencv-python-headless
+PyYAML