Skip to main content

Convert videos, images, gifs, and even live video to ASCII art!

Project description

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

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:

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

to-ascii-6.0.1.tar.gz (16.8 kB view hashes)

Uploaded Source

Built Distribution

to_ascii-6.0.1-py3-none-any.whl (20.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page