From 7a1a1cf9e88ef3dd834d47f3239502d64623ae50 Mon Sep 17 00:00:00 2001 From: Lovell Fuller Date: Wed, 9 Mar 2022 19:18:41 +0000 Subject: [PATCH] Docs: add/correct some operation examples --- docs/api-operation.md | 82 +++++++++++++++++++++++++++++++++++-------- lib/operation.js | 65 +++++++++++++++++++++++++++------- 2 files changed, 121 insertions(+), 26 deletions(-) diff --git a/docs/api-operation.md b/docs/api-operation.md index 9d03d7ba..a158c457 100644 --- a/docs/api-operation.md +++ b/docs/api-operation.md @@ -53,6 +53,12 @@ The use of `flip` implies the removal of the EXIF `Orientation` tag, if any. * `flip` **[Boolean][6]** (optional, default `true`) +### Examples + +```javascript +const output = await sharp(input).flip().toBuffer(); +``` + Returns **Sharp** ## flop @@ -64,6 +70,12 @@ The use of `flop` implies the removal of the EXIF `Orientation` tag, if any. * `flop` **[Boolean][6]** (optional, default `true`) +### Examples + +```javascript +const output = await sharp(input).flop().toBuffer(); +``` + Returns **Sharp** ## affine @@ -178,7 +190,15 @@ When used without parameters the default window is 3x3. * `size` **[number][1]** square mask size: size x size (optional, default `3`) - +### Examples + +```javascript +const output = await sharp(input).median().toBuffer(); +``` + +```javascript +const output = await sharp(input).median(5).toBuffer(); +``` * Throws **[Error][5]** Invalid parameters @@ -277,6 +297,12 @@ Enhance output image contrast by stretching its luminance to cover the full dyna * `normalise` **[Boolean][6]** (optional, default `true`) +### Examples + +```javascript +const output = await sharp(input).normalise().toBuffer(); +``` + Returns **Sharp** ## normalize @@ -287,6 +313,12 @@ Alternative spelling of normalise. * `normalize` **[Boolean][6]** (optional, default `true`) +### Examples + +```javascript +const output = await sharp(input).normalize().toBuffer(); +``` + Returns **Sharp** ## clahe @@ -306,7 +338,16 @@ This will, in general, enhance the clarity of the image by bringing out darker d cumulative histogram. A value of 0 disables contrast limiting. Valid values are integers in the range 0-100 (inclusive) (optional, default `3`) - +### Examples + +```javascript +const output = await sharp(input) + .clahe({ + width: 3, + height: 3, + }) + .toBuffer(); +``` * Throws **[Error][5]** Invalid parameters @@ -458,28 +499,41 @@ brightness is multiplicative whereas lightness is additive. ### Examples ```javascript -sharp(input) +// increase brightness by a factor of 2 +const output = await sharp(input) .modulate({ - brightness: 2 // increase brightness by a factor of 2 - }); + brightness: 2 + }) + .toBuffer(); +``` -sharp(input) +```javascript +// hue-rotate by 180 degrees +const output = await sharp(input) .modulate({ - hue: 180 // hue-rotate by 180 degrees - }); + hue: 180 + }) + .toBuffer(); +``` -sharp(input) +```javascript +// increase lightness by +50 +const output = await sharp(input) .modulate({ - lightness: 50 // increase lightness by +50 - }); + lightness: 50 + }) + .toBuffer(); +``` +```javascript // decreate brightness and saturation while also hue-rotating by 90 degrees -sharp(input) +const output = await sharp(input) .modulate({ brightness: 0.5, saturation: 0.5, - hue: 90 - }); + hue: 90, + }) + .toBuffer(); ``` Returns **Sharp** diff --git a/lib/operation.js b/lib/operation.js index c1e08614..4294c6c1 100644 --- a/lib/operation.js +++ b/lib/operation.js @@ -63,6 +63,10 @@ function rotate (angle, options) { /** * Flip the image about the vertical Y axis. This always occurs after rotation, if any. * The use of `flip` implies the removal of the EXIF `Orientation` tag, if any. + * + * @example + * const output = await sharp(input).flip().toBuffer(); + * * @param {Boolean} [flip=true] * @returns {Sharp} */ @@ -74,6 +78,10 @@ function flip (flip) { /** * Flop the image about the horizontal X axis. This always occurs after rotation, if any. * The use of `flop` implies the removal of the EXIF `Orientation` tag, if any. + * + * @example + * const output = await sharp(input).flop().toBuffer(); + * * @param {Boolean} [flop=true] * @returns {Sharp} */ @@ -291,6 +299,13 @@ function sharpen (options) { /** * Apply median filter. * When used without parameters the default window is 3x3. + * + * @example + * const output = await sharp(input).median().toBuffer(); + * + * @example + * const output = await sharp(input).median(5).toBuffer(); + * * @param {number} [size=3] square mask size: size x size * @returns {Sharp} * @throws {Error} Invalid parameters @@ -421,6 +436,10 @@ function negate (options) { /** * Enhance output image contrast by stretching its luminance to cover the full dynamic range. + * + * @example + * const output = await sharp(input).normalise().toBuffer(); + * * @param {Boolean} [normalise=true] * @returns {Sharp} */ @@ -431,6 +450,10 @@ function normalise (normalise) { /** * Alternative spelling of normalise. + * + * @example + * const output = await sharp(input).normalize().toBuffer(); + * * @param {Boolean} [normalize=true] * @returns {Sharp} */ @@ -446,6 +469,14 @@ function normalize (normalize) { * * @since 0.28.3 * + * @example + * const output = await sharp(input) + * .clahe({ + * width: 3, + * height: 3, + * }) + * .toBuffer(); + * * @param {Object} options * @param {number} options.width - integer width of the region in pixels. * @param {number} options.height - integer height of the region in pixels. @@ -655,28 +686,38 @@ function recomb (inputMatrix) { * @since 0.22.1 * * @example - * sharp(input) + * // increase brightness by a factor of 2 + * const output = await sharp(input) * .modulate({ - * brightness: 2 // increase brightness by a factor of 2 - * }); + * brightness: 2 + * }) + * .toBuffer(); * - * sharp(input) + * @example + * // hue-rotate by 180 degrees + * const output = await sharp(input) * .modulate({ - * hue: 180 // hue-rotate by 180 degrees - * }); + * hue: 180 + * }) + * .toBuffer(); * - * sharp(input) + * @example + * // increase lightness by +50 + * const output = await sharp(input) * .modulate({ - * lightness: 50 // increase lightness by +50 - * }); + * lightness: 50 + * }) + * .toBuffer(); * + * @example * // decreate brightness and saturation while also hue-rotating by 90 degrees - * sharp(input) + * const output = await sharp(input) * .modulate({ * brightness: 0.5, * saturation: 0.5, - * hue: 90 - * }); + * hue: 90, + * }) + * .toBuffer(); * * @param {Object} [options] * @param {number} [options.brightness] Brightness multiplier