oakamoore/image-to-ascii

A command line tool for converting images to ASCII art

image-to-ascii

Overview

A command line tool for converting images to ASCII art.

Installation

1. Clone this project

git clone https://github.com/Oakamoore/image-to-ascii.git

2. Step into the repository

cd image-to-ascii

3. Build the project using CMake

# Configure the build
cmake -S . -B build

# Build project binaries 
cmake --build build

Specifying a Build Configuration

Depending on the type of CMake generator being used, a build configuration (Debug, Release etc.) can be specified as follows:

Single Configuration Generator

# Configure a release build
cmake -S . -B build -D CMAKE_BUILD_TYPE=Release

# Build release binaries
cmake --build build

Multi-Configuration Generator

# Configure the build
cmake -S . -B build 

# Build release binaries
cmake --build build --config Release

Disabling Testing

To prevent tests from being built, append -D ENABLE_TESTING=0 to the build configuration command.

Usage

Once the project is built, navigate to the newly created build directory, image-to-ascii/build/, and locate the executable.

1. Run the program once, to create the input/ and output/ directories (if they do not already exist):

./image-to-ascii

2. Populate the input/ directory with the images to be converted

3. Run the program again, this time supplying command line arguments - in the form of the names of images with their file extensions:

./image-to-ascii apple.png banana.png 

If the arguments provided are valid image names, the output/ directory will be populated as follows:

# Place images to be converted here
input/
	apple.png
	banana.png

# Creates a directory based on the image's file name
# Holds the intermediate conversion steps (defaulted to 'png')
output/	
	apple/
		apple_resized.png
		apple_greyscale.png
		apple_ascii.txt
	banana/
		banana_resized.png
		banana_greyscale.png
		banana_ascii.txt

For subsequent uses the first step can be skipped, so long as the intput/ directory exists.

Testing

Once the project is built, navigate to image-to-ascii/build/tests/, and locate the testing executable.

The tests/../input/ directory should be populated by a sample image - if this isn't the case, then delete the image-to-ascii/build/ directory and rebuild the project.

Run the test(s) with the following command:

./image-to-ascii-tests

Known Issues

Secure Functions

MSVC defaults to its implementation of secure _s functions (that are poorly supported).

stb_image_write.h (as of this commit ) defines __STDC_LIB_EXT1__ to determine whether or not to use these _s functions, though certain versions of Visual Studio require __STDC_WANT_SECURE_LIB__ to function.

This project's workaround is defining _CRT_SECURE_NO_WARNINGS in image.cpp, to suppress deprecation warnings, in favour of the non _s functions.

Warnings as Errors

This project was built with Visual Studio, and has both Warnings as Errors (/WX) and Warning Level Four (/W4) enabled. This project also makes use of the stb image processing header libraries, which don't compile cleanly with /W4.

This project's solution is wrapping the offending third party header library includes in #pragma warning(push, n) and #pragma warning(pop) to temporarily disable warnings:

#pragma warning(push, 0)
#include "stb_image.h"
#include "stb_image_write.h"
#include "stb_image_resize2.h"
#pragma warning(pop)

This is of course implementation defined, so not all compilers will support this. If this doesn't work for your specific compiler, consider temporarily disabling your equivalent of /W4 when using this project.