Default to single-channel output from extractChannel #2658

lib/channel.js

@@ -72,13 +72,17 @@ function ensureAlpha (alpha) {
  * Extract a single channel from a multi-channel image.
  *
  * @example
- * sharp(input)
+ * // green.jpg is a greyscale image containing the green channel of the input
+ * await sharp(input)
  *   .extractChannel('green')
- *   .toColourspace('b-w')
- *   .toFile('green.jpg', function(err, info) {
- *     // info.channels === 1
- *     // green.jpg is a greyscale image containing the green channel of the input
- *    });
+ *   .toFile('green.jpg');
+ *
+ * @example
+ * // red1 is the red value of the first pixel, red2 the second pixel etc.
+ * const [red1, red2, ...] = await sharp(input)
+ *   .extractChannel(0)
+ *   .raw()
+ *   .toBuffer();
  *
  * @param {number|string} channel - zero-indexed channel/band number to extract, or `red`, `green`, `blue` or `alpha`.
  * @returns {Sharp}
@@ -94,7 +98,7 @@ function extractChannel (channel) {
   } else {
     throw is.invalidParameterError('channel', 'integer or one of: red, green, blue, alpha', channel);
   }
-  return this;
+  return this.toColourspace('b-w');
 }
 
 /**

lib/colour.js

@@ -64,7 +64,7 @@ function grayscale (grayscale) {
  *  .toColourspace('rgb16')
  *  .toFile('16-bpp.png')
  *
- * @param {string} [colourspace] - output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/libvips/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568)
+ * @param {string} [colourspace] - output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/libvips/libvips/blob/3c0bfdf74ce1dc37a6429bed47fa76f16e2cd70a/libvips/iofuncs/enumtypes.c#L777-L794)
  * @returns {Sharp}
  * @throws {Error} Invalid parameters
  */