ICU-LIB

Image Converter Ultra Library (ICU-LIB) is the reusable format and image-processing library behind the icu command-line tool and viewer.

Features

• Decode and encode common raster image formats.
• Decode and encode LVGL v8/v9 image data.
• Decode and encode MIRX flat images, scenes, indexed images, and font chunks.
• Decode GIF, APNG, and animated WebP timelines and encode MIRX FRAMES containers.
• Parse TTF, OTF, and TTC font outlines and metadata.
• Import and export SVG scene data.
• Provide reusable image post-processing, quantization, dithering, and diff helpers.

Usage

cargo add icu_lib

The library uses MiData as the shared representation between format implementations:

input bytes -> EnDecoder::decode -> MiData -> EnDecoder::encode -> output bytes

A minimal conversion example:

use icu_lib::endecoder::{common, lvgl, ColorFormat};
use icu_lib::midata::MiData;
use icu_lib::EncoderParams;
use std::fs;

fn main() {
    let data = fs::read("input.png").expect("failed to read input");
    let input = common::AutoDetect {};
    let mid = MiData::decode_from(&input, data);

    let output = mid.encode_into(
        &lvgl::LVGL {},
        EncoderParams::new()
            .with_color_format(ColorFormat::ARGB8888)
            .with_stride_align(1)
            .with_lvgl_version(lvgl::LVGLVersion::V9),
    );

    fs::write("output.bin", output).expect("failed to write output");
}

Encode an animation with lossless profile selection and 64-byte encoded-input alignment:

use icu_lib::endecoder::common::animation;
use icu_lib::endecoder::mirui::frames::{self, FramesOptions};
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = fs::read("input.webp")?;
    let animation = animation::decode(&source)?.ok_or("input is not animated")?;
    let output = frames::encode(
        &animation,
        FramesOptions::new()
            .with_input_alignment(64)
            .with_max_delta_frames(8),
    )?;
    fs::write("output.mirx", output.bytes())?;
    Ok(())
}

FramesOptions enables only lossless candidates by default. with_quality explicitly adds quantized frequency candidates. Encoded-input alignment controls every stored DATA address; decoded output stride and address alignment remain runtime requirements.

EncoderParams also supports dithering, format-specific compression, MIRX sample coding, and raw image header options. MirxCoding::FrequencyReversible preserves supported samples exactly; MirxCoding::FrequencyQuantized(quality) accepts qualities from 1 through 100 and preserves alpha/index components exactly. See the public API and the main repository README for CLI-level examples.

Architecture

       ╔═══════════════╗                       
       ║               ║                       
       ║               ║                       
┌ ─ ─ ─ ─ ─ ─ ┐        ║                       
  ┌ ─ ─ ─ ─ ┐          ║                       
│  EnDecoder  │        ▼                       
  └ ─ ─ ─ ─ ┘   ┌ ─ ─ ─ ─ ─ ─ ┐                
│┌───────────┐│   ┌ ─ ─ ─ ─ ┐                  
 │    PNG    │  │   MidData   │                
│└───────────┘│   └ ─ ─ ─ ─ ┘                  
 ┌───────────┐  │┌───────────┐│                
││   JPEG    ││  │   ARGB    │                 
 └───────────┘  │└───────────┘│ ╔-------------╗
│┌───────────┐│  ┌───────────┐  ║   ICU_LIB   ║
 │    SVG    │  ││   PATH    ││ ╚-------------╝
│└───────────┘│  └───────────┘                 
 ┌───────────┐  │┌── ─── ─── ┐│                
││ LVGL BIN  ││     CUSTOM   │                 
 └───────────┘  │└── ─── ─── ┘│                
│┌── ─── ─── ┐│  ─ ─ ─ ─ ─ ─ ─                 
    CUSTOM   │         ║                       
│└── ─── ─── ┘│        ║                       
 ─ ─ ─ ─ ─ ─ ─         ║                       
       ▲               ║                       
       ║               ║                       
       ╚═══════════════╝                       

The main modules are:

• endecoder/: format-specific implementations and automatic detection.
• midata/: shared RGBA, grayscale, path, font, and indexed-image models.
• postprocess/: reusable image transformations.

When adding a format, keep format-specific knowledge in endecoder, use an existing MiData variant when it can represent the data correctly, register automatic detection when appropriate, and add focused tests. See CONTRIBUTING.md for the complete integration checklist.

License

ICU-LIB is licensed under the MIT license.