README.md

Face Attendance API

نظام حضور بالتعرف على الوجه، مبني على FastAPI + PostgreSQL + YOLOv8 (كشف الوجه) + EdgeFace (embedding).

هيكل المشروع

face_attendance/
├── app/
│   ├── main.py                 # نقطة تشغيل التطبيق
│   ├── config.py                # الإعدادات (DB, threshold, مسارات الموديلات)
│   ├── api/
│   │   ├── register.py         # POST /register  → تسجيل شخص جديد
│   │   └── attendance.py       # POST /attendance → تسجيل الحضور
│   ├── database/
│   │   ├── database.py         # اتصال SQLAlchemy
│   │   └── models.py           # جدول Person + جدول Attendance
│   ├── services/
│   │   ├── edgeface_model.py   # تعريف موديل EdgeFace (بدون تعديل)
│   │   ├── embedding.py        # تحميل EdgeFace وحساب embedding
│   │   ├── face_detector.py    # تحميل YOLO وكشف/تتبع الوجوه
│   │   └── recognition.py      # مقارنة embeddings وتحديد الشخص
│   ├── utils/
│   │   └── preprocess.py       # تجهيز الصورة + cosine similarity
│   └── weights/                # حط هنا ملفات الموديلات (.pt)
├── requirements.txt
└── .env.example

1) تجهيز البيئة

python -m venv venv
source venv/bin/activate      # ويندوز: venv\Scripts\activate

pip install -r requirements.txt

2) تجهيز PostgreSQL

CREATE DATABASE face_attendance;

انسخ .env.example إلى .env وعدّل البيانات حسب السيرفر بتاعك:

cp .env.example .env

الجداول (person, attendance) هتتعمل تلقائيًا أول ما السيرفر يشتغل، مفيش حاجة تعملها يدوي.

3) حط ملفات الموديلات

حط الملفين دول جوه app/weights/:

• YoloV8_Face.pt
• edgeface_xxs_q.pt

(لو الاسم مختلف عندك، عدّله فى app/config.py)

4) تشغيل السيرفر

uvicorn app.main:app --reload

هيفتح على: http://127.0.0.1:8000/docs (Swagger UI تلقائي لتجربة الـ APIs).

5) استخدام الـ APIs

تسجيل شخص جديد

curl -X POST "http://127.0.0.1:8000/register/?name=Hossam"

هتفتح الكاميرا:

• اضغط c لما وجهك يبقى واضح فى المربع الأخضر → يسجل فى الداتابيز.
• اضغط q للإلغاء.

تسجيل الحضور (Real-time)

curl -X POST "http://127.0.0.1:8000/attendance/"

هتفتح الكاميرا وتتعرف على كل الوجوه اللي قدامها وتسجلهم فى جدول attendance (مرة واحدة بس لكل شخص فى اليوم). اضغط q لإنهاء الجلسة.

ملاحظات للتعديل لاحقًا

• threshold التعرف: غيّره من RECOGNITION_THRESHOLD فى app/config.py.
• رقم الكاميرا: غيّره من CAMERA_INDEX فى نفس الملف (لو عندك أكتر من كاميرا).
• تسجيل شخص من صورة بدل الكاميرا مباشرة: عدّل app/api/register.py فقط، باقي الملفات مش هتتأثر.
• الترقية إلى pgvector (بحث أسرع للـ embeddings عند زيادة عدد الأشخاص): غيّر نوع عمود embedding فى app/database/models.py من ARRAY(Float) إلى Vector(512) بعد تفعيل extension pgvector فى بوستجريس.