文本渲染器

生成用于训练深度学习 OCR 模型的文本行图像（例如 CRNN）。

目录

• 特性
• 先决条件
• 安装
• 运行示例
• 快速入门
• 使用 Albumentations 效果
• 所有效果/布局示例
• 贡献
• 字体查看器
• 构建文档
• 引用 text_renderer

特性

• 模块化设计。您可以轻松添加不同的组件：语料库、效果、布局。
• 与 Albumentations 集成，以实现图像增强效果。
• 支持在图像上使用不同效果渲染多个语料库。布局 负责多个语料库之间的排版。
• 支持在渲染过程的不同阶段应用效果：语料库效果、布局效果、渲染效果。
• 生成竖排文本。
• 支持生成与 PaddleOCR 兼容的 lmdb 数据集，详情请参阅 数据集。
• 提供一个网页字体查看器。
• 语料库采样器：有助于实现字符平衡。

文档

先决条件

• Python 3.10+
• 操作系统：Linux、macOS 或 Windows

安装

git clone https://github.com/oh-my-ocr/text_renderer
cd text_renderer
uv sync

或者使用 pip：

pip install '.[tools]'   # 包含字体查看器和实用脚本
pip install '.[docs]'    # 包括 Sphinx 用于构建文档

运行示例

运行以下命令以使用示例数据生成图像：

uv run python main.py \
    --config example_data/example.py \
    --dataset img \
    --num_processes 2 \
    --log_period 10

Windows 用户注意： 请使用 ^ 代替 \ 来换行，或将命令写成一行：

uv run python main.py --config example_data/example.py --dataset img --num_processes 2 --log_period 10

数据将生成在 example_data/output 目录中。一个 labels.json 文件包含所有标注，格式如下：

{
  "labels": {
    "000000000": "test",
    "000000001": "text2"
  },
  "sizes": {
    "000000000": [
      120,
      32 
    ],
    "000000001": [
      128,
      32 
    ]
  },
  "num-samples": 2
}

您也可以使用 --dataset lmdb 将图像存储在 lmdb 文件中，lmdb 文件包含以下键：

• num-samples
• image-000000000
• label-000000000
• size-000000000

您可以查看配置文件 example_data/example.py，了解如何使用 text_renderer， 或按照 快速入门 学习如何设置配置。

快速入门

准备文件资源

• 字体文件：.ttf、.otf、.ttc
• 任意尺寸的背景图像，可以来自您的业务场景，也可以来自公开可用的数据集（如 COCO、VOC）。
• 语料库：text_renderer 提供了多种 文本采样方法，要使用这些方法，您需要从两个方面考虑语料库的准备：

1. 语料库必须是您希望进行 OCR 识别的目标语言。
2. 语料库应符合您的实际业务需求，例如教育领域、医疗领域等。

• 字符集文件【可选但建议】：现实场景中的 OCR 模型（如 CRNN）通常只支持有限的字符集， 因此在数据生成过程中最好过滤掉字符集之外的字符。您可以通过设置 chars_file 参数来实现这一点。

您可以从这里下载为本次“快速入门”预先准备好的文件资源：

• simsun.ttf
• background.png
• eng_text.txt

请将这些资源文件保存在同一目录下：

workspace
├── bg
│ └── background.png
├── corpus
│ └── eng_text.txt
└── font
    └── simsun.ttf

创建配置文件

在 workspace 目录下创建一个名为 config.py 的文件。每个配置文件必须包含一个 configs 变量，该变量是一个由 GeneratorCfg 组成的列表。

完整的配置文件如下：

import os
from pathlib import Path

from text_renderer.effect import *
from text_renderer.corpus import *
from text_renderer.config import (
    RenderCfg,
    NormPerspectiveTransformCfg,
    GeneratorCfg,
    SimpleTextColorCfg,
)

CURRENT_DIR = Path(os.path.abspath(os.path.dirname(__file__)))


