pictex

Added

• Letter Spacing (letter_spacing()): Controls the extra space between characters, mirroring the CSS letter-spacing property.
  • Accepts an absolute pixel offset (letter_spacing(8)), a percentage of the font's space-character width (letter_spacing("10%")), or a LetterSpacing instance for type-safe usage.
  • Negative values tighten character spacing.
  • Pass "normal" to restore the font's default spacing.
  • Inherited, so it can be set once on a Canvas or container and applied to all Text nodes inside.

from pictex import Canvas, Column, Text

Canvas().font_size(34).color("#1e1e2e").background_color("#cdd6f4").render(
    Column(
        Text("Default spacing"),
        Text("letter_spacing(5)").letter_spacing(5),
        Text("letter_spacing(10)").letter_spacing(10),
        Text("letter_spacing('30%')").letter_spacing("30%"),
        Text("letter_spacing(-4)").letter_spacing(-4),
    ).gap(10).padding(28)
).save("example_letter_spacing.png")

• Text Box Edge (text_box_edge()): Controls how the top and bottom edges of a text node's bounding box are calculated. Inspired by the CSS text-box-trim / text-box-edge properties.
  • "font" (default): Box edges are derived from the font's ascent/descent metrics - stable and content-independent.
  • "glyphs": Box edges are derived from the actual bounds of the rendered glyphs - tightly wraps visible characters, removing empty ascender/descender space.
  • Shorthand (text_box_edge("glyphs")) sets both edges at once. Keyword form (text_box_edge(top="glyphs")) sets each edge independently, omitted keywords default to "font".
  • Inherited, so it can be set once on a Canvas or container and applied to all Text nodes inside.

from pictex import Canvas, Row, Column, Text

Canvas().font_size(54).background_color("#eff1f5").render(
    Row(
        Column(
            Text('"font" (default)').font_size(12).color("gray"),
            Text("hello").color("#1e1e2e").background_color("#cba6f7"),
        ).gap(6).align_items("center"),
        Column(
            Text('"glyphs"').font_size(12).color("gray"),
            Text("hello").color("#1e1e2e").background_color("#a6e3a1").text_box_edge("glyphs"),
        ).gap(6).align_items("center"),
    ).gap(40).padding(28)
).save("example_text_box_edge.png")

• Per-side padding and margin: Convenience methods to set a single side without touching the others.
  • padding_top(), padding_right(), padding_bottom(), padding_left()
  • padding_horizontal() (left + right), padding_vertical() (top + bottom)
  • margin_top(), margin_right(), margin_bottom(), margin_left()
  • margin_horizontal() (left + right), margin_vertical() (top + bottom)

# Before
Text("Hello").padding(0, 0, 0, 20)   # only left padding — positional, error-prone
Text("Hello").padding(10, 0, 10, 0)  # only vertical padding

# After
Text("Hello").padding_left(20)
Text("Hello").padding_vertical(10)

• background_image() now accepts a Path object in addition to a string, consistent with font_family() and font_fallbacks().

Changed

• line_height() now takes "auto" as default value, meaning each line's vertical space is derived from the font's own metrics (ascent + descent + leading). Previously, the default was 1.0 * font_size, which ignored the font's built-in spacing and was inconsistent with standard typographic behavior.

  *Visual change

Fixed

• Contextual Shaping Across Font Runs: Scripts like Arabic and Indic that rely on contextual joining (e.g., initial/medial/final character forms) now shape correctly even when a word is split across multiple font runs due to font fallback. Previously, each run was shaped in isolation, causing characters at run boundaries to render in their disconnected (isolated) form instead of the correct joined form.
• Text Wrapping: Text nodes with first line empty were not calculating their height correctly.
• Line Height Calculation: Line height calculation is now based on the maximum metrics (ascent, descent, leading) of all fonts used in a single line. Previously, it simply used the primary font's metrics, which could result in wrong line heights when using fallback fonts or multiple fonts in the same line.
• Baseline Alignment: The text baseline within a line is now determined by the highest ascent of all fonts present in that line. Previously, the baseline was dictated solely by the primary font, causing vertical misalignment when rendering taller fallback fonts (like emojis).
• Text Decoration Positioning: The vertical position for underlines and strikethroughs now adapts to the fonts used within the line. Previously, these positions were fixed to the primary font's metrics, which caused decorations to be misaligned or cut through taller fallback characters.
• Text Direction: Fixed RTL text rendering where complex ligatures were broken and diacritics misaligned. HarfBuzz now natively processes logical text instead of pre-reversed strings, restoring OpenType GSUB/GPOS features.
• Text Layout: Corrected HarfBuzz Y-offset coordinate mapping to Skia's Y-axis, fixing vertically displaced Arabic diacritics.

Full Changelog: https://github.com/francozanardi/pictex/compare/v2.1.1...v2.1.2

Fixed

• Text Wrapping: Fixed false word-wrapping when no width constraint is set, caused by floating-point precision mismatch between glyph advance measurement and wrapping logic.
• Text Wrapping: Fixed CJK text not wrapping within fixed-width containers. Characters from Han, Hiragana, Katakana, and Hangul scripts are now treated as individual breakable units.

Full Changelog: https://github.com/francozanardi/pictex/compare/v2.1.0...v2.1.1

PicTex v2.1.0

What's New

Advanced Text Shaping (HarfBuzz)

PicTex has migrated from Skia to HarfBuzz for text shaping. This decision was made after facing some issues with skia-python, such as characters width calculation ("👨‍👩‍👧‍👦" or "ZWJ"). See #43 for more info about this.

Unicode Bidirectional Support (LTR/RTL)

PicTex now natively supports languages like Arabic and Hebrew, even when mixed with LTR text.

• Automatic Reordering: Mixed English and Arabic text now flows correctly without manual intervention.
• Text Direction API: New .direction() method to control horizontal layout flow across containers.

New Builder Methods

• width() & height(): Convenience methods for direct size control (e.g., Text("Hello").width(200)).
• Enhanced font_weight(): Now supports CSS-style string values (e.g., "bold", "extra-bold", "light").
• direction(): Set layout flow to "ltr" or "rtl" at the container level.

Fixes

• Word Wrapping with multiple fonts: Word wrapping was not working correctly when a single line contained multiple fonts. That was because it was using the primary font to measure each text run, instead of using the right run font.
• Vertical Alignment: Fixed baseline inconsistencies when mixing different fonts or scripts in a single line. All text now aligns perfectly to a common baseline. The common baseline is obtained from the primary font, even when all the text in the line is using a fallback font.

Before & After Comparison

from pictex import *

(
    Canvas()
    .background_color(NamedColor.PINK)
    .color(NamedColor.BLUE)
    .font_size(100)
    .render("سلام -> درود")
).save("example.png")

Before: Text runs are rendered LTR (no BiDi) + word wraping bug (because of font fallback for rendering).

After (v2.1.0): Correct RTL reordering + word wraping is handled correctly even when font fallbacks are used.

Full Changes: https://github.com/francozanardi/pictex/compare/v2.0.2...v2.1.0