คอร์ API
แกนหลัก API
omr.api เป็นพื้นผิวเล็กที่โค้ดส่วนใหญ่โต้ตอบด้วย: OmrEngine, TemplateProcessor, ImageCollection และ FormValidationLogic enum.
OmrEngine
OmrEngine เป็นโรงงานที่ไม่มีสถานะ. Generate(source, settings) รับแหล่งที่มาของ markup-DSL หรือ TemplateConfig tree และคืนค่า GenerationResult. GetTemplateProcessor(templateSource, validationLogic) โหลดเส้นทางไฟล์ .omr ที่บันทึกไว้ก่อนหน้าและคืนค่า TemplateProcessor ที่ผูกไว้; แหล่งที่มาของสตรีมแทนที่จะรับอาร์กิวเมนต์การเข้ารหัสข้อความก่อนตรรกะการตรวจสอบ.
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 เป็นค่า zero ของ enum. การตรวจสอบใช้กับคำถามที่ Multiselect ถูกปิดการใช้งานเท่านั้น; GlobalPageSettings.Multiselect มีค่าเริ่มต้นเป็นเปิดใช้งาน.
TemplateProcessor
Recognize(source, recognitionThreshold) จดจำภาพสแกนหนึ่งภาพ. RecognizeFolder(folderPath, recognitionThreshold) จดจำทุกภาพในโฟลเดอร์ในการเรียกครั้งเดียว. Recalculate(result, recognitionThreshold) ทำการให้คะแนนใหม่กับผลลัพธ์ที่จดจำแล้วโดยใช้เกณฑ์ต่างกัน, โดยไม่ต้องอ่านภาพต้นฉบับใหม่.
ImageCollection
แผนที่แบบเพิ่มต่อเท่านั้น (append-only) ที่แยกแยะตัวอักษรใหญ่-เล็ก จากชื่อไปยังไบต์ของภาพดิบ. 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ก่อนเชื่อมั่นผลลัพธ์ที่สร้างขึ้น.
ปัญหาทั่วไป
| ปัญหา | สาเหตุ | วิธีแก้ไข |
|---|---|---|
| การลงทะเบียนภาพสองครั้งทำให้เกิด | ImageCollection.Add ไม่อนุญาตให้ใช้ชื่อซ้ำ | ตรวจสอบ Contains(name) ก่อน หรือใช้ชื่อที่ไม่ซ้ำกันสำหรับแต่ละภาพ |
| คำตอบแบบหลายตัวเลือกที่ไม่ได้รับอนุญาตจะถูกยอมรับโดยไม่มีการแจ้งเตือน | ค่าเริ่มต้น FormValidationLogic.Ignore ไม่ทำให้เกิดข้อผิดพลาด | ส่ง FormValidationLogic.Exception ไปยัง GetTemplateProcessor() และตรวจสอบให้แน่ใจว่า Multiselect ของคำถามถูกปิดการใช้งาน |
FAQ
การใช้ OmrEngine ซ้ำในหลายเทมเพลตปลอดภัยหรือไม่?
ใช่ — มันไม่มีสถานะ; การเรียก Generate()/GetTemplateProcessor() แต่ละครั้งเป็นอิสระ.
ฉันจะระบุโฟลเดอร์สแกนทั้งหมดได้อย่างไรในครั้งเดียว?
เรียก TemplateProcessor.RecognizeFolder(folderPath, recognitionThreshold) แทนการวนลูป Recognize() ด้วยตนเอง.
API Reference สรุป
| คลาส/เมธอด | คำอธิบาย |
|---|---|
OmrEngine.Generate | เรนเดอร์เทมเพลตเป็นภาพหน้า + .omr descriptor |
OmrEngine.GetTemplateProcessor | โหลด .omr descriptor เพื่อการจดจำ |
TemplateProcessor.Recognize / RecognizeFolder / Recalculate | จุดเริ่มต้นการจดจำ |
ImageCollection.Add / Contains / as_dict | รีจิสทรีภาพในหน่วยความจำสำหรับมาร์กอัป |
FormValidationLogic | enum พฤติกรรมการละเมิดการตรวจสอบ |
