Add support to normalise for lower and upper percentiles (#3583)

lib/constructor.js

@@ -235,6 +235,8 @@ const Sharp = function (input, options) {
     gammaOut: 0,
     greyscale: false,
     normalise: false,
+    normaliseLower: 1,
+    normaliseUpper: 99,
     claheWidth: 0,
     claheHeight: 0,
     claheMaxSlope: 3,

lib/index.d.ts

@@ -447,18 +447,26 @@ declare namespace sharp {
         negate(negate?: boolean | NegateOptions): Sharp;
 
         /**
-         * Enhance output image contrast by stretching its luminance to cover the full dynamic range.
-         * @param normalise true to enable and false to disable (defaults to true)
+         * Enhance output image contrast by stretching its luminance to cover a full dynamic range.
+         *
+         * Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.
+         *
+         * Luminance values below the `lower` percentile will be underexposed by clipping to zero.
+         * Luminance values above the `upper` percentile will be overexposed by clipping to the max pixel value.
+         *
+         * @param normalise options
+         * @throws {Error} Invalid parameters
          * @returns A sharp instance that can be used to chain operations
          */
-        normalise(normalise?: boolean): Sharp;
+        normalise(normalise?: NormaliseOptions): Sharp;
 
         /**
          * Alternative spelling of normalise.
-         * @param normalize true to enable and false to disable (defaults to true)
+         * @param normalize options
+         * @throws {Error} Invalid parameters
          * @returns A sharp instance that can be used to chain operations
          */
-        normalize(normalize?: boolean): Sharp;
+        normalize(normalize?: NormaliseOptions): Sharp;
 
         /**
          * Perform contrast limiting adaptive histogram equalization (CLAHE)
@@ -1218,6 +1226,13 @@ declare namespace sharp {
         alpha?: boolean | undefined;
     }
 
+    interface NormaliseOptions {
+      /** Percentile below which luminance values will be underexposed. */
+      lower?: number | undefined;
+      /** Percentile above which luminance values will be overexposed. */
+      upper?: number | undefined;
+    }
+
     interface ResizeOptions {
         /** Alternative means of specifying width. If both are present this takes priority. */
         width?: number | undefined;

lib/operation.js

@@ -469,16 +469,50 @@ function negate (options) {
 }
 
 /**
- * Enhance output image contrast by stretching its luminance to cover the full dynamic range.
+ * Enhance output image contrast by stretching its luminance to cover a full dynamic range.
+ *
+ * Uses a histogram-based approach, taking a default range of 1% to 99% to reduce sensitivity to noise at the extremes.
+ *
+ * Luminance values below the `lower` percentile will be underexposed by clipping to zero.
+ * Luminance values above the `upper` percentile will be overexposed by clipping to the max pixel value.
  *
  * @example
- * const output = await sharp(input).normalise().toBuffer();
+ * const output = await sharp(input)
+ *   .normalise()
+ *   .toBuffer();
  *
- * @param {Boolean} [normalise=true]
+ * @example
+ * const output = await sharp(input)
+ *   .normalise({ lower: 0, upper: 100 })
+ *   .toBuffer();
+ *
+ * @param {Object} [options]
+ * @param {number} [options.lower=1] - Percentile below which luminance values will be underexposed.
+ * @param {number} [options.upper=99] - Percentile above which luminance values will be overexposed.
  * @returns {Sharp}
  */
-function normalise (normalise) {
-  this.options.normalise = is.bool(normalise) ? normalise : true;
+function normalise (options) {
+  if (is.plainObject(options)) {
+    if (is.defined(options.lower)) {
+      if (is.number(options.lower) && is.inRange(options.lower, 0, 99)) {
+        this.options.normaliseLower = options.lower;
+      } else {
+        throw is.invalidParameterError('lower', 'number between 0 and 99', options.lower);
+      }
+    }
+    if (is.defined(options.upper)) {
+      if (is.number(options.upper) && is.inRange(options.upper, 1, 100)) {
+        this.options.normaliseUpper = options.upper;
+      } else {
+        throw is.invalidParameterError('upper', 'number between 1 and 100', options.upper);
+      }
+    }
+  }
+  if (this.options.normaliseLower >= this.options.normaliseUpper) {
+    throw is.invalidParameterError('range', 'lower to be less than upper',
+      `${this.options.normaliseLower} >= ${this.options.normaliseUpper}`);
+  }
+  this.options.normalise = true;
   return this;
 }
 
@@ -486,13 +520,17 @@ function normalise (normalise) {
  * Alternative spelling of normalise.
  *
  * @example
- * const output = await sharp(input).normalize().toBuffer();
+ * const output = await sharp(input)
+ *   .normalize()
+ *   .toBuffer();
  *
- * @param {Boolean} [normalize=true]
+ * @param {Object} [options]
+ * @param {number} [options.lower=1] - Percentile below which luminance values will be underexposed.
+ * @param {number} [options.upper=99] - Percentile above which luminance values will be overexposed.
  * @returns {Sharp}
  */
-function normalize (normalize) {
-  return this.normalise(normalize);
+function normalize (options) {
+  return this.normalise(options);
 }
 
 /**