# fh2019ustc/docscanner architecture

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

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

## Overview

##### Project type and purpose
- From the file tree and README, this is a research‐oriented, PyTorch-based document image rectification tool (“DocScanner”).
- It provides code for training two neural modules (Document Localization and Progressive Rectification), running inference on distorted images, and evaluating results via image metrics (MS-SSIM, LD) and OCR metrics.
- There is no web front‐end in the repo (the online demo is external), so the focus is on data pipelines, model modules, and evaluation scripts.

##### File structure
- Top-level scripts:
- inference.py – main entry for rectifying images
- update.py – likely orchestrates model updates or training runs
- extractor.py, seg.py – preprocessing/segmentation utilities
- OCR_eval.py – runs OCR evaluation on rectified output
- eval.m, evalUnwarp.m – MATLAB scripts for image quality metrics
- Model definitions: model.py
- Data folders: distorted/ (input examples), rectified/ (inference output)
- Configuration: requirements.txt (Python deps), ocr_img.txt (OCR test set indices)
- No dedicated “src” folder—scripts and modules are all at project root.

##### Key insights from README
- Two main neural modules:
a. Document Localization Module (trained on Doc3D + DTD)
b. Progressive Rectification Module (trained on background-excluded Doc3D)
- Inference pipeline: load pre-trained weights from model_pretrained/, read from distorted/, write to rectified/
- Evaluation pipelines:
- Image metrics via MATLAB interface (ssim_ld_eval.m)
- OCR metrics via pytesseract in OCR_eval.py
- External dependencies: PyTorch/GPU, MATLAB 2019a+, Tesseract 5.x, Google Drive for data/model storage.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        TD1[(Doc3D Dataset)]:::datastore
        TD2[(DTD Dataset)]:::datastore
        PRE1[/extractor.py/]:::orchestrator
        PRE2[/seg.py/]:::orchestrator
        NN["model.py\n(Neural Modules)"]:::compute
        TR[/update.py/]:::orchestrator
        MP[(model_pretrained/)]:::datastore
        TD1 -->|feeds| PRE1
        PRE1 -->|features| PRE2
        PRE2 -->|inputs| NN
        TD2 -->|augments| NN
        NN -->|trained weights| TR
        TR -->|stores| MP
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        DS[(distorted/)]:::datastore
        INF[/inference.py/]:::orchestrator
        LOC["Document\nLocalization Module"]:::compute
        REC["Progressive\nRectification Module"]:::compute
        OUT[(rectified/)]:::datastore
        DS -->|reads| INF
        INF -->|calls| LOC
        LOC -->|output| REC
        REC -->|writes| OUT
    end

    %% Evaluation Pipeline
    subgraph "Evaluation Pipeline"
        direction TB
        OUT -->|input| EVAL1[/eval.m/]:::orchestrator
        OUT -->|input| EVAL2[/evalUnwarp.m/]:::orchestrator
        OUT -->|input| OCR[/OCR_eval.py/]:::orchestrator
        OCR -->|uses| OCRIDX[(ocr_img.txt)]:::datastore
        EVAL1 -->|calls MATLAB| MATLAB[("MATLAB Engine")]:::external
        EVAL2 -->|calls MATLAB| MATLAB
        OCR -->|calls Tesseract| TESSA[("Tesseract OCR")]:::external
    end

    %% Dependencies
    subgraph "Environment & Dependencies"
        direction TB
        REQ[(requirements.txt)]:::datastore
        GD[("Google Drive")]:::external
    end

    %% External Links
    MP -->|hosted on| GD

    %% Click Events
    click PRE1 "https://github.com/fh2019ustc/docscanner/blob/main/extractor.py"
    click PRE2 "https://github.com/fh2019ustc/docscanner/blob/main/seg.py"
    click NN "https://github.com/fh2019ustc/docscanner/blob/main/model.py"
    click TR "https://github.com/fh2019ustc/docscanner/blob/main/update.py"
    click INF "https://github.com/fh2019ustc/docscanner/blob/main/inference.py"
    click DS "https://github.com/fh2019ustc/docscanner/tree/main/distorted/"
    click OUT "https://github.com/fh2019ustc/docscanner/tree/main/rectified/"
    click EVAL1 "https://github.com/fh2019ustc/docscanner/blob/main/eval.m"
    click EVAL2 "https://github.com/fh2019ustc/docscanner/blob/main/evalUnwarp.m"
    click OCR "https://github.com/fh2019ustc/docscanner/blob/main/OCR_eval.py"
    click OCRIDX "https://github.com/fh2019ustc/docscanner/blob/main/ocr_img.txt"
    click REQ "https://github.com/fh2019ustc/docscanner/blob/main/requirements.txt"
    click MP "https://github.com/fh2019ustc/docscanner/tree/main/model_pretrained/"

    %% Styles
    classDef datastore fill:#ADD8E6,stroke:#000;
    classDef compute fill:#90EE90,stroke:#000;
    classDef orchestrator fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
