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 theOrientation
EXIF tag (this is the default orientation) - Updates the
PixelXDimension
andPixelYDimension
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 >=14
.
Install with npm:
$ npm install jpeg-autorotate --global
# --global isn't required if you plan to use the node module
Usage
Options
Option | Default value | Description |
---|---|---|
quality |
100 |
Quality of the JPEG. Uncompressed by default, so the resulting image may be bigger than the original one. |
jpegjsMaxResolutionInMP |
jpeg-js default |
maxResolutionInMP option in jpeg-js (doc) |
jpegjsMaxMemoryUsageInMB |
jpeg-js default |
maxMemoryUsageInMB option in jpeg-js (doc) |
CLI
Rotate a single image:
$ jpeg-autorotate /Users/johan/IMG_1234.jpg
Rotate a set of images:
$ jpeg-autorotate /Users/johan/images/IMG_*.jpg
Glob support:
$ jpeg-autorotate "/Users/johan/images/IMG_*.{jpg,jpeg,JPG,JPEG}"
Passing options:
$ jpeg-autorotate /Users/johan/IMG_1234.jpg --quality=85 --jpegjsMaxResolutionInMP=1234
Node module
The Node module will load the image, apply the rotation, and return the binary data as a Buffer, allowing you to:
Sample usage
const jo = require('jpeg-autorotate')
const options = {
quality: 8,
jpegjsMaxResolutionInMP: 1234,
}
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
Example:
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!')
}
})
Troubleshooting
Thumbnail too large
The piexifjs module has a 64kb limit when reading thumbnails. If you get the Given thumbnail is too large error, you can try to remove the thumbnail from the image before rotating it:
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)
return Buffer.from(piexif.insert(exifBytes, imageString), 'binary')
}
Changelog
This project uses semver.
Version | Date | Notes |
---|---|---|
9.0.0 |
2023-02-11 | Drop Node 12 support |
8.0.1 |
2022-01-10 | Remove colors package from dependencies |
8.0.0 |
2021-11-12 | Node 16 support Drop support for Node 10 |
7.1.1 |
2020-10-11 | Introduce code coverage Fix an error if options are not passed |
7.1.0 |
2020-10-10 | Introduce jpegjsMaxResolutionInMP & jpegjsMaxMemoryUsageInMB options (#26) |
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 optionDrop support for Node 6 & 7 Introduce new quality property in the jo.rotate callbackPublic 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 supportDrop 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.
Contributing
Bug reports and feature requests are welcome! More details in the contribution guidelines.