# KGYS — Kamera Görüntü İnceleme Sistemi

Emniyet Müdürlüğü kamera arşivlerinde şüpheli kişi tespiti için geliştirilmiş yerel AI sistemi.  
Tüm veriler cihazda kalır, dışarıya hiçbir şey çıkmaz.

---

## Ne Yapıyor?

### 1. Yüz Tanıma ile Şüpheli Arama
- Şüpheliye ait fotoğraf sisteme yüklenir
- Seçilen kamera arşiv videosu kare kare taranır
- Yüz vektörü (512 boyutlu ArcFace embedding) karşılaştırılır
- Eşleşen anlar: **kamera ID + zaman damgası + güven skoru** ile raporlanır
- Sonuca göre kare fotoğrafı kaydedilir

### 2. Çoklu Kamera Taraması
- Bir klasördeki tüm videolar sırayla taranır
- Her video dosya adı otomatik olarak kamera ID'si olarak kullanılır
- Sonuçlar tek dashboard'da birleştirilir

### 3. AI ile Türkçe Metin Araması
- "Siyah tişörtlü, mavi kotlu erkek" gibi Türkçe tarif girilir
- Claude (Sonnet 4.6) tarifi parse eder → İngilizce CLIP sorgusuna çevirir
- VisionCCTV CLIP backend üzerinde video içi arama yapılır
- Cinsiyet, renk, kıyafet analizini Claude üretir

---

## Kullanılan Modeller

| Model | Görev | Çalışma Yeri |
|---|---|---|
| **InsightFace buffalo_l** | Yüz tespiti + ArcFace embedding (512 vektör) | Yerel (CPU/GPU) |
| **RetinaFace** | Yüz bölgesi tespiti (buffalo_l içinde) | Yerel |
| **ArcFace** | Yüz kimlik vektörü çıkarımı | Yerel |
| **Claude Sonnet 4.6** | Türkçe tarif → İngilizce CLIP sorgusu | API (claude.gg) |
| **CLIP** | Metin → görüntü semantik eşleştirme | VisionCCTV backend |

---

## Teknik Mimari

```
[Şüpheli Fotoğrafı]
    → RetinaFace (yüz tespit)
    → ArcFace (512 boyutlu vektör) → referans embedding

[Kamera Arşiv Videosu]
    → Her N. kare seçilir (varsayılan: 1 FPS)
    → RetinaFace: yüz tespiti
    → ArcFace: 512 boyutlu vektör
    → Cosine similarity: referans ile karşılaştır (eşik: 0.45+)
    → Eşleşme → kare kaydet + DB'ye yaz

[AI Metin Araması]
    → Claude: Türkçe → JSON + İngilizce sorgu
    → CLIP backend: video indexi üzerinde arama
    → Sonuçlar dashboard'da gösterilir
```

---

## Doğruluk Beklentisi

| Kamera Tipi | Beklenen Doğruluk |
|---|---|
| Full HD sabit kamera | %60–80 |
| PTZ kamera | %50–70 |
| MOBESE | %20–45 |

> Değerler ideal koşullarda geçerlidir: yüz önden, net görüntü, maske/şapka yok.  
> Gerçek saha koşullarında (ters ışık, kalabalık, hareket bulanıklığı) daha düşük çıkabilir.  
> GFPGAN gibi yüz iyileştirme modelleri, düşük çözünürlüklü görüntülerde bazı senaryolarda eşleşme başarısını artırabilir; ancak yüz yapısını değiştirme riski taşıdığından dikkatli kullanılmalıdır.  
> Son karar her zaman insan tarafından verilir. Sistem aday listesi çıkarır.

---

## Performans (1 Kamera, 24 Saat Arşiv, 1 FPS)

86.400 kare — RetinaFace + ArcFace zinciri için tahmini süreler:

| Donanım | Tahmini Süre | Açıklama |
|---|---|---|
| Apple M5 (CPU) | ~45–90 dakika | Tek thread, CPU inferans |
| RTX 4060 | ~12–20 dakika | ~70–120 FPS beklenti |
| RTX 4090 | ~5–10 dakika | ~150–300 FPS beklenti |
| H100 80GB | ~2–4 dakika | Batch inferans ile |

