# fh2019ustc/docgeonet architecture

> Architecture diagram of the GitHub repository fh2019ustc/docgeonet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fh2019ustc/docgeonet
- Repository: https://github.com/fh2019ustc/docgeonet

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Store
    Distorted["Distorted Images"]:::store
    click Distorted "https://github.com/fh2019ustc/docgeonet/tree/main/distorted/"

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        FeatureExtraction["extractor.py"]:::pre
        Segmentation["seg.py"]:::pre
        GeoEnc["position_encoding.py"]:::pre
    end
    click FeatureExtraction "https://github.com/fh2019ustc/docgeonet/blob/main/extractor.py"
    click Segmentation "https://github.com/fh2019ustc/docgeonet/blob/main/seg.py"
    click GeoEnc "https://github.com/fh2019ustc/docgeonet/blob/main/position_encoding.py"

    %% Core Model
    subgraph "Core Model"
        UNet["unet.py"]:::core
        Model["model.py"]:::core
    end
    click UNet "https://github.com/fh2019ustc/docgeonet/blob/main/unet.py"
    click Model "https://github.com/fh2019ustc/docgeonet/blob/main/model.py"

    %% Inference Engine
    InferenceEngine["inference.py"]:::core
    click InferenceEngine "https://github.com/fh2019ustc/docgeonet/blob/main/inference.py"

    %% Output Store
    recOutput["rec/ (Rectified Images)"]:::store
    click recOutput "https://github.com/fh2019ustc/docgeonet/tree/main/rec/"

    %% Evaluation Modules
    subgraph "Evaluation Modules"
        subgraph "Image Quality Metrics"
            SSIMDoc["ssim_ld_eval_DocUNet.m"]:::eval
            SSIMDIR["ssim_ld_eval_DIR300.m"]:::eval
            EvalUnwarp["evalUnwarp.m"]:::eval
        end
        subgraph "OCR Metrics"
            OCREvalDoc["OCR_eval_DocUNet.py"]:::eval
            OCREvalDIR["OCR_eval_DIR300.py"]:::eval
            OCRImgDoc["ocr_img_DocUNet.txt"]:::eval
            OCRImgDIR["ocr_img_DIR300.txt"]:::eval
        end
    end
    click SSIMDoc "https://github.com/fh2019ustc/docgeonet/blob/main/ssim_ld_eval_DocUNet.m"
    click SSIMDIR "https://github.com/fh2019ustc/docgeonet/blob/main/ssim_ld_eval_DIR300.m"
    click EvalUnwarp "https://github.com/fh2019ustc/docgeonet/blob/main/evalUnwarp.m"
    click OCREvalDoc "https://github.com/fh2019ustc/docgeonet/blob/main/OCR_eval_DocUNet.py"
    click OCREvalDIR "https://github.com/fh2019ustc/docgeonet/blob/main/OCR_eval_DIR300.py"
    click OCRImgDoc "https://github.com/fh2019ustc/docgeonet/blob/main/ocr_img_DocUNet.txt"
    click OCRImgDIR "https://github.com/fh2019ustc/docgeonet/blob/main/ocr_img_DIR300.txt"

    %% External Service
    Demo["Hugging Face Spaces"]:::external

    %% Connections
    Distorted -->|images| FeatureExtraction -->|features| Segmentation -->|masks| GeoEnc -->|geometry maps| UNet -->|features| Model -->|predictions| InferenceEngine -->|rectified image| recOutput
    recOutput -->|input images| SSIMDoc
    recOutput -->|input images| SSIMDIR
    recOutput -->|input images| EvalUnwarp
    recOutput -->|input images| OCREvalDoc
    recOutput -->|input images| OCREvalDIR
    recOutput -->|input images| OCRImgDoc
    recOutput -->|input images| OCRImgDIR
    Demo -->|API call| InferenceEngine

    %% Styles
    classDef store fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef pre fill:#a3c4f3,stroke:#333,stroke-width:1px;
    classDef core fill:#a5d6a7,stroke:#333,stroke-width:1px;
    classDef eval fill:#f9c694,stroke:#333,stroke-width:1px;
    classDef external fill:#d7b2e0,stroke:#333,stroke-width:1px;
```
