Doc refresh for #1438 #1439

docs/api-operation.md

@@ -131,10 +131,12 @@ This can improve the perceived brightness of a resized image in non-linear colou
 JPEG and WebP input images will not take advantage of the shrink-on-load performance optimisation
 when applying a gamma correction.
 
+Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.
+
 ### Parameters
 
 -   `gamma` **[Number][1]** value between 1.0 and 3.0. (optional, default `2.2`)
--   `gammaOut` ** [Number][1]** value between 1.0 and 3.0. (optional, defaults to same as `gamma`)
+-   `gammaOut` **[Number][1]?** value between 1.0 and 3.0. (optional, defaults to same as `gamma`)
 
 
 -   Throws **[Error][5]** Invalid parameters

docs/api-resize.md

@@ -30,23 +30,23 @@ Possible interpolation kernels are:
 
 -   `nearest`: Use [nearest neighbour interpolation][4].
 -   `cubic`: Use a [Catmull-Rom spline][5].
--   `mitchell`: Use a [Mitchell-Netravali spline][13].
--   `lanczos2`: Use a [Lanczos kernel][6] with `a=2`.
+-   `mitchell`: Use a [Mitchell-Netravali spline][6].
+-   `lanczos2`: Use a [Lanczos kernel][7] with `a=2`.
 -   `lanczos3`: Use a Lanczos kernel with `a=3` (the default).
 
 ### Parameters
 
--   `width` **[Number][7]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
--   `height` **[Number][7]?** pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
--   `options` **[Object][8]?** 
-    -   `options.width` **[String][9]?** alternative means of specifying `width`. If both are present this take priority.
-    -   `options.height` **[String][9]?** alternative means of specifying `height`. If both are present this take priority.
-    -   `options.fit` **[String][9]** how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`. (optional, default `'cover'`)
-    -   `options.position` **[String][9]** position, gravity or strategy to use when `fit` is `cover` or `contain`. (optional, default `'centre'`)
-    -   `options.background` **([String][9] \| [Object][8])** background colour when using a `fit` of `contain`, parsed by the [color][10] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
-    -   `options.kernel` **[String][9]** the kernel to use for image reduction. (optional, default `'lanczos3'`)
-    -   `options.withoutEnlargement` **[Boolean][11]** do not enlarge if the width _or_ height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option. (optional, default `false`)
-    -   `options.fastShrinkOnLoad` **[Boolean][11]** take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images. (optional, default `true`)
+-   `width` **[Number][8]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
+-   `height` **[Number][8]?** pixels high the resultant image should be. Use `null` or `undefined` to auto-scale the height to match the width.
+-   `options` **[Object][9]?** 
+    -   `options.width` **[String][10]?** alternative means of specifying `width`. If both are present this take priority.
+    -   `options.height` **[String][10]?** alternative means of specifying `height`. If both are present this take priority.
+    -   `options.fit` **[String][10]** how the image should be resized to fit both provided dimensions, one of `cover`, `contain`, `fill`, `inside` or `outside`. (optional, default `'cover'`)
+    -   `options.position` **[String][10]** position, gravity or strategy to use when `fit` is `cover` or `contain`. (optional, default `'centre'`)
+    -   `options.background` **([String][10] \| [Object][9])** background colour when using a `fit` of `contain`, parsed by the [color][11] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
+    -   `options.kernel` **[String][10]** the kernel to use for image reduction. (optional, default `'lanczos3'`)
+    -   `options.withoutEnlargement` **[Boolean][12]** do not enlarge if the width _or_ height are already less than the specified dimensions, equivalent to GraphicsMagick's `>` geometry option. (optional, default `false`)
+    -   `options.fastShrinkOnLoad` **[Boolean][12]** take greater advantage of the JPEG and WebP shrink-on-load feature, which can lead to a slight moiré pattern on some images. (optional, default `true`)
 
 ### Examples
 
@@ -114,7 +114,7 @@ sharp(input)
   });
 ```
 
--   Throws **[Error][12]** Invalid parameters
+-   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
 
@@ -125,12 +125,12 @@ This operation will always occur after resizing and extraction, if any.
 
 ### Parameters
 
