kwantu/document_transcription
Domain:
digital infrastructureRecord type:
software
Creator:
kwa
Host:
An open-source pipeline for extracting structured identity information from South African Smart ID cards and ID Books using computer vision and OCR.
# ID Processing Pipeline (SA Documents)
> An open-source pipeline for extracting structured identity information from South African Smart ID cards and ID Books using computer vision and OCR.
---
## Overview
This pipeline accepts a South African identity document image (or PDF) via an API and returns a structured JSON
object containing key identity fields — including surname, forenames, and identity number. It supports
two document classes:
- **Smart ID Card** (class `0`)
- **ID Book** (class `1`)
The pipeline is designed to run on a development server and is published as open source for review as
a Digital Public Good (DPG). All model weights are included in this repository.
---
## Quickstart
```python
from app.core.pipeline import full_pipeline
result, is_valid = full_pipeline(
input_path="path/to/document.jpg",
dest_path="path/to/output/",
save_process=False
)
print(result)
print(is_valid)
```
```terminaloutput
{
"Surname": "SMITH",
"Names": "JOHN JAMES",
"Identity Number": "8001015009087"
}
True
```
Accepted input formats: `.jpg`, `.jpeg`, `.png`, `.pdf` (first page only).
---
## How It Works
The pipeline processes each document through six sequential stages:
1. **API Ingestion** — Document image is received and normalised. PDFs are rasterised at 200 DPI.
2. **Document Classification** — An EfficientNetB0 classifier assigns a document class (Smart ID or ID Book) to the image.
3. **Region Segmentation** — A class-specific YOLO11s model localises and crops the metadata strip and photo regions.
4. **Geometry Correction** — The metadata crop is reoriented, rescaled, and deskewed using OpenCV before being passed to the OCR engine.
5. **OCR Extraction** — Tesseract v5 extracts raw text from the preprocessed metadata region.
6. **Field Formatting** — Rule-based filtering cleans the raw OCR output and extracts key fields into a structured dictionary, which is saved as a JSON file …