ASCII Art C Library for Real-Time Rendering

Header-only open-source C library for turning images and video frames into printable ASCII glyphs. Lightweight, WebAssembly-ready, and designed for real-time rendering workflows.

Connect to the PixLab Console Explore the PixLab Console for vision, document, and media APIs that complement local and embedded developer workflows.

Version 2.197 (Release Notes ↗)

ASCII Art is a header-only open-source C library with WebAssembly support developed by PixLab and inspired by the work of Nenad Markus ↗. It converts input images or video frames into printable ASCII characters in real time using a single decision tree ↗ built around pixel-intensity comparisons.

For a live demonstration with static images, webcam or camera input, and a walkthrough of the algorithm, visit art.pixlab.io.

ASCII Camera is now available on Unity Asset Store - assetstore.unity.com/packages/slug/165558 ↗

This implementation is based on the paper:
N. Markus, M. Fratarcangeli, I. S. Pandzic and J. Ahlberg, "Fast Rendering of Image Mosaics and ASCII Art", Computer Graphics Forum, 2015, dx.doi.org/10.1111/cgf.12597 ↗

Download
Getting Started
C API Reference

Download

ASCII ART HEX MODEL

This hex model is generated during training. It contains both the codebook and the decision tree used for real-time rendering. After downloading, place it in the same directory as the ASCII Art source files.

Download HEX Model

ASCII ART Source Code

This ZIP archive contains the full ASCII Art C source code bundled into a single amalgamated source file for straightforward embedding.

Download Source

Getting Started

Embedding the library in your application is straightforward. Add ascii_art.c, the accompanying header file ↗, and the downloadable model from above to your source tree, then call the following APIs in sequence:

Call AsciiArtInit first to initialize the ascii_render structure defined in the ascii_art.h header file.
Prepare the input by converting it to the grayscale colorspace. You can use an external library such as OpenCV or the SOD image object ↗, or rely on the built-in AsciiArtLoadImage helper.
Allocate a buffer large enough to hold the full ASCII text output. The required size is returned by AsciiArtTextBufSize. This step is optional if you want only the binary ASCII glyph image output.
Finally, convert the input image into ASCII glyphs or text with AsciiArtRender.

Below is a simple C program that demonstrates typical usage of the ASCII Art C/C++ interfaces.

sample.c ↗ on GitHub. Please report issues or feature requests on the project GitHub page ↗.

C API REFERENCE GUIDE

This is the C language interface to ASCII Art. In this release, three core interfaces are exported plus one optional helper for simpler integration.

void AsciiArtInit(ascii_render *pRender)

Description

Initialize and prepare the ascii_render structure. This is usually the first API call an application makes before working with the ASCII Art library.

Parameters

ascii_render *pRender

A pointer to a stack- or heap-allocated ascii_render structure declared in the library header.

unsigned int AsciiArtTextBufSize(ascii_render *pRender, int img_width, int img_height)

Description

Calculate the amount of bytes needed to hold the entire ASCII text output of the input image.

Parameters

`ascii_render *pRender`	A pointer to an already initialized `ascii_render` structure.
`int img_width`	Width of the input image to be processed.
`int img_height`	Height of the input image to be processed.

Return Type

Amount of bytes needed to hold the entire buffer that can be safely passed to a memory allocation routine such as malloc().

void AsciiArtRender(ascii_render *pRender, unsigned char *zPixels /*IN/OUT*/, int *pnWidth /*IN/OUT*/, int *pnHeight /*IN/OUT*/, unsigned char *zBuf/* Optional/OUT */, int Optimize)

Description

Transform a grayscale input image into ASCII Art.

Parameters

`ascii_render *pRender`	A pointer to an already initialized `ascii_render` structure.
`unsigned char *zPixels IN/OUT`	A pointer to a writable memory buffer holding the raw pixels of the input image. The pixels must be in the grayscale colorspace, where each byte corresponds to a shade of gray. If you are working with OpenCV, then cvtColor ↗ (cv::COLOR_RGB2GRAY) should produce a grayscale image suitable for this routine. The grayscale pixels are converted to ASCII glyphs in place, which means the input buffer must be writable. The built-in `AsciiArtLoadImage` can be called to load an image from disk suitable for this routine.
`int *pnWidth IN/OUT`	A pointer to an integer holding the width of the input image to be processed.
`int *pnHeight IN/OUT`	A pointer to an integer holding the height of the input image to be processed.
`unsigned char *zBuf Optional/OUT`	When set, the text output of the input image is written into this buffer. The buffer must be large enough to hold the full text output. Call `AsciiArtTextBufSize` first to get the required size.
`int Optimize`	If non-zero, apply contrast-enhancing preprocessing to the grayscale input using adaptive histogram equalization ↗. This option is CPU intensive.

unsigned char * AsciiArtLoadImage(const char *zPath, int *pWidth, int *pHeight)

Description

Load an image from disk and convert it to the grayscale colorspace. Once complete, the returned memory buffer can be passed directly to AsciiArtRender. This helper is available only when the library is compiled with the ART_ENABLE_STB_IMAGE directive.

`const char *zPath`	Path to the target image. In this release, the supported formats are PNG, JPEG, PGM, PPM, and BMP.
`int *pWidth OUT`	The width of the target image is written into this pointer.
`int *pHeight IN/OUT`	The height of the target image is written into this pointer.

Return Value

A pointer to a writable buffer holding the raw grayscale pixels of the target image that can be passed to AsciiArtRender. When finished, free this buffer with the standard C library free() routine. NULL is returned on failure.