Skip to Content
Documentation@blazediff/cli

@blazediff/cli

Command-line tool for high-performance image comparison. Supports multiple algorithms including the native Rust binary (fastest), JavaScript pixel diff, GMSD, SSIM, MS-SSIM, and Hitchhiker’s SSIM.

View Detailed Benchmarks 

Installation

Global Installation

npm install -g @blazediff/cli

Local Installation

npm install --save-dev @blazediff/cli

Using npx

npx blazediff-cli image1.png image2.png diff.png

Features

  • Native Binary: Rust + SIMD for maximum performance (3-4x faster than odiff)
  • Multiple Algorithms: Pixel diff, GMSD, SSIM, MS-SSIM, Hitchhiker’s SSIM
  • Multiple Formats: PNG, JPEG, WebP support
  • High Performance: Optimized implementations for all algorithms
  • Flexible Output: Save diff/similarity maps or get exit codes
  • CI/CD Ready: Perfect for automated visual testing
  • Cross-Platform: Works on Windows, macOS, and Linux

Available Commands

blazediff-cli bin (default)

Native Rust binary with SIMD optimization. The fastest option - 3-4x faster than odiff on large images.

Basic Usage

# Default command (bin)
blazediff-cli image1.png image2.png diff.png
 
# Or explicitly
blazediff-cli bin image1.png image2.png diff.png

With Options

blazediff-cli image1.png image2.png diff.png --threshold 0.05 --antialiasing

Options

blazediff-cli bin <image1> <image2> <output> [options]
 
Options:
  -t, --threshold <n>      Color difference threshold (0-1, default: 0.1)
  -a, --antialiasing       Enable anti-aliasing detection
  --diff-mask              Output only differences (transparent background)
  --fail-on-layout         Fail immediately if images have different dimensions
  -c, --compression <n>    PNG compression level (0-9, default: 0)
  -h, --help               Display help

Exit Codes

  • 0 - Images are identical
  • 1 - Images have differences
  • 2 - Error (file not found, invalid format, etc.)
blazediff-cli image1.png image2.png diff.png
if [ $? -eq 0 ]; then
  echo "Images match!"
else
  echo "Images differ!"
fi

Why so fast? Uses a two-pass block-based algorithm with SIMD acceleration (NEON on ARM, SSE4.1 on x86). The cold pass quickly identifies unchanged blocks, then the hot pass only processes changed regions.

When to Use Each Algorithm

Use bin (default) when:

  • You need maximum performance
  • You’re running in CI/CD pipelines
  • You’re comparing large images (4K+)
  • You want the smallest binary footprint

Use core when:

  • You need custom diff colors
  • You want to customize the color space
  • You need fine-grained control over output appearance
  • You’re already using pngjs/sharp in your pipeline

Use gmsd when:

  • You need a similarity score for CI/CD
  • You’re comparing images with compression artifacts
  • You want gradient-based perceptual quality
  • You need fast single-threaded computation

Use ssim when:

  • You need MATLAB-compatible results
  • You want high accuracy with Gaussian weighting
  • You need automatic downsampling for large images
  • Research or comparison requires standard SSIM

Use msssim when:

  • You need multi-scale analysis
  • You’re working with images at different resolutions
  • You want better correlation with human perception
  • You can afford ~2-3x computation cost vs SSIM

Use hitchhikers-ssim when:

  • You need maximum performance (~4x faster than SSIM)
  • You’re processing large images or many images
  • You want O(1) window computation
  • You need flexible window stride for overlapping/non-overlapping windows
Last updated on
@blazediff/object@blazediff/bin