ASCII Art Converter Website
This project is a website that allows users to upload an image, transform the image into black and white ASCII art, and then display the resulting ASCII art to the user on the site. The website also works the other way around: users can submit ASCII art, transform the ASCII text into a black and white image, and then display the resulting image to the user on the site. The ASCII/image conversions are implemented by the ascii_art_converter library crate written by the authors. This crate uses the image crate to aid in these conversions. The web application is implemented by the authors in the ascii_art_converter_website binary crate. This crate uses the actix-web crate to run a web server and create routing where both static HTML files and HTML files created by the Handlebars templating engine are served. All HTML files are styled using the Bootstrap CSS library. The ascii_art_converter_website crate uses the ascii_art_converter crate to perform image-to-ASCII and ASCII-to-image conversions.
When a user navigates to the root route of the web application, they will have a choice of using the image to ASCII art converter or the ASCII art to image converter. Each of these converters will go to separate web routes with separate forms for either image (PNG or JPEG) input or ASCII text input. For the image to ASCII art converter, the web application will allow users to upload an image via an HTML form. After the image is submitted, the MIME type is validated to be supported by the application. Then once the server generates the ASCII art, it will display the ASCII to the user using HTML generated by the Handlebars templating engine. For the ASCII art to image converter, the web application will allow users to enter ASCII art into a text box via an HTML form. After the form is submitted, the server will verify that valid ASCII text was submitted. Then it will generate an image based on the ASCII art and will display the image to the user using HTML generated by the Handlebars templating engine. The results for both the image to ASCII and ASCII to image conversion can be copied by the user directly off the web page. Finally, each results page includes a back button to allow the user to return to the root home page and start the submission process over again from scratch.
To build the project, clone this git repository to your local machine. Then navigate into the ascii-art-converter-website directory and run the following command to compile the project and start the web server:
cargo run
You'll see terminal output similar to the following once the web app is up and running:
[2023-06-09T04:58:50Z INFO actix_server::builder] starting 8 workers
[2023-06-09T04:58:50Z INFO actix_server::server] Actix runtime found; starting in Actix runtime
Finally, navigate to this url in your browser to display the homepage of the web app and follow the instructions on the page to start doing some ASCII/image conversions: http://127.0.0.1:8080/.
To ensure our project worked, we did a lot of incremental manual testing. As each new change was added both the new change was thoroughly tested manually and regression tests were performed to ensure that no existing functionality was broken by the change. This included testing both happy path scenarios and negative test cases.
Throughout the development of the ascii_art_converter library crate, automated test cases were added to help aid in this incremental testing. Additionally, two example programs were composed to test the library crate throughout its development. Once the crate was finished, a richer suite of automated unit tests was completed to more thoroughly test the application. For the ascii_art_converter_website binary crate, we relied solely on manual testing using a web browser throughout its development, but a full suite of automated unit tests was added to test the project upon its completion.
An example demo illustrating the operation of our code can be found here: https://youtu.be/XGguxxa04WY.
We finished the entire MVP of the project which included allowing the user to convert ASCII art to an image and an image to ASCII art on website. This also included all of the necessary form input validation with informative error messages displayed to the user that allowed them to retry with new input. We are also able to display the results of both types of conversion to the user on the site. Both the ASCII art and PNG image results page have a back button that takes the user back to the homepage of the app, so that if they want, they can choose to start a new ASCII or image conversion. Finally, users can take directly copy the ASCII text results off of the page and can use the browser's native "Save Image As..." function to save the image result.
Unfortunately, we were not able to meet our stretch goals of adding a download button to the results page for either ASCII art or PNG images or allowing the user to choose scaled up or scaled down versions of their results. Additionally, we ended up abandoning our original plan to use workspaces to separate our work because it ended up creating issues with creating file paths in the website. It was easier to work without workspaces than to try to force it. Additionally, we came across an issue in Chrome when attempting to use the browser's native "Save Image As..." function to save an image result. When selecting this option, we would receive a network error which was odd because we were able to use Chrome's dev tools as well as our own server log to validate that no network requests were being sent. If the user took the extra step to click on the failed download and select the "Resume" option, the image download completed successfully. We researched this issue extensively online and found many other examples of others who have ran into this same error in downloading images produced by forms over the last decade without identifying a single resolution. We did not encounter this error in the other browsers tested (Firefox and Safari), so given that this seems to be part of a larger Chrome-specific error, we decided that this was not an issue we could prioritize and resolve within the time constraints of our project.
Despite these challenges, we are extremely pleased with the end result of our project. We put in a lot of time and effort into our project, including very thorough manual and automated testing. We also ended up overcoming a number of difficult and unexpected challenges. For example, ASCII art of a reasonable size will be translated into an extremely small image because there is a 1:1 translation from each ASCII character to an individual pixel. This meant we had to scale up images that were created from ASCII art. There were trade offs to consider when picking an algorithm for doing this scaling because some made the resulting image more blurry than desired and others made it more pixelated than desired, so a lot of fine tuning was required to create a resulting image of reasonable quality.
We also took a lot of pride in the overall quality of our code and the time we took to make sure our code was refactored to be well modularized, clearly commented, and easily testable. Some of the automated testing was actually more difficult and time consuming than the creation of the actual project code (for example, figuring out how to create test data for multipart forms). However, we learned a lot from doing this work, so we both felt it was worth forgoing our stretch goals to take the time to invest in these tests. Ultimately, we were more satisfied with the quality of our collaboration on this project. While we worked on some sections individually, we paired quite a bit on many portions of the project which resulted in more learning opportunities for both of us as well as an overall better quality end result.
In the future, we would love to implement garbage collection of the PNG files that result from ASCII to image conversions and are placed in the /static/conversion_results directory. In a production caliber app, these files would be deleted by a garbage collector when they were no longer needed. Additionally, we found simpler PNG and JPEG images (rather than more complex and detailed images) resulted in much clearer and better quality ASCII art. We tested this out using other online image to ASCII art converters and found similar results to those produced by our project. So while this left us feeling that overall the quality of our image to ASCII conversion work was adequate when compared with existing converters, we still feel that if given more time, we would ideally love to try to explore more algorithms for refining our ASCII results to work with more complex image input.
This project is licensed under the MIT License, the terms of which can be found in the LICENSE.txt file.
The developer documents can be generated using the doc comments found throughout the code using the following command from the ascii-art-converter-website directory:
cargo doc --open
Generating the documentation this way will automatically open the docs in your browser. It will also include the documentation of all of the dependencies used in our project, so the list of crates on the left hand side of the page will initially look a bit overwhelming. However, it's worthwhile to produce the documentation with all of this additional detail because it allows the documentation for the ascii_art_converter_website crate and the ascii_art_converter crate to include direct links to types and functions it leverages from outside crates and overall enriches that portion of the documentation. The ascii_art_converter_website crate and the ascii_art_converter crate can be found in the list of crates on the left hand side of the page, and these are the two crates that contain the documentation that was generated for the specific code in this project.
The ascii_art_converter_website binary crate creates a web server that responds to specific route requests. Although it has documentation to help navigate the code base for this crate, it's not meant to be used as library for another project; rather, it is a completed project on its own. The ascii_art_converter_website crate is a client of the ascii_art_converter library crate, and the ascii_art_converter crate could be separated out from this overall package. Then the public interface of this crate could be used as a library for another project. The ascii_art_converter_website crate leverages the ascii_to_image() and image_to_ascii() functions from the ascii_art_converter crate to perform ASCII/image conversions as well as the ConvertError enum to identify errors returned from these functions.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent