Apppublic

TCETMILI/PassportExtractor

sourceHugging Faceupdated 7mo agoView on Hugging Face

1likes

App README

🛂 Global Passport Extractor V2.6

Pasaport görsellerinden otomatik veri çıkarma ve yüz eşleştirme sistemi

![Python](https://python.org) ![FastAPI](https://fastapi.tiangolo.com) ![Streamlit](https://streamlit.io) ![License](LICENSE)

🎯 Genel Bakış

Global Passport Extractor, PDF, PNG veya JPG formatındaki pasaport görsellerinden yapılandırılmış verileri otomatik olarak çıkaran ve yüklenen fotoğrafları pasaport sahipleriyle eşleştiren kapsamlı bir sistemdir.

Temel İş Akışı

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Belge Yükleme  │ ──▶ │  Sınıflandırma   │ ──▶ │  Veri Çıkarma   │
│  (PDF/PNG/JPG)  │     │  (PASSPORT/PHOTO)│     │  (LLM + Regula) │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                          │
                                                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Excel Export   │ ◀── │  TCFOTO Kayıt    │ ◀── │  Yüz Eşleştirme │
│  (Türkçe UTF-8) │     │  (TC No ile)     │     │  (128D Embedding)│
└─────────────────┘     └──────────────────┘     └─────────────────┘

🆕 V2 Yenilikleri

V2.6 (2025-01) - Yayına Hazır Sürüm 🚀

—✅ Native Dosya Seçici: Masaüstü kullanımında işletim sisteminin kendi dosya seçicisi (Tkinter) entegre edildi.
—✅ Web Modu: Mobil ve Tablet erişimi için DEPLOYMENT_MODE="WEB" desteği eklendi.
—✅ Akıllı PDF Kurtarma: Bozuk veya hatalı uzantılı PDF'ler otomatik olarak görsel olarak kurtarılır.
—✅ Geniş Açı Biyometrik (200x200): Omuz ve başörtüsünü içeren 200x200 piksel hassas kırpma.
—✅ Çift Kayıt (Dual Save): Çıktılar hem ana çıktı klasörüne hem de kaynak klasörün içine (yedekli) kaydedilir.
—✅ Regula SSL Fix: Kurumsal ağlarda SSL sertifika hataları için çözüm eklendi.

V1 → V2 Karşılaştırması

Özellik	V1	V2.6
Yüz Eşleştirme	❌ Yok	✅ 128D face_recognition
Dosya Seçici	Standart	✅ Native (Desktop) / Web (Mobil)
Portre Çıkarma	❌ Yok	✅ Regula SDK + Fallback
Fotoğraf Sınıflandırma	❌ Yok	✅ Hybrid (Heuristic + LLM)
TCFOTO Kayıt	❌ Yok	✅ TC No ile otomatik
Önbellek Sistemi	❌ Yok	✅ JSON + PKL cache

backend/services/
├── classifier.py       # Belge sınıflandırma (YENİ)
├── face_encoder.py     # 128D yüz kodlama (YENİ)
├── face_matcher.py     # Yüz eşleştirme (YENİ)
├── photo_processor.py  # Fotoğraf işleme (YENİ)
├── cache_manager.py    # Önbellek yönetimi (YENİ)
└── ...

✨ Özellikler

🧠 Akıllı Veri Çıkarma

—OpenAI GPT-4o entegrasyonu ile yüksek doğrulukta OCR
—Regula SDK ile profesyonel belge işleme
—MRZ (Machine Readable Zone) otomatik parse etme
—Çoklu pasaport desteği (tek görselde birden fazla pasaport)

👤 Yüz Eşleştirme Sistemi

—face_recognition kütüphanesi ile 128 boyutlu yüz kodlama
—Pasaport fotoğrafı ↔ Yüklenen fotoğraf otomatik eşleştirme
—Benzerlik skoru hesaplama (%60+ eşleşme)
—TCFOTO klasörüne TC kimlik numarası ile kayıt

📊 Belge Sınıflandırma

—Hybrid yaklaşım: Heuristic analiz + LLM fallback
—Otomatik belge tipi tespiti:
—PASSPORT - Pasaport sayfası
—PHOTO - Vesikalık/portre fotoğrafı
—UNKNOWN - Belirsiz (yüz varsa eşleştirmeye dahil)
—UNREADABLE - Okunamayan belge

📁 Dosya Format Desteği

—PDF - Çok sayfalı PDF'ler otomatik ayrıştırılır
—PNG - Yüksek kaliteli görsel desteği
—JPG/JPEG - Standart fotoğraf formatı
—WebP, BMP, TIFF - Ek format desteği

💾 Önbellek Sistemi

—İşlenmiş pasaportlar JSON olarak saklanır
—Yüz kodlamaları PKL formatında önbelleklenir
—Tekrar işleme gerektirmez, hızlı sonuç

📈 Excel Çıktı

—Türkçe karakter desteği (UTF-8)
—Özelleştirilebilir Excel şablonu
—Otomatik kolon eşleştirme

💻 Sistem Gereksinimleri

Minimum Gereksinimler

—İşletim Sistemi: macOS 10.15+, Ubuntu 20.04+, Windows 10+
—Python: 3.9 veya üzeri
—RAM: 8 GB (16 GB önerilir)
—Disk: 2 GB boş alan

Python Bağımlılıkları

txt

# Temel
fastapi>=0.100.0
uvicorn>=0.23.0
streamlit>=1.28.0
python-dotenv>=1.0.0

# Görsel İşleme
pillow>=10.0.0
opencv-python>=4.8.0
numpy>=1.24.0

# PDF İşleme
pdf2image>=1.16.0
PyMuPDF>=1.23.0

# Yüz Tanıma
face_recognition>=1.3.0
dlib>=19.24.0

# AI/LLM
openai>=1.0.0

# Excel
openpyxl>=3.1.0

# HTTP
httpx>=0.25.0
python-multipart>=0.0.6

Sistem Bağımlılıkları

macOS:

bash

brew install cmake
brew install poppler

Ubuntu/Debian:

bash

sudo apt-get update
sudo apt-get install -y cmake libopenblas-dev liblapack-dev
sudo apt-get install -y poppler-utils

Windows:

—CMake kurulumu gerekli
—Poppler kurulumu gerekli

🚀 Kurulum

1. Projeyi İndirin

bash

# ZIP dosyasını çıkartın veya
unzip V2_FINAL_STABLE.zip
cd V2

2. Sanal Ortam Oluşturun (Önerilir)

bash

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# veya
.\venv\Scripts\activate   # Windows

3. Bağımlılıkları Yükleyin

bash

pip install --upgrade pip
pip install -r requirements.txt

4. Ortam Değişkenlerini Ayarlayın

bash

# .env dosyası oluşturun
echo "OPENAI_API_KEY=sk-your-api-key-here" > .env

# Opsiyonel ayarlar
echo "LLM_MODEL=gpt-4o" >> .env
echo "MAX_WORKERS=10" >> .env

5. Uygulamayı Başlatın

Tek Komutla (Önerilir):

bash

python3 run_panel.py

veya Manuel:

bash

# Terminal 1 - Backend
uvicorn backend.main:app --reload --port 8000

# Terminal 2 - Frontend
streamlit run frontend/app.py --server.port 8501

6. Tarayıcıda Açın

http://localhost:8501

📖 Kullanım

Web Arayüzü

1.Belge Yükleme
2.Sol panelden dosyalarınızı sürükleyip bırakın
3.PDF, PNG, JPG formatları desteklenir
4.Birden fazla dosya aynı anda yüklenebilir

1.İşleme
2."İşle" butonuna tıklayın
3.İşlem durumu progress bar ile gösterilir
4.Loglar gerçek zamanlı güncellenir

1.Sonuçları İnceleme
2.Ortada: Çıkarılan pasaport verileri tablosu
3.Sağda: Yüz eşleştirme sonuçları (kartlar halinde)

1.Dışa Aktarma
2."Excel İndir" butonu ile sonuçları indirin
3.TCFOTO klasöründen eşleşen fotoğrafları alın

Komut Satırı Kullanımı

python

from backend.main_pipeline import process_uploaded_files

# Dosyaları yükle
with open("passport.pdf", "rb") as f:
    file_bytes = f.read()

# İşle
records, matches = process_uploaded_files(
    file_datas=[(file_bytes, "passport.pdf")],
    model="gpt-4o",
    use_cache=True
)

# Sonuçları yazdır
for record in records:
    print(f"{record.given_names} {record.surname} - TC: {record.tc_kimlik_no}")

API Kullanımı

bash

# Dosya yükleme
curl -X POST "http://localhost:8000/extract" \
  -H "Content-Type: multipart/form-data" \
  -F "files=@passport.pdf"

# Sağlık kontrolü
curl "http://localhost:8000/health"

📂 Klasör Yapısı

V2/
├── 📄 run_panel.py              # Ana başlatıcı script
├── 📄 requirements.txt          # Python bağımlılıkları
├── 📄 .env                      # Ortam değişkenleri (oluşturulacak)
├── 📄 README.md                 # Bu dosya
│
├── 📁 backend/                  # Backend servisleri
│   ├── 📄 __init__.py
│   ├── 📄 main.py               # FastAPI uygulaması
│   ├── 📄 main_pipeline.py      # Ana işleme pipeline'ı
│   ├── 📄 config.py             # Konfigürasyon ayarları
│   ├── 📄 models.py             # Veri modelleri
│   │
│   └── 📁 services/             # Servis modülleri
│       ├── 📄 classifier.py     # Belge sınıflandırma
│       ├── 📄 extractor.py      # Pasaport veri çıkarma
│       ├── 📄 face_encoder.py   # Yüz kodlama (128D)
│       ├── 📄 face_matcher.py   # Yüz eşleştirme
│       ├── 📄 photo_processor.py# Fotoğraf işleme
│       ├── 📄 excel_exporter.py # Excel dışa aktarma
│       ├── 📄 pdf_utils.py      # PDF işleme
│       ├── 📄 cache_manager.py  # Önbellek yönetimi
│       ├── 📄 naming.py         # İsimlendirme yardımcıları
│       └── 📄 scanner.py        # Regula SDK entegrasyonu
│
├── 📁 frontend/                 # Frontend uygulaması
│   └── 📄 app.py                # Streamlit arayüzü
│
├── 📁 templates/                # Şablonlar
│   └── 📄 EXCEL_TASLAK.xlsx     # Excel çıktı şablonu
│
├── 📁 workspace/                # Çalışma klasörleri (otomatik oluşur)
│   ├── 📁 BELGELER/             # Yüklenen belgeler
│   ├── 📁 PASAPORTLAR/          # Kırpılmış pasaport görselleri
│   ├── 📁 FOTO/                 # Çıkarılan vesikalık fotoğraflar
│   ├── 📁 TCFOTO/               # TC No ile adlandırılmış fotoğraflar
│   ├── 📁 OKUNAMADI/            # İşlenemeyen belgeler
│   └── 📁 EXCEL/                # Excel çıktıları
│
├── 📁 output/                   # Çıktı klasörü
│   └── 📁 cache/                # Önbellek
│       ├── 📁 passports/        # Pasaport JSON önbelleği
│       └── 📁 face_encodings/   # Yüz kodlama önbelleği
│
└── 📁 docker/                   # Docker dosyaları
    ├── 📄 Dockerfile.backend
    ├── 📄 Dockerfile.frontend
    └── 📄 docker-compose.yml

🔌 API Referansı

Endpoints

`POST /extract`

Pasaport belgelerini işler ve veri çıkarır.

Request:

http

POST /extract HTTP/1.1
Content-Type: multipart/form-data

files: [binary]

Response:

json

{
  "success": true,
  "records": [
    {
      "given_names": "MEHMET",
      "surname": "ÖRNEK",
      "tc_kimlik_no": "12345678901",
      "date_of_birth": "1990-01-15",
      "passport_number": "U12345678",
      "date_of_issue": "2020-01-01",
      "date_of_expiry": "2030-01-01",
      "issuing_authority": "ANKARA"
    }
  ],
  "photo_matches": [
    {
      "photo_filename": "foto1.jpg",
      "matched_tc": "12345678901",
      "matched_name": "MEHMET ORNEK",
      "similarity": 0.87
    }
  ],
  "excel_path": "/workspace/EXCEL/passports_extracted.xlsx"
}

`GET /health`

Sistem sağlık kontrolü.

Response:

json

{
  "status": "healthy",
  "version": "2.0.0",
  "openai_configured": true,
  "face_recognition_available": true
}

`POST /classify`

Tek bir görseli sınıflandırır.

Response:

json

{
  "document_type": "PASSPORT",
  "confidence": 0.95,
  "method": "hybrid",
  "details": "aspect=1.42, faces=1, face_ratio=0.045"
}

⚙️ Konfigürasyon

Ortam Değişkenleri (.env)

Değişken	Varsayılan	Açıklama
`OPENAI_API_KEY`	-	OpenAI API anahtarı (zorunlu)
`LLM_MODEL`	`gpt-4o`	Kullanılacak LLM modeli
`MAX_WORKERS`	`10`	Maksimum paralel işçi sayısı
`BACKEND_URL`	`http://localhost:8000`	Backend API adresi

Konfigürasyon Dosyası (config.py)

python

# Yüz eşleştirme hassasiyeti
FACE_MATCH_THRESHOLD = 0.6  # Düşük = daha katı, Yüksek = daha toleranslı

# Minimum yüz boyutu (piksel)
MIN_FACE_SIZE = 60

# Sınıflandırma güven eşiği
CLASSIFICATION_CONFIDENCE_THRESHOLD = 0.7

# Görsel işleme
VISION_MAX_DIMENSION = 1200
JPEG_QUALITY = 95

# Vesikalık boyutu
PHOTO_OUTPUT_SIZE = 200  # 200x200 kare piksel

📊 Excel Çıktı Şeması

Kolon Yapısı

Kolon	Açıklama	Örnek
A	Sıra No	1
B	Adlar	MEHMET
C	Soyad	ÖRNEK
D	TC Kimlik No	12345678901
E	Doğum Tarihi	1990-01-15
F	Pasaport No	U12345678
G	Veriliş Tarihi	2020-01-01
H	Geçerlilik Tarihi	2030-01-01
I	Veren Makam	ANKARA

Şablon Kullanımı

templates/EXCEL_TASLAK.xlsx dosyasını düzenleyerek özel şablon oluşturabilirsiniz.

💾 Önbellek Sistemi

Nasıl Çalışır?

1.Pasaport Önbelleği (output/cache/passports/)
2.İşlenen her pasaport MD5 hash ile saklanır
3.JSON formatında veri depolanır
4.Aynı dosya tekrar yüklendiğinde önbellekten okunur

1.Yüz Kodlama Önbelleği (output/cache/face_encodings/)
2.128 boyutlu yüz vektörleri PKL formatında saklanır
3.Eşleştirme işlemleri hızlanır

Önbelleği Temizleme

bash

# Tüm önbelleği temizle
rm -rf output/cache/*

# Sadece pasaport önbelleğini temizle
rm -rf output/cache/passports/*

# Sadece yüz kodlamalarını temizle
rm -rf output/cache/face_encodings/*

🐳 Docker ile Çalıştırma

Docker Compose

bash

# Servisleri başlat
docker compose up -d

# Logları izle
docker compose logs -f

# Servisleri durdur
docker compose down

Manuel Docker Build

bash

# Backend
docker build -f Dockerfile.backend -t passport-extractor-backend .

# Frontend
docker build -f Dockerfile.frontend -t passport-extractor-frontend .

# Çalıştır
docker run -d -p 8000:8000 --env-file .env passport-extractor-backend
docker run -d -p 8501:8501 passport-extractor-frontend

☁️ Web Deployment (Hugging Face / Cloud)

Bu projeyi Hugging Face Spaces veya herhangi bir Docker tabanlı cloud servisinde çalıştırarak Tablet ve Telefondan erişilebilir hale getirebilirsiniz.

Hugging Face Spaces Kurulumu

1.Space Oluşturun: Hugging Face üzerinde yeni bir Space açın.
2.SDK Seçimi: "Docker" seçeneğini işaretleyin.
3.Dockerfile Ayarı:
4.Projedeki Dockerfile.hf_space dosyasının adını Dockerfile olarak değiştirin (veya içeriğini kopyalayın).
5.Bu Dockerfile, hem Backend hem Frontend'i tek bir container'da çalıştırır.
6.Ortam Değişkenleri (Secrets):
7.Space ayarlarından "Variables/Secrets" kısmına şunları ekleyin: | Anahtar | Değer | Açıklama | |---------|-------|----------| | OPENAI_API_KEY | sk-... | OpenAI anahtarınız | | DEPLOYMENT_MODE | WEB | Önemli: Web arayüzünü (Upload) aktif eder. | | LLM_MODEL | gpt-4o | (Opsiyonel) Model seçimi |

Nasıl Çalışır?

—Web Modunda (`DEPLOYMENT_MODE=WEB`): Masaüstü (native) dosya seçici devre dışı kalır. Yerine standart "Sürükle Bırak" alanı gelir.
—Bu sayede iPhone, iPad veya Android cihazlardan tarayıcı üzerinden fotoğraf çekip yükleyebilirsiniz.

🔧 Sorun Giderme

Sık Karşılaşılan Sorunlar

1. "face_recognition yüklenemedi" hatası

macOS:

bash

brew install cmake
pip install dlib
pip install face_recognition

Linux:

bash

sudo apt-get install cmake libopenblas-dev liblapack-dev
pip install dlib
pip install face_recognition

2. "PDF dönüştürme hatası"

bash

# macOS
brew install poppler

# Linux
sudo apt-get install poppler-utils

3. "OpenAI API hatası"

—.env dosyasında OPENAI_API_KEY değerini kontrol edin
—API anahtarınızın geçerli ve bakiyeli olduğundan emin olun

4. "Yüz eşleşmiyor" sorunu

—FACE_MATCH_THRESHOLD değerini artırın (örn: 0.6 → 0.7)
—Fotoğraf kalitesini kontrol edin
—Yüzün net görünür olduğundan emin olun

5. "Türkçe karakterler bozuk"

—Excel dosyasını UTF-8 encoding ile açın
—LibreOffice kullanıyorsanız import sırasında UTF-8 seçin

Log Seviyesi Ayarlama

python

# backend/main_pipeline.py içinde
import logging
logging.basicConfig(level=logging.DEBUG)  # Detaylı loglar için

📝 Versiyon Geçmişi

V2.1.0 (2024-12)

—✅ Excel'den fotoğraf kolonları kaldırıldı
—✅ Boş kayıtlara "OKUNAMAYANLAR klasöründe" notu eklendi
—✅ FOTO/TCFOTO boyutu 200x200 kare yapıldı
—✅ Yatay görsel desteği eklendi (sağ/sol kırpma fallback)
—✅ Vesikalıktan yüz kırpma ile TCFOTO kaydetme

V2.0.0 (2024-12)

—✅ Yüz eşleştirme sistemi eklendi
—✅ TCFOTO otomatik kayıt
—✅ Hybrid belge sınıflandırma
—✅ Önbellek sistemi
—✅ 3 kolonlu modern UI
—✅ Gevşetilmiş eşleştirme threshold'ları

V1.1.0 (2024-11)

—✅ Cache sistemi
—✅ PDF desteği
—✅ Excel şablon desteği

V1.0.0 (2024-10)

—🎉 İlk sürüm
—✅ Temel pasaport veri çıkarma
—✅ OpenAI GPT-4o entegrasyonu

🤝 Katkıda Bulunma

1.Bu repoyu fork edin
2.Feature branch oluşturun (git checkout -b feature/YeniOzellik)
3.Değişikliklerinizi commit edin (git commit -m 'Yeni özellik eklendi')
4.Branch'inizi push edin (git push origin feature/YeniOzellik)
5.Pull Request açın

📄 Lisans

Bu proje MIT lisansı altında lisanslanmıştır. Detaylar için LICENSE dosyasına bakın.

📞 İletişim

Sorularınız veya geri bildirimleriniz için:

—📧 Email: taha.cetmili@piramit.ai

Global Passport Extractor V2 ile pasaport işleme hiç bu kadar kolay olmamıştı! 🚀

Made with ❤️ by Piramit AI

</div>