Add autoOrient operation and constructor option #4144

lib/operation.js

@@ -18,22 +18,19 @@ 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.
+ * 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.
  *
@@ -41,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' })
@@ -68,12 +54,15 @@ const vipsPrecision = {
  * @throws {Error} Invalid parameters
  */
 function rotate (angle, options) {
-  if (this.options.useExifOrientation || 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)) {
+    return this.autoOrient();
+  }
+  if (this.options.angle || this.options.rotationAngle) {
+    this.options.debuglog('ignoring previous rotate options');
+    this.options.angle = 0;
+    this.options.rotationAngle = 0;
+  }
+  if (is.integer(angle) && !(angle % 90)) {
     this.options.angle = angle;
   } else if (is.number(angle)) {
     this.options.rotationAngle = angle;
@@ -92,6 +81,34 @@ function rotate (angle, options) {
   return this;
 }
 
+/**
+ * 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
+ * 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 () {
+  this.options.input.autoOrient = true;
+  return this;
+}
+
 /**
  * Mirror the image vertically (up-down) about the x-axis.
  * This always occurs before rotation, if any.
@@ -935,6 +952,7 @@ function modulate (options) {
  */
 module.exports = function (Sharp) {
   Object.assign(Sharp.prototype, {
+    autoOrient,
     rotate,
     flip,
     flop,