1 | ![Version](https://img.shields.io/npm/v/jpeg-autorotate.svg)
|
2 | [![Build Status](https://travis-ci.org/johansatge/jpeg-autorotate.svg?branch=master)](https://travis-ci.org/johansatge/jpeg-autorotate)
|
3 | ![Downloads](https://img.shields.io/npm/dm/jpeg-autorotate.svg)
|
4 | ![Dependencies](https://img.shields.io/david/johansatge/jpeg-autorotate.svg)
|
5 | ![devDependencies](https://img.shields.io/david/dev/johansatge/jpeg-autorotate.svg)
|
6 |
|
7 | ![Icon](icon.png)
|
8 |
|
9 | > Rotates JPEG images based on EXIF orientation.
|
10 |
|
11 | ---
|
12 |
|
13 | * [What does it do](#what-does-it-do)
|
14 | * [Installation](#installation)
|
15 | * [Usage](#usage)
|
16 | * [CLI](#cli)
|
17 | * [Node module](#node-module)
|
18 | * [Sample usage](#sample-usage)
|
19 | * [Error handling](#error-handling)
|
20 | * [Options](#options)
|
21 | * [Changelog](#changelog)
|
22 | * [License](#license)
|
23 | * [Credits](#credits)
|
24 |
|
25 | ## What does it do
|
26 |
|
27 | This tool applies the right orientation to a JPEG image, based on its EXIF tag. More precisely, it:
|
28 |
|
29 | * Rotates the pixels
|
30 | * Rotates the thumbnail, if there is one
|
31 | * Writes `1` in the `Orientation` EXIF tag (this is the default orientation)
|
32 | * Updates the `PixelXDimension` and `PixelYDimension` EXIF values
|
33 | * Does **not** alter the other EXIF tags
|
34 |
|
35 | It may be useful, if:
|
36 |
|
37 | * You need to compress your image with a tool that strips EXIF data without rotating the pixels (like the great [ImageOptim](https://imageoptim.com/))
|
38 | * You need to upload the image, but the destination application does not support EXIF orientation (like [WordPress](https://wordpress.org/))
|
39 | * You just want to get rid of the orientation tag, while leaving the other tags **intact**
|
40 |
|
41 | > More information about EXIF:
|
42 | > * [EXIF Orientation Handling Is a Ghetto](http://www.daveperrett.com/articles/2012/07/28/exif-orientation-handling-is-a-ghetto/)
|
43 | > * [Standard EXIF Tags](http://www.exiv2.org/tags.html)
|
44 |
|
45 | ## Installation
|
46 |
|
47 | Install with [npm](https://www.npmjs.com/):
|
48 |
|
49 | ```bash
|
50 | $ npm install jpeg-autorotate --global
|
51 | # --global isn't required if you plan to use the node module
|
52 | ```
|
53 |
|
54 | ## Usage
|
55 |
|
56 | ### CLI
|
57 |
|
58 | ```bash
|
59 | # Rotates a single image
|
60 | $ jpeg-autorotate /Users/johan/IMG_1234.jpg
|
61 | # Rotates a set of images
|
62 | $ jpeg-autorotate /Users/johan/images/IMG_*.jpg
|
63 | # Glob support
|
64 | $ jpeg-autorotate "/Users/johan/images/IMG_*.{jpg,jpeg,JPG,JPEG}"
|
65 | ```
|
66 |
|
67 | ### Node module
|
68 |
|
69 | The tool is available as a Node module. It will load the image, apply the rotation, and return the binary data as a [Buffer](https://nodejs.org/api/buffer.html), allowing you to:
|
70 |
|
71 | * Save it on disk
|
72 | * Load it in an image processing module (like [jimp](https://github.com/oliver-moran/jimp), [lwip](https://github.com/EyalAr/lwip), [gm](https://github.com/aheckmann/gm)...)
|
73 | * ...
|
74 |
|
75 | #### Sample usage
|
76 |
|
77 | ```javascript
|
78 | var jo = require('jpeg-autorotate');
|
79 | var options = {quality: 85};
|
80 | var path = '/Users/johan/IMG_1234.jpg'; // You can use a Buffer, too
|
81 | jo.rotate(path, options, function(error, buffer, orientation, dimensions)
|
82 | {
|
83 | if (error)
|
84 | {
|
85 | console.log('An error occurred when rotating the file: ' + error.message);
|
86 | return;
|
87 | }
|
88 | console.log('Orientation was: ' + orientation);
|
89 | console.log('Height after rotation: ' + dimensions.height);
|
90 | console.log('Width after rotation: ' + dimensions.width);
|
91 | // ...
|
92 | // Do whatever you need with the resulting buffer
|
93 | // ...
|
94 | });
|
95 | ```
|
96 |
|
97 | #### Error handling
|
98 |
|
99 | The `error` object returned in the callback contains a readable `message`, but also a `code` for better error handling. Available codes are the following:
|
100 |
|
101 | ```javascript
|
102 | var jo = require('jpeg-autorotate');
|
103 |
|
104 | jo.errors.read_file; // File could not be opened
|
105 | jo.errors.read_exif; // EXIF data could not be read
|
106 | jo.errors.no_orientation; // No orientation tag was found
|
107 | jo.errors.unknown_orientation; // The orientation tag is unknown
|
108 | jo.errors.correct_orientation; // The image orientation is already correct
|
109 | jo.errors.rotate_file; // An error occurred when rotating the image
|
110 | ```
|
111 |
|
112 | Sample usage:
|
113 |
|
114 | ```javascript
|
115 | var jo = require('jpeg-autorotate');
|
116 | jo.rotate('/image.jpg', function(error, buffer, orientation)
|
117 | {
|
118 | if (error && error.code === jo.errors.correct_orientation)
|
119 | {
|
120 | console.log('The orientation of this image is already correct!');
|
121 | }
|
122 | });
|
123 | ```
|
124 |
|
125 | ### Options
|
126 |
|
127 | The following options are available.
|
128 |
|
129 | | Option | Context | Default value | Description
|
130 | | --- | --- | --- | --- |
|
131 | | `quality` | *CLI, module* | 100 | Quality of the JPEG - Uncompressed by default, so the resulting image may be bigger than the original one |
|
132 | | `jobs` | *CLI* | 10 | Max number of concurrent processes, when loading several images
|
133 |
|
134 | To use options with the CLI:
|
135 |
|
136 | ```
|
137 | $ jpeg-autorotate /image.jpg --jobs=100 --quality=85
|
138 | ```
|
139 |
|
140 | ## Changelog
|
141 |
|
142 | This project uses [semver](http://semver.org/).
|
143 |
|
144 | | Version | Date | Notes |
|
145 | | --- | --- | --- |
|
146 | | `3.1.0` | 2017-12-03 | Output dimensions after rotation (@tayler) |
|
147 | | `3.0.1` | 2017-07-30 | Node 8 support<br>Update dependencies |
|
148 | | `3.0.0` | 2017-02-11 | CLI supports `glob`<br>No more `node 0.12` support<br>Drop semicolons<br>Add eslint rules |
|
149 | | `2.0.0` | 2016-06-03 | Supports buffers in entry<br>Returns a buffer even if there was an error<br>Improves tests |
|
150 | | `1.1.0` | 2016-04-23 | Adds test suite, removes lwip dependency |
|
151 | | `1.0.3` | 2016-03-29 | Displays help when no path given in CLI |
|
152 | | `1.0.2` | 2016-03-21 | Adds missing options in CLI help |
|
153 | | `1.0.1` | 2016-03-21 | Fixes NPM publishing fail ^_^ |
|
154 | | `1.0.0` | 2016-03-21 | Initial version |
|
155 |
|
156 | ## License
|
157 |
|
158 | This project is released under the [MIT License](license.md).
|
159 |
|
160 | ## Credits
|
161 |
|
162 | * [piexifjs](https://github.com/hMatoba/piexifjs)
|
163 | * [jpeg-js](https://github.com/eugeneware/jpeg-js)
|
164 | * [exif-orientation-examples](https://github.com/recurser/exif-orientation-examples)
|
165 | * [async](https://github.com/caolan/async)
|
166 | * [colors](https://github.com/Marak/colors.js)
|
167 | * [yargs](https://github.com/bcoe/yargs)
|
168 | * [FontAwesome](http://fontawesome.io/)
|
169 | * [Chai](http://chaijs.com/)
|
170 | * [Mocha](http://mochajs.org)
|
171 | * [eslint](http://eslint.org)
|
172 | * [glob](https://github.com/isaacs/node-glob)
|