Repository files navigation

ODiff is a blazing fast native image comparison tool. Checkbenchmarks for the results, but it compares the visual difference between 2 images inmilliseconds. It was originally designed to handle the "big" images. Thanks toOCaml and its speedy and predictable compiler we can significantly speed up your CI pipeline.

base	comparison	diff

• ✅ Cross-format comparison - Yes .jpg vs .png comparison without any problems.
• ✅ Support for.png,.jpeg,.jpg, and.tiff
• ✅ Supports comparison of images with different layouts.
• ✅ Anti-aliasing detection
• ✅ Ignoring regions
• ✅ UsingYIQ NTSCtransmission algorithm to determine visual difference.

• ⏹ Reading image from memory buffer
• ⏹ Reading images from url

Run the simple comparison. Image paths can be one of supported formats, diff output is optional and can only be.png.

odiff <IMG1 path> <IMG2 path> [DIFF output path]

We also provides direct node.js binding for theodiff. Run theodiff from nodejs:

const{ compare}=require("odiff-bin");const{ match, reason}=awaitcompare("path/to/first/image.png","path/to/second/image.png","path/to/diff.png");

Checkoutcypress-odiff, a cypress plugin to add visual regression tests usingodiff-bin.

LostPixel – Holistic visual testing for your Frontend allows very easy integration with storybook and uses odiff for comparison

Argos CI – Visual regression service powering projects like material-ui. (It became 8x faster with odiff)

Visual Regression Tracker – Self hosted visual regression service that allows to use odiff as screenshot comparison engine

OSnap – Snapshot testing tool written in OCaml that uses config based declaration to define test and was built by odiff collaborator.

Here is an api reference:

The best way to get up-to-date cli interface is just to type the

odiff --help

NodeJS Api is pretty tiny as well. Here is a typescript interface we have:

exporttypeODiffOptions=Partial<{/** Color used to highlight different pixels in the output (in hex format e.g. #cd2cc9). */diffColor:string;/** Output full diff image. */outputDiffMask:boolean;/** Do not compare images and produce output if images layout is different. */failOnLayoutDiff:boolean;/** Return { match: false, reason: '...' } instead of throwing error if file is missing. */noFailOnFsErrors:boolean;/** Color difference threshold (from 0 to 1). Less more precise. */threshold:number;/** If this is true, antialiased pixels are not counted to the diff of an image */antialiasing:boolean;/** If `true` reason: "pixel-diff" output will contain the set of line indexes containing different pixels */captureDiffLines:boolean;/** If `true` odiff will use less memory but will be slower with larger images */reduceRamUsage:boolean;/** An array of regions to ignore in the diff. */ignoreRegions:Array<{x1:number;y1:number;x2:number;y2:number;}>;}>;declarefunctioncompare(basePath:string,comparePath:string,diffPath:string,options?:ODiffOptions):Promise<|{match:true}|{match:false;reason:"layout-diff"}|{match:false;reason:"pixel-diff";/** Amount of different pixels */diffCount:number;/** Percentage of different pixels in the whole image */diffPercentage:number;/** Individual line indexes containing different pixels. Guaranteed to be ordered and distinct.  */diffLines?:number[];}|{match:false;reason:"file-not-exists";/** Errored file path */file:string;}>;export{compare};

Compare option will return{ match: true } if images are identical. Otherwise return{ match: false, reason: "*" } with a reason why images were different.

Make sure that diff output file will be created only if images have pixel difference we can see 👀

We provide prebuilt binaries for most of the used platforms, there are a few ways to install them:

The recommended and cross-platform way to install this lib is npm and node.js. Make sure that this package is compiled directly to the platform binary executable, so the npm package contains all binaries andpost-install script will automatically link the right one for the current platform.

Important: package name isodiff-bin. But the binary itself isodiff

npm install odiff-bin

Then give it a try 👀

odiff --help

Download the binaries for your platform fromrelease page.

Run the benchmarks by yourself. Instructions of how to run the benchmark ishere

Performance matters. At least for sort of tasks like visual regression. For example, if you are running 25000 image snapshots per month you can save20 hours of CI time per month by speeding up comparison time in just3 seconds per snapshot.

3s * 25000 / 3600 = 20,83333 hours

Here isodiff performance comparison with other popular visual difference solutions. We are going to compare some real-world use cases.

Lets compare 2 screenshots of full-sizehttps::/cypress.io page:

Wow. Odiff is mostly 6 times faster than imagemagick and pixelmatch. And this will be even clearer if image will become larger. Lets compare an8k image to find a difference withanother 8k image:

Yes it is significant improvement. And the produced difference will be the same for all 3 commands.

If you have recently updated, please read thechangelog for details of what has changed.

The project is licensed under the terms ofMIT license

This project was highly inspired bypixelmatch andimagemagick.

...one day a donation button will appear here. But for now you can followauthor's twitter :)