Refactor: autoOrient() is primary, rotate() is alias

docs/api-operation.md

@@ -1,19 +1,15 @@
 ## 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.
-
-The use of `rotate` without an angle will remove the EXIF `Orientation` tag, if any.
+For backwards compatibility, if no angle is provided, `.autoOrient()` will be called.
 
 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
@@ -36,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)
@@ -64,17 +48,29 @@ const resizeThenRotate = await sharp(input)
 ## autoOrient
 > autoOrient() ⇒ <code>Sharp</code>
 
-Alias for calling `rotate()` with no arguments, which orients the image based
-on EXIF orientsion.
+Auto-orient based on the EXIF `Orientation` tag, then remove the tag.
+Mirroring is supported and may infer the use of a flip operation.
 
-This operation is aliased to emphasize its purpose, helping to remove any
-confusion between rotation and orientation.
+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

lib/operation.js

@@ -18,19 +18,15 @@ const vipsPrecision = {
 };
 
 /**
- * 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.
- *
- * The use of `rotate` without an angle will remove the EXIF `Orientation` tag, if any.
+ * For backwards compatibility, if no angle is provided, `.autoOrient()` will be called.
  *
  * 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
@@ -42,17 +38,6 @@ const vipsPrecision = {
  * for example `.rotate(x).extract(y)` will produce a different result to `.extract(y).rotate(x)`.
  *
  * @example
- * 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
  * const rotateThenResize = await sharp(input)
  *   .rotate(90)
  *   .resize({ width: 16, height: 8, fit: 'fill' })
@@ -69,12 +54,12 @@ const vipsPrecision = {
  * @throws {Error} Invalid parameters
  */
 function rotate (angle, options) {
-  if (this.options.useExifOrientation || this.options.angle || this.options.rotationAngle) {
+  if (!is.defined(angle)) { return this.autoOrient(); }
+
+  if (this.options.angle || this.options.rotationAngle) {
     this.options.debuglog('ignoring previous rotate options');
   }
-  if (!is.defined(angle)) {
-    this.options.useExifOrientation = true;
-  } else if (is.integer(angle) && !(angle % 90)) {
+  if (is.integer(angle) && !(angle % 90)) {
     this.options.angle = angle;
   } else if (is.number(angle)) {
     this.options.rotationAngle = angle;
@@ -94,19 +79,31 @@ function rotate (angle, options) {
 }
 
 /**
- * Alias for calling `rotate()` with no arguments, which orients the image based
- * on EXIF orientsion.
+ * Auto-orient based on the EXIF `Orientation` tag, then remove the tag.
+ * Mirroring is supported and may infer the use of a flip operation.
  *
- * This operation is aliased to emphasize its purpose, helping to remove any
- * confusion between rotation and orientation.
+ * Previous or subsequent use of `rotate(angle)` and either `flip()` or `flop()`
+ * will logically occur after auto-orientation, regardless of call order.
  *
  * @example
  * const output = await sharp(input).autoOrient().toBuffer();
  *
+ * @example
+ * 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);
+ *
  * @returns {Sharp}
  */
 function autoOrient () {
-  return this.rotate();
+  this.options.useExifOrientation = true;
+  return this;
 }
 
 /**

test/unit/rotate.js

@@ -441,9 +441,9 @@ describe('Rotation', function () {
     let warningMessage = '';
     const s = sharp();
     s.on('warning', function (msg) { warningMessage = msg; });
-    s.rotate();
+    s.rotate(90);
     assert.strictEqual(warningMessage, '');
-    s.rotate();
+    s.rotate(180);
     assert.strictEqual(warningMessage, 'ignoring previous rotate options');
   });