Allow sharpen options to be provided as an Object

Also exposes x1, y2, y3 parameters #2561 #2935

lib/operation.js

@@ -185,40 +185,105 @@ function affine (matrix, options) {
  * When a `sigma` is provided, performs a slower, more accurate sharpen of the L channel in the LAB colour space.
  * Separate control over the level of sharpening in "flat" and "jagged" areas is available.
  *
- * @param {number} [sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
- * @param {number} [flat=1.0] - the level of sharpening to apply to "flat" areas.
- * @param {number} [jagged=2.0] - the level of sharpening to apply to "jagged" areas.
+ * See {@link https://www.libvips.org/API/current/libvips-convolution.html#vips-sharpen|libvips sharpen} operation.
+ *
+ * @example
+ * const data = await sharp(input).sharpen().toBuffer();
+ *
+ * @example
+ * const data = await sharp(input).sharpen({ sigma: 2 }).toBuffer();
+ *
+ * @example
+ * const data = await sharp(input)
+ *   .sharpen({
+ *     sigma: 2,
+ *     m1: 0
+ *     m2: 3,
+ *     x1: 3,
+ *     y2: 15,
+ *     y3: 15,
+ *   })
+ *   .toBuffer();
+ *
+ * @param {Object} [options] - if present, is an Object with optional attributes.
+ * @param {number} [options.sigma] - the sigma of the Gaussian mask, where `sigma = 1 + radius / 2`.
+ * @param {number} [options.m1=1.0] - the level of sharpening to apply to "flat" areas.
+ * @param {number} [options.m2=2.0] - the level of sharpening to apply to "jagged" areas.
+ * @param {number} [options.x1=2.0] - threshold between "flat" and "jagged"
+ * @param {number} [options.y2=10.0] - maximum amount of brightening.
+ * @param {number} [options.y3=20.0] - maximum amount of darkening.
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
-function sharpen (sigma, flat, jagged) {
-  if (!is.defined(sigma)) {
+function sharpen (options) {
+  if (!is.defined(options)) {
     // No arguments: default to mild sharpen
     this.options.sharpenSigma = -1;
-  } else if (is.bool(sigma)) {
-    // Boolean argument: apply mild sharpen?
-    this.options.sharpenSigma = sigma ? -1 : 0;
-  } else if (is.number(sigma) && is.inRange(sigma, 0.01, 10000)) {
-    // Numeric argument: specific sigma
-    this.options.sharpenSigma = sigma;
-    // Control over flat areas
-    if (is.defined(flat)) {
-      if (is.number(flat) && is.inRange(flat, 0, 10000)) {
-        this.options.sharpenFlat = flat;
+  } else if (is.bool(options)) {
+    // Deprecated boolean argument: apply mild sharpen?
+    this.options.sharpenSigma = options ? -1 : 0;
+  } else if (is.number(options) && is.inRange(options, 0.01, 10000)) {
+    // Deprecated numeric argument: specific sigma
+    this.options.sharpenSigma = options;
+    // Deprecated control over flat areas
+    if (is.defined(arguments[1])) {
+      if (is.number(arguments[1]) && is.inRange(arguments[1], 0, 10000)) {
+        this.options.sharpenM1 = arguments[1];
       } else {
-        throw is.invalidParameterError('flat', 'number between 0 and 10000', flat);
+        throw is.invalidParameterError('flat', 'number between 0 and 10000', arguments[1]);
       }
     }
-    // Control over jagged areas
-    if (is.defined(jagged)) {
-      if (is.number(jagged) && is.inRange(jagged, 0, 10000)) {
-        this.options.sharpenJagged = jagged;
+    // Deprecated control over jagged areas
+    if (is.defined(arguments[2])) {
+      if (is.number(arguments[2]) && is.inRange(arguments[2], 0, 10000)) {
+        this.options.sharpenM2 = arguments[2];
       } else {
-        throw is.invalidParameterError('jagged', 'number between 0 and 10000', jagged);
+        throw is.invalidParameterError('jagged', 'number between 0 and 10000', arguments[2]);
+      }
+    }
+  } else if (is.plainObject(options)) {
+    if (is.number(options.sigma) && is.inRange(options.sigma, 0.01, 10000)) {
+      this.options.sharpenSigma = options.sigma;
+    } else {
+      throw is.invalidParameterError('options.sigma', 'number between 0.01 and 10000', options.sigma);
+    }
+    if (is.defined(options.m1)) {
+      if (is.number(options.m1) && is.inRange(options.m1, 0, 10000)) {
+        this.options.sharpenM1 = options.m1;
+      } else {
+        throw is.invalidParameterError('options.m1', 'number between 0 and 10000', options.m1);
+      }
+    }
+    if (is.defined(options.m2)) {
+      if (is.number(options.m2) && is.inRange(options.m2, 0, 10000)) {
+        this.options.sharpenM2 = options.m2;
+      } else {
+        throw is.invalidParameterError('options.m2', 'number between 0 and 10000', options.m2);
+      }
+    }
+    if (is.defined(options.x1)) {
+      if (is.number(options.x1) && is.inRange(options.x1, 0, 10000)) {
+        this.options.sharpenX1 = options.x1;
+      } else {
+        throw is.invalidParameterError('options.x1', 'number between 0 and 10000', options.x1);
+      }
+    }
+    if (is.defined(options.y2)) {
+      if (is.number(options.y2) && is.inRange(options.y2, 0, 10000)) {
+        this.options.sharpenY2 = options.y2;
+      } else {
+        throw is.invalidParameterError('options.y2', 'number between 0 and 10000', options.y2);
+      }
+    }
+    if (is.defined(options.y3)) {
+      if (is.number(options.y3) && is.inRange(options.y3, 0, 10000)) {
+        this.options.sharpenY3 = options.y3;
+      } else {
+        throw is.invalidParameterError('options.y3', 'number between 0 and 10000', options.y3);
       }
     }
   } else {
-    throw is.invalidParameterError('sigma', 'number between 0.01 and 10000', sigma);
+    throw is.invalidParameterError('sigma', 'number between 0.01 and 10000', options);
   }
   return this;
 }