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[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
- 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
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
- 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]
apply_opencv_fx
(image
:numpy.ndarray
, *,resize_dims
:Optional[Tuple[int, int]]
) ->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-6.0.1.tar.gz
(16.8 kB
view hashes)
Built Distribution
to_ascii-6.0.1-py3-none-any.whl
(20.6 kB
view hashes)