yera.runtime.handlers._charts.common

Shared utilities for Kitty chart handlers: terminal geometry, figure sizing, and image emission.

Symbols

def figure_geometry — Compute figure dimensions and font sizes from terminal geometry.
def get_char_cell_px — Query the terminal for its character cell size in pixels.
def kitty_emit — Emit PNG bytes using the Kitty terminal graphics protocol.

figure_geometry

figure_geometry(
    console_width: int,
    char_w_px: int,
    char_h_px: int,
    font_scale: float = 1.0,
) → tuple[float, float, int, int]

Compute figure dimensions and font sizes from terminal geometry.

For narrow terminals (below 100 columns) the figure uses the full available width minus padding. For wider terminals it is capped at 75% of the available width, and never exceeds _MAX_FIG_WIDTH_IN inches regardless of terminal size. Font sizes scale proportionally with the figure width.

Parameters

console_width
type: int

Terminal width in character columns.

char_w_px
type: int

Character cell width in pixels.

char_h_px
type: int

Character cell height in pixels.

font_scale
type: float = 1.0

Multiplicative scale factor applied to both font sizes.

Returns

type: tuple[float, float, int, int]

Tuple of (fig_width_inches, fig_height_inches, axis_font_pt, tick_font_pt).

get_char_cell_px

get_char_cell_px() → tuple[int, int]

Query the terminal for its character cell size in pixels.

Sends ANSI escape sequence CSI 14 t to request the terminal window size in pixels, then divides by the character grid dimensions to derive the cell width and height. Falls back to sensible defaults if the terminal does not respond or the query fails.

Note: this is unix-only and will fallback to (8, 16) on windows.

Returns

type: tuple[int, int]

Tuple of (char_width_px, char_height_px).

kitty_emit

kitty_emit(
    png: bytes,
    px_width: int,
    console_width: int,
    left_pad: int = 4,
    char_w_px: int = 10,
) → None

Emit PNG bytes using the Kitty terminal graphics protocol.

Centres the image horizontally within the terminal.

Parameters

png
type: bytes

PNG image bytes.

px_width
type: int

Pixel width of the image, used for centering.

console_width
type: int

Terminal width in columns, used for centering.

left_pad
type: int = 4

Minimum left indent in columns, applied when the computed centre indent is smaller.

char_w_px
type: int = 10

Character cell width in pixels, used to convert the image's pixel width to a column count for centering. Defaults to 10.