xbrz-cli

A command-line tool for upscaling pixel art using the xBRZ algorithm. Powered by the xbrz-rs crate.

Installation

cargo install xbrz-cli

Or directly from the repository:

cargo install --git https://github.com/boekabart/xbrz-cli

Or from a local clone:

cargo build --release

The binary will be at target/release/xbrz-cli.

Large LUT feature

For slightly faster scaling at the cost of a larger binary, enable the large_lut feature:

cargo build --release --features large_lut

Usage

xbrz-cli <INPUT> [-o OUTPUT] [-f FACTOR] [-F FORMAT] [-v]

Arguments

Argument	Description
INPUT	Path to the input image
-o, --output	Output path (default: <input>_hq<N>.<ext>)
-f, --factor	Scale factor, 2-6 (default: 2)
-F, --format	Output format override (png, jpeg, bmp, webp, tiff, tga, gif, qoi, jxl)
-v, --verbose	Print dimensions and timing info to stderr

Examples

Scale a sprite 2x (outputs sprite_hq2.png):

xbrz-cli sprite.png

Scale 4x with explicit output:

xbrz-cli sprite.png -o sprite_4x.png -f 4

Convert format while scaling:

xbrz-cli input.bmp -o output.webp -f 3

Verbose output:

xbrz-cli tile.png -f 6 -v
# Input:  16x16
# Output: 96x96 (factor 6)
# Done in 0.01s

Supported Formats

PNG, JPEG, BMP, WebP, TIFF, TGA, GIF, QOI, JPEG XL

Note: JPEG does not support alpha transparency. When outputting to JPEG, any alpha channel will be lost.

Note: JPEG XL output is lossless only, encoded via zune-jpegxl.

Architecture

Single-file binary crate (src/main.rs). No library component.

Flow: CLI args (clap) → image decode (image crate) → xBRZ upscale (xbrz-rs) → image encode & save.

Key dependency: xbrz-rs provides scale_rgba(source, width, height, factor) -> Vec<u8> for factors 1-6.

Development

cargo clippy -- -D warnings        # Lint
cargo fmt --check                  # Format check
cargo fmt                          # Auto-format

Acknowledgments

The actual xBRZ scaling is performed by xbrz-rs, a Rust implementation of Zenju's xBRZ algorithm. All credit for the upscaling magic goes to them — this CLI is just a thin wrapper to make it easy to use from the command line.

License

GPL-3.0-only — see LICENSE.