Improve docs relating to single-channel raw pixel output

docs/api-channel.md

@@ -49,9 +49,10 @@ Extract a single channel from a multi-channel image.
 ```javascript
 sharp(input)
   .extractChannel('green')
-  .toFile('input_green.jpg', function(err, info) {
+  .toColourspace('b-w')
+  .toFile('green.jpg', function(err, info) {
     // info.channels === 1
-    // input_green.jpg contains the green channel of the input image
+    // green.jpg is a greyscale image containing the green channel of the input
    });
 ```
 

docs/api-output.md

@@ -296,7 +296,9 @@ Returns **Sharp**
 
 ## raw
 
-Force output to be raw, uncompressed uint8 pixel data.
+Force output to be raw, uncompressed, 8-bit unsigned integer (unit8) pixel data.
+Pixel ordering is left-to-right, top-to-bottom, without padding.
+Channel ordering will be RGB or RGBA for non-greyscale colourspaces.
 
 ### Examples
 
@@ -307,6 +309,16 @@ const { data, info } = await sharp('input.jpg')
   .toBuffer({ resolveWithObject: true });
 ```
 
+```javascript
+// Extract alpha channel as raw pixel data from PNG input
+const data = await sharp('input.png')
+  .ensureAlpha()
+  .extractChannel(3)
+  .colourspace('b-w')
+  .raw()
+  .toBuffer();
+```
+
 Returns **Sharp** 
 
 ## tile

docs/api-resize.md

@@ -11,14 +11,16 @@ When both a `width` and `height` are provided, the possible methods by which the
 -   `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
 -   `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
 -   `outside`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.
-    Some of these values are based on the [object-fit][1] CSS property.
+
+Some of these values are based on the [object-fit][1] CSS property.
 
 When using a `fit` of `cover` or `contain`, the default **position** is `centre`. Other options are:
 
 -   `sharp.position`: `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`.
 -   `sharp.gravity`: `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` or `centre`.
 -   `sharp.strategy`: `cover` only, dynamically crop using either the `entropy` or `attention` strategy.
-    Some of these values are based on the [object-position][2] CSS property.
+
+Some of these values are based on the [object-position][2] CSS property.
 
 The experimental strategy-based approach resizes so one dimension is at its target length
 then repeatedly ranks edge regions, discarding the edge with the lowest score based on the selected strategy.

lib/channel.js

@@ -54,9 +54,10 @@ function ensureAlpha () {
  * @example
  * sharp(input)
  *   .extractChannel('green')
- *   .toFile('input_green.jpg', function(err, info) {
+ *   .toColourspace('b-w')
+ *   .toFile('green.jpg', function(err, info) {
  *     // info.channels === 1
- *     // input_green.jpg contains the green channel of the input image
+ *     // green.jpg is a greyscale image containing the green channel of the input
  *    });
  *
  * @param {Number|String} channel - zero-indexed band number to extract, or `red`, `green` or `blue` as alternative to `0`, `1` or `2` respectively.

lib/output.js

@@ -517,7 +517,9 @@ function heif (options) {
 }
 
 /**
- * Force output to be raw, uncompressed uint8 pixel data.
+ * Force output to be raw, uncompressed, 8-bit unsigned integer (unit8) pixel data.
+ * Pixel ordering is left-to-right, top-to-bottom, without padding.
+ * Channel ordering will be RGB or RGBA for non-greyscale colourspaces.
  *
  * @example
  * // Extract raw RGB pixel data from JPEG input
@@ -525,6 +527,15 @@ function heif (options) {
  *   .raw()
  *   .toBuffer({ resolveWithObject: true });
  *
+ * @example
+ * // Extract alpha channel as raw pixel data from PNG input
+ * const data = await sharp('input.png')
+ *   .ensureAlpha()
+ *   .extractChannel(3)
+ *   .colourspace('b-w')
+ *   .raw()
+ *   .toBuffer();
+ *
  * @returns {Sharp}
  */
 function raw () {

lib/resize.js

@@ -101,12 +101,14 @@ function isRotationExpected (options) {
  * - `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions.
  * - `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified.
  * - `outside`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified.
+ *
  * Some of these values are based on the [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) CSS property.
  *
  * When using a `fit` of `cover` or `contain`, the default **position** is `centre`. Other options are:
  * - `sharp.position`: `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`.
  * - `sharp.gravity`: `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` or `centre`.
  * - `sharp.strategy`: `cover` only, dynamically crop using either the `entropy` or `attention` strategy.
+ *
  * Some of these values are based on the [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) CSS property.
  *
  * The experimental strategy-based approach resizes so one dimension is at its target length

test/unit/raw.js

@@ -168,5 +168,19 @@ describe('Raw pixel data', function () {
           done();
         });
     });
+
+    it('extract A from RGBA', () =>
+      sharp(fixtures.inputPngWithTransparency)
+        .resize(32, 24)
+        .extractChannel(3)
+        .toColourspace('b-w')
+        .raw()
+        .toBuffer({ resolveWithObject: true })
+        .then(({ info }) => {
+          assert.strictEqual('raw', info.format);
+          assert.strictEqual(1, info.channels);
+          assert.strictEqual(32 * 24, info.size);
+        })
+    );
   });
 });