🇧🇩 bangla-render

Bengali Text Rendering for Matplotlib & Seaborn (with full OpenType shaping)

bangla-render is the first open-source Python library that enables fully correct Bengali text rendering inside Matplotlib and Seaborn.

Matplotlib cannot shape Bengali text — it does not use HarfBuzz and therefore fails with:

Matra (ি, ী, ু, ূ, ৃ)
Reph (র্)
Juktakkhor (জ্ঞ, ক্ষ, ন্দ, ত্ম, ন্ত …)
GSUB/GPOS OpenType shaping

So Bengali titles, axis labels, annotations, and heatmap text become broken, disjoint, or scrambled.

💡 bangla-render solves this completely. It uses Qt's HarfBuzz engine to shape Bengali correctly, renders it into an RGBA image, and overlays it into Matplotlib using OffsetImage, bypassing Matplotlib's broken text renderer entirely.

✨ What's New in v0.2

Area	Change
Architecture	Single file split into 5 dedicated modules
Font handling	Auto-discovery, validation & fallback chain
Performance	LRU render cache (256 entries, ~4× speedup on repeated labels)
Layout engine	Full `BanglaLayoutManager` — event-driven, multi-subplot aware
Tick labels	New `set_bangla_xticks()` / `set_bangla_yticks()`
Indic scripts	Hindi (Devanagari) and Tamil verified out-of-the-box
Environment	Headless / Colab / Kaggle detection in `backend.py`
Test suite	Benchmark, debug JSON reports, 4-subplot and multi-subplot tests

✨ Features

✔ Full Bengali OpenType shaping

Correct matra placement
Proper conjunct formation
Reph, rafar, vowel signs
Multi-line paragraph shaping
True Unicode (no ANSI/Bijoy hacks)

✔ High-level Matplotlib API

br.set_bangla_title(ax, "বাংলা শিরোনাম")
br.set_bangla_xlabel(ax, "এক্স অক্ষ")
br.set_bangla_ylabel(ax, "ওয়াই অক্ষ")
br.set_bangla_xticks(ax, positions, ["একটি", "দুটি", "তিনটি"])
br.set_bangla_yticks(ax, positions, ["রাগ", "আনন্দ", "ভয়"])
br.text(ax, 0.5, 0.5, "মাঝখানে", coord="axes")

✔ Heatmap and confusion-matrix support

br.add_bangla_in_cell(ax, row, col, "খুশি", rows, cols)

✔ Automatic layout engine

apply_bangla_layout(fig, auto=True) measures every placed label using the Matplotlib renderer and adjusts margins so titles, tick labels, and axis labels never overlap — correctly for any number of subplots.

✔ Works everywhere

Matplotlib and Seaborn
Jupyter / JupyterLab / VS Code
Windows 10/11, macOS, Linux
Any Matplotlib backend (Agg, TkAgg, QtAgg, …)

🔍 Before & After Comparison

Line Plot

Default Matplotlib	With bangla-render

Heatmap

Before	After

Confusion Matrix

Before	After

🔥 Why This Library Exists

Matplotlib cannot shape Indic scripts. Even with Bangla fonts installed, it produces:

Disjoint characters
Wrong glyph order
Broken juktakkhor
Incorrect matra positioning

Existing "solutions" only work for very simple words like ভয়, রাগ — but fail completely for:

খুশি
দৃষ্টিভঙ্গি
শ্রদ্ধা
ব্যবস্থাপনা
হাস্যোজ্জ্বল
পর্যালোচনায়
And any real paragraph

Before bangla-render, there was:

No PyPI library
No correct Bengali shaping
No Seaborn heatmap support
No way to set Bengali xlabel/ylabel/title
No Unicode-safe method

bangla-render fills this gap for the first time.

🚀 Try It Instantly

Run the demo notebook directly in your browser — no setup needed:

Platform	Launch
Kaggle
Google Colab

📦 Installation

pip install bangla-render

Dependencies (installed automatically):

Package	Purpose
`PySide6`	Qt / HarfBuzz shaping engine
`NumPy`	RGBA array conversion
`Matplotlib`	Plot integration

Font note: On Windows, Nirmala UI (built-in) is used automatically.
On Linux / macOS, install Noto Sans Bengali:
sudo apt install fonts-noto or brew install font-noto-sans

🚀 Quick Start

Line plot

