English | 中文

WordCanvas

Introduction

The core functionality of this project is the "Text Image Generation Tool".

We addressed issues such as insufficient data volume, class imbalance, and lack of diversity by generating a large variety of synthetic Chinese text images. To achieve this, we referred to several existing text synthesis tools, which provided us with significant insights and inspired us to create a new text image generator from scratch.

Documentation

For information on how to install and use this package, please refer to the WordCanvas Documents. You can get all detailed information about this project from the documents.

Installation

Currently, there is no package available on PyPI, and there are no plans to provide one in the near future. To use this project, you must clone it directly from Github and then install the required dependencies.

• Note: Before installation, please ensure you have installed DocsaidKit. If you have not installed DocsaidKit, please refer to the DocsaidKit Installation Guide.

Installation Steps

1. Clone the project:

   git clone https://github.com/DocsaidLab/WordCanvas.git

2. Enter the project directory:

   cd WordCanvas

3. Install dependencies:

   pip install wheel

4. Build the package:

   python setup.py bdist_wheel

5. Install the package:

   pip install dist/wordcanvas-*-py3-none-any.whl

Following these steps, you should be able to successfully install WordCanvas.

Once installed, you are ready to use the project.

Test the Installation

You can test whether the installation was successful with the following command:

python -c "import wordcanvas; print(wordcanvas.__version__)"
# >>> 0.4.2

If you see a version number similar to 0.4.2, it indicates the installation was successful.

QuickStart

Getting started is often the hardest part, so let's keep it simple.

Starting with a String

Start with a basic declaration to begin using the tool.

from wordcanvas import WordCanvas

gen = WordCanvas()

Using default settings, you can directly call the function to generate a text image.

text = "你好！Hello, World!"
img, infos = gen(text)
print(img.shape)
# >>> (67, 579, 3)

Specifying a Specific Font

You can specify your preferred font using the font parameter.

gen = WordCanvas(
    font_path="/path/to/your/font/OcrB-Regular.ttf"
)

text = 'Hello, World!'
img, infos = gen(text)

When the font does not support the input text, tofu characters will appear.

text = 'Hello, 中文!'
img, infos = gen(text)

Setting Image Size

Use the output_size parameter to adjust the image size.

gen = WordCanvas(output_size=(64, 1024)) # Height 64, Width 1024
img, infos = gen(text)
print(img.shape)
# >>> (64, 1024, 3)

When the set size is smaller than the text image size, the text image will automatically be scaled down.

That is, the text will be squeezed together, forming a thin rectangle, like this:

text = '你好' * 10
gen = WordCanvas(output_size=(64, 512))  # Height 64, Width 512
img, infos = gen(text)

Adjusting Background Color

Use the background_color parameter to adjust the background color.

gen = WordCanvas(background_color=(255, 0, 0)) # Red background
img, infos = gen(text)

Adjusting Text Color

Use the text_color parameter to adjust the text color.

gen = WordCanvas(text_color=(0, 255, 0)) # Green text
img, infos = gen(text)

Adjusting Text Alignment

:::warning Remember the image size we mentioned earlier? In default settings, setting text alignment is meaningless. You must allow extra space in the text image to see the effect of alignment. :::

Use the align_mode parameter to adjust the text alignment mode.

from wordcanvas import AlignMode, WordCanvas

gen = WordCanvas(
    output_size=(64, 1024),
    align_mode=AlignMode.Center
)

text = '你好！ Hello, World!'
img, infos = gen(text)

• Center alignment: AlignMode.Center

  

• Right alignment: AlignMode.Right

  

• Left alignment: AlignMode.Left

  

• Scatter alignment: AlignMode.Scatter

  

Adjusting Text Direction

Use the direction parameter to adjust the text direction.

• Outputting horizontal text

  text = '你好！'
  gen = WordCanvas(direction='ltr') # Left to right horizontal text
  img, infos = gen(text)

  

• Outputting vertical text

  text = '你好！'
  gen = WordCanvas(direction='ttb') # Top to bottom vertical text
  img, infos = gen(text)

  

• Outputting vertical text with scatter alignment

  text = '你好！'
  gen = WordCanvas(
      direction='ttb',
      align_mode=AlignMode.Scatter,
      output_size=(64, 512)
  )
  img, infos = gen(text)

  

Adjusting Output Direction

Use the output_direction parameter to adjust the output direction.

• Vertical text, horizontal output

  from wordcanvas import OutputDirection, WordCanvas
  
  gen = WordCanvas(
      direction='ttb',
      output_direction=OutputDirection.Horizontal
  )
  
  text = '你好！'
  img, infos = gen(text)

  

• Horizontal text, vertical output

  from wordcanvas import OutputDirection, WordCanvas
  
  gen = WordCanvas(
      direction='ltr',
      output_direction=OutputDirection.Vertical
  )
  
  text = '你好！'
  img, infos = gen(text)

  

Flattening Text

In scenarios where the text is particularly flat, you can use the text_aspect_ratio parameter.

gen = WordCanvas(
    text_aspect_ratio=0.25, # Text height / text width = 1/4
    output_size=(32, 1024),
)  # Flattened text

text = "Flattened test"
img, infos = gen(text)

Dashboard

That's a brief overview of the basic functionality.

Finally, let's take a look at the dashboard feature.

gen = WordCanvas()
print(gen)

You can also skip print and just output directly, as we've implemented the __repr__ method. The output will display a simple dashboard.

You can see:

• The first column is Property, which lists all the settings.
• The second column is Current Value, which shows the value of the parameters "at this moment."
• The third column is SetMethod, which describes the method to set the parameter. Parameters marked set can be directly modified; those marked reinit require reinitialization of the WordCanvas object.
• The fourth column is DType, which is the data type of the parameter.
• The fifth column is Description, which describes the parameter.

Most parameters can be directly set, meaning when you need to change output characteristics, you don't need to rebuild a WordCanvas object, just set them directly. Parameters that require reinit typically involve font initialization, like text_size. So, be aware, not all parameters can be directly set.

gen.output_size = (64, 1024)
gen.text_color = (0, 255, 0)
gen.align_mode = AlignMode.Center
gen.direction = 'ltr'
gen.output_direction = OutputDirection.Horizontal

After setting, simply call to get the new text image.

If you've set a parameter that requires reinit, you'll encounter an error:

• AttributeError: can't set attribute

  gen.text_size = 128
  # >>> AttributeError: can't set attribute

Summary

While many features weren't mentioned, this covers the basic functionalities.

That concludes the basic usage of this project; if you need more advanced features, please refer to the WordCanvas Documents.

Citation

If you find our work helpful, please cite the following:

@misc{yuan2024wordcanvas,
  author = {Ze Yuan},
  title = {WordCanvas},
  year = {2024},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/DocsaidLab/WordCanvas}}
}