image optimize

中文 | English

Support multi process for image, such as: resize, gray, crop, flip, rotate, brighten, contrast, sharpen, blur, padding, watermark and optimize.

Installation

Shell script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/vicanso/imageoptimize/main/install.sh | bash

Install a specific version or to a custom directory:

# Specific version
curl -fsSL https://raw.githubusercontent.com/vicanso/imageoptimize/main/install.sh | bash -s v0.4.3

# Custom install directory
curl -fsSL https://raw.githubusercontent.com/vicanso/imageoptimize/main/install.sh | INSTALL_DIR=~/.local/bin bash

Pre-built binary

Download the archive for your platform from GitHub Releases, extract and place the binary in your PATH.

Build from source

cargo install imageoptimize --features bin

Usage

imageoptimize [OPTIONS] <SOURCE>

<SOURCE> is the root directory to scan. The tool recurses through it and processes all matching images.

Options

Examples

Optimize in place — overwrite originals with smaller files:

imageoptimize --overwrite /path/to/images

Optimize to a separate directory — keeps originals untouched and also generates AVIF/WebP variants:

imageoptimize /path/to/source --output /path/to/output

Process only JPEG files:

imageoptimize /path/to/source --output /path/to/output --format jpeg --format jpg

Generate AVIF variants only (skip WebP):

imageoptimize /path/to/source --output /path/to/output --convert jpeg-avif --convert png-avif

Disable format conversion (optimize originals only, no AVIF/WebP):

imageoptimize /path/to/source --output /path/to/output --convert disable

Custom quality:

imageoptimize /path/to/source --output /path/to/output \
  --jpeg-quality 75 --png-quality 85 --avif-quality 70 --webp-quality 75

Dry run — preview compression results without writing any files:

imageoptimize /path/to/source --output /path/to/output --dry-run

Skip small files — ignore files under 100 KB (too small to benefit from optimization):

imageoptimize /path/to/source --output /path/to/output --min-size 100

Exclude paths — skip thumbnail directories and files with a -small suffix:

imageoptimize /path/to/source --output /path/to/output \
  --exclude "**/thumb/**" \
  --exclude "*-small.*"

Resize before encoding — shrink anything wider than 1920 px or taller than 1080 px:

imageoptimize /path/to/source --output /path/to/output --resize 1920x1080

Use 0 to leave one dimension unconstrained (e.g. --resize 1920x0 limits width only).

Output

Before processing begins, the tool prints how many source images were found:

Found 12 images

Each processed file then prints a one-line summary:

 PCT    DIFF   SIZE    TIME  FILE
----  ------  -----  ------  ----
 69%  (0.59)   12kb    2.8s  asset/image/line_mixin.webp (N)
 55%  (0.54)   10kb    2.8s  asset/image/line_mixin.avif (N)
SKIP                   2.8s  asset/image/line_mixin.jpeg (-)

Fields: output path · file size · size relative to original · dssim perceptual difference · elapsed time.

The DIFF value is the DSSIM score multiplied by 1000. Lower is better; 0.00 means visually lossless. Values above 1.00 are shown in yellow as a warning of noticeable quality loss.

• (N) — new file created
• (U) — existing file overwritten
• (-) — skipped (optimized size was not smaller than original; original is preserved)

A summary line is printed after all files are processed:

Optimized 12 files: 8.4mb → 5.1mb, saved 3.3mb (39%), 2 unchanged

If any files fail to process, the count is shown in red at the end of the summary: , 1 failed.

In --dry-run mode the header shows [DRY RUN] and the summary reads Would optimize ….

Library API

The core pipeline is exposed as a Rust library. Each processing step is a task — a Vec<String> where the first element is the task name and the rest are arguments.

use imageoptimize::{run, new_load_task, new_resize_task, new_optim_task};

let result = run(vec![
    new_load_task("file:///path/to/image.jpg"),
    new_resize_task(800, 0),        // width=800, height proportional
    new_optim_task("webp", 80, 0),  // encode to WebP quality 80
]).await?;

let bytes = result.get_buffer()?;

Available tasks

optim speed parameter:

Watermark positions: leftTop, top, rightTop, left, center, right, leftBottom, bottom, rightBottom (default).

License

This project is licensed under the Apache License 2.0 license.