Image Buffer Comparison Tool

Build a tool that efficiently compares two image buffers and reports whether they are identical. The tool must be optimized for performance, especially when processing large images or performing many comparisons in sequence.

Background

When comparing image data represented as byte arrays in RGBA format (4 bytes per pixel: red, green, blue, alpha), a naive byte-by-byte comparison can be slow. Your task is to implement an efficient comparison that minimizes memory allocations and maximizes throughput.

Requirements

Core Functionality

Your implementation must:

1. Accept two image buffers of equal size in RGBA format (Uint8Array, Uint8ClampedArray, or Node.js Buffer)
2. Accept width and height dimensions that match the buffer sizes (buffer length = width × height × 4)
3. Return the number of mismatched pixels between the two images
4. Return 0 if images are identical
5. Support an optional third buffer parameter for writing a grayscale output image showing identical pixels

Performance Constraints

The implementation must be optimized for:

• Memory efficiency: No intermediate buffer allocations during comparison
• Speed: Use efficient comparison techniques for identical or near-identical images
• Buffer view handling: Properly handle typed array views that may have non-zero byte offsets

Output Generation (Optional)

When a third output buffer is provided:

• Write a grayscale representation for pixels that match between the two input images
• The grayscale value should be calculated as: 0.299 × red + 0.587 × green + 0.114 × blue
• For differing pixels, mark them with red color [255, 0, 0, 255]
• Blend the grayscale value with the alpha channel: grayscale × alpha / 255

Test Cases

• Given two identical 10×10 RGBA buffers (400 bytes each), returns 0 mismatched pixels @test
• Given two 10×10 RGBA buffers where exactly 5 pixels differ, returns 5 @test
• Given two identical buffers and an output buffer, fills output with grayscale version of input @test
• Given two different buffers and an output buffer, marks differing pixels as red in output @test

Implementation

@generates

API

/**
 * Compares two image buffers pixel by pixel and returns the number of mismatched pixels.
 * Optionally generates a visual diff output.
 *
 * @param {Uint8Array|Uint8ClampedArray|Buffer} img1 - First image buffer in RGBA format
 * @param {Uint8Array|Uint8ClampedArray|Buffer} img2 - Second image buffer in RGBA format
 * @param {Uint8Array|Uint8ClampedArray|Buffer|null} output - Optional output buffer for diff visualization
 * @param {number} width - Image width in pixels
 * @param {number} height - Image height in pixels
 * @returns {number} Number of pixels that differ between img1 and img2
 */
function compareImages(img1, img2, output, width, height) {
  // Implementation here
}

module.exports = { compareImages };

Dependencies { .dependencies }

pixelmatch { .dependency }

Provides pixel-level image comparison with performance optimizations.