Skip to content

Convert videos, images, gifs, and even live video to ASCII art! (Now with color support)

License

Notifications You must be signed in to change notification settings

Iapetus-11/To-ASCII

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

To-Ascii Code Quality PYPI Version PYPI Downloads

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

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:

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