libcaesium

To use the library in a production environment, compile with the --release flag. This is critical for performance, especially for PNG optimizations using the Zopfli algorithm, which can be extremely slow in debug mode.

cargo build --release

PNG compression behavior is controlled via the png field within CSParameters.

• Lossless vs Lossy: Controlled by parameters.png.optimize. If true, lossless() is used; if false, lossy() is used.
• Lossless Options:
  • optimization_level: An integer (clamped 0-6) used to set the oxipng preset.
  • force_zopfli: If true, uses the Zopfli deflater. Note that for files larger than 2MB, the iteration count is automatically reduced to 5 to maintain performance.
• Lossy Options:
  • quality: A value used to set the quantization quality in imagequant.
• Metadata:
  • Metadata (ICC profiles and EXIF) is preserved if parameters.keep_metadata is set to true.

Use c_compress_to_size to compress an image to fit within a max_output_size (in bytes). The return_smallest flag determines if the smallest possible version should be returned.

struct CCSResult c_compress_to_size(
    const char *input_path,
    const char *output_path,
    struct CCSParameters params,
    uintptr_t max_output_size,
    bool return_smallest
);

Use convert_in_memory to transform image data from one format to another without writing to disk. It returns the converted bytes.

use caesium::{parameters::CSParameters, convert_in_memory, SupportedFileTypes};
use std::fs;

let parameters = CSParameters::new();
let image_bytes = fs::read("input.tiff").unwrap();

let converted_bytes = convert_in_memory(image_bytes, &parameters, SupportedFileTypes::Png).unwrap();

Use convert to change an image's file format. You must specify the target format using the SupportedFileTypes enum.

use caesium::{parameters::CSParameters, convert, SupportedFileTypes};

let parameters = CSParameters::new();
let input_file_path = "input.png".to_string();
let output_file_path = "output.jpg".to_string();

let result = convert(input_file_path, output_file_path, &parameters, SupportedFileTypes::Jpeg);
assert!(result.is_ok());

Use c_convert to change an image's format. You must provide the target SupportedFileTypes enum value.

struct CCSResult c_convert(
    const char *input_path,
    const char *output_path,
    enum SupportedFileTypes format,
    struct CCSParameters params
);

Use the compress function to optimize an image file on disk. You must provide the input path, output path, and a CSParameters object to configure settings like metadata preservation and JPEG quality.

use caesium::parameters::CSParameters;
use caesium::compress;

let mut parameters = CSParameters::new();
parameters.keep_metadata = true;
parameters.jpeg.quality = 60;

let input_file_path = "input.jpg".to_string();
let output_file_path = "output.jpg".to_string();

let result = compress(input_file_path, output_file_path, &parameters);
assert!(result.is_ok());

Use compress_to_size to attempt to compress an image until it fits under a specific byte threshold. This function takes the input path, output path, parameters, a max_output_size in bytes, and a boolean return_smallest which determines if the smallest version should be returned.

use caesium::parameters::CSParameters;
use caesium::compress_to_size;

let mut parameters = CSParameters::new();
let input_file_path = "input.webp".to_string();
let output_file_path = "output.webp".to_string();
let max_output_size = 100_000; // 100 KB

let result = compress_to_size(input_file_path, output_file_path, &mut parameters, max_output_size, true);
assert!(result.is_ok());

Use c_compress to compress an image from a file path to another file path. The function returns a CCSResult struct indicating success or failure.

struct CCSResult c_compress(
    const char *input_path,
    const char *output_path,
    struct CCSParameters params
);

Use c_compress_in_memory to compress raw image data. The output is written to a CByteArray struct. Important: You must call c_free_byte_array to free the memory allocated for the output buffer.

struct CCSResult c_compress_in_memory(
    const uint8_t *input_data,
    uintptr_t input_length,
    struct CCSParameters params,
    struct CByteArray *output
);

// After use:
c_free_byte_array(*output);

Use compress_in_memory to process image data already loaded into a byte buffer. This returns a new Vec<u8> containing the compressed data.

use caesium::parameters::CSParameters;
use caesium::compress_in_memory;
use std::fs;

let parameters = CSParameters::new();
let image_bytes = fs::read("input.png").unwrap();

let compressed_bytes = compress_in_memory(image_bytes, &parameters).unwrap();

The CCSParameters struct allows fine-grained control over the compression process for different formats.

JPEG Options:

• jpeg_quality: u32
• jpeg_chroma_subsampling: u32 (Supported values: 444, 422, 420, 411)
• jpeg_progressive: bool
• jpeg_optimize: bool
• jpeg_preserve_icc: bool

PNG Options:

• png_quality: u32
• png_optimization_level: u32
• png_force_zopfli: bool
• png_optimize: bool

WebP Options:

• webp_quality: u32
• webp_lossless: bool

GIF Options:

• gif_quality: u32

TIFF Options:

• tiff_compression: u32 (Values: 1=Lzw, 2=Deflate, 3=Packbits, others=Uncompressed)
• tiff_deflate_level: u32 (Values: 1=Fast, 6=Balanced, others=Best)

General Options:

• keep_metadata: bool
• keep_rotation: bool
• width: u32
• height: u32