wolfhece.opengl.glyph_atlas

MSDF glyph atlas for GPU text rendering.

Renders TrueType glyphs at high resolution via PIL, computes a Multi-channel Signed Distance Field (MSDF), and packs them into a 3-channel (RGB) OpenGL texture atlas. The MSDF preserves sharp corners that a single-channel SDF rounds off, giving noticeably crisper text at small pixel sizes.

Usage:

atlas = GlyphAtlas.get("arial.ttf")   # cached singleton per font
atlas.bind(0)                          # bind to texture unit 0
m = atlas.get_metrics('A')             # query glyph layout info

Author: HECE - University of Liege, Pierre Archambeau Date: 2026

Copyright (c) 2026 University of Liege. All rights reserved.

Module Contents

wolfhece.opengl.glyph_atlas._HAS_PIL = True

wolfhece.opengl.glyph_atlas._HAS_SCIPY = True

wolfhece.opengl.glyph_atlas._DEFAULT_CHARSET: list[str]

class wolfhece.opengl.glyph_atlas.GlyphMetrics

Layout metrics for a single glyph in the MSDF atlas.

All spatial values are normalised so that 1.0 equals one em (i.e. the RENDER_SIZE used during atlas construction).

char

The character.

uv_x

Left U coordinate in the atlas (0..1).

uv_y

Top V coordinate in the atlas (0..1).

uv_w

U extent of the cell.

uv_h

V extent of the cell.

offset_x

X offset from cursor to quad left edge (normalised).

offset_y

Y offset from baseline to quad top in font coords (negative = above baseline).

quad_w

Total quad width including SDF padding (normalised).

quad_h

Total quad height including SDF padding (normalised).

advance

Horizontal advance to the next character (normalised).

char: str = ''

uv_x: float = 0.0

uv_y: float = 0.0

uv_w: float = 0.0

uv_h: float = 0.0

offset_x: float = 0.0

offset_y: float = 0.0

quad_w: float = 0.0

quad_h: float = 0.0

advance: float = 0.0

class wolfhece.opengl.glyph_atlas.GlyphAtlas(font_name: str = 'arial.ttf', charset: list[str] | None = None)

MSDF glyph atlas backed by a 3-channel RGB OpenGL texture.

Build once per font; the atlas is cached and reused for all rendering. Each channel encodes a signed distance field for a different subset of contour edges (grouped by normal direction). The fragment shader reconstructs sharp corners via median(r, g, b).

Encoding: 0.5 = edge, >0.5 = inside, <0.5 = outside (per channel).

Parameters:

• font_name – TrueType font file name (resolved via wolfhece.textpillow.load_font()).

• charset – List of characters to include. Defaults to ASCII printable + common accented latin characters.

RENDER_SIZE: int = 64

SDF_SPREAD: float = 8.0

PAD: int = 12

ATLAS_MAX_WIDTH: int = 1024

_cache: dict[str, GlyphAtlas]

font_name = 'arial.ttf'

_charset

_metrics: dict[str, GlyphMetrics]

_texture_id: int | None = None

_atlas_width: int = 0

_atlas_height: int = 0

_atlas_data: numpy.ndarray | None = None

_line_height: float = 1.0

_ascender: float = 0.8

_descender: float = 0.2

classmethod get(font_name: str = 'arial.ttf') → GlyphAtlas

Return a cached atlas for font_name, creating it if needed.

classmethod clear_cache()

Destroy all cached atlases and free GPU textures.

_build()

Render all glyphs, compute SDF, shelf-pack into atlas.

static _compute_sdf(bitmap: numpy.ndarray, spread: float) → numpy.ndarray

Compute a single-channel SDF from a greyscale bitmap.

Returns array in [0, 1]: 0.5 = edge, >0.5 = inside, <0.5 = outside. Falls back to a simple ramp when scipy is not installed.

Kept as a building block for _compute_msdf().

static _compute_msdf(bitmap: numpy.ndarray, spread: float) → numpy.ndarray

Compute a 3-channel MSDF from a greyscale bitmap.

Each RGB channel encodes the signed distance to edge pixels whose gradient direction (outward normal) falls in a different 120° sector. The fragment shader recovers sharp corners via median(r, g, b).

Returns (H, W, 3) float32 array in [0, 1]. Falls back to 3× duplicated SDF when scipy is not available.

upload()

Upload atlas data as a 3-channel GL_RGB8 OpenGL texture.

bind(unit: int = 0)

Bind atlas texture to the given texture unit.

destroy()

Free GPU texture memory.

get_metrics(char: str) → GlyphMetrics | None

Return metrics for char, or None if absent from the atlas.

property metrics: dict[str, GlyphMetrics]

Full metrics dictionary (read-only view).

property line_height: float

Line height relative to one em.

property ascender: float

Ascender relative to one em.

property descender: float

Descender relative to one em.

property texture_id: int | None

property atlas_size: tuple[int, int]

(width, height) of the atlas texture in pixels.

property atlas_data: numpy.ndarray | None

Raw MSDF atlas as a float32 array of shape (H, W, 3) (for testing).