import matplotlib.pyplot as plt
import bangla_render as br

br.init_renderer()                          # initialise Qt once

fig, ax = plt.subplots(figsize=(6, 4))

ax.plot([1, 2, 3, 4, 5], [2, 4, 3, 5, 4])

br.set_bangla_title(ax,  "রেখাচিত্র")
br.set_bangla_xlabel(ax, "সময় (মাস)")
br.set_bangla_ylabel(ax, "মান")
br.set_bangla_xticks(ax, [1, 2, 3, 4, 5],
                    ["জানু", "ফেব্রু", "মার্চ", "এপ্রিল", "মে"])

br.apply_bangla_layout(fig, auto=True)
plt.savefig("line_plot.png", dpi=150)
plt.show()

Heatmap

import seaborn as sns
import numpy as np
import matplotlib.pyplot as plt
import bangla_render as br

br.init_renderer()

data  = np.random.rand(3, 3)
words = [["খুশি", "রাগ", "আশা"],
         ["ভয়",  "বিস্ময়", "শান্তি"],
         ["ঘৃণা", "আনন্দ", "সুখ"]]

fig, ax = plt.subplots(figsize=(6, 6))
sns.heatmap(data, ax=ax, cbar=True,
            xticklabels=False, yticklabels=False)

rows, cols = data.shape
for i in range(rows):
    for j in range(cols):
        br.add_bangla_in_cell(ax, i, j, words[i][j], rows, cols)

br.set_bangla_title(ax,  "বাংলা হিটম্যাপ")
br.set_bangla_xlabel(ax, "পূর্বাভাস শ্রেণি")
br.set_bangla_ylabel(ax, "আসল শ্রেণি")

br.apply_bangla_layout(fig, auto=True)
plt.savefig("heatmap.png", dpi=150)
plt.show()

Multi-subplot figure

import matplotlib.pyplot as plt
import bangla_render as br

br.init_renderer()

fig, axes = plt.subplots(1, 2, figsize=(12, 5))

# Left subplot
axes[0].plot([1, 2, 3], [3, 1, 4])
br.set_bangla_title(axes[0],  "বাম প্লট")
br.set_bangla_xlabel(axes[0], "সময়")
br.set_bangla_ylabel(axes[0], "মান")

# Right subplot — with colorbar (ylabel auto-skipped when blocked)
import numpy as np
im = axes[1].imshow(np.random.rand(3, 3), cmap="viridis")
fig.colorbar(im, ax=axes[1])
br.set_bangla_title(axes[1],  "ডান হিটম্যাপ")
br.set_bangla_xlabel(axes[1], "কলাম")

br.apply_bangla_layout(fig, auto=True)
plt.savefig("multisubplot.png", dpi=150)
plt.show()

🌐 Other Indic Scripts

The rendering pipeline is language-agnostic — pass any Brahmic script Unicode string and a matching OpenType font:

# Hindi (Devanagari) — uses Nirmala UI on Windows
br.set_bangla_ylabel(ax, "वास्तविक वर्ग",
                    font_family="Nirmala UI")

# Tamil — same font on Windows
br.set_bangla_ylabel(ax, "உண்மை வகை",
                    font_family="Nirmala UI")

Verified scripts: Bengali, Hindi (Devanagari), Tamil.
Expected to work (font availability required): Assamese, Odia, Gujarati, Gurmukhi, Sinhala.

🧩 API Reference

Initialisation

Function	Description
`init_renderer()`	Initialise Qt application (call once at startup)
`check_environment()`	Report Qt status, headless mode, Colab/Kaggle detection
`get_renderer_status()`	Detailed Qt initialisation info

Font utilities

Function	Description
`find_best_bangla_font()`	Return the best available Bengali font name
`list_available_fonts()`	List all system fonts
`list_bangla_candidate_fonts()`	List Bengali candidate fonts found on system

Plot labels

Function	Description
`set_bangla_title(ax, text, **kw)`	Set per-axes title
`set_bangla_xlabel(ax, text, **kw)`	Set x-axis label
`set_bangla_ylabel(ax, text, **kw)`	Set y-axis label
`set_bangla_xticks(ax, positions, labels, **kw)`	Set x-axis tick labels
`set_bangla_yticks(ax, positions, labels, **kw)`	Set y-axis tick labels

Annotations

