Pixelization

Pixelization is a high-performance Rust library and CLI tool for transforming images into pixel art.

It implements advanced quantization algorithms, including:

1. K-Means Clustering: A classic statistical approach to find the best color palette.
2. Pixelated Image Abstraction (PIA): An implementation of the paper Pixelated Image Abstraction (Gerstner et al., 2012), which utilizes superpixels and bilateral filtering to create aesthetically pleasing, structure-aware pixel art.

Example Output

Installation

As a CLI Tool

You can install the binary directly from crates.io (once published) or from source:

# From source
cargo install --path . --features cli

⚠️ System Requirements (Read before installing): This library uses ndarray-linalg, which requires a BLAS backend.

• Ubuntu/Debian: sudo apt-get install libopenblas-dev gfortran
• macOS: The Accelerate framework is usually built-in, but you may need gfortran (via brew).
• Windows: You may need to install a pre-compiled LAPACK/BLAS binary or use vcpkg.

As a Library

Add this to your Cargo.toml:

[dependencies]
pixelization = "0.1.0"

Usage

CLI

# Basic usage with PIA (default)
pixelize input.jpg --scale 4 --n_colors 8

# Using K-Means with specific output path
pixelize input.jpg -o output.png --method kmeans --n_colors 16 --scale 2

Rust Code

use pixelization::{PIAPixelizer, Pixelizer};

fn main() {
    let img = image::open("assets/images/ferris_3d.png").unwrap();
    
    // Configure PIA
    let mut pia = PIAPixelizer::default();
    pia.set_verbose(true);

    // Pixelize: (image, width, height, number_of_colors)
    let result = pia.pixelize(&img, 64, 64, 8).unwrap();
    
    result.save("output.png").unwrap();
}

Algorithms

• K-Means: Good for general color reduction. Fast.
• PIA: Excellent for preserving shapes and cartoons. It uses an iterative process involving superpixels, graph cuts, and palette optimization.

License

This project is licensed under the MIT License.