Default to single-channel output from extractChannel #2658

docs/api-channel.md

@@ -64,13 +64,18 @@ Extract a single channel from a multi-channel image.
 ### Examples
 
 ```javascript
-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
-   });
+await sharp(input)
+  .extractChannel('green')
+  .toFile('green.jpg');
+```
+
+```javascript
+// red1 is the red value of the first pixel, red2 the second pixel etc.
+const [red1, red2, ...] = await sharp(input)
+  .extractChannel(0)
+  .raw()
+  .toBuffer();
 ```
 
 *   Throws **[Error][3]** Invalid channel

docs/api-colour.md

@@ -86,4 +86,4 @@ Returns **Sharp**
 
 [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
 
-[6]: https://github.com/libvips/libvips/blob/master/libvips/iofuncs/enumtypes.c#L568
+[6]: https://github.com/libvips/libvips/blob/3c0bfdf74ce1dc37a6429bed47fa76f16e2cd70a/libvips/iofuncs/enumtypes.c#L777-L794

docs/changelog.md

@@ -17,6 +17,9 @@ Requires libvips v8.11.0
 * Allow multiple platform-arch binaries in same `node_modules` installation tree.
   [#2575](https://github.com/lovell/sharp/issues/2575)
 
+* Default to single-channel `b-w` space when `extractChannel` is used.
+  [#2658](https://github.com/lovell/sharp/issues/2658)
+
 ## v0.28 - *bijou*
 
 Requires libvips v8.10.6

lib/channel.js

@@ -72,13 +72,17 @@ function ensureAlpha (alpha) {
  * Extract a single channel from a multi-channel image.
  *
  * @example
- * 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
- *    });
+ * await sharp(input)
+ *   .extractChannel('green')
+ *   .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
  */

test/unit/extractChannel.js

@@ -57,8 +57,8 @@ describe('Image channel extraction', function () {
   it('With colorspace conversion', function (done) {
     const output = fixtures.path('output.extract-lch.jpg');
     sharp(fixtures.inputJpg)
-      .toColourspace('lch')
       .extractChannel(1)
+      .toColourspace('lch')
       .resize(320, 240, { fastShrinkOnLoad: false })
       .toFile(output, function (err, info) {
         if (err) throw err;
@@ -70,12 +70,13 @@ describe('Image channel extraction', function () {
   });
 
   it('Alpha from 16-bit PNG', function (done) {
-    const output = fixtures.path('output.extract-alpha-16bit.jpg');
+    const output = fixtures.path('output.extract-alpha-16bit.png');
     sharp(fixtures.inputPngWithTransparency16bit)
+      .resize(16)
       .extractChannel(3)
-      .toFile(output, function (err, info) {
+      .toFile(output, function (err) {
         if (err) throw err;
-        fixtures.assertMaxColourDistance(output, fixtures.expected('extract-alpha-16bit.jpg'));
+        fixtures.assertMaxColourDistance(output, fixtures.expected('extract-alpha-16bit.png'));
         done();
       });
   });