IconBaker (LIB)

A simple solution for generating .ico and .icns icons. This crate serves as IconBaker CLI's internal library.

Usage

This crate's API revolves around the concept of binding source images to a set of sizes and resampling configurations. The following example demonstrates this principle:

use icon_baker::prelude::*;

const N_ENTRIES: usize = 1;

fn main() {
    // Creating the icon
    let mut icon = Icon::ico(n_entries);

    // Importing the source image
    let src_image = SourceImage::from_file("img.jpg").unwrap();

    // Configuring the entry
    let opts = IconOptions::new(
        vec![(32, 32), (64, 64)] /* 32x32 and 64x64 sizes */,
        ResamplingFilter::Linear /* Iterpolate the image */,
        Crop::Square             /* Square image */
    );

    // Adding the entry
    icon.add_entry(opts, &src_image).unwrap();
}

Note that the capacity argument in the Icon::ico, Icon::icns, Icon::png_sequence and Icon::new methods specifies the expected number of entries in a given Icon, not the number of sizes (since a single entry can contain multiple sizes).

Sampling From Multiple Sources

Let's say you want to customize your icon so that the smaller versions of it are less detailed. IconBaker helps you achieve this result by allowing to sample from multiple sources.

You can simply combine separate source images by specifying to which entry they should be assigned:

use icon_baker::prelude::*;

const N_ENTRIES: usize = 2;

fn main() {
    let option = IconOptions::new;
    let mut icon = Icon::ico(n_entries);

    // Importing the source images
    let small = SourceImage::from_file("small.jpg").unwrap();
    let large = SourceImage::from_file("small.png").unwrap();

    // Configuring the entries
    let filter = ResamplingFilter::Nearest;
    let crop = Crop::Square;

    let small_opt = option(vec![(16, 16)], filter, crop);
    let large_opt = option(vec![(32, 32)], filter, crop);

    // Adding the entries
    icon.add_entry(small_opt, &small).unwrap();
    icon.add_entry(large_opt, &large).unwrap();
}

Note that different IconOption do not need to share the same rasampling options (namely the filter and crop fields) and can even share a common source field.

However, different entries cannot share a common Size in there sizes field. For example, the following program will panic at second call of icon.add_entry():

use icon_baker::prelude::*;

const N_ENTRIES: usize = 2;

fn main() {
    let option = IconOptions::new;
    let mut icon = Icon::ico(n_entries);

    // Importing the source images
    let src1 = SourceImage::from_file("src1.jpg").unwrap();
    let src2 = SourceImage::from_file("src2.png").unwrap();

    // Configuring the entries
    let filter = ResamplingFilter::Nearest;
    let crop = Crop::Square;

    let src1_opt = option(vec![(16, 16)], filter, crop);
    let src2_opt = option(vec![(16, 16)], filter, crop);

    // Adding the entries
    icon.add_entry(src1_opt, &src1).expect("Returns `Ok(())`");
    icon.add_entry(src2_opt, &src2)
        .expect("Returns `Err(Error::SizeAlreadyIncluded((16, 16))))`");
}

Writing to Files

Writing to files can be easily done by calling the Icon::write method:

use icon_baker::prelude::*;
use std::fs::File;

/* Const declarations */

fn main() {
    let mut icon = Icon::ico(N_ENTRIES);

    /* Process the icon */

    if let Ok(&file) = File::create("myfile.ico") {
        match icon.write(file) {
            Ok(()) => println!("File 'myfile.ico' saved!"),
            Err(_) => println!("An error occurred ;-;")
        }
    }
}

Supported Image Formats

Limitations

There are two main limitations in this crate: both ICNS and SVG are not fully supported. Due to the use of external depencies, this crate is not able to fully support the formal specifications of those two file formats.

However, the coverage provided by these external dependencies should be enough for most use cases.

ICNS Support

Icon Baker uses the icns crate for generating .icns files. The supported icon types are specified by the creators of such crate as follows:

SVG Support

IconBaker uses the nsvg crate for rasterizing .svg files. According to the authors of the crate:

Like NanoSVG, the rasteriser only renders flat filled shapes. It is not particularly fast or accurate, but it is a simple way to bake vector graphics into textures.

The author of icon_baker is inclined to search for alternatives to nsvg if inquired to. Help would be appreciated.