Bin-Amer/hieroglyph-ocr-models

Hieroglyph OCR Models Hub — YOLO26n + TrOCR + MobileNetV3 (171 Gardiner Classes)

مستودع نماذج التعرّف الضوئي على الرموز الهيروغليفية المصرية وأكواد جاردينر

يحتوي هذا المستودع على الأوزان المدربة (Model Weights) الخاصة بمشروع Hieroglyph OCR Merged Project للكشف عن مواقع الرموز الهيروغليفية داخل اللوحات الحجرية والبرديات وتصنيفها إلى أكواد جاردينر القياسية (Gardiner Sign List Codes).

النماذج المتوفرة في هذا المستودع | Included Models

اسم النموذج / الملف	المهمة (Task)	المعمارية	الصيغة والحجم	دقة الإدخال / المخرجات	الاستخدام الموصى به
hieroglyph_yolo26n_synthetic_real_v2.pt	كشف مواقع الرموز (0: glyph)	Ultralytics YOLO26n	PyTorch (.pt — 5.47 MB)	1024×1024	التشغيل السحابي والبحثي (Colab / Gradio / API)
hieroglyph_yolo26n_synthetic_real_v2_w8a32.tflite	كشف مواقع الرموز على الهاتف	YOLO26n Quantized (W8A32)	LiteRT / TFLite (.tflite — 10.0 MB)	Input: [1, 3, 640, 640] Output: [1, 5, 8400]	تطبيق الأندرويد المحمول دون إنترنت (Offline Android APK)
trocr_gardiner_v2/ (model.safetensors)	قراءة كود جاردينر من القصاصة	microsoft/trocr-base-handwritten (ViT + RoBERTa)	Hugging Face SafeTensors (1.33 GB)	Input: 384×384 RGB Max Length: 12 tokens	القراءة السحابية عالية الدقة للقصاصات المكتشفة
gardiner_mobilenetv3_small_171_v1.keras	تصنيف الرموز (171 فئة جاردينر)	MobileNetV3-Small	Keras v3 (.keras — 4.72 MB)	Input: 224×224×3 Output: 171 classes	التصنيف السريع وعرض أعلى 3 احتمالات (Top-3)
gardiner_mobilenetv3_small_171.tflite	تصنيف الرموز على الهاتف	MobileNetV3-Small	LiteRT / TFLite (.tflite)	Input: [1, 224, 224, 3] Output: [1, 171]	مدمج داخل تطبيق Flutter Android Offline v4.5.0

ملخص الأداء والمقاييس الفعلية | Evaluation Metrics Summary

تم تقييم جميع النماذج تحت سياسة منع تسرب البيانات (Page-Level Split) مع إبقاء مجموعة الاختبار (Locked Test) مقفلة تماماً حتى التقييم النهائي:

1. كاشف الرموز (YOLO26n — Stage B Real Fine-Tuning)

• Precision: 79.07%
• Recall: 71.08%
• mAP@50: 78.21% (مقارنة بـ 1.93% عند التدريب على البيانات الاصطناعية فقط في Stage A)
• mAP@50-95: 46.45%

2. قارئ الأكواد السحابي (TrOCR-Base — trocr_gardiner_v2)

• Validation Exact Accuracy (Ground-Truth Crops - 420 samples): 94.29% (CER = 4.66%)
• Validation Accuracy on Matched YOLO Boxes (334 boxes): 93.41%
• Locked Test Accuracy on Matched YOLO Boxes (571 boxes): 92.12%
• Valid Gardiner Code Rate: 100.0%

3. مصنف الهواتف المحمولة (MobileNetV3-Small — 171 Gardiner Classes)

• Validation Accuracy (420 real crops): Top-1 = 87.62% | Top-3 = 95.24% (وعلى الفئات المدعومة بصور حقيقية: Top-1 = 89.71% | Top-3 = 97.55%)
• Locked Test Accuracy (829 real crops): Top-1 = 84.44% (v1) | Top-3 = 92.64% (v2) (وعلى الفئات المدعومة بصور حقيقية: Top-1 = 86.10% | Top-3 = 94.46%)

4. التقييم الشامل للنظام (End-to-End Pipeline: YOLO → Crop → TrOCR)

عند Confidence = 0.35 وشرط تطابق الصندوق IoU >= 0.50:

• Validation End-to-End Accuracy (Known Classes): 75.91% (74.29% شاملاً الفئات غير المرئية)
• Locked Test End-to-End Accuracy (Known Classes): 64.70% (63.45% شاملاً 12 فئة نادرة غير مرئية في التدريب)

طريقة الاستخدام السريع في بايثون | Quick Inference Example (Python)

import cv2
from PIL import Image
import torch
from transformers import TrOCRProcessor, VisionEncoderDecoderModel
from huggingface_hub import hf_hub_download
from ultralytics import YOLO

REPO_ID = "your-username/hieroglyph-ocr-models"
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"

# 1. تحميل كاشف YOLO26n
yolo_path = hf_hub_download(
    repo_id=REPO_ID,
    filename="yolo/hieroglyph_yolo26n_synthetic_real_v2.pt",
)
detector = YOLO(yolo_path)

# 2. تحميل قارئ أكواد جاردينر TrOCR
processor = TrOCRProcessor.from_pretrained(REPO_ID, subfolder="trocr_gardiner_v2")
recognizer = VisionEncoderDecoderModel.from_pretrained(
    REPO_ID, subfolder="trocr_gardiner_v2"
).to(DEVICE)
recognizer.eval()

# 3. الكشف والقراءة على صورة لوحة هيروغليفية
image_bgr = cv2.imread("stele_sample.jpg")
results = detector.predict(source=image_bgr, imgsz=1024, conf=0.35, iou=0.50)[0]

for box in results.boxes.xyxy.cpu().numpy():
    x1, y1, x2, y2 = map(int, box)
    crop_rgb = cv2.cvtColor(image_bgr[y1:y2, x1:x2], cv2.COLOR_BGR2RGB)
    pil_crop = Image.fromarray(crop_rgb)

    # توسيط داخل مربع أبيض قبل القراءة
    side = max(pil_crop.size)
    square = Image.new("RGB", (side, side), (255, 255, 255))
    square.paste(pil_crop, ((side - pil_crop.width) // 2, (side - pil_crop.height) // 2))

    pixel_values = processor(images=square, return_tensors="pt").pixel_values.to(DEVICE)
    with torch.no_grad():
        generated_ids = recognizer.generate(pixel_values, max_length=12, num_beams=2)
    gardiner_code = processor.batch_decode(generated_ids, skip_special_tokens=True)[0].strip()
    print(f"Box [{x1}, {y1}, {x2}, {y2}] -> Gardiner Code: {gardiner_code}")

حدود الاستخدام والتنبيه العلمي | Limitations & Bias

• يتعرف النموذج على أكواد جاردينر القياسية (مثل N35, M17, G17) ولا ينفذ ترجمة لغوية أو دلالية للنصوص المصرية القديمة.
• الفئات الـ 18 النادرة التي لم تتوفر لها قصاصات حقيقية في مجموعة التدريب الأصلية (واعتمدت على توليد Unicode فقط) تكون دقتها على الصور الحقيقية منخفضة، لذا يُنصح بعرض Top-3 أو تنبيه المستخدم عندما تكون ثقة التصنيف منخفضة.