def story_data():
    return GeneratorCfg(
        num_image=10,
        save_dir=CURRENT_DIR / "output",
        render_cfg=RenderCfg(
            bg_dir=CURRENT_DIR / "bg",
            height=32,
            perspective_transform=NormPerspectiveTransformCfg(20, 20, 1.5),
            corpus=WordCorpus(
                WordCorpusCfg(
                    text_paths=[CURRENT_DIR / "corpus" / "eng_text.txt"],
                    font_dir=CURRENT_DIR / "font",
                    font_size=(20, 30),
                    num_word=(2, 3),
                ),
            ),
            corpus_effects=Effects(Line(0.9, thickness=(2, 5))),
            gray=False,
            text_color_cfg=SimpleTextColorCfg(),
        ),
    )


configs = [story_data()]

在上述配置中，我们完成了以下工作：

1. 指定了资源文件的位置。
2. 指定了文本采样方法：从语料库中随机选择 2 或 3 个单词。
3. 配置了一些用于生成的效果：
   • 透视变换 NormPerspectiveTransformCfg
   • 随机 Line 效果
   • 将输出图像高度固定为 32 像素。
   • 生成彩色图像。gray=False, SimpleTextColorCfg()。
4. 指定了字体相关参数：font_size、font_dir。

运行

运行 main.py。它有 4 个参数：

• config: Python 配置文件路径。
• dataset: 数据集格式，可选 img 或 lmdb。
• num_processes: 使用的进程数。
• log_period: 日志打印周期。（0, 100）

使用 Albumentations 效果

Text Renderer 集成了 Albumentations 用于图像增强。以下是可用的 Albumentations 效果：

• AlbumentationsEffect - 用于封装任何 Albumentations 增强器的通用包装器。
• AlbumentationsEmboss / Emboss - 浮雕效果。
• AlbumentationsMotionBlur / MotionBlur - 动感模糊效果。
• GaussianBlur - 高斯模糊。
• Noise、UniformNoise、SaltPepperNoise、PoissonNoise - 各种噪声效果。
• BrightnessContrast - 亮度和对比度调整。
• Rotate - 旋转。
• ShiftScaleRotate - 平移、缩放和旋转的组合。
• ElasticTransform - 弹性变换。
• GridDistortion - 网格扭曲。
• OpticalDistortion - 光学畸变。

使用示例

from text_renderer.effect import AlbumentationsEffect, AlbumentationsEmboss, Effects
import albumentations as A

# 使用内置的 Albumentations 效果
effects = Effects([
    AlbumentationsEmboss(alpha=(0.9, 1.0), strength=(1.5, 1.6)),
])

# 使用自定义的 Albumentations 增强器
custom_aug = A.Compose([
    A.GaussianBlur(blur_limit=(0, 1), p=1.0),
    A.RandomBrightnessContrast(brightness_limit=0.2, contrast_limit=0.2, p=1.0)
])
effects = Effects([
    AlbumentationsEffect(transform=custom_aug),
])

所有效果/布局示例

所有效果/布局配置示例可在链接中找到。

• bg_and_text_mask: 将三张宽度相同的图像水平拼接在一起，可用于训练如EraseNet这样的GAN模型。

	名称	示例
0	bg_and_text_mask
1	char_spacing_compact
2	char_spacing_large
3	color_image
4	curve
5	dropout_horizontal
6	dropout_rand
7	dropout_vertical
8	emboss
9	extra_text_line_layout
10	line_bottom
11	line_bottom_left
12	line_bottom_right
13	line_horizontal_middle
14	line_left
15	line_right
16	line_top
17	line_top_left
18	line_top_right
19	line_vertical_middle
20	padding
21	perspective_transform
22	same_line_layout_different_font_size
23	vertical_text

贡献

设置Commitizen以规范提交信息。

• 语料库：欢迎为项目贡献更多语料库生成器。这些生成器不一定需要是通用的，也可以是特定业务场景下的生成器，例如生成身份证号码等。

字体查看器

安装工具扩展包后，启动字体查看器：

uv sync --extra tools
uv run streamlit run tools/font_viewer.py -- web /path/to/fonts_dir

构建文档

uv sync --extra docs
cd docs
uv run make html
open _build/html/index.html

引用 text_renderer

