icy_sixel

A high-performance, 100% pure Rust implementation of a SIXEL encoder and decoder.

I wanted a pure Rust implementation to simplify deployment of my cross-platform applications. In version 0.4.0, I rewrote the encoder using quantette, a high-quality color quantization library licensed under MIT/Apache-2.0. It uses Wu's algorithm with Floyd-Steinberg dithering for excellent results.

The decoder is a clean-room implementation based on the SIXEL specification, with SIMD optimizations for maximum performance.

Features

• SIXEL Encoder: High-quality color quantization with quantette (Wu's algorithm + Floyd-Steinberg dithering)
• SIXEL Decoder: Clean-room implementation with RGBA output and SSE2 SIMD acceleration
• Transparency Support: Full alpha channel handling in both encoder and decoder
• Pure Rust: No C dependencies, easy to build and deploy
• Cross-platform: Works on Linux, macOS, and Windows

Installation

Add this to your Cargo.toml:

[dependencies]
icy_sixel = "0.4"

Usage

Encoding an Image to SIXEL

use icy_sixel::{sixel_encode, EncodeOptions};

// RGBA image data (4 bytes per pixel)
let rgba = vec![
    255, 0, 0, 255,   // Red pixel
    0, 255, 0, 255,   // Green pixel
    0, 0, 255, 255,   // Blue pixel
];

let options = EncodeOptions::default();
let sixel = sixel_encode(&rgba, 3, 1, &options)?;
print!("{}", sixel);

Encoding with Custom Options

use icy_sixel::{sixel_encode, EncodeOptions, QuantizeMethod};

let options = EncodeOptions {
    max_colors: 64,        // Use only 64 colors (2-256)
    diffusion: 0.875,      // Floyd-Steinberg dithering strength (0.0-1.0)
    quantize_method: QuantizeMethod::Wu,  // or QuantizeMethod::kmeans()
};

let sixel = sixel_encode(&rgba, width, height, &options)?;

Decoding SIXEL to Image Data

use icy_sixel::sixel_decode;

let sixel_data = b"\x1bPq#0;2;100;0;0#0~-\x1b\\";
let image = sixel_decode(sixel_data)?;
// image.rgba contains RGBA pixel data (4 bytes per pixel)
// image.width and image.height contain dimensions

CLI Tool

The crate includes a command-line tool for encoding and decoding:

# Install the CLI
cargo install sixel

# Encode a PNG to SIXEL (outputs to stdout by default)
sixel encode image.png

# Encode with custom settings
sixel encode image.png -o output.six --colors 64 --diffusion 0.5 --method kmeans

# Read from stdin
cat image.png | sixel encode -o output.six

# Decode SIXEL to PNG
sixel decode image.six -o output.png

# Decode from stdin
cat image.six | sixel decode -o output.png

Architecture

Encoder

The encoder uses quantette for high-quality color quantization with Wu's algorithm and Floyd-Steinberg dithering. This produces excellent results, especially for images with gradients or complex color distributions.

Decoder

The decoder is a clean-room implementation derived from the SIXEL specification:

• Returns RGBA buffers (4 bytes per pixel) for easy integration with graphics libraries
• SIMD-accelerated horizontal span filling on x86/x86_64 (SSE2)
• Optimized with color caching and loop unrolling
• Comprehensive bounds checking prevents buffer overflows

Showcase

Original image for reference (596×936 pixels, 879 KB PNG):

Color Palette Comparison (Wu quantizer, full diffusion)

Colors	SIXEL Size	Result
256	1.1 MB
16	440 KB
2	105 KB

Dithering Comparison (Wu quantizer, 16 colors)

Diffusion	SIXEL Size	Result
Off (0.0)	420 KB
Full (0.875)	440 KB

Quantizer Comparison (256 colors, full diffusion)

Method	SIXEL Size	Result
Wu	1.1 MB
K-means	1.3 MB

Benchmarks

Performance measurements on the test image (596×936 pixels, beelitz_heilstätten.png):

Encoder Performance

Quantizer Comparison

Color Count Impact

Diffusion Strength Impact

Decoder Performance

Scaling with Size

Color Palette Size

Benchmarks run with cargo bench using Criterion on Linux.

License

Licensed under the Apache License, Version 2.0 — see LICENSE for details.