API Documentation

This section provides detailed documentation for all piltext modules and classes.

Core Modules

FontManager

ImageDrawer

ImageHandler

TextBox

TextGrid

ConfigLoader

ConfigExporter

Specialized Modules

ImageDial

ImageSquares

ImagePlot

ASCIIArt

ASCII art image conversion.

This module provides utilities for converting PIL images to ASCII art representations. It supports both colored (using ANSI escape codes) and monochrome ASCII output.

Examples

Convert an image to colored ASCII art:

>>> from PIL import Image
>>> from piltext.ascii_art import display_as_ascii
>>> img = Image.open("example.png")
>>> ascii_art = display_as_ascii(img, columns=80)
>>> print(ascii_art)

Convert to monochrome ASCII art:

>>> ascii_art = display_as_ascii(img, columns=60, monochrome=True)
>>> print(ascii_art)

Use custom characters:

>>> ascii_art = display_as_ascii(img, char="█▓▒░ ", columns=100)
>>> print(ascii_art)
piltext.ascii_art.display_readable_text(texts: list[str], width: int = 80, line_spacing: int = 1, center: bool = True, colors: list[str | int | None] | None = None, anchors: list[str | None] | None = None, grid_info: dict | None = None) → str[source]

Display text content in readable ASCII format.

Parameters:

  • texts (list[str]) – List of text strings to display.

  • width (int, optional) – Width for centering text. Default is 80.

  • line_spacing (int, optional) – Number of blank lines between text items. Default is 1.

  • center (bool, optional) – Whether to center text. Default is True.

  • colors (list[str or int or None], optional) – List of colors for each text item. Can be hex strings (#RRGGBB), integers (grayscale), or None. Default is None.

  • anchors (list[str or None], optional) – List of anchor positions for each text item (e.g., ‘mm’, ‘lt’, ‘rb’). Default is None.

  • grid_info (dict, optional) – Grid layout information including rows, columns, and merge cells. Default is None.

Returns:

Formatted text output with optional ANSI color codes.

Return type:

str

piltext.ascii_art.display_as_ascii(img: Image, columns: int = 80, width_ratio: float = 2.2, char: str | None = None, monochrome: bool = False) → str[source]

Convert a PIL Image to ASCII art representation.

Parameters:

  • img (PIL.Image.Image) – The image to convert to ASCII art.

  • columns (int, optional) – Target width in characters for the ASCII output. Default is 80.

  • width_ratio (float, optional) – Character aspect ratio adjustment (characters are typically taller than they are wide). Default is 2.2.

  • char (str, optional) – Custom characters to use for rendering, ordered from darkest to brightest. If None, uses default characters “ .:−=+*#%@”.

  • monochrome (bool, optional) – If True, output monochrome ASCII without ANSI color codes. If False, use ANSI escape codes for colored output. Default is False.

Returns:

The ASCII art representation of the image, with newlines separating rows. If colored, includes ANSI escape codes.

Return type:

str

Examples

Basic colored ASCII art:

>>> from PIL import Image
>>> img = Image.open("photo.jpg")
>>> ascii_art = display_as_ascii(img, columns=80)
>>> print(ascii_art)

Monochrome ASCII art with custom width:

>>> ascii_art = display_as_ascii(img, columns=60, monochrome=True)
>>> print(ascii_art)

Custom character set:

>>> ascii_art = display_as_ascii(img, char="█▓▒░ ", columns=100)
>>> print(ascii_art)

Notes

  • The image is automatically resized to fit the specified column width

  • Brightness is calculated from the grayscale version of the image

  • Color matching (when not monochrome) uses a predefined 16-color palette

  • The aspect ratio is adjusted using width_ratio to account for terminal character dimensions