@blazediff/cli

CLI for image comparison. Wraps the native Rust binary (fastest), JS pixel diff, GMSD, SSIM, MS-SSIM, and Hitchhiker’s SSIM.

View Detailed Benchmarks

Installation

Global Installation


npm install -g @blazediff/cli


pnpm add -g @blazediff/cli


yarn global add @blazediff/cli


bun add --global @blazediff/cli

Local Installation


npm install --save-dev @blazediff/cli


pnpm add --save-dev @blazediff/cli


yarn add --dev @blazediff/cli


bun add --dev @blazediff/cli

Using npx


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


pnpm dlx blazediff-cli image1.png image2.png diff.png


yarn dlx blazediff-cli image1.png image2.png diff.png


bun x blazediff-cli image1.png image2.png diff.png

Available Commands

core-native (default)

`blazediff-cli core-native` (default)

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

Basic Usage


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

With Options


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

Options


blazediff-cli core-native <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)
  -c, --compression <n>      PNG compression level (0-9, default: 0)
  --interpret                Run structured interpretation (region detection + classification)
  --output-format <fmt>      Output format: png (default) or html (interpret report)
  -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.

Interpret Mode

Add --interpret to get structured diff analysis — region detection, content-aware classification (Addition, Deletion, Shift, ContentChange, ColorChange, RenderingNoise), severity scoring, and human-readable summaries.


# JSON output to stdout
blazediff-cli image1.png image2.png --interpret
 
# With diff image + interpretation
blazediff-cli image1.png image2.png diff.png --interpret
 
# HTML report
blazediff-cli image1.png image2.png report.html --output-format html

Example


$ blazediff-cli image1.png image2.png --interpret
{
  "summary": "Moderate visual change detected (1.87% of image, 10 regions).\n...",
  "severity": "Medium",
  "diffPercentage": 1.87,
  "regions": [...]
}
 
$ blazediff-cli image1.png image2.png report.html --output-format html
# writes report.html with side-by-side images and clickable region rows

core

`blazediff-cli core`

Pure JavaScript pixel-by-pixel comparison. Slower than core-native but offers more customization options like custom diff colors and color spaces.

Basic Usage


blazediff-cli core image1.png image2.png

Save Diff Image


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

Options


blazediff-cli core <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
  --codec <name>           Image codec (pngjs, sharp, jsquash-png)
  -h, --help               Display help

Exit Codes

0 - Images are identical or within threshold
1 - Images have differences beyond threshold


blazediff-cli core image1.png image2.png
if [ $? -eq 0 ]; then
  echo "Images match!"
else
  echo "Images differ!"
fi

gmsd

`blazediff-cli gmsd`

GMSD (Gradient Magnitude Similarity Deviation) perceptual quality assessment. Returns a similarity score from 0-1.

Basic Usage


blazediff-cli gmsd image1.png image2.png

Save GMS Map


blazediff-cli gmsd image1.png image2.png --output gms-map.png

Options


blazediff-cli gmsd <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output GMS map image path
  --downsample <n>         Downsample factor (0 or 1, default: 0)
  -h, --help              Display help

Output

Prints the GMSD score (lower = more similar):

0.0 - Images are identical
0.0-0.05 - Very low difference
0.05-0.15 - Low difference
0.15-0.35 - Moderate difference
>0.35 - High difference

Example


$ blazediff-cli gmsd reference.png test.png
GMSD: 0.0234
 
$ blazediff-cli gmsd reference.png test.png --output gms-map.png
GMSD: 0.0234
GMS map saved to: gms-map.png

ssim

`blazediff-cli ssim`

Standard SSIM (Structural Similarity Index) with Gaussian weighting. MATLAB-compatible with <0.01% error.

Basic Usage


blazediff-cli ssim image1.png image2.png

Save SSIM Map


blazediff-cli ssim image1.png image2.png --output ssim-map.png

Options


