Image Converter imgc 🗜️

imgc is a command-line utility focusing on converting images into other formats, specifically focusing on support for modern image standards and encoders.

imgc simplifies the process of batch converting images, optimizing for both performance and storage efficiency.

Usage example using the docker container:

> docker run -v ./examples/:/targets/ -it gunzinger/imgc-rs:latest imgc "**/*.*" avif
Converting 16 files...
Using "ravif" (0.12.0) with options (quality: 90, speed: 3, bit depth: Eight, color model: RGB)
Encode statistics:
Successful: 15
Skipped:    0
Errors:     0
Total input size:  24.0 MiB
Total output size: 13.2 MiB
Compression ratio: 54.95%

Key Features 🧰

• Broad Format Support: Works with many supported image formats.
• Works with huge images: Can optimize very large images (~1GiB input image size, 32Kx16K px dimensions).
• Speedy Processing: Written in Rust to keep overhead to a minimum, we also take advantage of rayon for parallel processing.
• Input selection using Glob Patterns: Target selection is made intuitive for cli enthusiasts via glob patterns.
• Custom Output: Choose where your converted images are saved.

Supported formats

Input formats 🖼️

To keep it simple: JPEG, PNG, GIF, WebP, BMP, DDS, Farbfeld, HDR, ICO, EXR, PNM, QOI, TGA, TIFF

Input images are decoded using the image crate, please see their documentation for supported image formats.

Output formats 📤

• webp, webp encoder using the webp crate (libwebp bindings) - offers lossy and lossless encoding
• webp-image, webp encoder using the image crate - offers lossless encoding
• avif, avif encoder using the ravif crate - offers lossy and lossless encoding
• png, png encoder using the image crate - offers lossless encoding
• jpeg, jpeg optimizer using the mozjpeg crate - only optimizes images

Output format notes 📝

When working with very large input images, please keep in mind the output format limits. In particular:

• webp: maximum dimension of 16384x16384px
• avif: maximum dimension of 65536x65536px, note Baseline Profile and Advanced Profile limits if you want to be friendly to consuming hardware decoders. :)

Requests

If this does not cover your needs, please feel free to open an issue to request additional input and/or output formats.

I am focusing on supporting modern image formats supported in browsers, as this tool is optimally suited for optimizing static directories for different web apps.

For a good overview of browser support, see the caniuse.com pages for different images, e.g.: avif, webp.

Installation 💾

Using published binaries 📡

Binaries for Windows and Linux are built for every tag.

See the GitHub releases page for downloads.

Using the docker image 🐳

Docker containers are also built for every tag.

See the Docker Hub page for available tags.

docker run -it gunzinger/imgc-rs:latest imgc --help

# directory passthrough on linux
docker run -v ./input-folder/:/targets/ -it gunzinger/imgc-rs:latest imgc "/targets/**/*.png" avif

# note that on windows the volume passthroughs need to have absolute paths, e.g. (for powershell)
docker run -v ${PWD}/input-folder/:/targets/ -it gunzinger/imgc-rs:latest imgc "/targets/**/*.png" avif

How to Use imgc 🧑‍💻

Basic Usage

The imgc program uses glob patterns for target selection:

imgc "examples/**/*.png" webp
imgc "examples/**/*.jpg" webp
imgc "examples/**/*" webp

Specifying an output directory 🗃️

imgc "examples/**/*" webp -o output_images

Cleaning up generated files 🧹

Warning: Use this command with caution. This is basically rm -rf with regex.

imgc "examples/**/*.webp" clean

Command Help 📖

For detailed command usage, see all arguments with --help or -h:

❯ imgc --help
A configurable and efficient batch image converter written in Rust.

Usage: imgc [OPTIONS] <PATTERN> <COMMAND>

Commands:
  webp        Convert images to webp format (using webp crate)
  webp-image  Convert images to webp format (using image crate)
  avif        Convert images to avif format (using ravif crate)
  png         Convert images to png format (using image crate)
  jpeg        Convert images to optimized jpeg format (using mozjpeg crate)
  clean       Remove files matching a glob pattern
  help        Print this message or the help of the given subcommand(s)

Arguments:
  <PATTERN>  Glob pattern to match images to convert. Example: `images/**/*.png`

Options:
  -o, --output <OUTPUT>               Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension
      --overwrite-if-smaller          Overwrite the existing output file if the current conversion resulted in a smaller file
      --overwrite-existing            Overwrite existing output files regardless of size
      --discard-if-larger-than-input  Discards the encoding result if it is larger than the input file (does not create an output file)
      --discard-input-alpha-channel   Discards the alpha channel of the input image(s) if it is present. (this does not make loading faster, but it can improve the encoding result)
  -h, --help                          Print help
  -V, --version                       Print version

For the webp command:

❯ imgc webp --help                                     
Convert images to webp format (using webp crate)

Usage: imgc  <PATTERN> webp [OPTIONS]

Options:
      --lossless                      Use lossless encoding mode. Defaults to false
  -q, --quality <QUALITY>             Control target quality (0 - 100, lower is worse but results in smaller files). Defaults to 90.0
  -o, --output <OUTPUT>               Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension
      --overwrite-if-smaller          Overwrite the existing output file if the current conversion resulted in a smaller file
      --overwrite-existing            Overwrite existing output files regardless of size
      --discard-if-larger-than-input  Discards the encoding result if it is larger than the input file (does not create an output file)
      --discard-input-alpha-channel   Discards the alpha channel of the input image(s) if it is present. (this does not make loading faster, but it can improve the encoding result)
  -h, --help                          Print help

For the webp-image command:

❯ imgc <PATTERN> webp-image [OPTIONS]

