Converts pictures into ASCII art
Project description
ASCII Magic
Python package that converts images into ASCII art for terminals and HTML. Thanks to Colorama it's compatible with the Windows terminal. Code based on ProfOak's Ascii Py.
Changelog
v1.6: OOP functionality, to_file()
Instalation
pip install ascii_magic
Basic usage
import ascii_magic
my_art = ascii_magic.from_image_file('images/moon.jpg')
ascii_magic.to_terminal(my_art)
Result:
Available functions
from_image_file()
Converts an image file into ASCII art.
ascii_magic.from_image_file(
path: str,
columns: int = 120,
width_ratio: float = 2.2,
char: str = None,
back: Back = None,
mode: Modes = Modes.TERMINAL,
) -> str
path
: a PIL-compatible file, such as a jpeg or pngcolumns (optional)
: the number of characters per row, more columns = wider artwidth_ratio (optional)
: ASCII characters are not squares, so this adjusts the width to height ratiochar (optional)
: instead of using many different ASCII glyphs, you can use a single one, such as '#'back (optional)
: In terminal mode, sets the background color with one of:ascii_magic.Back.BLACK
ascii_magic.Back.RED
ascii_magic.Back.GREEN
ascii_magic.Back.YELLOW
ascii_magic.Back.BLUE
ascii_magic.Back.MAGENTA
ascii_magic.Back.CYAN
ascii_magic.Back.WHITE
mode (optional)
: one of:ascii_magic.Modes.TERMINAL
: outputs ASCII with terminal color codes (8 tones)ascii_magic.Modes.ASCII
: outputs pure ASCII with no color codes, resulting in a "grayscale" imageascii_magic.Modes.HTML_TERMINAL
: outputs HTML simulating terminal colorsascii_magic.Modes.HTML
: as above, but with full color
Example:
my_art = ascii_magic.from_image_file(
'images/lion.jpg',
columns=200,
back=ascii_magic.Back.BLUE
)
ascii_magic.to_terminal(my_art)
Result:
Example:
my_art = ascii_magic.from_image_file(
'images/lion.jpg',
columns=200,
width_ratio=2,
mode=ascii_magic.Modes.HTML
)
ascii_magic.to_html_file('ascii_art.html', my_art)
Result:
Example:
my_art = ascii_magic.from_image_file(
'images/lion.jpg',
columns=200,
mode=ascii_magic.Modes.ASCII
)
ascii_magic.to_terminal(my_art)
Result:
from_url()
As above, but using the URL of an image. Raises an urllib.error.URLError
if something goes wrong while requesting the image, but you can also catch it as an OSError
if you don't want to import urllib to your project.
ascii_magic.from_url(
url: str,
# same art creation settings as above
) -> str
url
: an URL which will be loaded via urllib (supports redirects)
Example:
try:
my_art = ascii_magic.from_url('https://source.unsplash.com/800x600?nature', columns=100)
except OSError as e:
print(f'Could not load the image, server said: {e.code} {e.msg}')
from_clipboard()
As above, but with the contents of the clipboard. Raises a OSError
if the clipboard doesn't contain an image.
Requires PyGObject under Linux.
ascii_magic.from_clipboard(
# same art creation settings as above
) -> str
Example:
try:
my_art = ascii_magic.from_clipboard(columns=100)
except OSError:
print('The clipboard does not contain an image')
from_image()
As above, but using an image loaded with Pillow.
ascii_magic.from_image(
img: Image,
# same art creation settings as above
) -> str
img
: PIL image object
Example:
from PIL import Image
img = Image.open('images/lion.jpg')
my_art = ascii_magic.from_image(img, columns=100)
init_terminal()
Initializes Colorama, which is required on Windows for displaying art in terminal mode. It's the same as doing colorama.init()
.
ascii_magic.init_terminal() -> None
to_terminal()
Initializes Colorama, which is required on Windows for displaying ASCII with color in terminal mode, and prints the art. It's the same as doing colorama.init()
and then print(art)
.
ascii_magic.to_terminal(
art: str
) -> None
to_file()
New in v1.6. Writes the art to a text file.
ascii_magic.to_file(
path: str,
art: str
) -> None
to_html_file()
Writes the art to a barebones HTML file inside a <pre>
.
ascii_magic.to_html_file(
path: str,
art: str,
styles: str = '...', # See description
additional_styles: str = '',
auto_open: bool = False
) -> None
path
: The relative path and filename of the HTML fileinput
: The markup which will be includedstyles (optional)
: A string with a bunch of CSS styles for the<pre>
element, by default:- display: inline-block;
- border-width: 4px 6px;
- border-color: black;
- border-style: solid;
- background-color: black;
- font-size: 8px;
additional_styles (optional)
: You can add your own styles without removing the default onesauto_open (optional)
: If True,webbrowser.open()
will be called on the HTML file
example:
my_art = ascii_magic.from_image_file('images/lion.jpg', mode=ascii_magic.Modes.HTML)
ascii_magic.to_html_file('lion.html', my_art, additional_styles='background: #222;')
quick_test()
Runs ascii_magic with a random Unsplash picture with the default parameters and prints it to the terminal.
ascii_magic.quick_test() -> None
The AsciiArt object
New in v1.6. The following functions return an AsciiArt
object: obj_from_url()
, obj_from_clipboard()
, obj_from_image_file()
and obj_from_image()
.
An AsciiArt object
has the following methods: to_terminal()
, to_file()
and to_html_file()
. These methods work as their non-oop counterparts described above and, in addition, they accept the same art settings as from_image_file()
(path, columns, width_ratio, etc).
OOP example:
my_art_obj = ascii_magic.obj_from_url('https://source.unsplash.com/800x600?nature')
my_art_obj.to_html_file(
'ascii_art.html',
columns=200,
char="@",
additional_styles='background: #222;'
)
obj_from_url()
Takes the URL of an image and returns an AsciiArt
object.
ascii_magic.obj_from_url(
url: str
) -> AsciiArt
obj_from_clipboard()
As above, but with the clipboard. Check from_clipboard()
for more information.
ascii_magic.obj_from_clipboard() -> AsciiArt
obj_from_image_file()
As above, but with the path of an image file.
ascii_magic.obj_from_image_file(
file_path: str
) -> AsciiArt
obj_from_image()
As above, but with an image loaded with PIL.
ascii_magic.obj_from_image(
img: Image
) -> AsciiArt
AsciiArt.to_terminal()
Generates an ASCII art, initializes Colorama and prints it to the terminal. All arguments are keyword arguments. Check from_image_file()
for more details about these art creation settings (columns, char, width_ratio, etc).
my_art_obj.to_terminal(
columns: int = 120,
width_ratio: float = 2.2,
char: str = None,
back: Back = None,
mode: Modes = Modes.TERMINAL,
) -> None
AsciiArt.to_file()
Generates an ASCII art and prints it to a text file. All arguments except file_path are keyword arguments.
my_art_obj.to_file(
file_path: str,
# same art creation settings as above
) -> None
AsciiArt.to_html_file()
Generates an ASCII art and prints it to an HTML file. All arguments except file_path are keyword arguments. Check the non-OOP version of this function for more details.
my_art_obj.to_html_file(
file_path: str,
styles: str = '...', # see the non-OOP version
additional_styles: str = '',
auto_open: bool = False
# same art creation settings as above
) -> None
Licence
Copyright (c) 2020 Leandro Barone.
Usage is provided under the MIT License. See LICENSE for the full details.
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
Built Distribution
Hashes for ascii_magic-1.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 937447d8677b7428856729c298c0264afd62fc2b8e7ff90c82000492cdc5f8d4 |
|
MD5 | 2953fc3a199435b77c2a3edfa9aa3655 |
|
BLAKE2b-256 | 020602879511c876fc5b0adc6009d739cfe3f53cfc6b32c5fb79e572fda93526 |