# sanster/text_renderer architecture

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

- Interactive diagram: https://gitdiagram.com/sanster/text_renderer
- Repository: https://github.com/sanster/text_renderer

## Overview

##### Project type and purpose
- This is a standalone CLI tool (“Text Renderer”) for generating synthetic text images (both Latin and non-Latin) to train OCR models. It reads text corpora and font data, applies layout and visual effects, and writes out image files plus labels.

##### High-level architecture overview
- The system is organized around a single main entry point (main.py) that wires together:
- An argument/config loader
- A data layer (fonts, char lists, corpora)
- A modular text-generation pipeline (corpus selection → line creation → effects → rendering)
- An output writer
- Optional GPU acceleration is provided via a compiled Cython/OpenCV module.

##### Main components and their relationships
A. CLI & Configuration
- parse_args.py / help_runner.py
- libs/config.py reads YAML (configs/default.yaml or user-supplied)
→ produces a Config object used by downstream modules

B. Data Layer (read-only resources)
- data/chars (character files)
- data/corpus (raw text files)
- data/fonts (directory trees for each language)
- data/fonts_list (precomputed font lists)

C. Core Pipeline (under textrenderer/)
1) Corpus module (textrenderer/corpus/*.py)
- Chooses/generates text strings based on language or list rules
2) Remapper (textrenderer/remaper.py)
- Applies strict-mode filtering or character remapping
3) Liner (textrenderer/liner.py)
- Builds text lines or paragraphs, handling spacing, wrap, alignment
4) Noiser (textrenderer/noiser.py)
5) Renderer (textrenderer/renderer.py)
- Renders final image: either via PIL/OpenCV CPU path or GPU path

D. GPU Acceleration (optional)
- libs/gpu/GpuWrapper.pyx + setup.py
- Requires prebuilt OpenCV with CUDA support
- Renderer selects GPU path when “--gpu” is passed

E. Output Writer
- main.py writes images + labels to output/<config_name>/

F. Utility Scripts & Tools (separate helpers)
- tools/*.py (tfrecord maker, font checker, balancer)
- gists/*.py (small demo scripts)

##### Architectural patterns and principles
- Pipeline pattern: a linear sequence of text/image transformations
- Modular separation: each effect or data source lives in its own module
- Configuration-driven: effects and fractions are defined in YAML
- Optional acceleration: pluggable GPU wrapper

- CLI & Config Loader
- Data Store (Chars, Corpora, Fonts)
- Corpus Generator
- Remapper
- Liner
- Noiser
- Renderer (CPU/OpenCV & GPU/CUDA)
- Output Writer
- (Optional) Tools & Gists

- CLI → Config Loader → Core Pipeline
- Core Pipeline stages in sequence (Corpus → Remap → Liner → Noiser → Renderer)
- Renderer → Output Writer → File System

- Parser: argparse (parse_args.py)
- Config: PyYAML (requirements.txt)
- Pipeline: Python modules under textrenderer/
- Rendering: PIL, OpenCV (cv2), optional Cython/C++ GPU wrapper
- Build: setup.py for libs/gpu

d. Data flows:
- Read-only from data/ → pipeline
- Write-only to output/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Configuration
    subgraph "CLI & Configuration"
        CLI["Arg Parser\nparse_args.py"]:::config
        Help["Help Runner\nhelp_runner.py"]:::config
        ConfigLoader["Config Loader\nlibs/config.py"]:::config
        DefaultYAML["Default Config\nconfigs/default.yaml"]:::config
        TestYAML["Test Config\nconfigs/test.yaml"]:::config
    end

    %% Data Layer
    subgraph "Data Layer"
        Chars["Chars\n(data/chars/)"]:::data
        EngChars["eng.txt"]:::data
        ChnChars["chn.txt"]:::data
        CorpusData["Corpora\n(data/corpus/)"]:::data
        Hitchhiker["The Hitchhiker's Guide...\n.txt"]:::data
        Fonts["Fonts\n(data/fonts/)"]:::data
        EngFonts["eng/"]:::data
        ChnFontFile["msyh.ttc"]:::data
        FontsList["Fonts List\n(data/fonts_list/)"]:::data
        EngFontList["eng.txt"]:::data
        ChnFontList["chn.txt"]:::data
    end

    %% Core Pipeline
    subgraph "Core Pipeline"
        Corpus["1. Corpus Generator\n(textrenderer/corpus)"]:::process
        Remap["2. Remapper\n(textrenderer/remaper.py)"]:::process
        Liner["3. Liner\n(textrenderer/liner.py)"]:::process
        Noiser["4. Noiser\n(textrenderer/noiser.py)"]:::process
        RendererModule["5. Renderer\n(textrenderer/renderer.py)"]:::process
    end

    %% GPU Acceleration
    subgraph "GPU Acceleration (Optional)"
        GPUWrapperPXD["GpuWrapper.pxd"]:::gpu
        GPUWrapperPYX["GpuWrapper.pyx"]:::gpu
        Pyopencv["pyopencv_converter.cpp"]:::gpu
        GpuSetup["setup.py"]:::gpu
    end

    %% Output Writer
    Output["Output Writer\nmain.py"]:::output

    %% Utilities
    subgraph "Utilities & Tools"
        ToolsSub["Tools"]:::util
        Balancer["balancer.py"]:::util
        CharCheck["char_frequency_check.py"]:::util
        FontCheck["check_font.py"]:::util
        TFRecCheck["check_tfrecord.py"]:::util
        MakeTFRec["make_tfrecord.py"]:::util
        GistsSub["Gists"]:::util
        CV2Remap["cv2_remap.py"]:::util
        DrawText["draw_transparent_text.py"]:::util
        Outline["outline.py"]:::util
        Seamless["seamlessClone.py"]:::util
    end

    %% Data relationships
    CLI -->|reads YAML| ConfigLoader
    ConfigLoader -->|loads| DefaultYAML
    ConfigLoader -->|loads| TestYAML
    CLI -->|parses args| Help

    Chars --> EngChars
    Chars --> ChnChars
    CorpusData --> Hitchhiker
    Fonts --> EngFonts
    EngFonts --> ChnFontFile
    FontsList --> EngFontList
    FontsList --> ChnFontList

    %% Pipeline flow
    ConfigLoader -->|provides config| Corpus
    Chars -->|reads chars| Corpus
    CorpusData -->|reads corpus| Corpus
    FontsList -->|reads list| Corpus
    Corpus -->|generates text| Remap
    Remap -->|filters/remaps| Liner
    Liner -->|builds lines| Noiser
    Noiser -->|adds noise| RendererModule

    RendererModule -->|CPU path| Output
    RendererModule -->|GPU path| GPUWrapperPYX
    GPUWrapperPYX --> Pyopencv
    GPUWrapperPYX --> GPUWrapperPXD
    GPUWrapperPXD --> GpuSetup

    Output -->|writes images/labels| FS["File System\n(output/<config>)"]:::output

    %% Utilities flow
    CLI -.-> Balancer
    CLI -.-> CharCheck
    CLI -.-> FontCheck
    CLI -.-> TFRecCheck
    CLI -.-> MakeTFRec
    CLI -.-> CV2Remap
    CLI -.-> DrawText
    CLI -.-> Outline
    CLI -.-> Seamless

    %% Click Events
    click CLI "https://github.com/sanster/text_renderer/blob/master/parse_args.py"
    click Help "https://github.com/sanster/text_renderer/blob/master/help_runner.py"
    click ConfigLoader "https://github.com/sanster/text_renderer/blob/master/libs/config.py"
    click DefaultYAML "https://github.com/sanster/text_renderer/blob/master/configs/default.yaml"
    click TestYAML "https://github.com/sanster/text_renderer/blob/master/configs/test.yaml"

    click EngChars "https://github.com/sanster/text_renderer/blob/master/data/chars/eng.txt"
    click ChnChars "https://github.com/sanster/text_renderer/blob/master/data/chars/chn.txt"
    click Hitchhiker "https://github.com/sanster/text_renderer/blob/master/data/corpus/The Hitchhiker's Guide to the Galaxy.txt"
    click EngFonts "https://github.com/sanster/text_renderer/tree/master/data/fonts/eng/"
    click ChnFontFile "https://github.com/sanster/text_renderer/blob/master/data/fonts/chn/msyh.ttc"
    click EngFontList "https://github.com/sanster/text_renderer/blob/master/data/fonts_list/eng.txt"
    click ChnFontList "https://github.com/sanster/text_renderer/blob/master/data/fonts_list/chn.txt"

    click Corpus "https://github.com/sanster/text_renderer/blob/master/textrenderer/corpus/corpus.py"
    click Corpus "https://github.com/sanster/text_renderer/blob/master/textrenderer/corpus/eng_corpus.py"
    click Corpus "https://github.com/sanster/text_renderer/blob/master/textrenderer/corpus/chn_corpus.py"
    click Corpus "https://github.com/sanster/text_renderer/blob/master/textrenderer/corpus/list_corpus.py"
    click Corpus "https://github.com/sanster/text_renderer/blob/master/textrenderer/corpus/random_corpus.py"
    click Corpus "https://github.com/sanster/text_renderer/blob/master/textrenderer/corpus/corpus_utils.py"
    click Remap "https://github.com/sanster/text_renderer/blob/master/textrenderer/remaper.py"
    click Liner "https://github.com/sanster/text_renderer/blob/master/textrenderer/liner.py"
    click Noiser "https://github.com/sanster/text_renderer/blob/master/textrenderer/noiser.py"
    click RendererModule "https://github.com/sanster/text_renderer/blob/master/textrenderer/renderer.py"

    click GPUWrapperPYX "https://github.com/sanster/text_renderer/blob/master/libs/gpu/GpuWrapper.pyx"
    click GPUWrapperPXD "https://github.com/sanster/text_renderer/blob/master/libs/gpu/GpuWrapper.pxd"
    click Pyopencv "https://github.com/sanster/text_renderer/blob/master/libs/gpu/pyopencv_converter.cpp"
    click GpuSetup "https://github.com/sanster/text_renderer/blob/master/libs/gpu/setup.py"

    click Output "https://github.com/sanster/text_renderer/blob/master/main.py"

    click Balancer "https://github.com/sanster/text_renderer/blob/master/tools/balancer.py"
    click CharCheck "https://github.com/sanster/text_renderer/blob/master/tools/char_frequency_check.py"
    click FontCheck "https://github.com/sanster/text_renderer/blob/master/tools/check_font.py"
    click TFRecCheck "https://github.com/sanster/text_renderer/blob/master/tools/check_tfrecord.py"
    click MakeTFRec "https://github.com/sanster/text_renderer/blob/master/tools/make_tfrecord.py"

    click CV2Remap "https://github.com/sanster/text_renderer/blob/master/gists/cv2_remap.py"
    click DrawText "https://github.com/sanster/text_renderer/blob/master/gists/draw_transparent_text.py"
    click Outline "https://github.com/sanster/text_renderer/blob/master/gists/outline.py"
    click Seamless "https://github.com/sanster/text_renderer/blob/master/gists/seamlessClone.py"

    %% Styles
    classDef config fill:#D0E1FF,stroke:#0366D6,stroke-width:2px
    classDef data fill:#DFFFD0,stroke:#228B22,stroke-width:2px
    classDef process fill:#FFE4B5,stroke:#DAA520,stroke-width:2px
    classDef gpu fill:#FFD0D0,stroke:#D83434,stroke-width:2px
    classDef output fill:#E8D0FF,stroke:#8A2BE2,stroke-width:2px
    classDef util fill:#F0F0F0,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5
```
