Improve API and add documentation

Author: Prior99

Diff for: README.md

@@ -15,11 +15,27 @@ Please also refer to the **[Documentation](https://prior99.github.io/native-imag
     * [Table of contents](#table-of-contents)
     * [Supported environments](#supported-environments)
     * [Usage](#usage)
+        * [Basic example](#basic-example)
+        * [Usage with node-libpng](#usage-with-node-libpng)
+        * [The resulting values explained](#the-resulting-values-explained)
+        * [Antialiasing Detection](#antialiasing-detection)
+        * [Color threshold](#color-threshold)
     * [Contributing](#contributing)
     * [Contributors](#contributors)
 
 ## Usage
 
+More sophisticated, fully working examples can be found [here](example/):
+
+ * [Simple example](example/src/simple.js)
+ * [Antialiasing Detection](example/src/antialiasing-detection.js)
+ * [Generate no diff image](example/src/no-diff-image.js)
+ * [Color Threshold comparison](example/src/color-threshold.js)
+
+### Basic example
+
+A basic example of how to use this library can look like this:
+
 ```typescript
 import { diffImages } from "native-image-diff";
 
@@ -47,6 +63,142 @@ const { image, pixels, totalDelta } = diffImages(image1, image2);
 // the most different and `0` being total equal.
 ```
 
+The two buffers in `image1` and `image2` are expected to contain an RGB or RGBA encoded 8bit image. In the above example an RGB image was used.
+
+Both images will be compared pixel-per-pixel and the result as well as a visualization of the difference is returned.
+
+This 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.
+
+With these input images:
+
+![](images/pixels-example-ya.png) ![](images/pixels-example-yay.png)
+
+The generate diff image will look like this:
+
+![](images/pixels-example-diff.png)
+
+### Usage with node-libpng
+
+This 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:
+
+```typescript
+import { diffImages } from "native-image-diff";
+import { readPngFileSync, writePngFileSync } from "node-libpng";
+
+const { image, pixels } = diffImages(readPngFileSync("./image1.png"), readPngFileSync("./image2.png"));
+console.log(`Compared both images. ${pixels} were different.`);
+
+writePngFileSync("./diff.png", image.data, { width: image.width, height: image.height });
+// In JS this can be even shorter: `writePngFileSync("./diff.png", image.data, image);`.
+```
+
+### The resulting values explained
+
+A result might look like this:
+
+```js
+{
+    pixels: 286,
+    totalDelta: 3434604.5,
+    image: {
+        width: 100,
+        height: 100,
+        data: <Buffer 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 ... >
+    }
+}
+```
+
+#### pixels
+
+This represents the total amount of pixels differing between both images.
+
+#### totalDelta
+
+This is the summed up total perceived difference of all pixels. It grows with the color difference of every unmatched pixel.
+
+In 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
+with a black image would yield a higher difference as comparing an orange with a red image.
+
+It doesn't feature any specific unit and should be used for relative comparisons only.
+
+#### image
+
+This property is only generate if [generateDiffImage](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#generatediffimage) is set to `true` (default).
+
+It's properties `width` and `height` represent the dimensions of the generated image in pixels and `data` holds a RGBA buffer
+of raw image data showing the visual difference between both input images. Different pixels are drawn in red and pixels which
+only 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)
+is set to `true` (default).
+
+### Antialiasing Detection
+
+By default this library will try to detect whether a pixel was part of antialiasing and ignore the respective change.
+This works ~90% of the time:
+
+These images (one with and one without antialiasing):
+
+![](images/antialiasing-example-no-antialiasing.png) ![](images/antialiasing-example-with-antialiasing.png)
+
+Will look like this with detection enabled:
+
+![](images/antialiasing-example-diff-detection-enabled.png)
+
+The yellow pixels represent detected antialiasing will not be included in the [pixels](https://prior99.github.io/native-image-diff/docs/interfaces/diffresult.html#pixels)
+property of the result.
+
+And like this with detection disabled:
+
+![](images/antialiasing-example-diff-detection-disabled.png)
+
+Disable the detection by providing `false` as [detectAntialiasing](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#detectantialiasing).
+
+### Color threshold
+
+It's possible to specify a different [colorThreshold](https://prior99.github.io/native-image-diff/docs/interfaces/diffimagesarguments.html#colorthreshold).
+
+The color threshold ranges from `0` to `1` with `1` permitting all changes and `0` permitting none.
+It influences the allowed per-pixel color difference.
+
+The following example shows the visual difference between a gradient and a red rectangle with different thresholds:
+
+Input images:
+
+![](images/red-rectangle-example-red.png) ![](images/red-rectangle-example-gradient.png)
+
+Thresholds from 0.0 to 0.7:
+
+*0.0: (2826 pixels different)*
+
+![](images/red-rectangle-example-0-diff.png)
+
+*0.1: (2413 pixels different)*
+
+![](images/red-rectangle-example-10-diff.png)
+
+*0.2: (1986 pixels different)*
+
+![](images/red-rectangle-example-20-diff.png)
+
+*0.3: (1570 pixels different)*
+
+![](images/red-rectangle-example-30-diff.png)
+
+*0.4: (1142 pixels different)*
+
+![](images/red-rectangle-example-40-diff.png)
+
+*0.5: (731 pixels different)*
+
+![](images/red-rectangle-example-50-diff.png)
+
+*0.6: (300 pixels different)*
+
+![](images/red-rectangle-example-60-diff.png)
+
+*0.7: (0 pixels different)*
+
+![](images/red-rectangle-example-70-diff.png)
+
 ## Supported environments
 
 This is a native Addon to NodeJS which delivers prebuilt binaries. Only some environments are supported:

Diff for: example/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "native-image-diff-example",
+  "dependencies": {
+    "native-image-diff": "file:..",
+    "node-libpng": "^0.2.0"
+  }
+}

Diff for: example/src/antialiasing-detection.js

@@ -0,0 +1,37 @@
+const NodeLibpng = require("node-libpng");
+const NativeImageDiff = require("native-image-diff");
+
+// Read the images from PNG images on the disk.
+const imageNoAntialiasing =
+    NodeLibpng.readPngFileSync(`${__dirname}/../../images/antialiasing-example-no-antialiasing.png`);
+const imageAntialiasing =
+    NodeLibpng.readPngFileSync(`${__dirname}/../../images/antialiasing-example-with-antialiasing.png`);
+
+// Compare both images with antialiasing detection enabled.
+const resultDetectionEnabled = NativeImageDiff.diffImages({
+    image1: imageNoAntialiasing,
+    image2: imageAntialiasing,
+    // This can be omitted; It's `true` by default.
+    detectAntialiasing: true,
+});
+console.log(`Antialiasing detection enabled: ${resultDetectionEnabled.pixels} pixels were different.`);
+// Write the diff image to the disk.
+NodeLibpng.writePngFileSync(
+    `${__dirname}/../../images/antialiasing-example-diff-detection-enabled.png`,
+    resultDetectionEnabled.image.data,
+    resultDetectionEnabled.image,
+);
+
+// Compare both images with antialiasing detection disabled.
+const resultDetectionDisabled = NativeImageDiff.diffImages({
+    image1: imageNoAntialiasing,
+    image2: imageAntialiasing,
+    detectAntialiasing: false,
+});
+console.log(`Antialiasing detection disabled: ${resultDetectionDisabled.pixels} pixels were different.`);
+// Write the diff image to the disk.
+NodeLibpng.writePngFileSync(
+    `${__dirname}/../../images/antialiasing-example-diff-detection-disabled.png`,
+    resultDetectionDisabled.image.data,
+    resultDetectionDisabled.image,
+);

Diff for: example/src/color-threshold.js

@@ -0,0 +1,25 @@
+const NodeLibpng = require("node-libpng");
+const NativeImageDiff = require("native-image-diff");
+
+// Read the images from PNG images on the disk.
+const imageRed = NodeLibpng.readPngFileSync(`${__dirname}/../../images/red-rectangle-example-red.png`);
+const imageGradient = NodeLibpng.readPngFileSync(`${__dirname}/../../images/red-rectangle-example-gradient.png`);
+
+// Compare the images with different color thresholds.
+for (let colorThreshold = 0; colorThreshold <= 0.7; colorThreshold += 0.1) {
+    const result = NativeImageDiff.diffImages({
+        image1: imageRed,
+        image2: imageGradient,
+        colorThreshold,
+        detectAntialiasing: false,
+    });
+    const percent = Math.floor(colorThreshold * 100);
+    // Log the result for this threshold.
+    console.log(`Color threshold ${percent}%: ${result.pixels} pixels were different.`);
+    // Write the diff image.
+    NodeLibpng.writePngFileSync(
+        `${__dirname}/../../images/red-rectangle-example-${percent}-diff.png`,
+        result.image.data,
+        result.image,
+    );
+}

Diff for: example/src/no-diff-image.js

@@ -0,0 +1,14 @@
+const NodeLibpng = require("node-libpng");
+const NativeImageDiff = require("native-image-diff");
+
+// Read the images from PNG images on the disk.
+const imageA = NodeLibpng.readPngFileSync(`${__dirname}/../../images/pixels-example-ya.png`);
+const imageB = NodeLibpng.readPngFileSync(`${__dirname}/../../images/pixels-example-yay.png`);
+// Compare both images. Don't generate a diff image.
+const result = NativeImageDiff.diffImages({
+    image1: imageA,
+    image2: imageB,
+    generateDiffImage: false,
+});
+// Log the result.
+console.log(`${result.pixels} pixels were different.`);

Diff for: example/src/simple.js

@@ -0,0 +1,12 @@
+const NodeLibpng = require("node-libpng");
+const NativeImageDiff = require("native-image-diff");
+
+// Read the images from PNG images on the disk.
+const imageA = NodeLibpng.readPngFileSync(`${__dirname}/../../images/pixels-example-ya.png`);
+const imageB = NodeLibpng.readPngFileSync(`${__dirname}/../../images/pixels-example-yay.png`);
+// Compare both images.
+const result = NativeImageDiff.diffImages(imageA, imageB);
+// Log the result.
+console.log(`${result.pixels} pixels were different.`);
+// Write the diff image to the disk.
+NodeLibpng.writePngFileSync(`${__dirname}/../../images/pixels-example-diff.png`, result.image.data, result.image);

Diff for: example/yarn-error.log

@@ -0,0 +1,33 @@
+Arguments: 
+  /home/prior/.nvm/versions/node/v8.9.3/bin/node /home/prior/.nvm/versions/node/v8.9.3/bin/yarn add file:..
+
+PATH: 
+  /home/prior/.nvm/versions/node/v8.9.3/bin:/home/prior/.cargo/bin:/home/prior/.cargo/bin:/usr/local/sbin:/usr/local/bin:/usr/bin:/opt/android-sdk/platform-tools:/opt/android-sdk/tools:/opt/cuda/bin:/usr/lib/emscripten:/usr/lib/jvm/default/bin:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl
+
+Yarn version: 
+  1.3.2
+
+Node version: 
+  8.9.3
+
+Platform: 
+  linux x64
+
+npm manifest: 
+  {
+    "name": "native-image-diff-example",
+    "main": "src/index.js"
+  }
+
+yarn manifest: 
+  No manifest
+
+Lockfile: 
+  No lockfile
+
+Trace: 
+  Error: https://registry.yarnpkg.com/node-fetch: ETIMEDOUT
+      at Timeout._onTimeout (/home/prior/.nvm/versions/node/v8.9.3/lib/node_modules/yarn/lib/cli.js:123749:19)
+      at ontimeout (timers.js:475:11)
+      at tryOnTimeout (timers.js:310:5)
+      at Timer.listOnTimeout (timers.js:270:5)