Add most dominant colour to image stats #640

docs/api-input.md

@@ -72,6 +72,7 @@ A `Promise` is returned when `callback` is not provided.
 -   `isOpaque`: Is the image fully opaque? Will be `true` if the image has no alpha channel or if every pixel is fully opaque.
 -   `entropy`: Histogram-based estimation of greyscale entropy, discarding alpha channel if any (experimental)
 -   `sharpness`: Estimation of greyscale sharpness based on the standard deviation of a Laplacian convolution, discarding alpha channel if any (experimental)
+-   `dominant`: Object containing most dominant sRGB colour based on a 4096-bin 3D histogram (experimental)
 
 ### Parameters
 
@@ -89,7 +90,8 @@ image
 ```
 
 ```javascript
-const { entropy, sharpness } = await sharp(input).stats();
+const { entropy, sharpness, dominant } = await sharp(input).stats();
+const { r, g, b } = dominant;
 ```
 
 Returns **[Promise][5]<[Object][6]>** 

docs/changelog.md

@@ -12,6 +12,9 @@ Requires libvips v8.10.0
 
 * JPEG output `quality` >= 90 no longer automatically sets `chromaSubsampling` to `4:4:4`.
 
+* Add most `dominant` colour to image `stats`.
+  [#640](https://github.com/lovell/sharp/issues/640)
+
 ## v0.25 - *yield*
 
 Requires libvips v8.9.1