textsynth

textsynth makes images of Perso-Arabic text. You give a string to the library. The library gives a PIL.Image back.

The library can change the text before it draws the text. It can also add ink damage to the image. Use textsynth to make training data for OCR and HTR models.

Install

pip install textsynth      # or: uv add textsynth

Quick start

The library does not include a font. Give the path of a font that has Perso-Arabic letters.

from textsynth import render

image = render("بسم الله", "Amiri-Regular.ttf", size=72)
image.save("out.png")

The five stages

Synthesizer sends a string through five stages. You can use each stage alone. Only the shaper is necessary.

from textsynth import (
    Synthesizer, Layout, GlyphSubstitution, BorrowedGlyph,
    Smudge, Blobify, InkBleed, orthographic_variation,
)

synth = Synthesizer(
    font="Amiri-Regular.ttf",
    layout=Layout(size=72, tracking=-1, supersample=2, jitter_y=0.6),
    text_rules=[orthographic_variation(swap=0.3)],
    font_patches=[GlyphSubstitution("مم", BorrowedGlyph("Oblegg-Jawi.otf", "A"))],
    effects=[Smudge(length=7), Blobify(), InkBleed(1.0)],
    seed=7,
)
image = synth("سايا ممباچ سورت خبر")

Elongation

Kashida

Kashida finds each connection in a word that you can extend. Then it puts tatweels at these positions. contrast controls the distribution.

Kashida(frequency=6, contrast=0.8).apply("حكيم", rng)   # 'حــــــكـيم'

A tatweel alone is not enough. The font draws a bar next to the letter, but it does not move the dots. KashidaForms makes one glyph from the bar and the letter, and moves the dots along the extension.

Synthesizer(
    font=FONT,
    text_rules=[Kashida(frequency=6, contrast=0.8)],   # keep this rule last
    font_patches=[KashidaForms(dot_shift=0.5)],        # 0 keeps the dots
)

Put Kashida last in the text rules. orthographic_variation removes tatweels. A kashida before that rule does not stay in the text.

Tadakhul

Tadakhul continues the tail of a letter below the word. The letters above the tail move up. Give the length in letters: length=2 makes the letter as long as the two letters after it.

Synthesizer(font=FONT, glyph_rules=[TadakhulMerged(letters="و", length=2)])

Three rules make this shape:

Command line

textsynth "ممتاز سايا" -f Amiri-Regular.ttf \
    --size 72 --tracking -1 --distress smudged \
    --substitute "مم=Oblegg-Jawi.otf:A" --vary 0.3 -o line.png

Refer to textsynth --help for all the options.

Limits

• A font patch can fail and give no error. If the font shapes with the AAT morx table, the patch does nothing. Many macOS fonts do this. Test the patch:

  before = [g.name for g in shape("ممتاز", font)]
  after = [g.name for g in shape("ممتاز", patch_font(font, [rule]))]
  assert before != after, "the rule did not operate"
  

• Each font has a different set of letters that can sweep. Amiri gives ر ز و ژ ۏ ؤ ڑ. Run examples/other_fonts.py to find the set for a font.

• A kashida needs a font that has flat connections. Nastaliq fonts do not work.

• The library does not do bidi. Divide a line of mixed Arabic and Latin text yourself.

• A letter from a fallback font does not join to the adjacent letters.

• The library uses a variable font at its default instance.

• One size value gives a different ink height in each font. Measure the ink, then scale each font.

More

• docs/design.md — how each stage operates, and why.
• examples/ — one script for each feature.
• notebooks/ — the notebooks, with their outputs.

Development

uv sync
uv run pytest

License

The library is under the MIT license.

assets/fonts/Amiri-Regular.ttf is Amiri, under the SIL Open Font License (Amiri-OFL.txt).

assets/fonts/ScheherazadeNew-Regular.ttf is Scheherazade New, by SIL Global, under the SIL Open Font License (ScheherazadeNew-OFL.txt).