How fh2019ustc/docgeonet works
Project Type and Purpose
• DocGeoNet is a research-oriented, Python-based tool for document image rectification.
• It provides scripts for inference, evaluation (image metrics & OCR metrics), and integrates a pretrained deep model (DocGeoNet).
• No traditional frontend; it’s a CLI/library with optional demo on Hugging Face Spaces.
File Structure
Top-level items:
• inference.py – loads pretrained model, processes images, writes rectified output.
• model.py, unet.py, position_encoding.py – define the neural network architecture and geometric feature encoding.
• extractor.py, seg.py – preprocessing modules for feature extraction / segmentation.
• distorted/ → input images; rec/ → rectified output.
• OCR_eval_*.py, ocr_img_*.txt – OCR-based evaluation scripts & image lists.
• ssim_ld_eval_*.m, evalUnwarp.m – MATLAB scripts for MS-SSIM & LD metrics.
• requirements.txt – Python dependencies (PyTorch, OpenCV, pytesseract, etc.).
Extract Additional Insights from README
• Demo pipeline on Hugging Face Spaces (CPU-based).
• Training uses external Doc3D dataset (training code not in this tree).
• Evaluation on two benchmarks (DocUNet & DIR300) using MATLAB and OCR scripts.
Main Components & Relationships
A. Data Ingestion
• “Distorted Images” (folder distorted/)
↓
B. Preprocessing Layer
• extractor.py – feature detection
• seg.py – segmentation / mask generation
• position_encoding.py – encode geometric priors
↓
C. Core Model (DocGeoNet)
• unet.py + model.py implementing geometric-representation network
• Built with PyTorch
↓
D. Inference Engine
• inference.py loads checkpoints from model_pretrained/, runs forward pass, applies warping to produce rectified images
↓
E. Output Store
• Writes corrected images to rec/
↓
F. Evaluation Modules (optional, parallel paths)
1. Image Quality Metrics (MATLAB)
– ssim_ld_eval_DocUNet.m, ssim_ld_eval_DIR300.m, evalUnwarp.m
2. OCR Metrics (Python)
– OCR_eval_DocUNet.py, OCR_eval_DIR300.py using tesseract & lists in ocr_img_*.txt
G. External Demo Service (optional)
• Hugging Face Spaces interface calls the same inference pipeline via API
Architectural Patterns & Design Principles
• Pipeline pattern: sequential preprocessing → model inference → postprocessing/evaluation.
• Modularity: separate scripts for data prep (extractor.py, seg.py), modeling (model.py, unet.py), inference (inference.py), evaluation (MATLAB & OCR).
• Extensibility: new modules (e.g., new evaluation metrics, alternative models) can slot into this pipeline.
Technology Stack
• Python (3.x), PyTorch, OpenCV, NumPy, Tesseract (OCR)
• MATLAB 2019a for SSIM & LD metrics
• External dataset: Doc3D for training; DocUNet / DIR300 for evaluation
• Demo hosting: Hugging Face Spaces (CPU backend)