Skip to content
A node module to rotate JPEG images based on EXIF orientation.
JavaScript
Branch: master
Clone or download
Latest commit 1e9bfb9 Sep 28, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Fix CLI & test resulting buffer in CLI unit tests Jun 7, 2019
test More readable tests Jun 7, 2019
.eslintignore Refactor internal code to use promises Mar 3, 2019
.eslintrc.js Refactor internal code to use promises Mar 3, 2019
.gitignore Introduce visual testing Dec 2, 2018
.travis.yml
icon.png Initial, raw code Mar 20, 2016
license.md Initial, raw code Mar 20, 2016
package.json 5.0.2 Sep 28, 2019
readme.md Add pngjs in credits Sep 28, 2019

readme.md

Version Build Status Downloads Dependencies devDependencies

Icon

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


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:

Installation

This module needs Node >=8.

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
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 (@tayler)
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

You can’t perform that action at this time.