แก้ปัญหาที่พบบ่อย

ติดตั้ง

อาการ	สาเหตุและวิธีแก้
ModuleNotFoundError: No module named 'cv2'	ติดตั้งคนละ Python กับที่ใช้รัน ใช้ python -m pip install opencv-contrib-python ด้วย python ตัวเดียวกับที่รันโค้ด
module 'cv2' has no attribute 'aruco'	ติดตั้ง opencv-python ไว้ ให้ถอนออกแล้วติดตั้ง opencv-contrib-python แทน
cv2.imshow error: The function is not implemented	ติดตั้ง opencv-python-headless ไว้ (ไม่มีหน้าต่าง) ให้ถอนออกแล้วติดตั้งใหม่

กล้อง

อาการ	สาเหตุและวิธีแก้
cap.read() ได้ ret = False ทันที	เลขกล้องผิด ลอง 1 หรือ 2 หรือมีโปรแกรมอื่นใช้กล้องอยู่ (Zoom, Teams, แอปกล้อง)
IP camera เชื่อมต่อไม่ได้ (timeout)	ตรวจตามลำดับ: เปิดลิงก์ใน browser ได้หรือไม่ → อยู่ Wi-Fi เดียวกันหรือไม่ → ปิด mobile data ของโทรศัพท์ → Wi-Fi ของมหาวิทยาลัยบางวงกั้นอุปกรณ์คุยกัน ให้ใช้ hotspot ของโทรศัพท์แทน
ภาพจาก IP camera ช้าลงเรื่อย ๆ	VideoCapture เก็บ frame ค้างใน buffer เมื่อประมวลผลช้ากว่ากล้อง ลดงานต่อ frame หรือใช้แบบ snapshot
ภาพมืดหรือสว่างเปลี่ยนเอง	กล้องปรับ exposure อัตโนมัติ ล็อกค่าตามใบงาน 3

หน้าต่างแสดงผล

อาการ	สาเหตุและวิธีแก้
หน้าต่างค้าง กดปิดไม่ได้	ต้องเรียก cv2.waitKey() ทุกรอบของลูป หน้าต่างจึงจะอัปเดต กด q ที่หน้าต่างภาพ (ไม่ใช่ที่เทอร์มินัล)
กด q แล้วไม่หยุด	คลิกที่หน้าต่างภาพก่อน แป้นพิมพ์ต้องเป็นภาษาอังกฤษ
ภาพใหญ่เกินจอ	ย่อด้วย cv2.resize ก่อนแสดง หรือ cv2.namedWindow("name", cv2.WINDOW_NORMAL) แล้วลากขยายเอง

ผลการประมวลผล

อาการ	สาเหตุและวิธีแก้
cv2.cvtColor error: !_src.empty()	ภาพเป็น None เพราะอ่านไฟล์ไม่เจอ (path ผิด) หรือกล้องไม่ส่งภาพ ตรวจ img is None ก่อน
หา marker ไม่ครบ 4 ตัว	marker เล็กเกินในภาพ แสงสะท้อนบนกระดาษ หรือถูกบัง ขยับกล้องให้ใกล้ขึ้นและใช้แสงกระจาย
findChessboardCorners หาไม่เจอ	PATTERN ต้องเป็นจำนวน มุมด้านใน (9, 6) ไม่ใช่จำนวนช่อง และต้องเห็นทั้งแผ่น
สี่เหลี่ยมถูกจำแนกเป็นวงกลม	ภาพเล็กหรือเบลอจน contour ไม่มีมุม เพิ่มขนาดชิ้นงานในภาพหรือปรับค่า 0.04 ใน approxPolyDP