blazediff-cli ssim <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output SSIM map image path
  --window-size <n>        Gaussian window size (default: 11)
  --k1 <n>                 Algorithm parameter (default: 0.01)
  --k2 <n>                 Algorithm parameter (default: 0.03)
  -h, --help              Display help

Output

Prints the SSIM score (higher = more similar):

1.0 - Identical images
0.99+ - Excellent similarity
0.95-0.99 - Very good similarity
0.90-0.95 - Good similarity
0.80-0.90 - Fair similarity
<0.80 - Poor similarity

Example


$ blazediff-cli ssim reference.png test.png
SSIM: 0.9876
 
$ blazediff-cli ssim reference.png test.png --output ssim-map.png --window-size 8
SSIM: 0.9823
SSIM map saved to: ssim-map.png

msssim

`blazediff-cli msssim`

MS-SSIM (Multi-Scale SSIM) for better perceptual correlation. Analyzes images at multiple scales.

Basic Usage


blazediff-cli msssim image1.png image2.png

Save MS-SSIM Map


blazediff-cli msssim image1.png image2.png --output msssim-map.png

Options


blazediff-cli msssim <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output SSIM map at finest scale
  --window-size <n>        Gaussian window size (default: 11)
  --scales <n>             Number of scales (default: 5)
  --method <type>          Aggregation method: product or sum (default: product)
  -h, --help              Display help

Prints the MS-SSIM score (higher = more similar, same scale as SSIM).


$ blazediff-cli msssim reference.png test.png
MS-SSIM: 0.9912

hitchhikers-ssim

`blazediff-cli hitchhikers-ssim`

Hitchhiker’s SSIM - fast rectangular-window SSIM using integral images. ~4x faster than standard SSIM.

Basic Usage


blazediff-cli hitchhikers-ssim image1.png image2.png

Save SSIM Map


blazediff-cli hitchhikers-ssim image1.png image2.png --output ssim-map.png

Options


blazediff-cli hitchhikers-ssim <image1> <image2> [options]
 
Options:
  -o, --output <path>      Output SSIM map image path
  --window-size <n>        Rectangular window size (default: 11)
  --window-stride <n>      Window stride (default: window-size)
  --no-cov-pooling         Disable CoV pooling (use mean pooling)
  --k1 <n>                 Algorithm parameter (default: 0.01)
  --k2 <n>                 Algorithm parameter (default: 0.03)
  -h, --help              Display help

Prints the SSIM score (higher = more similar, same scale as SSIM). CoV pooling is enabled by default.


$ blazediff-cli hitchhikers-ssim reference.png test.png
SSIM: 0.9597

When to Use Each Algorithm

Algorithm	Best for
`core-native` (default)	Maximum speed, CI/CD, large images, `--interpret` analysis
`core`	Custom diff colors, color space control, no native deps
`gmsd`	Similarity score, compression-tolerant
`ssim`	MATLAB-compatible, research
`msssim`	Multi-scale, varying resolutions
`hitchhikers-ssim`	Fast SSIM (~4x), large batches

@blazediff/cli

Installation

Global Installation

Local Installation

Using npx

Available Commands

core-native (default)

blazediff-cli core-native (default)

Basic Usage

With Options

Options

Exit Codes

Interpret Mode

Example

core

blazediff-cli core

Basic Usage

Save Diff Image

Options

Exit Codes

gmsd

blazediff-cli gmsd

Basic Usage

Save GMS Map

Options

Output

Example

ssim

blazediff-cli ssim

Basic Usage

Save SSIM Map

Options

Output

Example

msssim

blazediff-cli msssim

Basic Usage

Save MS-SSIM Map

Options

hitchhikers-ssim

blazediff-cli hitchhikers-ssim

Basic Usage

Save SSIM Map

Options

When to Use Each Algorithm

Links

`blazediff-cli core-native` (default)

`blazediff-cli core`

`blazediff-cli gmsd`

`blazediff-cli ssim`

`blazediff-cli msssim`

`blazediff-cli hitchhikers-ssim`