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) تجهيز البيئة

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

pip install -r requirements.txt
```

## 2) تجهيز PostgreSQL

```sql
CREATE DATABASE face_attendance;
```

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

```bash
cp .env.example .env
```

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

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

حط الملفين دول جوه `app/weights/`:
- `YoloV8_Face.pt`
- `edgeface_xxs_q.pt`

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

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

```bash
uvicorn app.main:app --reload
```

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

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

### تسجيل شخص جديد
```bash
curl -X POST "http://127.0.0.1:8000/register/?name=Hossam"
```
هتفتح الكاميرا:
- اضغط **c** لما وجهك يبقى واضح فى المربع الأخضر → يسجل فى الداتابيز.
- اضغط **q** للإلغاء.

### تسجيل الحضور (Real-time)
```bash
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` فى بوستجريس.