النواة API

النواة API

omr.api هي السطح الصغير الذي يتفاعل معه معظم الشيفرات: OmrEngine، TemplateProcessor، ImageCollection، وعدد FormValidationLogic enum.

OmrEngine

OmrEngine هي مصنع بلا حالة. Generate(source, settings) تقبل مصدر markup-DSL أو شجرة TemplateConfig وتعيد GenerationResult. GetTemplateProcessor(templateSource, validationLogic) يحمل مسار ملف .omr محفوظ مسبقًا ويعيد TemplateProcessor مرتبط؛ مصدر تدفق بدلاً من ذلك يأخذ معلمة text-encoding قبل منطق التحقق.

from omr.api import OmrEngine, FormValidationLogic

engine = OmrEngine()
gen = engine.Generate("final-exam.txt")
gen.Save("out", "final-exam")
processor = engine.GetTemplateProcessor("out/final-exam.omr", FormValidationLogic.Ignore)

FormValidationLogic

يتحكم في سلوك المحرك عندما تُكسر قاعدة التحقق من القالب — مثل قيد الاختيار المتعدد — أثناء التعرف: Ignore (الافتراضي) يقبل الانتهاك بصمت، Exception يرفع استثناء، وundefined هو القيمة الصفرية للعدد enum. الفحص يطبق فقط على الأسئلة التي يكون Multiselect فيها معطلاً؛ GlobalPageSettings.Multiselect يكون مفعلاً افتراضيًا.

TemplateProcessor

Recognize(source, recognitionThreshold) يتعرف على صورة ممسوحة واحدة. RecognizeFolder(folderPath, recognitionThreshold) يتعرف على كل صورة في مجلد في استدعاء واحد. Recalculate(result, recognitionThreshold) يعيد تقييم نتيجة تم التعرف عليها مسبقًا بعتبة مختلفة، دون إعادة قراءة الصورة الأصلية.

ImageCollection

خريطة مقتصرة على الإضافة، حساسة لحالة الأحرف، تربط اسماً ببايتات الصورة الخام. Add(name, image) يسجل صورة، Contains(name) يتحقق مما إذا كان الاسم مسجلاً بالفعل، Count يُبلغ عن عدد المسجلين، وas_dict() تُعيد الخريطة الداعمة. يمكن للترميز الإشارة إلى صورة مسجلة بالاسم (?image=<name>) بدلاً من مسار نظام الملفات.

from omr.api import ImageCollection

images = ImageCollection()
with open("logo.png", "rb") as f:
    images.Add("logo.png", f.read())

نصائح وأفضل الممارسات

• قم بتمرير FormValidationLogic.Exception أثناء التطوير لإظهار انتهاكات الاختيار المتعدد فورًا بدلاً من تجاهلها صامتًا (يُفعل فقط للأسئلة التي يكون فيها Multiselect معطَّل).
• Recalculate() أرخص من إعادة المسح — استخدمه عندما تحتاج فقط إلى تغيير عتبة التعرف.
• أسماء ImageCollection حساسة لحالة الأحرف؛ تسجيل الاسم نفسه مرتين يرفع استثناء بدلاً من الكتابة فوقه صامتًا.
• Generate() يُبلغ عن معظم الفشل عبر GenerationResult.ErrorCode/ErrorMessage بدلاً من رفع استثناء — تحقق من ErrorCode قبل الوثوق بالنتيجة المُولَّدة.

المشكلات الشائعة

FAQ

هل OmrEngine آمن لإعادة الاستخدام عبر قوالب متعددة؟

نعم — إنه بدون حالة؛ كل استدعاء Generate()/GetTemplateProcessor() مستقل.

كيف يمكنني التعرف على مجلد كامل من المسحات مرة واحدة؟

استدعِ TemplateProcessor.RecognizeFolder(folderPath, recognitionThreshold) بدلاً من تكرار Recognize() بنفسك.

ملخص API Reference

انظر أيضاً

• Aspose.OMR — Enterprise Documentation