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 details)

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

Details for the file to-ascii-6.0.1.tar.gz.

File metadata

  • Download URL: to-ascii-6.0.1.tar.gz
  • Upload date:
  • Size: 16.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.2.1 CPython/3.10.8 Darwin/21.6.0

File hashes

Hashes for to-ascii-6.0.1.tar.gz
Algorithm Hash digest
SHA256 3c2622b0d45cec8af422cd0cd0cc6d3972f87fc5f8045020c9b6558642d6d358
MD5 be60226f91771c5ba5b868a34422f499
BLAKE2b-256 9f2d2354a1827ae033195bbaa94a796fc320edab5796f9f5ad97c0bffeea3980

See more details on using hashes here.

File details

Details for the file to_ascii-6.0.1-py3-none-any.whl.

File metadata

  • Download URL: to_ascii-6.0.1-py3-none-any.whl
  • Upload date:
  • Size: 20.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.2.1 CPython/3.10.8 Darwin/21.6.0

File hashes

Hashes for to_ascii-6.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 992e9f3c3e91207b3c2986106a8d1665664a391d475246745790afcf4eb9f080
MD5 77b2358b961e67fb4181dfd7384b87e0
BLAKE2b-256 8464eaaea5edea186009f9259723c2b3b7a91c109718735fefef81889fbf57ec

See more details on using hashes here.

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