Skip to content
Asciiii project for Mhacks 2018
Branch: master
Clone or download
This branch is even with Allen-Wu:master.

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


Made in MHacks Build Status

Asciiii is an ASCII style converter made during MHacks11. It supports image (jpg/jpeg/png/gif) inputs and outputs the ASCII-style text strings depicted by the edge information of the input.

Table of Contents

Getting Started

There are two ways of accessing our project.

  • Visit our website
  • Clone the repo and run it on your own machine

These following instructions will get you a copy of the project up and running on your local machine for development and testing purposes.


  • Clone the GitHub repository
git clone


  • Install required libraries
pip install -e .
  • Run the program in terminal
python asciiii/ -h
usage: [-h] [-f FILE] [-l LINE] [-v] [-e ETA] [-li] [-g] [-c]

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  input image file path
  -l LINE, --line LINE  desired image width
  -v, --video           real-time video mode, need your camera
  -e ETA, --eta ETA     hyper-parameter for ascii matching
  -li, --light          use a small set of ascii with high frequency
  -g, --gif             generate a real-time gif with specific duration
  -c, --color           colorful mode


Web Application

alt text

Static Images and Gif

Static Image Gif

Colored Edges

alt text

Real-time Streaming

Camera Demo

Optimization Attempts

The bottleneck of the algorithm mainly lies in the computation process of determining the proper ascii character for each subpart of the input image. The computation process focuses on the comparing similarity of two grids based on the Hamming Distance. We try to optimize this process by different approaches.


Several heuristics methods can be used to directly map one subpart of image into an ascii character. For example, if the average pixel value is lower than one low threshold, it can be directly mapped to a empty space character.



We try using multi-threading module threading and assign one thread for each subpart computing. The best number of threads is between 8 and 10. However, the cost of creating thread is higher than expected, and the performance is worse than single thread.


Similar approach is used for multi-processing method, which is based on python module Pool module. However, the cost of creating separate process is also too high.

Machine Learning

In the field of computer vision, machine learning is very popular to analysis the feature in the image. We tried to implement a neural network to classify the windows in the target images based on which ascii character is most similar to the pixels graphically.


Since the sketch image after edge detection can be impressed as a binary image, we employ the multi-layer-percepton instead of complicated neural network such as CNN. The validation accuracy is limited to 70% on the dataset we generated.

Machine-generated dataset

The baseline method is using Hamilton distance to measure the similarity between image windows and asciiii characters. For lack of time, we use the Hamilton algorithm instead of labeling the image window by hand to generate training data. As a result, the validation accuracy is not very impressive.

We also print windnow and compare the prediction of two algorithms and find the machine learning model makes no more sense. In the following picture, "target" corresponds to Hamilton algorithm and prediction corresponds to machine learning.

alt text


Algorithm Packages

  • numpy, scientific computing and matrix operations
  • scipy, numerical algorithms and statistics
  • opencv-python, computer visions and image processing
  • imageio, interface for read and write images
  • PIL, Python image library
  • matplotlib, produce quality figures
  • torch, neural networks

Server Packages

  • flask, built-in web application server
  • sh, function caller
  • Werkzeug, WSGI utility library
  • Jinja2, HTML templates
You can’t perform that action at this time.