Function	Description
`bangla_text(ax, x, y, text, coord="axes", **kw)`	Place text at arbitrary coordinates
`add_bangla_in_cell(ax, row, col, text, rows, cols, **kw)`	Annotate heatmap / matrix cell

Layout

Function	Description
`apply_bangla_layout(fig, auto=False, **kw)`	Adjust margins; `auto=True` measures placed artists

Cache

Function	Description
`get_render_cache_info()`	Return cache hit/miss counts and occupancy
`clear_render_cache()`	Clear the LRU cache (useful before benchmarking)

Low-level rendering

Function	Description
`render_text(text, output_path, **kw)`	Render text to a PNG file
`render_text_qimage(text, **kw)`	Render text to a QImage (internal use)
`render_paragraph(text, output_path, **kw)`	Render multi-line paragraph to PNG

🏗 Architecture

bangla-render v0.2 — five-module architecture
─────────────────────────────────────────────
backend.py      Qt application lifecycle, headless / Colab / Kaggle detection
fonts.py        Font discovery, validation (conjunct/matra test), fallback chain
renderer.py     HarfBuzz shaping via Qt, QImage rasterisation, LRU cache
layout.py       BanglaLayoutManager — event-driven, multi-subplot, colorbar-aware
mpl_support.py  Public Matplotlib API — all set_bangla_* functions

⚡ Performance

Measured on Windows 10, Python 3.11.9, font: Nirmala UI, N = 50 calls, cold cache.

Text category	Median (ms)	Cache hit (ms)
Simple word (3–4 chars)	0.27	0.06
Conjunct consonant	0.32	0.07
Complex multi-conjunct	0.40	0.08
Axis label (medium)	0.57	0.10
6×6 heatmap (36 cells, batch)	10.5 ms total	—

The LRU cache delivers roughly a 4× speedup for repeated labels.

🧪 Running the Test Suite

git clone https://github.com/mbs57/bangla-render.git
cd bangla-render
pip install -e .
python tests/test_suite.py

Outputs saved to test_outputs/. Debug JSON reports saved to test_outputs/debug/.
Benchmark results saved to test_outputs/benchmark_results.txt and .json.

🗺 Roadmap

v0.1 — Bengali rendering for title, xlabel, ylabel, heatmap cells
v0.2 — Five-module architecture, font validation, LRU cache, tick labels, Indic scripts, layout engine
v0.3 — Mixed Bengali + MathText ( $\alpha$ ) support
v0.4 — Vector output via SVG path extraction
v0.5 — Extend verified Indic support: Odia, Gujarati, Malayalam, Telugu
v1.0 — Production-ready stable release and full documentation site

📄 License

MIT License — free for personal, academic, and commercial use.

📖 Citation

If you use bangla-render in research, please cite:

@article{shuvo2025banglarender,
  title   = {bangla-render: Correct Bengali Text Rendering for
             Matplotlib \& Seaborn Using Qt/HarfBuzz},
  author  = {Shuvo, Mrinal Basak},
  journal = {SoftwareX},
  year    = {2025},
  note    = {Under review, Manuscript SOFTX-D-25-00884}
}

⭐ Acknowledgements

This project aims to make scientific and data visualisation accessible to millions of Bengali speakers — helping students, educators, analysts, and researchers present data in their native language.

Built on the shoulders of Qt, HarfBuzz, Matplotlib, NumPy, and PySide6.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
assets		assets
bangla_render		bangla_render
dist		dist
examples		examples
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

🇧🇩 bangla-render

Bengali Text Rendering for Matplotlib & Seaborn (with full OpenType shaping)

✨ What's New in v0.2

✨ Features

✔ Full Bengali OpenType shaping

✔ High-level Matplotlib API

✔ Heatmap and confusion-matrix support

✔ Automatic layout engine

✔ Works everywhere

🔍 Before & After Comparison

Line Plot

Heatmap

Confusion Matrix

🔥 Why This Library Exists

🚀 Try It Instantly

📦 Installation

🚀 Quick Start

Line plot

Heatmap

Multi-subplot figure

🌐 Other Indic Scripts

🧩 API Reference

Initialisation

Font utilities

Plot labels

Annotations

Layout

Cache

Low-level rendering

🏗 Architecture

⚡ Performance

🧪 Running the Test Suite

🗺 Roadmap

📄 License

📖 Citation

⭐ Acknowledgements

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages