Add autoOrient operation and constructor option #4144

docs/api-composite.md

@@ -46,6 +46,7 @@ and https://www.cairographics.org/operators/
 | [images[].input.text.dpi] | <code>number</code> | <code>72</code> | the resolution (size) at which to render the text. Does not take effect if `height` is specified. |
 | [images[].input.text.rgba] | <code>boolean</code> | <code>false</code> | set this to true to enable RGBA output. This is useful for colour emoji rendering, or support for Pango markup features like `<span foreground="red">Red!</span>`. |
 | [images[].input.text.spacing] | <code>number</code> | <code>0</code> | text line height in points. Will use the font line height if none is specified. |
+| [images[].autoOrient] | <code>Boolean</code> | <code>false</code> | set to true to use EXIF orientation data, if present, to orient the image. |
 | [images[].blend] | <code>String</code> | <code>&#x27;over&#x27;</code> | how to blend this image with the image below. |
 | [images[].gravity] | <code>String</code> | <code>&#x27;centre&#x27;</code> | gravity at which to place the overlay. |
 | [images[].top] | <code>Number</code> |  | the pixel offset from the top edge. |

docs/api-constructor.md

@@ -33,6 +33,7 @@ where the overall height is the `pageHeight` multiplied by the number of `pages`
 | [options.failOn] | <code>string</code> | <code>&quot;&#x27;warning&#x27;&quot;</code> | When to abort processing of invalid pixel data, one of (in order of sensitivity, least to most): 'none', 'truncated', 'error', 'warning'. Higher levels imply lower levels. Invalid metadata will always abort. |
 | [options.limitInputPixels] | <code>number</code> \| <code>boolean</code> | <code>268402689</code> | Do not process input images where the number of pixels  (width x height) exceeds this limit. Assumes image dimensions contained in the input metadata can be trusted.  An integral Number of pixels, zero or false to remove limit, true to use default limit of 268402689 (0x3FFF x 0x3FFF). |
 | [options.unlimited] | <code>boolean</code> | <code>false</code> | Set this to `true` to remove safety features that help prevent memory exhaustion (JPEG, PNG, SVG, HEIF). |
+| [options.autoOrient] | <code>boolean</code> | <code>false</code> | Set this to `true` to rotate/flip the image to match EXIF `Orientation`, if any. |
 | [options.sequentialRead] | <code>boolean</code> | <code>true</code> | Set this to `false` to use random access rather than sequential read. Some operations will do this automatically. |
 | [options.density] | <code>number</code> | <code>72</code> | number representing the DPI for vector images in the range 1 to 100000. |
 | [options.ignoreIcc] | <code>number</code> | <code>false</code> | should the embedded ICC profile, if any, be ignored. |

docs/api-input.md

@@ -72,15 +72,9 @@ image
 ```
 **Example**  
 ```js
-// Based on EXIF rotation metadata, get the right-side-up width and height:
-
-const size = getNormalSize(await sharp(input).metadata());
-
-function getNormalSize({ width, height, orientation }) {
-  return (orientation || 0) >= 5
-    ? { width: height, height: width }
-    : { width, height };
-}
+// Get dimensions taking EXIF Orientation into account.
+const { autoOrient } = await sharp(input).metadata();
+const { width, height } = autoOrient;
 ```
 
 

docs/api-operation.md

@@ -1,22 +1,19 @@
 ## rotate
 > rotate([angle], [options]) ⇒ <code>Sharp</code>
 
-Rotate the output image by either an explicit angle
-or auto-orient based on the EXIF `Orientation` tag.
+Rotate the output image.
 
-If an angle is provided, it is converted to a valid positive degree rotation.
+The provided angle is converted to a valid positive degree rotation.
 For example, `-450` will produce a 270 degree rotation.
 
 When rotating by an angle other than a multiple of 90,
 the background colour can be provided with the `background` option.
 
-If no angle is provided, it is determined from the EXIF data.
-Mirroring is supported and may infer the use of a flip operation.
+For backwards compatibility, if no angle is provided, `.autoOrient()` will be called.
 
-The use of `rotate` without an angle will remove the EXIF `Orientation` tag, if any.
-
-Only one rotation can occur per pipeline.
-Previous calls to `rotate` in the same pipeline will be ignored.
+Only one rotation can occur per pipeline (aside from an initial call without
+arguments to orient via EXIF data). Previous calls to `rotate` in the same
+pipeline will be ignored.
 
 Multi-page images can only be rotated by 180 degrees.
 
@@ -35,18 +32,6 @@ for example `.rotate(x).extract(y)` will produce a different result to `.extract
 | [options] | <code>Object</code> |  | if present, is an Object with optional attributes. |
 | [options.background] | <code>string</code> \| <code>Object</code> | <code>&quot;\&quot;#000000\&quot;&quot;</code> | parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. |
 
-**Example**  
-```js
-const pipeline = sharp()
-  .rotate()
-  .resize(null, 200)
-  .toBuffer(function (err, outputBuffer, info) {
-    // outputBuffer contains 200px high JPEG image data,
-    // auto-rotated using EXIF Orientation tag
-    // info.width and info.height contain the dimensions of the resized image
-  });
-readableStream.pipe(pipeline);
-```
 **Example**  
 ```js
 const rotateThenResize = await sharp(input)
@@ -60,6 +45,34 @@ const resizeThenRotate = await sharp(input)
 ```
 
 
+## autoOrient
+> autoOrient() ⇒ <code>Sharp</code>
+
+Auto-orient based on the EXIF `Orientation` tag, then remove the tag.
+Mirroring is supported and may infer the use of a flip operation.
+
+Previous or subsequent use of `rotate(angle)` and either `flip()` or `flop()`
+will logically occur after auto-orientation, regardless of call order.
+
+
+**Example**  
+```js
+const output = await sharp(input).autoOrient().toBuffer();
+```
+**Example**  
+```js
+const pipeline = sharp()
+  .autoOrient()
+  .resize(null, 200)
+  .toBuffer(function (err, outputBuffer, info) {
+    // outputBuffer contains 200px high JPEG image data,
+    // auto-oriented using EXIF Orientation tag
+    // info.width and info.height contain the dimensions of the resized image
+  });
+readableStream.pipe(pipeline);
+```
+
+
 ## flip
 > flip([flip]) ⇒ <code>Sharp</code>
 

docs/changelog.md

@@ -16,6 +16,10 @@ Requires libvips v8.16.0
 
 * Expose WebP `smartDeblock` output option.
 
+* Add `autoOrient` operation and constructor option.
+  [#4151](https://github.com/lovell/sharp/pull/4151)
+  [@happycollision](https://github.com/happycollision)
+
 * TypeScript: Ensure channel counts use the correct range.
   [#4197](https://github.com/lovell/sharp/pull/4197)
   [@DavidVaness](https://github.com/DavidVaness)

docs/humans.txt

@@ -308,3 +308,6 @@ GitHub: https://github.com/sumitd2
 
 Name: Caleb Meredith
 GitHub: https://github.com/calebmer
+
+Name: Don Denton
+GitHub: https://github.com/happycollision