Options:
  -o, --output <OUTPUT>               Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension
      --overwrite-if-smaller          Overwrite the existing output file if the current conversion resulted in a smaller file
      --overwrite-existing            Overwrite existing output files regardless of size
      --discard-if-larger-than-input  Discards the encoding result if it is larger than the input file (does not create an output file)
      --discard-input-alpha-channel   Discards the alpha channel of the input image(s) if it is present. (this does not make loading faster, but it can improve the encoding result)
  -h, --help                          Print help

For the avif command:

❯ imgc avif --help                                     
Convert images to avif format (using ravif crate)

Usage: imgc <PATTERN> avif [OPTIONS]

Options:
  -q, --quality <QUALITY>
          Control target quality (0 - 100, lower is worse but results in smaller files). Defaults to 90.0
  -s, --speed <SPEED>
          Control encoding speed (1 - 10, lower is much slower but has a better quality and lower filesize). Defaults to 3
      --bit-depth <BIT_DEPTH>
          Choose internal bit depth. (in the generated avif file, nothing to do with the input file) [possible values: eight, ten, auto]
      --color-model <COLOR_MODEL>
          Choose internal color model. (in the generated avif file, nothing to do with the input file) [possible values: y-cb-cr, rgb]
      --alpha-color-mode <ALPHA_COLOR_MODE>
          Choose internal alpha color mode. (in the generated avif file, nothing to do with the input file) Irrelevant for images without transparency [possible values: unassociated-dirty, unassociated-clean, premultiplied]
  -a, --alpha-quality <ALPHA_QUALITY>
          Control target alpha quality (0 - 100, lower is worse). Defaults to 90.0
  -o, --output <OUTPUT>
          Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension
      --overwrite-if-smaller
          Overwrite the existing output file if the current conversion resulted in a smaller file
      --overwrite-existing
          Overwrite existing output files regardless of size
      --discard-if-larger-than-input
          Discards the encoding result if it is larger than the input file (does not create an output file)
  -h, --help
          Print help

For the png command:

❯ imgc png --help                                     
Convert images to png format (using image crate)

Usage: imgc <PATTERN> png [OPTIONS]

Options:
      --compression-type <COMPRESSION_TYPE>
          Choose the png compression type
          
          See: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
          
          [possible values: default, fast, best]

      --filter-type <FILTER_TYPE>
          Choose the png filter type
          
          See: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
          
          [possible values: no-filter, sub, up, avg, paeth, adaptive]

  -o, --output <OUTPUT>
          Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension

      --overwrite-if-smaller
          Overwrite the existing output file if the current conversion resulted in a smaller file

      --overwrite-existing
          Overwrite existing output files regardless of size

      --discard-if-larger-than-input
          Discards the encoding result if it is larger than the input file (does not create an output file)

      --discard-input-alpha-channel
          Discards the alpha channel of the input image(s) if it is present. (this does not make loading faster, but it can improve the encoding result)

  -h, --help
          Print help (see a summary with '-h')

For the jpeg command (unstable; likes to crash! this is a work in progress!):

❯ imgc <PATTERN> jpeg [OPTIONS]

Options:
  -o, --output <OUTPUT>               Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension
      --overwrite-if-smaller          Overwrite the existing output file if the current conversion resulted in a smaller file
      --overwrite-existing            Overwrite existing output files regardless of size
      --discard-if-larger-than-input  Discards the encoding result if it is larger than the input file (does not create an output file)
      --discard-input-alpha-channel   Discards the alpha channel of the input image(s) if it is present. (this does not make loading faster, but it can improve the encoding result)
  -h, --help                          Print help

For the clean command:

> imgc <PATTERN> clean [OPTIONS]

Options:
  -o, --output <OUTPUT>               Output directory (flat) of processed images. Defaults to the same location as the original images with the new file extension
      --overwrite-if-smaller          Overwrite the existing output file if the current conversion resulted in a smaller file
      --overwrite-existing            Overwrite existing output files regardless of size
      --discard-if-larger-than-input  Discards the encoding result if it is larger than the input file (does not create an output file)
      --discard-input-alpha-channel   Discards the alpha channel of the input image(s) if it is present. (this does not make loading faster, but it can improve the encoding result)
  -h, --help                          Print help

Examples

Input Directory Structure

examples
├── 1.png
├── 1.webp
├── img1
│   ├── 2.png
│   ├── 2.webp
│   └── img11
│       ├── 3.jpg
│       └── 3.webp
├── img2
│   ├── 4.jpeg
│   └── 4.webp
...

Example of webp command:

Example of clean command:

Building from source

Prerequisites

• Ensure you have the latest stable version of Rust and Cargo installed on your system.
• Nasm is needed for building rav1e. Install via apt install nasm / apk add nasm / choco install nasm.

Installation Guide

Install via crate

To install via the published crate, execute the following command:

cargo install imgc

Install from git

# 1. Clone the repository:
git clone https://github.com/Gunzinger/imgc-rs.git
cd imgc-rs
# 2. Build the project:
cargo build --release
3. Install locally
cargo install --path .

Uninstalling

To uninstall, remove the tool via cargo uninstall:

cargo uninstall imgc

What's Next

• Testing
• Publishing automation (binaries, docker)
• Introduce advanced options for image transformations (resize, rotate)
• Progress bar for encoding
• Expand support for additional input formats
  • avif
  • png
  • jpeg (WIP)
  • png (via oxipng crate)
  • heic/heif
  • jxl/jpeg-xl
  • incoming wishes
• Expand support for additional export formats by including more encoding libraries
• Image metadata handling (EXIF data preservation/stripping)
• Expand support for animated images/video encoding (to webp/avif/apng)
• Output logs (to enable usage in automations static directory optimizations by link-rewriting)
• winresource integration (application icon and .exe metadata for Windows binaries)
• GUI

License

This project under the MIT License.