Visual Diff Overlay Generator

Build a tool that compares two images and generates a transparent overlay showing only the differences, which can be composited onto any background.

Requirements

Your tool should accept two PNG image files and produce a transparent overlay image where:

• Matching pixels are fully transparent (not rendered)
• Differing pixels are rendered with full opacity in red
• The output can be overlaid on any background image or color

The tool should handle images with transparency and be suitable for creating difference visualizations in design tools or documentation.

Input/Output Specifications

Input

• Two PNG image files of equal dimensions
• Images may contain transparency

Output

• A PNG file containing only the differing pixels with full opacity
• All matching pixels should be fully transparent
• Use red color to highlight differences

Test Cases

• Given two identical 10x10 red squares, the output should be a fully transparent 10x10 image @test
• Given a 10x10 red square and a 10x10 blue square, the output should be a 10x10 image with all pixels red and fully opaque @test
• Given two 20x20 images where only the center 4 pixels differ, the output should be transparent except for the center 4 pixels which are red and fully opaque @test

Implementation

@generates

API

/**
 * Generates a transparent overlay showing only the differences between two images.
 *
 * @param {string} imagePath1 - Path to the first PNG image
 * @param {string} imagePath2 - Path to the second PNG image
 * @param {string} outputPath - Path where the transparent overlay PNG will be saved
 * @returns {Promise<number>} The number of differing pixels
 * @throws {Error} If images have different dimensions or cannot be read
 */
async function generateDiffOverlay(imagePath1, imagePath2, outputPath) {
  // IMPLEMENTATION HERE
}

module.exports = { generateDiffOverlay };

Dependencies { .dependencies }

pixelmatch { .dependency }

Provides pixel-level image comparison capabilities.

pngjs { .dependency }

Provides PNG image encoding and decoding support.