jpeg-autorotate

A node module to rotate JPEG images based on EXIF orientation.

---

• What does it do
• Installation
• Usage
  • CLI
  • Node module
    • Sample usage
    • Error handling
    • Thumbnail too large
  • Options
• Changelog
• License
• Credits

What does it do

This module applies the right orientation to a JPEG image, based on its EXIF tag. More precisely, it:

• Rotates the pixels
• Rotates the thumbnail, if there is one
• Writes 1 in the Orientation EXIF tag (this is the default orientation)
• Updates the PixelXDimension and PixelYDimension EXIF values
• Does not alter the other EXIF tags

It may be useful, if:

• You need to compress your image with a tool that strips EXIF data without rotating the pixels (like the great ImageOptim)
• You need to upload the image, but the destination application does not support EXIF orientation (like WordPress)
• You just want to get rid of the orientation tag, while leaving the other tags intact

More information about EXIF:

• EXIF Orientation Handling Is a Ghetto
• Standard EXIF Tags

Installation

This module needs Node >=10.

Install with npm:

$ npm install jpeg-autorotate --global
# --global isn't required if you plan to use the node module

Usage

CLI

# Rotates a single image
$ jpeg-autorotate /Users/johan/IMG_1234.jpg
# Rotates a set of images
$ jpeg-autorotate /Users/johan/images/IMG_*.jpg
# Glob support
$ jpeg-autorotate "/Users/johan/images/IMG_*.{jpg,jpeg,JPG,JPEG}"

Node module

The tool is available as a Node module. It will load the image, apply the rotation, and return the binary data as a Buffer, allowing you to:

• Save it on disk
• Load it in an image processing module (like jimp, lwip, gm...)
• ...

Sample usage

const jo = require('jpeg-autorotate')
const options = {quality: 85}
const path = '/Users/johan/IMG_1234.jpg' // You can use a Buffer, too

//
// With a callback:
//
jo.rotate(path, options, (error, buffer, orientation, dimensions, quality) => {
  if (error) {
    console.log('An error occurred when rotating the file: ' + error.message)
    return
  }
  console.log(`Orientation was ${orientation}`)
  console.log(`Dimensions after rotation: ${dimensions.width}x${dimensions.height}`)
  console.log(`Quality: ${quality}`)
  // ...Do whatever you need with the resulting buffer...
})

//
// With a Promise:
//
jo.rotate(path, options)
  .then(({buffer, orientation, dimensions, quality}) => {
    console.log(`Orientation was ${orientation}`)
    console.log(`Dimensions after rotation: ${dimensions.width}x${dimensions.height}`)
    console.log(`Quality: ${quality}`)
    // ...Do whatever you need with the resulting buffer...
  })
  .catch((error) => {
    console.log('An error occurred when rotating the file: ' + error.message)
  })

Error handling

The error object returned by the module contains a readable message, but also a code for better error handling. Available codes are the following:

const jo = require('jpeg-autorotate')

jo.errors.read_file // File could not be opened
jo.errors.read_exif // EXIF data could not be read
jo.errors.no_orientation // No orientation tag was found
jo.errors.unknown_orientation // The orientation tag is unknown
jo.errors.correct_orientation // The image orientation is already correct
jo.errors.rotate_file // An error occurred when rotating the image

Sample usage:

const jo = require('jpeg-autorotate')
jo.rotate('/image.jpg')
  .catch((error) => {
    if (error.code === jo.errors.correct_orientation) {
      console.log('The orientation of this image is already correct!')
    }
  })

Thumbnail too large

If you get the error "Given thumbnail is too large. max 64kB", you can remove the thumbnail before rotating the image:

import piexif from 'piexifjs'

function deleteThumbnailFromExif(imageBuffer) {
  const imageString = imageBuffer.toString('binary')
  const exifObj = piexif.load(imageString)
  delete exifObj.thumbnail
  delete exifObj['1st']
  const exifBytes = piexif.dump(exifObj)
  const newImageString = piexif.insert(exifBytes, imageString)
  return Buffer.from(newImageString, 'binary')
}

Options

The following options are available.

Option	Context	Default value	Description
quality	CLI, module	100	Quality of the JPEG - Uncompressed by default, so the resulting image may be bigger than the original one

To use options with the CLI:

$ jpeg-autorotate /image.jpg --quality=85

Changelog

This project uses semver.

Version	Date	Notes
7.0.0	2020-09-19	Don't publish test and linting files on NPM
6.0.0	2020-05-30	Dependencies update Drop support for Node < 10 From jpeg-js update: images larger than 100 megapixels or requiring more than 512MB of memory to decode will throw
5.0.3	2019-12-24	Fix multiple file support in CLI Dependencies update
5.0.2	2019-09-28	Dependencies update
5.0.1	2019-06-08	Fix CLI support
5.0.0	2019-03-03	Drop --jobs CLI option Drop support for Node 6 & 7 Introduce new quality property in the jo.rotate callback Public API now supports both callbacks and Promises Update documentation accordingly Update dependencies
4.0.1	2018-11-29	Fix rotations 5 and 7 (issue #11)
4.0.0	2018-07-15	Drop support for Node 4 & 5 Unpublish lockfile Use prettier for code formatting Update documentation Update dependencies
3.1.0	2017-12-03	Output dimensions after rotation
3.0.1	2017-07-30	Node 8 support Update dependencies
3.0.0	2017-02-11	CLI supports glob No more node 0.12 support Drop semicolons Add eslint rules
2.0.0	2016-06-03	Supports buffers in entry Returns a buffer even if there was an error Improves tests
1.1.0	2016-04-23	Adds test suite, removes lwip dependency
1.0.3	2016-03-29	Displays help when no path given in CLI
1.0.2	2016-03-21	Adds missing options in CLI help
1.0.1	2016-03-21	Fixes NPM publishing fail ^_^
1.0.0	2016-03-21	Initial version

License

This project is released under the MIT License.

Credits

• piexifjs
• jpeg-js
• exif-orientation-examples
• colors
• yargs
• FontAwesome
• Chai
• Mocha
• eslint
• glob
• prettier
• fs-extra
• pixelmatch
• pngjs