> Gerçek süre; video çözünürlüğü, karede kaç yüz olduğu ve disk okuma hızına göre değişir.

---

## Kurulum

```bash
cd ~/Desktop/kgys
python3 -m venv venv
source venv/bin/activate
pip install fastapi uvicorn insightface opencv-python-headless numpy aiofiles httpx python-dotenv
python main.py
```

Tarayıcıda aç: http://localhost:8002

---

## .env Yapılandırması

```env
ANTHROPIC_API_KEY=sk-...
ANTHROPIC_BASE_URL=https://app.claude.gg/v1
ANTHROPIC_MODEL=claude-sonnet-4-6
CLIP_BACKEND_URL=http://localhost:8000
```

---

## API Endpointleri

| Method | Endpoint | Açıklama |
|---|---|---|
| GET | `/` | Dashboard (HTML) |
| POST | `/api/sorgu/olustur` | Fotoğraf yükle → sorgu_id al |
| GET | `/api/sorgu/{id}/crop` | Yüz crop önizleme |
| POST | `/api/sorgu/{id}/tara` | Tek video tarama başlat |
| POST | `/api/sorgu/{id}/tara-klasor` | Çoklu kamera klasör tarama |
| GET | `/api/sorgu/{id}/durum` | Tarama ilerleme durumu |
| GET | `/api/sorgu/{id}/sonuc` | Eşleşme sonuçları |
| GET | `/api/sorgular` | Tüm geçmiş sorgular |
| POST | `/api/ai/metin-ara` | AI ile Türkçe metin araması |
| GET | `/api/ai/durum` | Claude + CLIP bağlantı durumu |

---

## Veritabanı Şeması

**sorgular** tablosu:
- `id`, `olusturma_zamani`, `fotograf_yolu`, `referans_embedding_yolu`
- `kamera_id`, `video_yolu`, `esik`
- `durum` → `bekliyor / taraniyor / tamamlandi / hata`
- `ilerleme`, `islenen_kare`, `toplam_kare`, `hata_mesaji`

**eslesmeler** tablosu:
- `sorgu_id`, `kamera_id`, `zaman_str`, `zaman_sn`, `kare_no`
- `skor` (cosine similarity), `det_skor` (yüz tespit güveni)
- `cinsiyet`, `yas`, `bbox_json`, `kare_dosyasi`

---

## ArcFace Benzerlik Eşikleri

| Skor Aralığı | Seviye | Yorum |
|---|---|---|
| 0.40 – 0.49 | Aday | Zayıf benzerlik, manuel inceleme gerekir |
| 0.50 – 0.59 | Yüksek | Güvenilir eşleşme, doğrulama önerilir |
| 0.60+ | Çok Yüksek | Güçlü eşleşme |

> 0.40 altı sonuçlar gösterilmez. Eşik dashboard'dan ayarlanabilir.

---

## Klasör Yapısı

```
kgys/
├── main.py          # FastAPI backend
├── scanner.py       # Video tarama motoru
├── database.py      # SQLite yardımcı fonksiyonlar
├── dashboard.html   # Tek sayfa web arayüzü
├── kgys.db          # SQLite veritabanı
├── .env             # API anahtarları (git'e ekleme!)
├── yuklemeler/      # Yüklenen fotoğraf ve videolar
├── kareler/         # Eşleşen kare görselleri
└── venv/            # Python sanal ortamı
```

---

## Geliştirme Yol Haritası

- [ ] GFPGAN ile düşük çözünürlüklü yüz iyileştirme
- [ ] Gerçek zamanlı RTSP kamera desteği
- [ ] Çoklu yüz takibi (Re-ID)
- [ ] Plaka tanıma (OCR) entegrasyonu
- [ ] PDF rapor çıktısı
- [ ] Kullanıcı yetkilendirme sistemi
- [ ] Docker ile kolay kurulum