IMGDIFF(1)

📦 version 7.44.0, in nixpkgs unstable

💅 IMGDIFF(1) — the BRL-CAD girlie's guide to image diffing ✨

okay so bestie, welcome to imgdiff, brought to you by the BRL-CAD fam 🫶. This is the lil tool that looks at two images and tells you exactly how much they disagree, pixel by pixel, channel by channel. No cap. Let's get into it 🎀

✨ NAME ✨

imgdiff — compare two images and report or visualize their differences 💖

🌸 SYNOPSIS 🌸

imgdiff [options] img1 img2 [output]

🦋 DESCRIPTION 🦋

So what does imgdiff actually do? It takes two images, img1 and img2, and compares them on a per-channel, per-pixel basis. Then it reports how many channels match exactly, how many differ by one unit, and how many differ by more than one unit. It's giving very meticulous, very detail-oriented, main character energy 👑

Input images are read through the libicv image library, which means literally any format libicv understands can be compared — we're talking pix(5), bw(5), and PNG, iykyk 🌈. And plot twist that slays: the two inputs don't even need to be the same format. Mix and match, bestie 💅

The image format is normally inferred from each file's extension. For raw formats that carry no embedded dimensions — that's pix(5) and bw(5) — imgdiff tries to deduce the width and height from the file size. When that fails (😭), you have to supply the dimensions explicitly. No guessing, no vibes, just numbers.

If you give an output path (either with -o or as a third positional argument) and the images differ, a difference image gets written that highlights the disagreeing pixels 🔥. And when PNG render metadata is present, imgdiff can also compare that metadata and emit nirt(1) shotline scripts that re-trace the differing pixels — perfect for debugging renders, lowkey iconic.

💜 OPTIONS 💜

  • -h, —help, -? — print a usage summary and dip. That's it, that's the whole option ✌️
  • -o file, —output file — write the difference image to file. Equivalent to passing output as a third positional argument. ⚠️ Heads up bestie: the file must not already exist. So don't come crying to me if it errors out 🙈
  • -n prefix, —nirt-output prefix — write nirt(1) shotline scripts for the differing pixels. You get one file per image that carries PNG render metadata: prefix\_img1.nirt and/or _prefix\_img2.nirt 🎯
  • —width-img1 # — width in pixels of the first image. For raw formats lacking embedded size, this is your girl 🫶
  • —height-img1 # — height in pixels of the first image.
  • —width-img2 # — width in pixels of the second image.
  • —height-img2 # — height in pixels of the second image.
  • —format-img1 format — override the auto-detected file format of the first input image. Because sometimes the extension is lying to you 💀
  • —format-img2 format — override the auto-detected file format of the second input image.
  • —output-format format — override the auto-detected file format of the output image.
  • -A, —approximate — instead of the per-channel report, compute an approximate perceptual difference metric and print the Hamming distance between the two images. It's giving "I don't need the details, just the number" ✨
  • -m, —metadata — compare embedded render metadata (PNG only) and report whether it's identical or differs. Metadata girlies rise 🌸

🍓 EXAMPLES 🍓

Example 1. Visualize the difference between two renders

imgdiff -o changed.png baseline.png current.png

Compares two PNG renders pixel by pixel, prints how many channels match or differ, and — if they differ — writes changed.png highlighting exactly which pixels changed 🔥. Super useful for spotting regressions in rt(1) output. Obsessed, honestly.

Example 2. Compare raw pix images of known size and trace differing pixels

imgdiff --width-img1 512 --height-img1 512 \
        --width-img2 512 --height-img2 512 \
        -n shots ref.pix new.pix

Compares two 512x512 pix(5) images whose dimensions cannot be inferred from the file (so we're telling it manually, because we're helpful like that 💅), and — for any image carrying render metadata — writes nirt(1) shotline scripts (shots_img1.nirt, shots_img2.nirt) that re-fire rays through the differing pixels 🎀

🌈 SEE ALSO 🌈

brlcad(1), nirt(1), rt(1), pix-png(1), pixdiff(1), pix(5), bw(5)

Go read them, they're all part of the same friend group fr fr 🫶

👑 AUTHOR 👑

BRL-CAD Team

This software is Copyright (c) 1989-2026 by the United States Government as represented by U.S. Army Research Laboratory.

💌 BUG REPORTS 💌

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org 📧. Not me personally, bestie — the devs. They got you 💜

k that's the whole page!! 🦋 this gloriousness is IMGDIFF(1) from the BRL-CAD manual — mwah, go diff some images, you're gonna slay ✨💅🎀

📦 where this page comes from