universal-render

Universal complex-script text rendering for Matplotlib and Seaborn, powered by Qt/HarfBuzz shaping.

Matplotlib's text engine cannot shape complex scripts — Bengali conjuncts break apart, Arabic letters don't join, Tamil and Thai vowels land in the wrong place, and often all you get is tofu boxes (▯▯▯). universal_render routes text through Qt's shaping engine (HarfBuzz) and embeds the correctly shaped result into your figures, with automatic script detection and per-script font fallback — no font configuration needed.

Before / After

Left: Matplotlib's own text engine. Right: the same text through universal_render — 22 scripts, same machine, zero configuration.

And it isn't just tofu: even with the correct font installed, Matplotlib (and, on Windows, mplcairo and Pillow — their official wheels ship without Raqm/HarfBuzz) silently renders complex scripts unshaped: Arabic unjoined, Bengali conjuncts split, with zero warnings. See evaluation/ for the measured comparison.

✨ Features

• Automatic Unicode script detection (detect_script, segment_runs)
• Per-script font fallback with glyph-coverage validation (auto_font_fallback)
• Correct shaping for Indic (Bengali, Hindi, Tamil, Telugu, …), RTL (Arabic, Hebrew), Southeast Asian (Thai, Khmer, Lao, Myanmar), CJK, and more — 22 scripts verified by the built-in self_test()
• Mixed-script text: Bengali + English + numbers in one string
• Native numerals for 16 scripts (to_native_numerals(2026, "Bengali") → ২০২৬)
• Drop-in replacements for titles, axis labels, tick labels, legends, annotations, and heatmap cell text
• Matplotlib-style text options: weight="bold", italic=True, alpha=0.5, rotation=45 (any angle, including rotated tick labels), multiline "\n" strings, title loc="left"/"center"/"right", and a proper figure suptitle
• DPI-safe layout: titles, labels, and ticks stay correctly placed at any savefig(dpi=..., bbox_inches="tight")
• Works headless (Colab/Kaggle/CI) via Qt offscreen mode
• Drop-in bangla_render compatibility: import universal_render.compat as br

🚀 Quick Example

import matplotlib.pyplot as plt
import universal_render as ur

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [3, 1, 4])

ur.set_multilingual_title(ax, "বাংলা শিরোনাম")        # Bengali — font auto-selected
ur.set_multilingual_xlabel(ax, "أشهر السنة")           # Arabic — shaped + RTL
ur.set_multilingual_ylabel(ax, "மாத விற்பனை")          # Tamil

ur.set_multilingual_xticks(ax, [1, 2, 3], ["एक", "दो", "तीन"])  # Hindi
ur.apply_multilingual_layout(fig, auto=True)

plt.savefig("plot.png", dpi=300)

One-call APIs

# Label a whole plot at once — each string picks its own script's font
ur.localize_axes(
    ax,
    title="বিক্রয় প্রতিবেদন ২০২৬",
    xlabel="महीना", ylabel="மதிப்பு",
    xticklabels=["জানু", "फ़र", "மார்", "April"],
    legend_labels=["পূর্বাভাস"],
)

# Annotated heatmap with native Bengali digits and auto text contrast
ur.multilingual_heatmap(
    ax, data, value_format=".2f", value_script="Bengali",
    row_labels=["ঢাকা", "চট্টগ্রাম", "খুলনা"],
    col_labels=["جودة", "คุณภาพ", "Quality"],
    title="গুণমান ম্যাট্রিক্স",
)

# Verify this machine renders all 22 supported scripts
ur.self_test()

📦 API Overview

🌍 Supported Script Families

Script detection additionally covers Katakana, Tibetan, Georgian, Armenian, and Ethiopic. One script serves many languages — language_to_script() maps ~60 language names.

📊 Evaluation

evaluation/compare_backends.py renders the same text with the same font file through every backend, so the shaping engine is the only variable. Findings on Windows (Python 3.11):

🛠 Installation

pip install universal-render

Or try it without installing anything — the demo notebook runs on Colab or Kaggle with one click (on Kaggle, enable Internet in the notebook settings).

Fonts: on Windows, everything works out of the box (Nirmala UI, Segoe UI, Leelawadee UI…). On Linux/Colab, install Noto fonts (fonts-noto / fonts-noto-cjk) — the fallback tables pick them up automatically. Verify any environment with:

import universal_render as ur
ur.self_test()   # prints a per-script pass/fail table

🧪 Tests

py tests/test_universal_render.py     # or: pytest tests/

Limitations

• Text is embedded as high-resolution raster images; SVG/PDF exports contain images rather than selectable vector glyphs.
• Arbitrary-angle rotated tick labels are center-anchored under their tick (Matplotlib anchors the label end).
• Scripts requiring vertical layout (e.g. traditional Mongolian) are not supported.

Citation

If you use universal-render in academic work, please cite the bangla-render paper (SoftwareX) for now — a dedicated paper for the universal framework is in preparation.

License

MIT © 2026 Mrinal Basak Shuvo