--   `extend` **([Number][7] \| [Object][8])** single pixel count to add to all edges or an Object with per-edge counts
-    -   `extend.top` **[Number][7]?** 
-    -   `extend.left` **[Number][7]?** 
-    -   `extend.bottom` **[Number][7]?** 
-    -   `extend.right` **[Number][7]?** 
-    -   `extend.background` **([String][9] \| [Object][8])** background colour, parsed by the [color][10] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
+-   `extend` **([Number][8] \| [Object][9])** single pixel count to add to all edges or an Object with per-edge counts
+    -   `extend.top` **[Number][8]?** 
+    -   `extend.left` **[Number][8]?** 
+    -   `extend.bottom` **[Number][8]?** 
+    -   `extend.right` **[Number][8]?** 
+    -   `extend.background` **([String][10] \| [Object][9])** background colour, parsed by the [color][11] module, defaults to black without transparency. (optional, default `{r:0,g:0,b:0,alpha:1}`)
 
 ### Examples
 
@@ -150,7 +150,7 @@ sharp(input)
   ...
 ```
 
--   Throws **[Error][12]** Invalid parameters
+-   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
 
@@ -164,11 +164,11 @@ Extract a region of the image.
 
 ### Parameters
 
--   `options` **[Object][8]** 
-    -   `options.left` **[Number][7]** zero-indexed offset from left edge
-    -   `options.top` **[Number][7]** zero-indexed offset from top edge
-    -   `options.width` **[Number][7]** dimension of extracted image
-    -   `options.height` **[Number][7]** dimension of extracted image
+-   `options` **[Object][9]** 
+    -   `options.left` **[Number][8]** zero-indexed offset from left edge
+    -   `options.top` **[Number][8]** zero-indexed offset from top edge
+    -   `options.width` **[Number][8]** dimension of extracted image
+    -   `options.height` **[Number][8]** dimension of extracted image
 
 ### Examples
 
@@ -190,7 +190,7 @@ sharp(input)
   });
 ```
 
--   Throws **[Error][12]** Invalid parameters
+-   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
 
@@ -201,10 +201,10 @@ The `info` response Object will contain `trimOffsetLeft` and `trimOffsetTop` pro
 
 ### Parameters
 
--   `threshold` **[Number][7]** the allowed difference from the top-left pixel, a number greater than zero. (optional, default `10`)
+-   `threshold` **[Number][8]** the allowed difference from the top-left pixel, a number greater than zero. (optional, default `10`)
 
 
--   Throws **[Error][12]** Invalid parameters
+-   Throws **[Error][13]** Invalid parameters
 
 Returns **Sharp** 
 
@@ -218,18 +218,18 @@ Returns **Sharp**
 
 [5]: https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline
 
-[6]: https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel
+[6]: https://www.cs.utexas.edu/~fussell/courses/cs384g-fall2013/lectures/mitchell/Mitchell.pdf
 
-[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+[7]: https://en.wikipedia.org/wiki/Lanczos_resampling#Lanczos_kernel
 
-[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
 
-[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[10]: https://www.npmjs.org/package/color
+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
 
-[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[11]: https://www.npmjs.org/package/color
 
-[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[13]: https://www.cs.utexas.edu/~fussell/courses/cs384g-fall2013/lectures/mitchell/Mitchell.pdf
+[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error

docs/changelog.md

@@ -14,7 +14,7 @@ Requires libvips v8.7.0.
   [#1438](https://github.com/lovell/sharp/pull/1438)
   [@Daiz](https://github.com/Daiz)
 
-* Add support for different output gamma from what is used for scaling.
+* Allow separate parameters for gamma encoding and decoding.
   [#1439](https://github.com/lovell/sharp/pull/1439)
   [@Daiz](https://github.com/Daiz)
 

lib/operation.js

@@ -189,9 +189,12 @@ function flatten (options) {
  * then increasing the encoding (brighten) post-resize at a factor of `gamma`.
  * This can improve the perceived brightness of a resized image in non-linear colour spaces.
  * JPEG and WebP input images will not take advantage of the shrink-on-load performance optimisation
- * when applying a gamma correction. Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.
+ * when applying a gamma correction.
+ *
+ * Supply a second argument to use a different output gamma value, otherwise the first value is used in both cases.
+ *
  * @param {Number} [gamma=2.2] value between 1.0 and 3.0.
- * @param {Number} [gammaOut] value between 1.0 and 3.0. Defaults to same as gamma.
+ * @param {Number} [gammaOut] value between 1.0 and 3.0. (optional, defaults to same as `gamma`)
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */
@@ -210,7 +213,7 @@ function gamma (gamma, gammaOut) {
   } else if (is.number(gammaOut) && is.inRange(gammaOut, 1, 3)) {
     this.options.gammaOut = gammaOut;
   } else {
-    throw new Error('Invalid post gamma correction (1.0 to 3.0) ' + gammaOut);
+    throw new Error('Invalid output gamma correction (1.0 to 3.0) ' + gammaOut);
   }
   return this;
 }