1 | EasyImage [![NPM version](https://badge.fury.io/js/easyimage.svg)](https://badge.fury.io/js/easyimage)
|
2 | =========
|
3 |
|
4 | EasyImage is a promise-based image processing module for Node.js, it is built on top of [ImageMagick](https://www.imagemagick.org/script/download.php), so make
|
5 | sure ImageMagick is installed on your system.
|
6 |
|
7 | ## Installation
|
8 |
|
9 | EasyImage 3 is only compatible with NodeJS 4 or greater.
|
10 |
|
11 | ```
|
12 | $ npm install --save easyimage
|
13 | ```
|
14 |
|
15 | For NodeJS 0.12, use [EasyImage 2](https://github.com/hacksparrow/node-easyimage/tree/v2.2.0)
|
16 |
|
17 | ```
|
18 | $ npm install --save easyimage@2
|
19 | ```
|
20 |
|
21 | ## Quick Start
|
22 |
|
23 | Get info about an image.
|
24 |
|
25 | ```
|
26 | import {info} from "easyimage";
|
27 | try {
|
28 | const imageInfo = await info("/path/to/image.jpg");
|
29 | } catch (e) {
|
30 | console.log("Error: ", e);
|
31 | }
|
32 | ```
|
33 |
|
34 | Convert an image from JPG to PNG.
|
35 |
|
36 | ```
|
37 | import {convert} from "easyimage";
|
38 | try {
|
39 | await convert({
|
40 | src: "/path/to/source.jpg",
|
41 | dst: "/path/to/dest.png",
|
42 | });
|
43 | } catch (e) {
|
44 | console.log("Error: ", e);
|
45 | }
|
46 | ```
|
47 |
|
48 | Create a thumbnail.
|
49 |
|
50 | ```
|
51 | import {thumbnail} from "easyimage";
|
52 | try {
|
53 | const thumbnailInfo = await thumbnail({
|
54 | src: "/path/to/source.jpg",
|
55 | width: 100,
|
56 | height: 100,
|
57 | });
|
58 |
|
59 | console.log("Thumbnail is at: " + thumbnailInfo.path);
|
60 | } catch (e) {
|
61 | console.log("Error: ", e);
|
62 | }
|
63 | ```
|
64 |
|
65 | ## Usage
|
66 |
|
67 | The EasyImage module is ES6 compatible. You can import just the commands that you will need.
|
68 |
|
69 | Every command which takes an options object which extends from [IBaseOptions](https://hacksparrow.github.io/node-easyimage/interfaces/ibaseoptions.html). You can use
|
70 | any of the parameters defined on `IBaseOptions`. For example, to prevent EasyImage from auto-orientating your image, you can pass `autoOrient: false` on any
|
71 | command.
|
72 |
|
73 | Every command must have a `src` parameter. If you do not specify a `dst`, then a random file will be created. Be sure to clean up randomly created files by
|
74 | either moving them to permanent storage, or deleting them. Some commands have other required options.
|
75 |
|
76 | See the [Docs](https://hacksparrow.github.io/node-easyimage/index.html) for all available options for each command.
|
77 |
|
78 | **convert**
|
79 |
|
80 | The [convert()](https://hacksparrow.github.io/node-easyimage/globals.html#convert) command can convert an image file from one type to another.
|
81 |
|
82 | **crop**
|
83 |
|
84 | The [crop()](https://hacksparrow.github.io/node-easyimage/globals.html#crop) command will crop an image to the specified size.
|
85 |
|
86 | **resize**
|
87 |
|
88 | The [resize()](https://hacksparrow.github.io/node-easyimage/globals.html#resize) command will resize an image to the specified size.
|
89 |
|
90 | **rescrop**
|
91 |
|
92 | The [rescrop()](https://hacksparrow.github.io/node-easyimage/globals.html#rescrop) command will resize and crop an image to the specified size.
|
93 |
|
94 | **rotate**
|
95 |
|
96 | The [rotate()](https://hacksparrow.github.io/node-easyimage/globals.html#rotate) command will rotate an image by the specified number of degrees.
|
97 |
|
98 | **thumbnail**
|
99 |
|
100 | The [thumbnail()](https://hacksparrow.github.io/node-easyimage/globals.html#thumbnail) command will create a thumbnail of the specified image.
|
101 |
|
102 |
|
103 | ## Helper Commands
|
104 |
|
105 | In addition to the above commands, there are three other commands available.
|
106 |
|
107 | **info**
|
108 |
|
109 | The [info()](https://hacksparrow.github.io/node-easyimage/globals.html#info) command will give you details about an image file.
|
110 |
|
111 |
|
112 | **execute**
|
113 |
|
114 | The [execute()]() command allows you directly run ImageMagick with your own tool and arguments. It will handle calling the appropriate ImageMagick version, and
|
115 | return the raw `stdout` and `stderr` to you.
|
116 |
|
117 |
|
118 | **getImageMagickVersion**
|
119 |
|
120 | The [getImageMagickVersion()](https://hacksparrow.github.io/node-easyimage/globals.html#getimagemagickversion) command will return the detected version of
|
121 | ImageMagick.
|
122 |
|
123 |
|
124 | ## Error Handling
|
125 |
|
126 | There are 5 different types of errors that can be thrown.
|
127 |
|
128 | - `BadDestinationError`
|
129 | - `ImageMagickMissingError`
|
130 | - `MissingExtensionError`
|
131 | - `MissingOptionsError`
|
132 | - `UnsupportedError`
|
133 |
|
134 | Which allows you to catch specific errors.
|
135 |
|
136 | ```
|
137 | import {convert, MissingOptionsError} from "easyimage";
|
138 |
|
139 | async function shouldError() {
|
140 | try {
|
141 | await convert({});
|
142 | console.log("I should not show");
|
143 | } catch (MissingOptionsError e) {
|
144 | console.log("I should show");
|
145 | } catch (Error e) {
|
146 | console.log("I should not show either");
|
147 | }
|
148 | }
|
149 |
|
150 | ```
|
151 |
|
152 | ## License (MIT)
|
153 |
|
154 | Copyright (c) 2015 Hage Yaapa <[http://www.hacksparrow.com](http://www.hacksparrow.com)>
|
155 |
|
156 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
157 | of this software and associated documentation files (the "Software"), to deal
|
158 | in the Software without restriction, including without limitation the rights
|
159 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
160 | copies of the Software, and to permit persons to whom the Software is
|
161 | furnished to do so, subject to the following conditions:
|
162 |
|
163 | The above copyright notice and this permission notice shall be included in
|
164 | all copies or substantial portions of the Software.
|
165 |
|
166 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
167 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
168 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
169 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
170 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
171 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
172 | SOFTWARE.
|