resemble.js

In Node.js, use the resemblejs/compareImages module for a Promise-based API. This is ideal for async/await workflows and works with file buffers.

const compareImages = require("resemblejs/compareImages");
const fs = require("mz/fs");

async function getDiff() {
    const options = {
        output: {
            errorColor: {
                red: 255,
                green: 0,
                blue: 255
            },
            errorType: "movement",
            transparency: 0.3,
            largeImageThreshold: 1200,
            useCrossOrigin: false,
            outputDiff: true
        },
        scaleToSameSize: true,
        ignore: "antialiasing"
    };

    const data = await compareImages(await fs.readFile("./your-image-path/People.jpg"), await fs.readFile("./your-image-path/People2.jpg"), options);

    await fs.writeFile("./output.png", data.getBuffer());
}

getDiff();

The following options are available via resemble.outputSettings():

• errorColor: An object {red, green, blue} defining the color used for errors.
• errorType: The type of error display (e.g., "movement").
• transparency: Float value for transparency.
• largeImageThreshold: Threshold in pixels. If image width/height exceeds this, the algorithm skips pixels to improve performance. Set to 0 to disable this behavior.
• useCrossOrigin: Boolean. Set to false if using Data URIs.
• outputDiff: Boolean. Whether to output the difference image.
• boundingBox: An object {left, top, right, bottom} to narrow the comparison area.
• boundingBoxes: An array of bounding box objects.
• ignoredBox: An object {left, top, right, bottom} to exclude an area from comparison.
• ignoredBoxes: An array of ignored box objects.
• ignoreAreasColoredWith: An object {r, g, b, a}. Pixels matching this color on the reference image will be excluded.

For more control, you can use the fluent API starting with resemble(image1). This allows you to chain configuration methods before calling compareTo(image2) and onComplete(callback).

Available chainable methods on the resemble instance:

• compareTo(secondFileData): Initiates comparison with a second image.
• onComplete(callback): Registers the callback for when comparison finishes.
• outputSettings(options): Configures how the diff image is generated.
• scaleToSameSize(): Scales images to match the first image's size.
• useOriginalSize(): Disables scaling (default behavior).
• ignoreNothing(), ignoreLess(), ignoreAntialiasing(), ignoreColors(), ignoreAlpha(): Preset tolerance configurations.
• setupCustomTolerance(customSettings): Manually sets tolerance values.
• setReturnEarlyThreshold(threshold): Sets a percentage threshold to stop comparison early.

Available chainable methods on the comparison object (returned by compareTo):

• outputSettings(options)
• scaleToSameSize()
• useOriginalSize()
• ignoreNothing(), ignoreLess(), ignoreAntialiasing(), ignoreColors(), ignoreAlpha()
• setupCustomTolerance(customSettings)
• setReturnEarlyThreshold(threshold)

You can set global output settings that apply to all subsequent resemble calls using resemble.outputSettings(options). This is useful for setting a consistent errorColor or errorType across your application.

Options for outputSettings:

• errorColor: Object { red, green, blue, alpha } (0-255) to define the color used for error pixels.
• errorType: String defining the error pixel transformation algorithm. Options: 'flat', 'movement', 'flatDifferenceIntensity', 'movementDifferenceIntensity', 'diffOnly'.
• transparency: Number (0-1) for the transparency of the error pixels.
• largeImageThreshold: Number to trigger optimization for large images.
• useCrossOrigin: Boolean to enable/disable cross-origin requests.
• boundingBoxes / ignoredBoxes: Arrays of objects { top, left, bottom, right } to include or exclude specific areas from comparison.
• ignoreAreasColoredWith: An object { r, g, b, a } representing a color that should be ignored during comparison.

The simplest way to compare two images is using the resemble.compare static method. It accepts two image sources (URLs, Buffers, or ImageData), an optional configuration object, and a callback function. The callback receives an error as the first argument and the comparison results as the second.

Supported image sources:

• Image URLs (strings)
• Node.js Buffers
• ImageData objects

Common configuration options:

• output: Object containing errorColor, errorType, transparency, boundingBoxes, ignoredBoxes, or ignoreAreasColoredWith.
• ignore: A string (e.g., 'antialiasing', 'colors', 'alpha', 'nothing', 'less') or an array of these strings to define how much difference to ignore.
• tolerance: Object to override specific tolerance values (e.g., red, green, blue, alpha, minBrightness, maxBrightness).
• scaleToSameSize: Boolean to scale images to match dimensions.
• returnEarlyThreshold: Number to stop comparison early if a certain mismatch percentage is reached.

The comparison result object (data) contains the following properties:

• misMatchPercentage: A string representing the percentage of mismatched pixels (e.g., "1.23").
• rawMisMatchPercentage: The numeric value of the mismatch percentage.
• isSameDimensions: Boolean indicating if images have the same width and height.
• dimensionDifference: Object { width, height } showing the difference in dimensions.
• diffBounds: Object { top, left, bottom, right } defining the bounding box of the differences.
• analysisTime: Time taken for the analysis in milliseconds.
• error: If an error occurred during loading, this contains the error message.

To retrieve the visual difference:

• data.getImageDataUrl(text?): Returns a Base64 Data URL of the diff image. If text is provided, it adds a label to the top of the image.
• data.getBuffer(includeOriginal?): Returns a Buffer of the diff image. If includeOriginal is true, it returns a buffer containing the original images and the diff side-by-side.