to-ascii

To-ASCII

Converts videos, images, gifs, and even live video into ascii art!

• Works on most image and video types including GIFs
• Works on LIVE VIDEO

[DEMO SITE] [Video Example] [Video Example 2]

Installation

Via pip:

pip install to-ascii[speedups,cli]

• The speedups extra is recommended, see below
• The cli extra is required for CLI use (it adds click as a dependency)

CLI Usage

Usage: toascii [OPTIONS] {image|video} SOURCE {colorconverter|colorconverternim|grayscaleconverter|grayscaleconverternim|htmlcolorconverter|htmlcolorconverternim}

Options:
  -g, --gradient TEXT
  -w, --width INTEGER RANGE       [x>=1]
  -h, --height INTEGER RANGE      [x>=1]
  --x-stretch, --xstretch FLOAT RANGE
                                  [x>0.0]
  --y-stretch, --ystretch FLOAT RANGE
                                  [x>0.0]
  --saturation FLOAT RANGE        [-1.0<=x<=1.0]
  --contrast FLOAT RANGE          [0.0<=x<=1.0]
  --blur INTEGER RANGE            [x>=2]
  --loop
  --help                          Show this message and exit.

CLI Examples

# live video
toascii video 0 colorconverternim -h 103 --x-stretch 3.5 --blur 10 --contrast 0.01 --saturation 0.0

toascii image sammie.jpg grayscaleconverter -h 32 --x-stretch 2.1 --blur 20 --contrast 0.0 --saturation 0.0

toascii video IMG_7845.MOV colorconverternim -h 81 --x-stretch 2.5 --blur 15 --contrast 0.01 --saturation 0.0 --loop

API Reference

Usage Examples Folder

class ConverterOptions(*, gradient: str, width: Optional[int], height: Optional[int], x_stretch: float, y_stretch: float, saturation: float, contrast: Optional[float])

• pydantic model for converter options
• Parameters / Attributes:
  • gradient: str - string containing the characters the converter will use when converting the image to ascii
    • must be at least one character
  • width: Optional[int] - width in characters of the final converted image
    • default value is None
    • must be greater than 0
  • height: Optional[int] - height in characters of the final converted image
    • default value is None
    • must be greater than 0
  • x_stretch: float - how much to stretch the width by
    • default value is 1.0 (which doesn't change the width by anything)
    • must be greater than 0.0
  • y_stretch: float - how much to stretch the height by
    • default value is 1.0 (which doesn't change the height by anything)
    • must be greater than 0.0
  • saturation: float - how much to adjust the saturation
    • default value is 0.5 (which increases the saturation)
    • must be between -1.0 and 1.0, 0.0 is no change to saturation
  • contrast: Optional[float] - how much to increase the contrast by
    • default value is None (which doesn't apply any contrast filter)
    • must be between 0.0 and 1.0
  • blur: Optional[int] - how much to blur the image by
    • default value is None (which doesn't apply any blur)
    • must be greater than 0

class ConverterBase(options: ConverterOptions)

• base class for implementing converters
• Parameters:
  • options: ConverterOptions - Options used when converting media
• Methods:
  • abstract asciify_image(image: numpy.ndarray) -> str
  • calculate_dimensions(initial_height: int, initial_width: int) -> Tuple[int, int]
  • apply_opencv_fx(image: numpy.ndarray, *, resize_dims: Optional[Tuple[int, int]]) -> numpy.ndarray
• Implementations:
  • GrayscaleConverter - converts media to grayscale ascii
  • GrayscaleConverterNim - converters media to grayscale ascii, see the Extensions section
  • ColorConverter - converts media to colored ascii using Colorama
  • ColorConverterNim - converts media to colored ascii using Colorama, see the Extensions section
  • HtmlColorConverter - converts media to ascii in colored html spans
  • HtmlColorConverterNim - converts media to ascii in colored html spans, see the Extensions section

class Image(source: Union[str, bytes, IOBase], converter: BaseConverter)

• class for converting an image to ascii
• Parameters:
  • source: Union[str, bytes, IOBase] - the source of the image that is to be loaded and converted
    • if source is a str, it's assumed that it's a path to an image file
    • if source is bytes or IOBase it's assumed to be the data of an image and is decoded in-memory
  • converter: ConverterBase - the converter used to convert the image
    • takes anything that implements ConverterBase
• Methods:
  • to_ascii() -> str
    • returns the image converted by the converter
  • view() -> None
    • prints out the converted image to the console

class Video(source: Union[str, int, bytes, IOBase], converter: BaseConverter, *, fps: Optional[float], loop: bool)

• class for converting a video to ascii
• Parameters:
  • source: Union[str, int bytes, IOBase] - the source of the video that is to be loaded and converted
    • if source is a str, it's assumed that it's a path to an image file
    • if source is bytes or IOBase it's assumed to be the data of an image and is written to a temporary file before being loaded and decoded by OpenCV
    • if source is an int, it's assumed to be the index of a camera device
    • see OpenCV's VideoCapture for more information
  • converter: ConverterBase - the converter used to convert the image
    • takes anything that implements ConverterBase
  • fps: Optional[float] - the fps to play the video at
    • default value is None
    • if None then the fps used is fetched from OpenCV's VideoCapture API
  • loop: bool - whether or not to loop the video when it's done playing
    • default value is False
    • if the video source is live, this parameter is ignored
• Methods:
  • get_ascii_frames() -> Generator[str, None, None] - returns a generator which yields each ascii frame as it is converted
  • view() -> None - prints out each frame of the converted video
    • if the video source is not live, this method will first generate all frames and cache them in memory for a smoother playback
    • if the loop parameter was set to True earlier, then this will play the video and restart it when it finishes unless the source is live

Extensions

• For each converter available, there is a separate implementation written in Nim
• These implementations are generally orders of magnitude faster than their Python counterparts
• To use these extensions you must install Nim and install the to-ascii[speedups] package via pip or your package manager of choice