numberlink.number_render

Bitmap text rendering utilities.

This module provides lightweight bitmap font data and helper functions to render small text overlays into RGB image arrays. The functions are intended for debug rendering and simple user interfaces where external font dependencies are undesirable. Use render_bitmap_text_to_array() to draw left-aligned text, render_bitmap_text_centered() to draw centered text, and build_endpoint_labels() to compute label positions for grid endpoints.

The module exposes a compact bitmap font mapping in BITMAP_FONT.

Module Contents

Functions

render_bitmap_text_to_array	Render text into an RGB image array at a top-left position.
render_bitmap_text_centered	Render text centered at the given pixel coordinates.
build_endpoint_labels	Compute label specifications for grid endpoints.

Data

BITMAP_FONT

API

numberlink.number_render.BITMAP_FONT: dict[str, tuple[int, ...]] = None

numberlink.number_render.render_bitmap_text_to_array(text: str, topleft: Coord, color: RGBInt, img: numpy.typing.NDArray[numpy.uint8], scale: int = 2, outline_color: RGBInt | None = (0, 0, 0), outline_thickness: int = 1) → int

Render text into an RGB image array at a top-left position.

Draw a string using the BITMAP_FONT mapping into the provided image array. The function writes directly into img and returns the horizontal advance in pixels from the original topleft to the end of the rendered text.

The image array uses the (row, column, channel) indexing convention. The topleft argument uses an (x, y) coordinate convention where x is the column and y is the row. Use render_bitmap_text_centered() to draw text centered at a point instead of at a top-left corner.

Parameters:

• text (str) – Text to render. Characters not present in BITMAP_FONT are rendered as space characters.

• topleft (tuple) – Pixel coordinates for the top-left corner as (x, y) where x is column and y is row.

• color (tuple[int, int, int]) – RGB color tuple with values in the range 0 to 255.

• img (numpy.ndarray) – Target RGB array with shape (H, W, 3) and dtype numpy.uint8. The array is modified in place.

• scale (int, optional) – Pixel size used for each bitmap cell. Min value is 1. Larger values scale the glyphs uniformly. Defaults to 2.

• outline_color (tuple[int, int, int] or None, optional) – RGB tuple used to draw an outline around glyphs. If None, no outline is drawn. Defaults to (0, 0, 0).

• outline_thickness (int, optional) – Outline thickness in pixels measured in bitmap units. Values less than 1 disable outline drawing. Defaults to 1.

Returns:

Horizontal width in pixels of the rendered string.

Return type:

int

See also

render_bitmap_text_centered() for centered text rendering.

Note

The function modifies img in place and performs clipping when the glyphs fall outside the image bounds.

numberlink.number_render.render_bitmap_text_centered(text: str, center: Coord, color: RGBInt, img: numpy.typing.NDArray[numpy.uint8], scale: int = 2, outline_color: RGBInt | None = (0, 0, 0), outline_thickness: int = 1) → None

Render text centered at the given pixel coordinates.

Compute a top-left origin that centers the rendered text at center and delegate to render_bitmap_text_to_array() for actual drawing. The center argument uses an (x, y) convention where x is column and y is row.

Parameters:

• text (str) – Text to render.

• center (tuple) – Pixel coordinates for the text center as (x, y) where x is column and y is row.

• color (tuple[int, int, int]) – RGB color tuple with values in the range 0 to 255.

• img (numpy.ndarray) – Target RGB array with shape (H, W, 3) and dtype numpy.uint8. The array is modified in place.

• scale (int, optional) – Pixel size used for each bitmap cell. Defaults to 2.

• outline_color (tuple[int, int, int] or None, optional) – RGB tuple used to draw an outline around glyphs or None to disable outlining. Defaults to (0, 0, 0).

• outline_thickness (int, optional) – Outline thickness in pixels measured in bitmap units. Defaults to 1.

See also

render_bitmap_text_to_array() for the drawing implementation.

numberlink.number_render.build_endpoint_labels(endpoints: collections.abc.Iterable[tuple[Coord, Coord]] | numpy.typing.NDArray[numpy.int_], pixels_per_cell_h: int, pixels_per_cell_w: int, min_scale: int | None = None, max_scale: int | None = None, gridline_thickness: int = 0) → list[tuple[str, Coord, RGBInt, int]]

Compute label specifications for grid endpoints.

Accept either a NumPy array of shape (num_colors, 2, 2) with endpoint coordinates in (row, col) format or an iterable of ((r0, c0), (r1, c1)) pairs. For each endpoint this function computes a text label string, a pixel center position suitable for render_bitmap_text_to_array(), and an adaptive bitmap scale that fits within the cell size.

The returned color tuple is a suggested foreground color for the text. The caller may override this when drawing. The function does not perform any drawing itself.

Parameters:

• endpoints (collections.abc.Iterable or numpy.ndarray) – Endpoint coordinate pairs. Supported formats are an array with shape (num_colors, 2, 2) or an iterable of pairs.

• pixels_per_cell_h (int) – Height of a single grid cell in pixels.

• pixels_per_cell_w (int) – Width of a single grid cell in pixels.

• min_scale (int or None, optional) – Minimum bitmap scale to suggest. If None no minimum is enforced. Defaults to None.

• max_scale (int or None, optional) – Maximum bitmap scale to suggest. If None no maximum is enforced. Defaults to None.

• gridline_thickness (int, optional) – Thickness of grid lines in pixels. Offsets label centers away from gridline pixels. Defaults to 0.

Returns:

A list of tuples (text, center, color, scale) where text is the string to draw, center is the pixel (x, y) center for render_bitmap_text_centered(), color is a suggested RGB foreground tuple, and scale is an integer bitmap scale.

Return type:

list[tuple[str, tuple[int, int], tuple[int, int, int], int]]

See also

render_bitmap_text_centered() and render_bitmap_text_to_array() for drawing functions that consume these specifications.