Convert videos, images, gifs, and even live video to ASCII art!
Project description
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
CLI Usage
Note: Required arguments are surrounded in <>
, optional arguments are surrounded in []
.
toascii <media_type> <source> <converter> [--gradient <string>] [--width <int>] [--height <int>] [--xstretch <float>] [--ystretch <float>] [--saturation <float>] [--contrast <float>] [--loop]
CLI Arguments
media_type
- the type of media, eitherimage
orvideo
source
- the source for the media, this is the primary argument in constructing an instance of an OpenCVVideoCapture
converter
- the converter used to convert the media, check this file for the available optionsgradient
- the characters used when converting an image to asciiwidth
- an integer value for the width in characters of the final converted imageheight
- an integer value for the height in characters of the final converted imagexstretch
- the amount to stretch the width byystretch
- the amount to stretch the height bysaturation
- how much to saturate the image, a value from -1.0 to 1.0.contrast
- how much to modify the contrast, a value from 0.0 to 1.0loop
- whether or not to loop the video when it is done playing
CLI Examples
# live video
toascii video 0 grayscaleconverternim --xstretch 3 --height 56 --saturation .25 --contrast .01
toascii image "C:\Users\miloi\Pictures\my_image.png" colorconverter
toascii video "C:\Users\miloi\Videos\omni_man.mp4" colorconverternim --height 32 --width 48 --saturation 0.5 --contrast 0.01 --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
- default value is
height
:Optional[int]
- height in characters of the final converted image- default value is
None
- must be greater than
0
- default value is
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
- default value is
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
- default value is
saturation
:float
- how much to adjust the saturation- default value is
0.5
(which increases the saturation) - must be between
-1.0
and1.0
,0.0
is no change to saturation
- default value is
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
and1.0
- default value is
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]
resize_image
(image
:numpy.ndarray
) ->numpy.ndarray
- abstract
- Implementations:
GrayscaleConverter
- converts media to grayscale asciiGrayscaleConverterNim
- converters media to grayscale ascii, see the Extensions sectionColorConverter
- converts media to colored ascii using ColoramaColorConverterNim
- converts media to colored ascii using Colorama, see the Extensions sectionHtmlColorConverter
- converts media to ascii in colored html spansHtmlColorConverterNim
- 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 astr
, it's assumed that it's a path to an image file - if
source
isbytes
orIOBase
it's assumed to be the data of an image and is decoded in-memory
- if
converter
:ConverterBase
- the converter used to convert the image- takes anything that implements
ConverterBase
- takes anything that implements
- 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 astr
, it's assumed that it's a path to an image file - if
source
isbytes
orIOBase
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 anint
, it's assumed to be the index of a camera device - see OpenCV's
VideoCapture
for more information
- if
converter
:ConverterBase
- the converter used to convert the image- takes anything that implements
ConverterBase
- takes anything that implements
fps
:Optional[float]
- the fps to play the video at- default value is
None
- if
None
then the fps used is fetched from OpenCV'sVideoCapture
API
- default value is
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
- default value is
- Methods:
get_ascii_frames
() ->Generator[str, None, None]
- returns a generator which yields each ascii frame as it is convertedview
() ->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 toTrue
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
Release history Release notifications | RSS feed
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-5.1.0.tar.gz
(17.0 kB
view hashes)
Built Distribution
to_ascii-5.1.0-py3-none-any.whl
(21.2 kB
view hashes)