{"id":13446480,"url":"https://github.com/Prior99/native-image-diff","last_synced_at":"2025-03-21T06:31:24.663Z","repository":{"id":30468142,"uuid":"125014545","full_name":"Prior99/native-image-diff","owner":"Prior99","description":"A simple library for comparing two images using a native C++ binding.","archived":false,"fork":false,"pushed_at":"2024-01-20T10:51:00.000Z","size":659,"stargazers_count":50,"open_issues_count":2,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T07:05:03.997Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Prior99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-13T08:06:59.000Z","updated_at":"2024-12-10T06:50:26.000Z","dependencies_parsed_at":"2024-06-18T17:08:54.645Z","dependency_job_id":"8de30312-fbd3-4731-9abf-ad5a89eadc24","html_url":"https://github.com/Prior99/native-image-diff","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prior99%2Fnative-image-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prior99%2Fnative-image-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prior99%2Fnative-image-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Prior99%2Fnative-image-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Prior99","download_url":"https://codeload.github.com/Prior99/native-image-diff/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244750775,"owners_count":20504143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T05:00:53.727Z","updated_at":"2025-03-21T06:31:24.324Z","avatar_url":"https://github.com/Prior99.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# native-image-diff\n\n[![npm](https://img.shields.io/npm/v/native-image-diff.svg)](https://www.npmjs.com/package/native-image-diff)\n[![Build Status](https://travis-ci.org/Prior99/native-image-diff.svg?branch=master)](https://travis-ci.org/Prior99/native-image-diff)\n[![Build status](https://ci.appveyor.com/api/projects/status/go1birwl4uvqhj49/branch/master?svg=true)](https://ci.appveyor.com/project/Prior99/native-image-diff/branch/master)\n[![Coverage Status](https://coveralls.io/repos/github/Prior99/native-image-diff/badge.svg?branch=master)](https://coveralls.io/github/Prior99/native-image-diff?branch=master)\n\nA simple library for comparing two images using a native C++ binding. This library is highly inspired by the great [pixelmatch](https://github.com/mapbox/pixelmatch).\nIn fact, many parts of the algorithms are 1:1 C++ reimplementations.\n\nPlease also refer to the **[Documentation](https://prior99.github.io/native-image-diff/docs/index.html)**.\n\n## Table of contents\n\n * [native-image-diff](#native-image-diff)\n    * [Table of contents](#table-of-contents)\n    * [Supported environments](#supported-environments)\n    * [Usage](#usage)\n        * [Basic example](#basic-example)\n        * [Usage with node-libpng](#usage-with-node-libpng)\n        * [The resulting values explained](#the-resulting-values-explained)\n        * [Antialiasing Detection](#antialiasing-detection)\n        * [Color threshold](#color-threshold)\n    * [Benchmark](#benchmark)\n    * [Contributing](#contributing)\n    * [Contributors](#contributors)\n\n## Supported environments\n\nThis is a native Addon to NodeJS which delivers prebuilt binaries. Only some environments are supported:\n\n| Node Version       | Windows 64-Bit     | Windows 32-Bit     | Linux 64-Bit       | Linux 32-Bit | OSX                |\n|--------------------|--------------------|--------------------|--------------------|--------------|--------------------|\n| Earlier            | ✗                  | ✗                  | ✗                  | ✗            | ✗                  |\n| Node 10 *(Abi 64)* | ✓                  | ✓                  | ✓                  | ✗            | ✓                  |\n| Node 11 *(Abi 67)* | ✓                  | ✓                  | ✓                  | ✗            | ✓                  |\n| Node 12 *(Abi 72)* | ✓                  | ✓                  | ✓                  | ✗            | ✓                  |\n| Node 13 *(Abi 79)* | ✓                  | ✓                  | ✓                  | ✗            | ✓                  |\n| Node 14 *(Abi 83)* | ✓                  | ✓                  | ✓                  | ✗            | ✓                  |\n| Node 15 *(Abi 88)* | ✓                  | ✓                  | ✓                  | ✗            | ✓                  |\n\n## Usage\n\nMore sophisticated, fully working examples can be found [here](example/):\n\n * [Simple example](example/src/simple.js)\n * [Antialiasing Detection](example/src/antialiasing-detection.js)\n * [Generate no diff image](example/src/no-diff-image.js)\n * [Color Threshold comparison](example/src/color-threshold.js)\n\n### Basic example\n\nA basic example of how to use this library can look like this:\n\n```typescript\nimport { diffImages } from \"native-image-diff\";\n\n// Somehow get buffers to an RGB or RGBA image.\nconst imageBuffer1 = Buffer.alloc(300);\nconst imageBuffer2 = Buffer.alloc(300);\n\nconst image1 = {\n    data: imageBuffer1,\n    width: 20,\n    height: 5\n};\n\nconst image2 = {\n    data: imageBuffer2,\n    width: 20,\n    height: 5\n};\n\nconst { image, pixels, totalDelta } = diffImages(image1, image2);\n// `image` now contains the width and the height of an RGBA image\n// visualizing the difference between `image1` and `image2`.\n// `pixels` is the number of pixels which didn't match.\n// `totalDelta` is a number denoting the relative difference\n// between the images with higher values being\n// the more different and `0` being entirely equal.\n```\n\nThe two buffers in `image1` and `image2` are expected to contain an RGB or RGBA encoded 8-bit image. In the above example an RGB image was used.\n\nBoth images will be compared pixel-per-pixel and the result as well as a visualization of the difference is returned.\n\nThis library does not provide any way to read or write images. Take a look at [usage with node-libpng](#usage-with-node-libpng) for an idea.\n\nWith these input images:\n\n![](images/pixels-example-ya.png) ![](images/pixels-example-yay.png)\n\nThe generate diff image will look like this:\n\n![](images/pixels-example-diff.png)\n\n### Usage with node-libpng\n\nThis library is API-compatible with [node-libpng](https://www.npmjs.com/package/node-libpng). It's simple to use decoded images as well as encoding them:\n\n```typescript\nimport { diffImages } from \"native-image-diff\";\nimport { readPngFileSync, writePngFileSync } from \"node-libpng\";\n\nconst { image, pixels } = diffImages(readPngFileSync(\"./image1.png\"), readPngFileSync(\"./image2.png\"));\nconsole.log(`Compared both images. ${pixels} were different.`);\n\nwritePngFileSync(\"./diff.png\", image.data, { width: image.width, height: image.height });\n// In JS this can be even shorter: `writePngFileSync(\"./diff.png\", image.data, image);`.\n```\n\n### The resulting values explained\n\nA result might look like this:\n\n```js\n{\n    pixels: 286,\n    totalDelta: 3434604.5,\n    image: {\n        width: 100,\n        height: 100,\n        data: \u003cBuffer 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ... \u003e\n    }\n}\n```\n\n#### pixels\n\nThis represents the total number of pixels differing between both images.\n\n#### totalDelta\n\nThis is the summed up total perceived difference of all pixels. It grows with the color difference of every unmatched pixel.\n\nIn comparison to the [pixels](https://prior99.github.io/native-image-diff/docs/interfaces/diffresult.html#pixels) property this property also represents how different all colors were. Comparing a white image\nwith a black image would yield a higher difference than comparing an orange with a red image.\n\nIt doesn't feature any specific unit and should be used for relative comparisons only.\n\n#### image\n\nThis property is only generated if [generateDiffImage](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#generatediffimage) is set to `true` (default).\n\nIts properties `width` and `height` represent the dimensions of the generated image in pixels and `data` holds a RGBA buffer\nof raw image data showing the visual difference between both input images. Different pixels are drawn in red, and pixels which\nonly differed between both images because of antialiasing will be drawn in yellow. This is only true if [detectAntialiasing](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#detectantialiasing)\nis set to `true` (default).\n\n### Antialiasing Detection\n\nBy default this library will try to detect whether a pixel was part of antialiasing and ignore the respective change.\nThis works ~90% of the time:\n\nThese images (one with and one without antialiasing):\n\n![](images/antialiasing-example-no-antialiasing.png) ![](images/antialiasing-example-with-antialiasing.png)\n\nWill look like this with detection enabled:\n\n![](images/antialiasing-example-diff-detection-enabled.png)\n\nThe yellow pixels represent detected antialiasing will not be included in the [pixels](https://prior99.github.io/native-image-diff/docs/interfaces/diffresult.html#pixels)\nproperty of the result.\n\nAnd like this with detection disabled:\n\n![](images/antialiasing-example-diff-detection-disabled.png)\n\nDisable the detection by providing `false` as [detectAntialiasing](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#detectantialiasing).\n\n### Color threshold\n\nIt's possible to specify a different [colorThreshold](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#colorthreshold).\n\nThe color threshold ranges from `0` to `1` with `1` permitting all changes and `0` permitting none.\nIt influences the allowed per-pixel color difference.\n\nThe following example shows the visual difference between a gradient and a red rectangle with different thresholds:\n\nInput images:\n\n![](images/red-rectangle-example-red.png) ![](images/red-rectangle-example-gradient.png)\n\nThresholds from 0.0 to 0.7:\n\n*0.0: (2826 pixels different)*\n\n![](images/red-rectangle-example-0-diff.png)\n\n*0.1: (2413 pixels different)*\n\n![](images/red-rectangle-example-10-diff.png)\n\n*0.2: (1986 pixels different)*\n\n![](images/red-rectangle-example-20-diff.png)\n\n*0.3: (1570 pixels different)*\n\n![](images/red-rectangle-example-30-diff.png)\n\n*0.4: (1142 pixels different)*\n\n![](images/red-rectangle-example-40-diff.png)\n\n*0.5: (731 pixels different)*\n\n![](images/red-rectangle-example-50-diff.png)\n\n*0.6: (300 pixels different)*\n\n![](images/red-rectangle-example-60-diff.png)\n\n*0.7: (0 pixels different)*\n\n![](images/red-rectangle-example-70-diff.png)\n\n## Benchmark\n\nAs it is a native addon, **native-image-diff** is much faster than [pixelmatch](https://github.com/mapbox/pixelmatch):\n\nThe chart below shows the comparison of comparing an 512x512 pixel image between [pixelmatch](https://github.com/mapbox/pixelmatch) and **native-image-diff**.\nThe operations per second are displayed (Higher is better).\n\n![diff benchmark](images/benchmark-diff.png)\n\n*(The x-axis scale shows the number of diffed images per second.)*\n\n## Contributing\n\nYarn is used instead of npm, so make sure it is installed. `npm install -g yarn`.\n\nGenerally, it should be enough to just run:\n\n```\nmake\n```\n\nwhich will install all node dependencies and compile the C++ code,\ncompile typescript, execute all test, lint the sources and build the docs.\n\n## Contributors\n\n - Alexander Dmitriev\n - Frederick Gnodtke\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPrior99%2Fnative-image-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPrior99%2Fnative-image-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPrior99%2Fnative-image-diff/lists"}