ASCIIscape is a simple Python CLI for converting images into ASCII that was made for CS50's final project.
You can install it by running pip install asciiscape from your terminal.
To run ASCIIscape type python -m asciiscape in your terminal of choice.
Then provide the PATH of the IMAGE you want to convert.
COLOR or GRAYSCALE: sets the resulting ASCII image to be printed either with color or in black and white, respectively.
SMALL or BIG or BRAILLE: sets the resulting ASCII image to be printed with a small charset (10 levels of brightness), a big charset (91 levels of brightness) or a braille charset.
DITHER and THRESHOLD: sets if the original image is to be dithered and the brightness threshold that the pixels are going to be compared against.
Choose your options and get your image converted to ASCII !
From left to right - Original, Small Charset, Braille Charset
The code is divided into 3 separate files "__main__.py", "console.py" and "imgUtils.py":
--->"__main__.py"" is mainly responsible for calling all of the functions from the other two functions, it's also the file that is run when the user types the command to start the application into the terminal.
--->"console.py" contains the functions that print text into the terminal and prompt the user for input, including the title, options, and ASCII image.
--->"imgUtils.py" contains all of the functions that relate to the processing of the images and arrays, including: loading and resizing images, converting an image to array of pixels, iterating through array of pixel, converting pixels to ASCII chars and dithering.
Roughly, the step by step, of how the program works is by taking the path of a image provided by the user and getting the conversion options, loading it with Pillow, resizing it to fit the terminal window, converting to a numpy array, where each element represents a pixel of the image, iterating through this array and converting each pixel into a ASCII character, which gets put into its own numpy array, then printing the ASCII character array with rich using the parameters chosen by the user.
The libraries Pillow, numpy and rich were used throught the entirety of the project. Pillow for the image loading and manipulation, numpy for working with arrays and rich for interaction with the terminal, without these libraries this project would not have been possible, so a massive thanks to all of them.
This project is a Python package made with Poetry, as such it has the main package folder "asciiscape", which contains the Python source code and the "__init__.py" file which defines the package. It also has the "pyproject.toml" file, which contains three tables, one that contains metadata about the package, another with the package dependencies and the last one with the Poetry dependencies.