jpeg-autorotate
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/jpeg-autorotate package

    7.1.1 • Public • Published

    Version Downloads Last commit Build Status Coverage Install size

    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 >=10.

    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:

    • 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: 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
    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 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

    Install

    npm i jpeg-autorotate

    DownloadsWeekly Downloads

    17,886

    Version

    7.1.1

    License

    MIT

    Unpacked Size

    22.3 kB

    Total Files

    7

    Last publish

    Collaborators

    • avatar