menshiva / ascii-art

A minimal desktop app for image to ASCII art conversion written in Python3.

ASCII Art

Key Features 🍪 | Requirements 🧬 | Build 🚀 | How to Use 📃 | Solving Problems 🐛 | Credits ✍

Key Features 🍪

• Supports JPEG, PNG, PPM, PGM image formats
• Light / Dark theme
• ASCII art symbols size adjustment
• Your own ASCII art symbol style
• Preserve an image's aspect ratio
• ASCII art animation with an adjustable duration
• Export your art to .txt file in full image resolution
• Available effects:
  • Contrast
  • Negative
  • Sharpen
  • Emboss

Requirements 🧬

• Python 3.8.1
• NumPy 1.19.5
• PySide2 5.15.2
• imageio 2.9.0
• pytest 6.2.1

Build 🚀

Install dependencies

Install all necessary dependencies:

$ pip3 install -r requirements.txt

Run application

Run ASCII Art:

$ python3 app.py

Test application (optional)

Use this command for ASCII Art testing:

$ pytest -v

How to Use 📃

Basics

1. Build and run the application
2. Press the menu button in the toolbar to open image list drawer
3. Press the Add image button to add image
4. In popup dialog:
   • Fill the Art name box (required)
   • Choose a path to your image from a file browser via Browse button (required)
   • Choose effects to be applied to your art (optional)
5. Press the Add button and wait for the image to convert
6. Enjoy your ASCII art!

Image properties

• To edit your image (changing art name or applying new effects):
  1. Press the three dots button below the needed image
  2. Click on the Properties button
  3. Apply your changes
  4. Press the Save button and wait for the image to re-convert
• To remove image from the list:
  1. Press the three dots button below the needed image
  2. Press the Remove image button
• To export image to .txt file:
  1. Press the three dots button below the needed image
  2. Press the Export to text file button
  3. Create new text file from opened file browser

Animation

• To enable this function you need to add at least 2 images
• Use the:
  1. Play animation button in a toolbar to start animation
  2. Stop animation button in a toolbar to stop animation

Settings

1. Press the three dots button in a toolbar
2. Press the Settings button

Optional utils

• Adjust ASCII art size by a slider placed on a toolbar
• Switch between Light and Dark theme in Settings in a Theme section
• Adjust animation duration by a slider in Settings in an Animation duration section
• Style ASCII art with your own symbols in Settings in a Grayscale level section:
  • Enter the sequence of symbols from darkest to lightest
  • Now your ASCII art will be displayed by these symbols

Solving Problems 🐛

Could not load the Qt platform plugin

• In case you are getting the following error while trying to run app.py:

Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Aborted (core dumped)

Then you might need to install libxcb-xinerama0 via command line:

$ sudo apt-get install libxcb-xinerama0

Credits ✍

Third-party libraries

• NumPy
• Qt for Python
• imageio

Used algorithms

• If you are interested in program's logic and algorithms, see also: about.pdf
• Image scaling algorithm
• RGB to grayscale preserving luminance algorithm
• Contrast effect algorithm
• Convolution (image kernel):
  • Image kernel
  • Kernel visualisation
  • Relation between image kernel and Fourier transform
  • Discrete Fourier Transform

Related

• Special thanks to Freepik for app icon!

Author

• Ivan Menshikov ([e-mail])

License

Copyright 2021 Ivan Menshikov

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.