如果您在研究中使用了 text_renderer，请考虑使用以下 BibTeX 条目。

@misc{text_renderer,
  author =       {oh-my-ocr},
  title =        {text_renderer},
  howpublished = {\url{https://github.com/oh-my-ocr/text_renderer}},
  year =         {2021}
}

Text Renderer 快速上手指南

Text Renderer 是一个用于生成文本行图像的开源工具，专为训练深度学习 OCR 模型（如 CRNN、PaddleOCR）设计。它支持模块化配置、多种数据增强效果以及垂直文本生成。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.10 及以上
• 依赖管理：推荐使用 uv（更快），也可使用 pip

安装步骤

方法一：使用 uv（推荐）

git clone https://github.com/oh-my-ocr/text_renderer
cd text_renderer
uv sync

方法二：使用 pip

如果您希望包含字体查看器和文档构建工具，可以使用以下命令：

pip install '.[tools]'   # 包含字体查看器和实用脚本
pip install '.[docs]'    # 包含用于构建文档的 Sphinx

提示：国内用户若下载依赖较慢，可配置国内镜像源（如清华源、阿里源）进行安装，例如：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple '.[tools]'。

基本使用

以下是生成 OCR 训练数据的最简流程，包含资源准备、配置文件编写和运行生成。

1. 准备资源文件

创建一个工作目录（例如 workspace），并在其中建立以下结构，放入字体、背景图和语料文件：

workspace
├── bg
│   └── background.png      # 背景图片
├── corpus
│   └── eng_text.txt        # 文本语料
└── font
    └── simsun.ttf          # 字体文件 (.ttf/.otf/.ttc)

您可以从项目示例数据中下载测试用的资源文件：

• simsun.ttf
• background.png
• eng_text.txt

2. 创建配置文件

在 workspace 目录下创建 config.py 文件。该文件需定义 configs 列表，包含生成任务的配置。

import os
from pathlib import Path

from text_renderer.effect import *
from text_renderer.corpus import *
from text_renderer.config import (
    RenderCfg,
    NormPerspectiveTransformCfg,
    GeneratorCfg,
    SimpleTextColorCfg,
)

CURRENT_DIR = Path(os.path.abspath(os.path.dirname(__file__)))


def story_data():
    return GeneratorCfg(
        num_image=10,  # 生成图片数量
        save_dir=CURRENT_DIR / "output",
        render_cfg=RenderCfg(
            bg_dir=CURRENT_DIR / "bg",
            height=32,  # 输出图像高度固定为 32
            perspective_transform=NormPerspectiveTransformCfg(20, 20, 1.5), # 透视变换
            corpus=WordCorpus(
                WordCorpusCfg(
                    text_paths=[CURRENT_DIR / "corpus" / "eng_text.txt"],
                    font_dir=CURRENT_DIR / "font",
                    font_size=(20, 30), # 字体大小随机范围
                    num_word=(2, 3),    # 每张图随机选取 2-3 个单词
                ),
            ),
            corpus_effects=Effects(Line(0.9, thickness=(2, 5))), # 添加线条干扰
            gray=False, # 生成彩色图像
            text_color_cfg=SimpleTextColorCfg(),
        ),
    )


configs = [story_data()]

3. 运行生成

进入 text_renderer 根目录（即 main.py 所在目录），执行以下命令启动生成任务：

Linux / macOS:

uv run python main.py \
    --config /path/to/workspace/config.py \
    --dataset img \
    --num_processes 2 \
    --log_period 10

Windows (CMD):

uv run python main.py --config C:\path\to\workspace\config.py --dataset img --num_processes 2 --log_period 10

参数说明：

• --config: 指向您创建的 config.py 文件的绝对路径。
• --dataset: 输出格式，img 表示保存为图片文件夹，lmdb 表示保存为 LMDB 数据库（兼容 PaddleOCR）。
• --num_processes: 并行进程数，可根据 CPU 核心数调整。
• --log_period: 日志打印间隔。

生成完成后，图片和标注文件（labels.json 或 LMDB 文件）将保存在配置中指定的 output 目录下。