a-sixel

A sixel library for encoding images.

Basic Usage

Simple Encoding

use a_sixel::BitMergeSixelEncoderBest;
use image::RgbaImage;

let img = RgbaImage::new(100, 100);
println!("{}", <BitMergeSixelEncoderBest>::encode(img));

Loading and Encoding an Image File

use a_sixel::KMeansSixelEncoder;
use image;

// Load an image from file
let image = image::open("examples/transparent.png").unwrap().to_rgba8();

// Encode with default settings (256 colors, Sierra dithering)
let sixel_output = <KMeansSixelEncoder>::encode(image);
println!("{}", sixel_output);

Custom Palette Size and Dithering

use a_sixel::{BitSixelEncoder, dither::NoDither};

let image = image::open("examples/transparent.png").unwrap().to_rgba8();

// Use 16 colors with no dithering for faster encoding
let sixel_output = BitSixelEncoder::<NoDither>::encode_with_palette_size(image, 16);
println!("{}", sixel_output);

Transparency

By default, a-sixel handles transparency by setting any fully-transparent pixels to all-bits-zero. This translates to a transparent pixel in most sixel implementations, but some terminals may not support this.

Sixel does not natively support partial transparency, but this library does have some support for rendering images as if partial transparency was supported. If the partial-transparency feature is enabled, a-sixel will query the terminal and attempt to determine the background color. Partially transparent pixels will then be blended with this background color before encoding. Note that with this approach, changing the terminal background color will not update partially transparent pixels to match. You will need to re-encode the image if the background color changes.

Choosing an Encoder

• I want good quality:
  • Use BitMergeSixelEncoderBest or KMeansSixelEncoder.
• I'm time constrained:
  • Use BitMergeSixelEncoderLow, BitSixelEncoder, or OctreeSixelEncoder.
• I'm really time constrained and can sacrifice a little quality:
  • Use BitSixelEncoder<NoDither>.

For a more detailed breakdown, here's the encoders by average speed and quality against the test images (speed figures will vary) at 256 colors with Sierra dithering:

Note: Execution time includes the time taken to compute error statistics - this is non-trivial. For example, exclusive of error statistics computation, bit-no-dither takes <100ms on average. Performance figures will vary based on machine, etc. They are only useful for comparing algorithms against each other within this dataset.

Here's the encoders at 16 colors with Sierra dithering:

This doesn't tell the full story, as sometimes a low MSE or DSSIM can be achieved while losing some highlight colors in the image. Take flowers.png for example:

This preserves the grey shades that make up the image well, but completely loses the blue of the flowers at the base of the trees.

• MSE: 3.23
• DSSIM: 0.0020
• PHash Distance: 10
• Mean ΔE: 1.42
• Max ΔE: 11.49
• ΔE >2.3: 14%
• ΔE >5.0: 0%

• MSE: 9.15
• DSSIM: 0.0091
• PHash Distance: 16
• Mean ΔE: 2.10
• Max ΔE: 9.23
• ΔE >2.3: 38%
• ΔE >5.0: 2%

This sacrifices some differentiation between shades of grey, but preserves the blue of the flowers.

License: MIT OR Apache-2.0