# robertknight/ocrs-models architecture

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

- Interactive diagram: https://gitdiagram.com/robertknight/ocrs-models
- Repository: https://github.com/robertknight/ocrs-models

## Overview

##### Main Components
- OCR Models (ocrs_models directory): This includes modules for:
- Text Detection (train_detection.py, datasets modules)
- Layout Analysis (train_layout.py, eval_layout.py, and corresponding dataset utilities)
- Text Recognition (train_rec.py)
- Evaluation processes (eval_detection.py, eval_layout.py)
- Postprocessing for predictions (postprocess.py)
- Model export functionality (export to ONNX, RTen, etc.)
- Data/Dataset Pipelines:
- Datasets support (datasets submodules: ddi100.py, hiertext.py, web_layout.py, util.py)
- Integration with open datasets such as HierText (as mentioned in README)
- Layout Scraper (layout-scraper directory):
- Main tool (layout-scraper.ts)
- Utility scripts (random-wiki-url-generator.js)
- URL lists input (url-lists directory with urls.txt)
- Supplementary Components:
- Documentation (docs folder with training instructions)
- CI/CD and configuration (Makefile, GitHub workflows, mypy.ini, pyproject.toml)

##### Relationships and Interactions
- Data Flow:
- The layout scraper is likely used to acquire real-world web data/HTML layouts that can be fed into the dataset pipelines.
- The dataset modules process raw data (from sources like HierText and potentially scraped data) to produce training examples.
- Training Pipeline:
- Each model (text detection, layout analysis, and text recognition) has its own training script and is fed processed dataset content.
- Postprocessing and evaluation modules interact with the models to validate outputs and fine-tune performance.
- Integration/Export:
- After training, models can be exported to different formats (ONNX, RTen) for downstream integration with the Ocrs OCR engine.
- CI/CD:
- GitHub workflows and the Makefile ensure testing, linting, and building of the system components.

##### Architectural Patterns and Design Principles
- Modular Design:
- Separation between data ingestion/scraping (layout-scraper) and core model training/evaluation (ocrs_models).
- Pipeline Architecture:
- Each stage—from dataset preparation, training, evaluation, to export—is isolated for clarity.
- Extensibility:
- The design allows for the addition of more datasets or model variations since different processing scripts handle each stage.
- Technology Mix:
- Python with PyTorch for model training.
- TypeScript/Node.js for the layout scraper.
- External libraries (ONNX, RTen) used for model export.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% OCR Models Pipeline Subgraph
    subgraph "OCR Models Pipeline"
        OM["OCR Models Pipeline"]:::python
        DS["Dataset Modules"]:::python
        TD["Text Detection Model"]:::python
        LA_T["Layout Analysis Training"]:::python
        LA_E["Layout Analysis Evaluation"]:::python
        TR["Text Recognition Model"]:::python
        EP["Evaluation (Detection)"]:::python
        PP["Postprocessing"]:::python
        ME["Model Export (ONNX/RTen)"]:::python
    end

    %% Layout Scraper Subgraph
    subgraph "Layout Scraper"
        LS["Layout Scraper Main"]:::nodejs
        LU["Layout Scraper Utility"]:::nodejs
        URL["URL Lists"]:::nodejs
    end

    %% Support Subgraph (Documentation and CI/CD)
    subgraph "Support"
        DOC["Documentation"]:::support
        subgraph "CI/CD & Config"
            CI1["CI Workflow"]:::support
            CI2["Makefile"]:::support
            CI3["mypy.ini"]:::support
            CI4["pyproject.toml"]:::support
        end
    end

    %% Relationships within OCR Models Pipeline
    OM --> DS
    DS -->|"feeds data to"| TD
    DS -->|"feeds data to"| LA_T
    DS -->|"feeds data to"| TR

    TD -->|"triggers"| EP
    LA_T -->|"triggers"| LA_E
    TR -->|"triggers"| EP

    EP -->|"processes"| PP
    PP -->|"exports to"| ME

    %% Interaction between Layout Scraper and OCR Models Pipeline
    LS -->|"scrapes"| DS

    %% CI/CD & Config interactions with Training Components
    CI1 -->|"triggers"| TD
    CI1 -->|"triggers"| LA_T
    CI1 -->|"triggers"| TR
    CI2 -->|"configures"| TD
    CI3 -->|"configures"| LA_T
    CI4 -->|"configures"| TR

    %% Documentation connected to CI/CD (support linkage)
    DOC --- CI1

    %% Click Events for OCR Models Pipeline
    click OM "https://github.com/robertknight/ocrs-models/tree/main/ocrs_models/"
    click DS "https://github.com/robertknight/ocrs-models/tree/main/ocrs_models/datasets/"
    click TD "https://github.com/robertknight/ocrs-models/blob/main/ocrs_models/train_detection.py"
    click LA_T "https://github.com/robertknight/ocrs-models/blob/main/ocrs_models/train_layout.py"
    click LA_E "https://github.com/robertknight/ocrs-models/blob/main/ocrs_models/eval_layout.py"
    click TR "https://github.com/robertknight/ocrs-models/blob/main/ocrs_models/train_rec.py"
    click EP "https://github.com/robertknight/ocrs-models/blob/main/ocrs_models/eval_detection.py"
    click PP "https://github.com/robertknight/ocrs-models/blob/main/ocrs_models/postprocess.py"

    %% Click Events for Layout Scraper
    click LS "https://github.com/robertknight/ocrs-models/blob/main/layout-scraper/layout-scraper.ts"
    click LU "https://github.com/robertknight/ocrs-models/blob/main/layout-scraper/tools/random-wiki-url-generator.js"
    click URL "https://github.com/robertknight/ocrs-models/blob/main/layout-scraper/url-lists/urls.txt"

    %% Click Events for Support Components
    click DOC "https://github.com/robertknight/ocrs-models/tree/main/docs/"
    click CI1 "https://github.com/robertknight/ocrs-models/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/robertknight/ocrs-models/tree/main/Makefile"
    click CI3 "https://github.com/robertknight/ocrs-models/blob/main/mypy.ini"
    click CI4 "https://github.com/robertknight/ocrs-models/blob/main/pyproject.toml"

    %% Style definitions
    classDef python fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef nodejs fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef support fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
```
