# belval/textrecognitiondatagenerator architecture

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

- Interactive diagram: https://gitdiagram.com/belval/textrecognitiondatagenerator
- Repository: https://github.com/belval/textrecognitiondatagenerator

## Overview

##### Project Type & Purpose
- This is a Python-based CLI tool *and* library whose sole purpose is to generate synthetic text images (Latin, non-Latin, handwritten) for OCR training. There is no “frontend” or “backend” in the web-app sense—rather, you have a CLI entrypoint plus a modular Python API.

##### File Structure Analysis
- Root level
- CI/CD: .circleci/, .github/workflows/, codecov.yml
- Packaging: setup.py, setup.cfg, MANIFEST.in, LICENSE, Dockerfile
- Tests: tests.py, tests/, tests/expected_results/
- Samples: samples/ (example images)
- trdg package
- Entry: run.py
- Core modules: background_generator.py, computer_text_generator.py, data_generator.py, distorsion_generator.py, string_generator.py, utils.py
- Generators: trdg/generators/{from_dict, from_random, from_strings, from_wikipedia}.py
- Resources:
– dicts/*.txt (word lists by language)
– fonts/{latin, cn, ja, ko, th}/
– images/ (background textures)
– handwritten_model/ (TensorFlow model files & translation.pkl)

##### Key README Insights
- Four generation strategies (dict, random, strings, wikipedia) all share the same transformation pipeline
- Optional handwritten pipeline powered by TensorFlow (if –hw flag is used)
- Uses Pillow for rendering, applies skew/blur/distortion, supports custom backgrounds and fonts
- Can be used as a CLI (`trdg …`) or as a Python module

a. Main Components
1. CLI Entrypoint
– trdg/run.py (parses args, dispatches to chosen Generator)
2. Python API
– `GeneratorFromDict`, `GeneratorFromRandom`, `GeneratorFromStrings`, `GeneratorFromWikipedia`
3. Resource Loaders
– Dictionary Loader (trdg/dicts/*.txt)
– Fonts Loader (trdg/fonts/*)
– Background Images Loader (trdg/images/)
4. Core Pipeline
– Text Generator (computer_text_generator.py or handwritten_text_generator.py)
– Background Generator (background_generator.py)
– Distortion Module (distorsion_generator.py)
– Blur/Skew Module (part of data_generator.py)
– Composite & Output Writer (saves image + label; supports masks)
5. Handwritten Pipeline (optional)
– TensorFlow Model (handwritten_model/)
6. Packaging & Tooling
– Docker Container (Dockerfile)
– CI/CD (CircleCI, GitHub Actions)
– Tests Suite (tests/)

b. Relationships & Data Flow
- CLI/API → Resource Loaders → Text Generator → Background Generator → Distortion → Blur/Skew → Composite → Output
- Handwritten branch: CLI/API + TensorFlow Model → same downstream pipeline
- Packaging/CI pipelines sit orthogonal to core data flow

c. Architectural Patterns & Principles
– Strategy Pattern: interchangeable “Generator” classes
– Pipeline Pattern: sequential transformation stages
– Resource-Driven: fonts, dicts, images are external pluggable assets
– Modular Test Harness: test files mirror expected outputs

d. Key Technologies & Libraries
– Python 3.x, Pillow (PIL), NumPy
– TensorFlow (only for handwritten)
– click/argparse (CLI argument parsing)
– Docker for containerization
– pytest/unittest for tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    title["TRDG System Architecture"]
    subgraph "Entrypoints" 
        direction TB
        Run["CLI Entrypoint (run.py)"]:::entry
        API_Dict["GeneratorFromDict"]:::entry
        API_Rand["GeneratorFromRandom"]:::entry
        API_Str["GeneratorFromStrings"]:::entry
        API_Wiki["GeneratorFromWikipedia"]:::entry
    end

    subgraph "Resource Loaders"
        direction TB
        DictLoader["Dictionary Loader"]:::loader
        FontLoader["Fonts Loader"]:::loader
        ImgLoader["Background Images Loader"]:::loader
        HWModelLoader["Handwritten Model Loader"]:::loader
    end

    subgraph "Core Pipeline"
        direction TB
        TextGen["ComputerTextGenerator\n(computer_text_generator.py)"]:::pipeline
        HandTextGen["HandwrittenTextGenerator\n(handwritten_text_generator.py)"]:::pipeline
        BackGen["BackgroundGenerator\n(background_generator.py)"]:::pipeline
        Distort["DistortionModule\n(distorsion_generator.py)"]:::pipeline
        BlurSkew["Blur/Skew & Composite\n(data_generator.py)"]:::pipeline
        Output["Composite & Output Writer"]:::pipeline
    end

    subgraph "Utilities"
        direction TB
        Strings["StringGenerator\n(string_generator.py)"]:::util
        Utils["Shared Utilities\n(utils.py)"]:::util
    end

    subgraph "Tooling & Packaging"
        direction TB
        Docker["Docker Container\n(Dockerfile)"]:::tool
        Packaging["Packaging Config\n(setup.py, setup.cfg, ...)"]:::tool
        CICD["CI/CD Configurations\n(.circleci, .github/workflows)"]:::tool
        TestsEntr["Test Suite Entrypoint\n(tests.py)"]:::tool
        TestsDir["Test Suite Directory\n(tests/)"]:::tool
    end

    %% Entrypoints to Resource Loaders and API to TextGen
    Run -->|args| DictLoader
    Run -->|args| FontLoader
    Run -->|args| ImgLoader
    Run -->|--hw flag| HWModelLoader
    Run -->|dispatch| API_Dict
    Run -->|dispatch| API_Rand
    Run -->|dispatch| API_Str
    Run -->|dispatch| API_Wiki

    API_Dict -->|"text data"| TextGen
    API_Rand -->|"text data"| TextGen
    API_Str -->|"text data"| TextGen
    API_Wiki -->|"text data"| TextGen

    %% Resources feeding loaders
    DictLoader -->|reads| Dicts
    FontLoader -->|loads| Fonts
    ImgLoader -->|loads| Images
    HWModelLoader -.->|loads| HWModel

    %% Pipeline flow
    TextGen --> BackGen
    HandTextGen -.-> BackGen
    BackGen --> Distort
    Distort --> BlurSkew
    BlurSkew --> Output

    %% Utilities
    Strings --> TextGen
    Utils --> TextGen
    Utils --> BackGen
    Utils --> Distort
    Utils --> BlurSkew

    %% Tooling connections
    Docker --> Run
    CICD -.-> Run
    CICD -.-> Packaging
    CICD -.-> TestsEntr
    TestsEntr --> TestsDir
    TestsEntr --> Run
    TestsEntr --> TextGen
    TestsEntr --> BackGen

    %% External Resources
    Dicts["dictonaries (*.txt)"]:::resource
    Fonts["fonts/"]:::resource
    Images["images/"]:::resource
    HWModel["handwritten_model/"]:::resource

    %% Click events
    click Run "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/run.py"
    click API_Dict "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/generators/from_dict.py"
    click API_Rand "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/generators/from_random.py"
    click API_Str "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/generators/from_strings.py"
    click API_Wiki "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/generators/from_wikipedia.py"
    click TextGen "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/computer_text_generator.py"
    click HandTextGen "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/handwritten_text_generator.py"
    click BackGen "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/background_generator.py"
    click Distort "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/distorsion_generator.py"
    click BlurSkew "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/data_generator.py"
    click Strings "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/string_generator.py"
    click Utils "https://github.com/belval/textrecognitiondatagenerator/blob/master/trdg/utils.py"
    click Dicts "https://github.com/belval/textrecognitiondatagenerator/tree/master/trdg/dicts/"
    click Fonts "https://github.com/belval/textrecognitiondatagenerator/tree/master/trdg/fonts/"
    click Images "https://github.com/belval/textrecognitiondatagenerator/tree/master/trdg/images/"
    click HWModel "https://github.com/belval/textrecognitiondatagenerator/tree/master/trdg/handwritten_model/"
    click Docker "https://github.com/belval/textrecognitiondatagenerator/tree/master/Dockerfile"
    click Packaging "https://github.com/belval/textrecognitiondatagenerator/blob/master/setup.py"
    click CICD "https://github.com/belval/textrecognitiondatagenerator/blob/master/.circleci/config.yml"
    click TestsEntr "https://github.com/belval/textrecognitiondatagenerator/blob/master/tests.py"
    click TestsDir "https://github.com/belval/textrecognitiondatagenerator/tree/master/tests/"

    %% Styles
    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef loader fill:#bbf,stroke:#333,stroke-width:1px
    classDef pipeline fill:#afa,stroke:#333,stroke-width:1px
    classDef util fill:#ffeb3b,stroke:#333,stroke-width:1px
    classDef resource fill:#ddd,stroke:#333,stroke-width:1px
    classDef tool fill:#fdd,stroke:#333,stroke-width:1px
```
