Rotation sugar and more

docs/api-operation.md

@@ -15,8 +15,9 @@ 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.
 
-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.
 
@@ -60,6 +61,22 @@ 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.
+
+This operation is aliased to emphasize its purpose, helping to remove any
+confusion between rotation and orientation.
+
+
+**Example**  
+```js
+const output = await sharp(input).autoOrient().toBuffer();
+```
+
+
 ## flip
 > flip([flip]) ⇒ <code>Sharp</code>
 

docs/humans.txt

@@ -299,3 +299,6 @@ GitHub: https://github.com/project0
 
 Name: Pongsatorn Manusopit
 GitHub: https://github.com/ton11797
+
+Name: Don Denton
+GitHub: https://github.com/happycollision

lib/composite.js

@@ -110,6 +110,7 @@ const blend = {
  * @param {number} [images[].input.text.dpi=72] - the resolution (size) at which to render the text. Does not take effect if `height` is specified.
  * @param {boolean} [images[].input.text.rgba=false] - 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>`.
  * @param {number} [images[].input.text.spacing=0] - text line height in points. Will use the font line height if none is specified.
+ * @param {Boolean} [images[].autoOrient=false] - set to true to use EXIF orientation data, if present, to orient the image.
  * @param {String} [images[].blend='over'] - how to blend this image with the image below.
  * @param {String} [images[].gravity='centre'] - gravity at which to place the overlay.
  * @param {Number} [images[].top] - the pixel offset from the top edge.

lib/constructor.js

@@ -357,6 +357,7 @@ const Sharp = function (input, options) {
     }
   };
   this.options.input = this._createInputDescriptor(input, options, { allowStream: true });
+  this.options.useExifOrientation = !!this.options.input.autoOrient;
   return this;
 };
 Object.setPrototypeOf(Sharp.prototype, stream.Duplex.prototype);

lib/index.d.ts

@@ -364,24 +364,72 @@ declare namespace sharp {
         //#region Operation functions
 
         /**
-         * Rotate the output image by either an explicit angle or auto-orient based on the EXIF Orientation tag.
+         * Rotate the output image by either an explicit angle
+         * or auto-orient based on the EXIF `Orientation` tag.
          *
-         * If an angle is provided, it is converted to a valid positive degree rotation. For example, -450 will produce a 270deg rotation.
+         * If an angle is provided, it 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.
+         * 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.
+         * 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 implies the removal of the EXIF Orientation tag, if any.
+         * The use of `rotate` without an angle will remove the EXIF `Orientation` tag, if any.
          *
-         * Method order is important when both rotating and extracting regions, for example rotate(x).extract(y) will produce a different result to extract(y).rotate(x).
-         * @param angle angle of rotation. (optional, default auto)
-         * @param options if present, is an Object with optional attributes.
+         * 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.
+         *
+         * Method order is important when rotating, resizing and/or extracting regions,
+         * 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' })
+         *   .toBuffer();
+         * const resizeThenRotate = await sharp(input)
+         *   .resize({ width: 16, height: 8, fit: 'fill' })
+         *   .rotate(90)
+         *   .toBuffer();
+         *
+         * @param {number} [angle=auto] angle of rotation.
+         * @param {Object} [options] - if present, is an Object with optional attributes.
+         * @param {string|Object} [options.background="#000000"] parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
+         * @returns {Sharp}
          * @throws {Error} Invalid parameters
-         * @returns A sharp instance that can be used to chain operations
          */
         rotate(angle?: number, options?: RotateOptions): Sharp;
 
+        /**
+         * Alias for calling `rotate()` with no arguments, which orients the image based
+         * on EXIF orientsion.
+         *
+         * This operation is aliased to emphasize its purpose, helping to remove any
+         * confusion between rotation and orientation.
+         *
+         * @example
+         * const output = await sharp(input).autoOrient().toBuffer();
+         *
+         * @returns {Sharp}
+         */
+        autoOrient(): Sharp
+
         /**
          * Flip the image about the vertical Y axis. This always occurs after rotation, if any.
          * The use of flip implies the removal of the EXIF Orientation tag, if any.
@@ -900,6 +948,13 @@ declare namespace sharp {
     }
 
     interface SharpOptions {
+        /**
+         * Auto-orient based on the EXIF `Orientation` tag, if present.
+         * Mirroring is supported and may infer the use of a flip operation.
+         *
+         * Using this option will remove the EXIF `Orientation` tag, if any.
+         */
+        autoOrient?: boolean;
         /**
          *  When to abort processing of invalid pixel data, one of (in order of sensitivity):
          *  'none' (least), 'truncated', 'error' or 'warning' (most), highers level imply lower levels, invalid metadata will always abort. (optional, default 'warning')

lib/input.js

@@ -24,9 +24,9 @@ const align = {
  * @private
  */
 function _inputOptionsFromObject (obj) {
-  const { raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd } = obj;
-  return [raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd].some(is.defined)
-    ? { raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd }
+  const { raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd, autoOrient } = obj;
+  return [raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd, autoOrient].some(is.defined)
+    ? { raw, density, limitInputPixels, ignoreIcc, unlimited, sequentialRead, failOn, failOnError, animated, page, pages, subifd, autoOrient }
     : undefined;
 }
 
@@ -36,6 +36,7 @@ function _inputOptionsFromObject (obj) {
  */
 function _createInputDescriptor (input, inputOptions, containerOptions) {
   const inputDescriptor = {
+    autoOrient: false,
     failOn: 'warning',
     limitInputPixels: Math.pow(0x3FFF, 2),
     ignoreIcc: false,
@@ -93,6 +94,14 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
         throw is.invalidParameterError('failOn', 'one of: none, truncated, error, warning', inputOptions.failOn);
       }
     }
+    // autoOrient
+    if (is.defined(inputOptions.autoOrient)) {
+      if (is.bool(inputOptions.autoOrient)) {
+        inputDescriptor.autoOrient = inputOptions.autoOrient;
+      } else {
+        throw is.invalidParameterError('autoOrient', 'boolean', inputOptions.autoOrient);
+      }
+    }
     // Density
     if (is.defined(inputOptions.density)) {
       if (is.inRange(inputOptions.density, 1, 100000)) {

lib/operation.js

@@ -21,8 +21,9 @@ const is = require('./is');
  *
  * 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.
  *
@@ -81,6 +82,22 @@ function rotate (angle, options) {
   return this;
 }
 
+/**
+ * Alias for calling `rotate()` with no arguments, which orients the image based
+ * on EXIF orientsion.
+ *
+ * This operation is aliased to emphasize its purpose, helping to remove any
+ * confusion between rotation and orientation.
+ *
+ * @example
+ * const output = await sharp(input).autoOrient().toBuffer();
+ *
+ * @returns {Sharp}
+ */
+function autoOrient () {
+  return this.rotate();
+}
+
 /**
  * Mirror the image vertically (up-down) about the x-axis.
  * This always occurs before rotation, if any.
@@ -895,6 +912,7 @@ function modulate (options) {
  */
 module.exports = function (Sharp) {
   Object.assign(Sharp.prototype, {
+    autoOrient,
     rotate,
     flip,
     flop,

src/common.cc

@@ -162,6 +162,8 @@ namespace sharp {
     descriptor->access = AttrAsBool(input, "sequentialRead") ? VIPS_ACCESS_SEQUENTIAL : VIPS_ACCESS_RANDOM;
     // Remove safety features and allow unlimited input
     descriptor->unlimited = AttrAsBool(input, "unlimited");
+    // Use the EXIF orientation to auto orient the image
+    descriptor->autoOrient = AttrAsBool(input, "autoOrient");
     return descriptor;
   }
 

src/common.h

@@ -37,6 +37,7 @@ namespace sharp {
   struct InputDescriptor {  // NOLINT(runtime/indentation_namespace)
     std::string name;
     std::string file;
+    bool autoOrient;
     char *buffer;
     VipsFailOn failOn;
     uint64_t limitInputPixels;
@@ -76,6 +77,7 @@ namespace sharp {
     int textAutofitDpi;
 
     InputDescriptor():
+      autoOrient(false),
       buffer(nullptr),
       failOn(VIPS_FAIL_ON_WARNING),
       limitInputPixels(0x3FFF * 0x3FFF),

src/pipeline.cc

@@ -77,10 +77,10 @@ class PipelineWorker : public Napi::AsyncWorker {
         // Rotate and flip image according to Exif orientation
         std::tie(autoRotation, autoFlip, autoFlop) = CalculateExifRotationAndFlip(sharp::ExifOrientation(image));
         image = sharp::RemoveExifOrientation(image);
-      } else {
-        rotation = CalculateAngleRotation(baton->angle);
       }
 
+      rotation = CalculateAngleRotation(baton->angle);
+
       // Rotate pre-extract
       bool const shouldRotateBefore = baton->rotateBeforePreExtract &&
         (rotation != VIPS_ANGLE_D0 || autoRotation != VIPS_ANGLE_D0 ||
@@ -102,18 +102,14 @@ class PipelineWorker : public Napi::AsyncWorker {
           image = image.rot(autoRotation);
           autoRotation = VIPS_ANGLE_D0;
         }
-        if (autoFlip) {
+        if (autoFlip != baton->flip) {
           image = image.flip(VIPS_DIRECTION_VERTICAL);
           autoFlip = false;
-        } else if (baton->flip) {
-          image = image.flip(VIPS_DIRECTION_VERTICAL);
           baton->flip = false;
         }
-        if (autoFlop) {
+        if (autoFlop != baton->flop) {
           image = image.flip(VIPS_DIRECTION_HORIZONTAL);
           autoFlop = false;
-        } else if (baton->flop) {
-          image = image.flip(VIPS_DIRECTION_HORIZONTAL);
           baton->flop = false;
         }
         if (rotation != VIPS_ANGLE_D0) {
@@ -405,11 +401,11 @@ class PipelineWorker : public Napi::AsyncWorker {
         image = image.rot(autoRotation);
       }
       // Mirror vertically (up-down) about the x-axis
-      if (baton->flip || autoFlip) {
+      if (baton->flip != autoFlip) {
         image = image.flip(VIPS_DIRECTION_VERTICAL);
       }
       // Mirror horizontally (left-right) about the y-axis
-      if (baton->flop || autoFlop) {
+      if (baton->flop != autoFlop) {
         image = image.flip(VIPS_DIRECTION_HORIZONTAL);
       }
       // Rotate post-extract 90-angle
@@ -640,6 +636,32 @@ class PipelineWorker : public Napi::AsyncWorker {
           composite->input->access = access;
           std::tie(compositeImage, compositeImageType) = sharp::OpenInput(composite->input);
           compositeImage = sharp::EnsureColourspace(compositeImage, baton->colourspacePipeline);
+
+          if (composite->input->autoOrient) {
+            // Calculate angle of rotation
+            VipsAngle compositeAutoRotation = VIPS_ANGLE_D0;
+            bool compositeAutoFlip = false;
+            bool compositeAutoFlop = false;
+
+            // Rotate and flip image according to Exif orientation
+            std::tie(compositeAutoRotation, compositeAutoFlip, compositeAutoFlop) =
+              CalculateExifRotationAndFlip(sharp::ExifOrientation(compositeImage));
+
+            compositeImage = sharp::RemoveExifOrientation(compositeImage);
+
+            if (compositeAutoRotation != VIPS_ANGLE_D0) {
+              compositeImage = compositeImage.rot(compositeAutoRotation);
+            }
+            // Mirror vertically (up-down) about the x-axis
+            if (compositeAutoFlip) {
+              compositeImage = compositeImage.flip(VIPS_DIRECTION_VERTICAL);
+            }
+            // Mirror horizontally (left-right) about the y-axis
+            if (compositeAutoFlop) {
+              compositeImage = compositeImage.flip(VIPS_DIRECTION_HORIZONTAL);
+            }
+          }
+
           // Verify within current dimensions
           if (compositeImage.width() > image.width() || compositeImage.height() > image.height()) {
             throw vips::VError("Image to composite must have same dimensions or smaller");

test/unit/composite.js

@@ -138,6 +138,21 @@ describe('composite', () => {
     fixtures.assertMaxColourDistance(actual, expected);
   });
 
+  it('autoOrient', (done) => {
+    const filename = 'composite-autoOrient.jpg';
+    const exifImg = fixtures.inputJpgWithExif;
+    const actual = fixtures.path(`output.${filename}`);
+    const expected = fixtures.expected(filename);
+    sharp({ create: { width: 600, height: 600, channels: 4, background: { ...red, alpha: 1 } } })
+      .composite([{
+        input: exifImg,
+        autoOrient: true
+      }])
+      .toFile(actual).then(() => {
+        fixtures.assertSimilar(actual, expected, done);
+      });
+  });
+
   it('zero offset', done => {
     sharp(fixtures.inputJpg)
       .resize(80)