Asciifier

_______             ______________________             
___    |_______________(_)__(_)__  __/__(_)____________
__  /| |_  ___/  ___/_  /__  /__  /_ __  /_  _ \_  ___/
_  ___ |(__  )/ /__ _  / _  / _  __/ _  / /  __/  /    
/_/  |_/____/ \___/ /_/  /_/  /_/    /_/  \___//_/ 

An cli app to convert images to ascii art

A command-line application written in Zig that converts images to ASCII art using OpenCV for image processing.

Features

• Convert images to ASCII art with customizable height
• Support for various image formats (PNG, JPEG, etc.)
• Option to save the resized image
• Configurable background (black or white)
• Fast processing using OpenCV

Prerequisites

• Zig compiler (version 0.15.1 or later)
• OpenCV compiled with libc++
• C++ compiler with libc++ support

Building OpenCV with libc++

Before building the application, you need to compile OpenCV with libc++ and install it to the path specified in the build configuration.

Option 1: Use the default path (~/.local/opencv-libcxx)

# Clone OpenCV
git clone https://github.com/opencv/opencv.git
cd opencv

# Create build directory
mkdir build && cd build

# Configure with CMake (using libc++)
export OPENCV_PREFIX="$HOME/.local/opencv-libcxx"
cmake -S opencv -B build-opencv-libcxx -G Ninja \
    -D CMAKE_BUILD_TYPE=Release \
    -D CMAKE_C_COMPILER=clang -D CMAKE_CXX_COMPILER=clang++ \
    -D CMAKE_INSTALL_PREFIX="$OPENCV_PREFIX" \
    -D CMAKE_BUILD_WITH_INSTALL_RPATH=ON \
    -D CMAKE_INSTALL_RPATH="$OPENCV_PREFIX/lib" -D CMAKE_INSTALL_RPATH_USE_LINK_PATH=ON \
    -D CMAKE_CXX_FLAGS="-stdlib=libc++" \
    -D CMAKE_EXE_LINKER_FLAGS="-stdlib=libc++ -lc++abi" \
    -D CMAKE_SHARED_LINKER_FLAGS="-stdlib=libc++ -lc++abi" \
    -D BUILD_SHARED_LIBS=ON \
    -D BUILD_LIST=core,imgproc,imgcodecs,highgui \
    -D WITH_OPENEXR=OFF \
    -D WITH_TBB=OFF -D WITH_OPENMP=OFF
      ..

# Build and install
cmake --build build-opencv-libcxx -j"$(nproc)"
cmake --install build-opencv-libcxx

Option 2: Use custom path with OPENCV_PREFIX environment variable

# Set custom OpenCV installation path
export OPENCV_PREFIX=/path/to/your/opencv-installation

# Then follow the same CMake configuration but use your custom path
cmake -DCMAKE_INSTALL_PREFIX=$OPENCV_PREFIX \
      # ... other options same as above

Building the Application

Once OpenCV is installed, build the application:

# Clone the repository
git clone <your-repo-url>
cd asciifier

# Build the application
zig build

# Run the application
zig build run -- <image_path> <height> [options]

Usage

# Basic usage
zig build run -- image.png 50

# Save the resized image
zig build run -- image.png 50 --save-image

# Use white background
zig build run -- image.png 50 --white-background

# Combine options
zig build run -- image.png 50 --save-image --white-background

Arguments

• image_path: Path to the input image file
• height: Height of the resized image (width scales proportionally)
• --save-image: Save the resized image to disk
• --white-background: Generate ASCII art optimized for white background

Demo Images

To showcase the application's capabilities, you can add demo images to the assets/ directory. Here's the recommended structure:

assets/
├── demo/
│   ├── input/
│   │   ├── sample1.png          # Original image 1
│   ├── output/
│   │   ├── sample1_ascii.txt    # ASCII output 1
│   └── README.md                 # Description of demo images

Adding Demo Images

1. Place original images in assets/demo/input/
2. Generate ASCII outputs using the application
3. Save outputs to assets/demo/output/
4. Update the demo section below with your images

Example Demo Outputs

Here are some examples of what the application can produce:

Input Image: Cat Portrait

ASCII Outputs

To see the ASCII art outputs, run the application on these images: The image is zoomed out to fit in the view, since the process convert each pixel in a ascii character, to see the original file go to assets/demo/output/cat_output.txt

# Generate ASCII art for cat image
zig build run -- assets/demo/input/cat.png 50

The outputs will be displayed in the terminal. You can also save them to files using the --save-image flag.

Project Structure

asciifier/
├── src/
│   ├── main.zig          # Main application logic
│   └── strings.zig       # Application strings and logo
│   └── cv.zig            # Application integration with opencv
│   └── helpers.zig       # Helpers functions to improve logic
├── cpp/
│   ├── lib.h             # C++ wrapper header
│   └── lib.cpp           # C++ wrapper implementation
├── build.zig             # Build configuration
├── build.zig.zon         # Package manifest
└── assets/               # Demo images and outputs

Dependencies

• OpenCV: Computer vision library for image processing
• libc++: C++ standard library implementation
• Zig: Programming language and build system

Troubleshooting

Common Issues

1. OpenCV not found: Ensure OpenCV is installed to the correct path
2. libc++ linking errors: Verify OpenCV was compiled with libc++
3. Runtime library errors: Check that all OpenCV libraries are in your library path

Environment Variables

• OPENCV_PREFIX: Custom OpenCV installation path
• LD_LIBRARY_PATH: Add OpenCV lib directory if libraries aren't found

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request