Docs: changelog entry and example for #2527

docs/api-constructor.md

@@ -38,11 +38,11 @@ Implements the [stream.Duplex][1] class.
         -   `options.create.width` **[number][8]?** integral number of pixels wide.
         -   `options.create.height` **[number][8]?** integral number of pixels high.
         -   `options.create.channels` **[number][8]?** integral number of channels, either 3 (RGB) or 4 (RGBA).
-        -   `options.create.noise` **[Object][6]?** describes a noise to be created.
-            -    `options.create.noise.type` **[string][5]?** type of generated noise. (supported: `gaussian`)
-            -    `options.create.noise.mean` **[number][8]?** mean of pixels in generated image.
-            -    `options.create.noise.sigma` **[number][8]?** standard deviation of pixels in generated image.
         -   `options.create.background` **([string][5] \| [Object][6])?** parsed by the [color][9] module to extract values for red, green, blue and alpha.
+        -   `options.create.noise` **[Object][6]?** describes a noise to be created.
+            -   `options.create.noise.type` **[string][5]?** type of generated noise, currently only `gaussian` is supported.
+            -   `options.create.noise.mean` **[number][8]?** mean of pixels in generated noise.
+            -   `options.create.noise.sigma` **[number][8]?** standard deviation of pixels in generated noise.
 
 ### Examples
 
@@ -103,6 +103,22 @@ const image = sharp(input, {
 await image.toFile('my-two-pixels.png');
 ```
 
+```javascript
+// Generate RGB Gaussian noise
+await sharp({
+  create: {
+    width: 300,
+    height: 200,
+    channels: 3,
+    noise: {
+      type: 'gaussian',
+      mean: 128,
+      sigma: 30
+    }
+ }
+}.toFile('noise.png');
+```
+
 -   Throws **[Error][10]** Invalid parameters
 
 Returns **[Sharp][11]** 

docs/changelog.md

@@ -13,6 +13,10 @@ Requires libvips v8.10.5
 * Revert: ensure all platforms use fontconfig for font rendering.
   [#2515](https://github.com/lovell/sharp/issues/2515)
 
+* Expose libvips gaussnoise operation to allow creation of Gaussian noise.
+  [#2527](https://github.com/lovell/sharp/pull/2527)
+  [@alza54](https://github.com/alza54)
+
 ### v0.27.0 - 22nd December 2020
 
 * Add support for AVIF to prebuilt binaries.

lib/constructor.js

@@ -104,6 +104,21 @@ const debuglog = util.debuglog('sharp');
  * });
  * await image.toFile('my-two-pixels.png');
  *
+ * @example
+ * // Generate RGB Gaussian noise
+ * await sharp({
+ *   create: {
+ *     width: 300,
+ *     height: 200,
+ *     channels: 3,
+ *     noise: {
+ *       type: 'gaussian',
+ *       mean: 128,
+ *       sigma: 30
+ *     }
+ *  }
+ * }.toFile('noise.png');
+ *
  * @param {(Buffer|Uint8Array|Uint8ClampedArray|string)} [input] - if present, can be
  *  a Buffer / Uint8Array / Uint8ClampedArray containing JPEG, PNG, WebP, AVIF, GIF, SVG, TIFF or raw pixel image data, or
  *  a String containing the filesystem path to an JPEG, PNG, WebP, AVIF, GIF, SVG or TIFF image file.
@@ -130,6 +145,10 @@ const debuglog = util.debuglog('sharp');
  * @param {number} [options.create.height] - integral number of pixels high.
  * @param {number} [options.create.channels] - integral number of channels, either 3 (RGB) or 4 (RGBA).
  * @param {string|Object} [options.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
+ * @param {Object} [options.create.noise] - describes a noise to be created.
+ * @param {string} [options.create.noise.type] - type of generated noise, currently only `gaussian` is supported.
+ * @param {number} [options.create.noise.mean] - mean of pixels in generated noise.
+ * @param {number} [options.create.noise.sigma] - standard deviation of pixels in generated noise.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */