Documentation

Module contents

Asciify package.

class asciify.AsciiManager(fontname: Optional[Union[str, Path]] = None, fontsize: int = 42, verbose: bool = True)

Bases: object

Manager class for ASCII art transformation and settings storage.

__init__(fontname: Optional[Union[str, Path]] = None, fontsize: int = 42, verbose: bool = True)

Initialize ASCII art transformation manager.

Parameters

  • fontname – Font name or path for image approximation, defaults to “courier.ttf”.

  • fontsize (int) – Font size for image approximation.

  • verbose (bool) – Verbosity flag.

Raises

OSError – No access to the requested font.

_find_closest_char(image: ~PIL.Image.Image, chars: ~typing.Dict[str, ~nptyping.ndarray.NDArray[typing_extensions.Literal[*, *], ~numpy.uint8]]) → str

Find a character with a glyph closest to the given image.

Runs exhaustive search over all the characters. Assumes the image and all character glyphs have common shape. Closeness is treated in terms of Frobenius matrix norm. Characters are filtered by intensity for speed up.

Return type

str

Parameters

  • image (Image) – Input image to compare with glyphs.

  • chars – Mapping from characters to grayscaled 2D glyphs.

Returns

Character with the closest glyph.

static _get_tile_size(input_size: Tuple[int, int], output_size: Tuple[int, int]) → Tuple[Tuple[int, int], Tuple[int, int]]

Get tile size based on the given input and output image sizes.

Calculate sizes of tiles \((T_W \times T_H)\) and tile coverage window \((C_W \times C_H)\) given input image \((I_W \times I_H)\) and tiled image \((O_W \times O_H)\) sizes.

\[\begin{split}\begin{gather*} T_W = \left\lfloor \frac{I_W}{O_W} \right\rfloor, \quad T_H = \left\lfloor \frac{I_H}{O_H} \right\rfloor \\ C_W = O_W * T_W, \quad C_H = O_H * T_H \end{gather*}\end{split}\]
Parameters

  • input_size – Input image size.

  • output_size – Tiled image size.

Returns

Tile and tile coverage window sizes.

Raises

ValueError – Tiled image size cannot be larger than the original one along any axis or have non-positive size.

_process_image_rowspan(metapixels: ~typing.Generator[~typing.Generator[~PIL.Image.Image, None, None], None, None], resized_chars: ~typing.Dict[str, ~nptyping.ndarray.NDArray[typing_extensions.Literal[*, *], ~numpy.uint8]], output_size: ~typing.Tuple[int, int]) → str

Process an image cropped into metapixels and transform it into ASCII art.

Return type

str

Parameters

  • metapixels – Image tiles generator.

  • resized_chars – Mapping from characters to grayscaled 2D glyphs.

  • output_size – Output ASCII art size in form (width, height).

Returns

String containing ASCII art.

transform(image: Image, output_size: Tuple[int, int]) → str

Transform an image into an ASCII art via glyph similarity scoring.

Return type

str

Parameters

  • image (Image) – Input image to transform.

  • output_size – Output ASCII art size in form (width, height).

Returns

String containing ASCII art.

Raises

ValueError – Output ASCII art cannot be larger than the original one along any axis or have non-positive size.

asciify.calculate_intensity(image: ~nptyping.ndarray.NDArray[typing_extensions.Literal[*, *], ~numpy.uint8]) → float

Evaluate intensity value for gray image.

Intensity is calculated as mean value for the gray image represented as 2D numpy array.

Return type

float

Parameters

image (NDArray) – Input gray image.

Returns

Intensity value.

asciify.draw_char(font: ImageFont, char: str) → Image

Draw ASCII character glyph and shrink image to fit the size.

Return type

Image

Parameters

  • font (ImageFont) – Font to draw a character.

  • char (str) – A character to draw.

Returns

ASCII character glyph.

asciify.get_tiles(image: Image, tile_size: Tuple[int, int]) → Generator[Generator[Image, None, None], None, None]

Crop an image into tiles of fixed size.

Right and bottom boundary tiles might be incomplete.

Parameters

  • image (Image) – Input image to crop.

  • tile_size – Tile size.

Returns

Image tiles generator.

asciify.score_similarity(lhs: ~nptyping.ndarray.NDArray[typing_extensions.Literal[*, *], ~numpy.uint8], rhs: ~nptyping.ndarray.NDArray[typing_extensions.Literal[*, *], ~numpy.uint8]) → float64

Evaluate score similarity between two gray images.

Get score similarity based on Frobenius matrix norm for two gray images represented as 2D numpy arrays, i.e. for grayscale matrices \(A\) and \(B\) the score is

\[-\Vert A - B\Vert_F^2 = -\sum_{i,j} \left(A_{ij} - B_{ij}\right)^2\]
Return type

float64

Parameters

  • lhs (NDArray) – Left score operand.

  • rhs (NDArray) – Right score operand.

Returns

Similarity score.