Skip to Content
Documentation@blazediff/bin

@blazediff/bin

Command-line tool for high-performance image comparison. Supports multiple algorithms (pixel-perfect diff, GMSD, SSIM, MS-SSIM, Hitchhiker’s SSIM) with PNG, JPEG, and WebP format support.

View Detailed Benchmarks 

Installation

Global Installation

npm install -g blazediff

Local Installation

npm install --save-dev blazediff

Using npx

npx blazediff diff image1.png image2.png

Features

  • Multiple Algorithms: Pixel-perfect 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 diff

Pixel-perfect image comparison with anti-aliasing detection. 60% faster than pixelmatch .

Basic Usage

blazediff diff image1.png image2.png

Save Diff Image

blazediff diff image1.png image2.png --output diff.png

Options

blazediff diff <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output diff image path
  -t, --threshold <n>      Matching threshold (0-1, default: 0.1)
  -a, --alpha <n>          Opacity of original in diff (0-1, default: 0.1)
  --diff-color <r,g,b>     Color for different pixels (default: 255,0,0)
  --aa-color <r,g,b>       Color for anti-aliased pixels (default: 255,255,0)
  --include-aa             Include anti-aliased pixels in diff count
  --diff-mask              Output diff mask with transparent background
  --no-fast-check          Disable fast buffer comparison
  -h, --help              Display help
  -v, --version           Display version

Exit Codes

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

When to Use Each Algorithm

Use diff when:

  • You need pixel-perfect comparison
  • You want to visualize exact pixel differences
  • You need anti-aliasing detection
  • Performance is critical (fastest for pixel differences)

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

CI/CD Integration

GitHub Actions Example

- name: Visual Regression Test
  run: |
    blazediff diff baseline.png test.png --threshold 0.01
    if [ $? -ne 0 ]; then
      echo "Visual regression detected!"
      exit 1
    fi

Using SSIM for Perceptual Testing

# Get SSIM score
SCORE=$(blazediff ssim reference.png test.png | grep -oP 'SSIM: \K[0-9.]+')
 
# Check if score is above threshold
if (( $(echo "$SCORE < 0.95" | bc -l) )); then
  echo "Images differ too much: SSIM=$SCORE"
  exit 1
fi
Last updated on
@blazediff/object@blazediff/ui