Metadata-Version: 2.4 Name: akshara-ocr Version: 0.3.0 Summary: Local-first Indonesian Identity Document OCR Framework (KTP, SIM, Paspor, STNK) Author: ID-Doc OCR Contributors License: MIT Keywords: ocr,ktp,sim,paspor,stnk,indonesia,tesseract,opencv,computer-vision,pydantic Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.11 Classifier: Programming Language :: Python :: 3.12 Classifier: Topic :: Scientific/Engineering :: Image Recognition Requires-Python: >=3.11 Description-Content-Type: text/markdown License-File: LICENSE Requires-Dist: opencv-python-headless>=4.8.0 Requires-Dist: numpy>=1.24.0 Requires-Dist: pillow>=10.0.0 Requires-Dist: pytesseract>=0.3.10 Requires-Dist: pydantic>=2.0.0 Provides-Extra: onnx Requires-Dist: onnxruntime>=1.15.0; extra == "onnx" Requires-Dist: rapidocr-onnxruntime>=1.3.0; extra == "onnx" Provides-Extra: server Requires-Dist: fastapi>=0.100.0; extra == "server" Requires-Dist: uvicorn>=0.22.0; extra == "server" Requires-Dist: python-multipart>=0.0.6; extra == "server" Provides-Extra: dev Requires-Dist: pytest>=7.0.0; extra == "dev" Requires-Dist: httpx>=0.24.0; extra == "dev" Provides-Extra: all Requires-Dist: onnxruntime>=1.15.0; extra == "all" Requires-Dist: rapidocr-onnxruntime>=1.3.0; extra == "all" Requires-Dist: fastapi>=0.100.0; extra == "all" Requires-Dist: uvicorn>=0.22.0; extra == "all" Requires-Dist: python-multipart>=0.0.6; extra == "all" Requires-Dist: pytest>=7.0.0; extra == "all" Requires-Dist: httpx>=0.24.0; extra == "all" Dynamic: license-file # ID-Doc OCR 🇮🇩 [![PyPI Version](https://img.shields.io/pypi/v/akshara-ocr.svg)](https://pypi.org/project/akshara-ocr/) [![CI Status](https://github.com/your-username/akshara-ocr/actions/workflows/ci.yml/badge.svg)](https://github.com/your-username/akshara-ocr/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/) **ID-Doc OCR** adalah framework Python open-source *local-first* untuk mengekstraksi data terstruktur dari berbagai dokumen identitas Indonesia (**KTP, SIM, Paspor, STNK**) menjadi model data **Pydantic V2 (Type-Safe)** dan JSON terformat. --- ## 🚀 Fitur Utama (v0.2.0) - **Multi-Dokumen Identitas**: Ekstraksi KTP, SIM (Surat Izin Mengemudi), Paspor Indonesia, dan STNK. - **Auto-Detection (`doc_type="auto"`)**: Otomatis mengenali jenis dokumen berbasis analisis kata kunci OCR mentah. - **Auto-Cropping & Perspective Transform**: Deteksi 4 sudut fisik kartu (`cv2.approxPolyDP`) & perataan posisi miring (`cv2.warpPerspective`) dengan *graceful fallback*. - **Validasi Matematika NIK KTP**: Validasi struktur 16-digit NIK (Provinsi, Kabupaten, tanggal lahir DDMMYY dengan offset wanita $+40$) & koreksi otomatis typo OCR (`O->0`, `I->1`, `B->8`). - **Pydantic V2 Schemas**: Output data tervalidasi tipe datanya (`KTPSchema`, `SIMSchema`, `PasporSchema`, `STNKSchema`). - **Zero-Dependency ONNX Fallback Engine**: Pilihan engine ringan *on-device* via ONNX Runtime tanpa perlu menginstal binary C++ Tesseract di OS. - **Built-in REST API Microservice**: Server FastAPI siap pakai via CLI (`akshara-ocr serve --port 8000`) dengan OpenAPI Swagger docs. --- ## 🛡️ Privacy-by-Design & Kepatuhan Hukum (UU PDP) > [!IMPORTANT] > **Pernyataan Privasi & Kepatuhan UU PDP (UU No. 27 Tahun 2022):** > 1. **100% Local-First & In-Memory**: Seluruh pemrosesan gambar dan ekstraksi data berjalan secara lokal di perangkat/server pengguna. **TIDAK ADA** data atau foto yang diunggah ke server cloud pihak ketiga. > 2. **No Logging by Default**: Gambar input dan hasil ekstraksi JSON tidak pernah ditulis ke disk atau disimpan dalam log file secara otomatis. > 3. **BUKAN Alat Verifikasi Identitas Resmi**: Library ini adalah alat bantu ekstraksi teks (*text extraction helper*), **BUKAN** alat verifikasi identitas resmi/legal atau deteksi keaslian dokumen (*liveness/fraud detection*). Pengembang dan pengguna library bertanggung jawab penuh atas kepatuhan terhadap **UU Pelindungan Data Pribadi (UU PDP)** saat mengimplementasikan library ini pada aplikasi produksi. > 4. **Penggunaan Data Uji Sintetis**: Seluruh pengujian dan pengembangan WAJIB menggunakan data dummy/sintetis fiktif. Dilarang menggunakan foto KTP/SIM/Paspor asli siapa pun untuk testing. --- ## 🎯 Panduan Confidence Score & Manual Review > [!TIP] > **Rekomendasi Verifikasi Produksi:** > Library ini menyediakan metadata tingkat keyakinan OCR per field pada `meta.confidence_per_field`. > **Aturan Praktis:** Field dengan *confidence score* **di bawah 70%** disarankan untuk **diverifikasi secara manual oleh operator/pengguna (human-in-the-loop)** sebelum disimpan ke database produksi aplikasi Anda. --- ## 📦 Instalasi ### 1. Install Package Python ```bash # Instalasi standar (Tesseract engine) pip install akshara-ocr # Instalasi lengkap (termasuk ONNX engine & REST API server) pip install "akshara-ocr[all]" ``` ### 2. Prasyarat Binary Tesseract OCR (Default Engine) Jika menggunakan default Tesseract engine: * **Windows**: `winget install --id UB-Mannheim.TesseractOCR -e` * **Linux (Ubuntu/Debian)**: `sudo apt-get install -y tesseract-ocr tesseract-ocr-ind` * **macOS**: `brew install tesseract` *(Catatan: Jika menginstal versi `pip install akshara-ocr[onnx]`, Anda tidak perlu menginstal binary Tesseract di OS!)* --- ## 💻 Contoh Penggunaan Python SDK ```python from akshara_ocr import IDDocOCR, KTPSchema # Inisialisasi SDK dengan auto-detection tipe dokumen sdk = IDDocOCR(doc_type="auto", auto_crop=True) # Ekstraksi dari path gambar (bisa juga dari bytes atau numpy ndarray) result: KTPSchema = sdk.extract("path/to/ktp_photo.jpg") # Output Pydantic V2 Schema & JSON print(result.nik) # "3573012304950001" print(result.nik_valid) # True print(result.provinsi_code) # "35" # Convert ke formatted JSON string print(result.model_dump_json(indent=2, by_alias=True)) ``` --- ## 🌐 CLI & REST API Microservice ### Ekstraksi Langsung via Terminal (CLI) ```bash # Ekstraksi KTP akshara-ocr path/to/ktp_photo.png # Simpan ke file JSON akshara-ocr path/to/ktp_photo.png -o result.json ``` ### Menjalankan REST Microservice Server ```bash # Jalankan FastAPI REST Server pada port 8000 akshara-ocr serve --port 8000 ``` Akses **Interactive OpenAPI Swagger Documentation** di browser pada: `http://127.0.0.1:8000/docs` --- ## 📜 Lisensi Lisensi open-source [MIT License](LICENSE).