README.md
1# Imaging
2
3[](https://godoc.org/github.com/disintegration/imaging)
4[](https://travis-ci.org/disintegration/imaging)
5[](https://coveralls.io/github/disintegration/imaging?branch=master)
6[](https://goreportcard.com/report/github.com/disintegration/imaging)
7
8Package imaging provides basic image processing functions (resize, rotate, crop, brightness/contrast adjustments, etc.).
9
10All the image processing functions provided by the package accept any image type that implements `image.Image` interface
11as an input, and return a new image of `*image.NRGBA` type (32bit RGBA colors, non-premultiplied alpha).
12
13## Installation
14
15 go get -u github.com/disintegration/imaging
16
17## Documentation
18
19http://godoc.org/github.com/disintegration/imaging
20
21## Usage examples
22
23A few usage examples can be found below. See the documentation for the full list of supported functions.
24
25### Image resizing
26
27```go
28// Resize srcImage to size = 128x128px using the Lanczos filter.
29dstImage128 := imaging.Resize(srcImage, 128, 128, imaging.Lanczos)
30
31// Resize srcImage to width = 800px preserving the aspect ratio.
32dstImage800 := imaging.Resize(srcImage, 800, 0, imaging.Lanczos)
33
34// Scale down srcImage to fit the 800x600px bounding box.
35dstImageFit := imaging.Fit(srcImage, 800, 600, imaging.Lanczos)
36
37// Resize and crop the srcImage to fill the 100x100px area.
38dstImageFill := imaging.Fill(srcImage, 100, 100, imaging.Center, imaging.Lanczos)
39```
40
41Imaging supports image resizing using various resampling filters. The most notable ones:
42- `Lanczos` - A high-quality resampling filter for photographic images yielding sharp results.
43- `CatmullRom` - A sharp cubic filter that is faster than Lanczos filter while providing similar results.
44- `MitchellNetravali` - A cubic filter that produces smoother results with less ringing artifacts than CatmullRom.
45- `Linear` - Bilinear resampling filter, produces smooth output. Faster than cubic filters.
46- `Box` - Simple and fast averaging filter appropriate for downscaling. When upscaling it's similar to NearestNeighbor.
47- `NearestNeighbor` - Fastest resampling filter, no antialiasing.
48
49The full list of supported filters: NearestNeighbor, Box, Linear, Hermite, MitchellNetravali, CatmullRom, BSpline, Gaussian, Lanczos, Hann, Hamming, Blackman, Bartlett, Welch, Cosine. Custom filters can be created using ResampleFilter struct.
50
51**Resampling filters comparison**
52
53Original image:
54
55
56
57The same image resized from 600x400px to 150x100px using different resampling filters.
58From faster (lower quality) to slower (higher quality):
59
60Filter | Resize result
61--------------------------|---------------------------------------------
62`imaging.NearestNeighbor` | 
63`imaging.Linear` | 
64`imaging.CatmullRom` | 
65`imaging.Lanczos` | 
66
67
68### Gaussian Blur
69
70```go
71dstImage := imaging.Blur(srcImage, 0.5)
72```
73
74Sigma parameter allows to control the strength of the blurring effect.
75
76Original image | Sigma = 0.5 | Sigma = 1.5
77-----------------------------------|----------------------------------------|---------------------------------------
78 |  | 
79
80### Sharpening
81
82```go
83dstImage := imaging.Sharpen(srcImage, 0.5)
84```
85
86`Sharpen` uses gaussian function internally. Sigma parameter allows to control the strength of the sharpening effect.
87
88Original image | Sigma = 0.5 | Sigma = 1.5
89-----------------------------------|-------------------------------------------|------------------------------------------
90 |  | 
91
92### Gamma correction
93
94```go
95dstImage := imaging.AdjustGamma(srcImage, 0.75)
96```
97
98Original image | Gamma = 0.75 | Gamma = 1.25
99-----------------------------------|------------------------------------------|-----------------------------------------
100 |  | 
101
102### Contrast adjustment
103
104```go
105dstImage := imaging.AdjustContrast(srcImage, 20)
106```
107
108Original image | Contrast = 15 | Contrast = -15
109-----------------------------------|--------------------------------------------|-------------------------------------------
110 |  | 
111
112### Brightness adjustment
113
114```go
115dstImage := imaging.AdjustBrightness(srcImage, 20)
116```
117
118Original image | Brightness = 10 | Brightness = -10
119-----------------------------------|----------------------------------------------|---------------------------------------------
120 |  | 
121
122### Saturation adjustment
123
124```go
125dstImage := imaging.AdjustSaturation(srcImage, 20)
126```
127
128Original image | Saturation = 30 | Saturation = -30
129-----------------------------------|----------------------------------------------|---------------------------------------------
130 |  | 
131
132## FAQ
133
134### Incorrect image orientation after processing (e.g. an image appears rotated after resizing)
135
136Most probably, the given image contains the EXIF orientation tag.
137The stadard `image/*` packages do not support loading and saving
138this kind of information. To fix the issue, try opening images with
139the `AutoOrientation` decode option. If this option is set to `true`,
140the image orientation is changed after decoding, according to the
141orientation tag (if present). Here's the example:
142
143```go
144img, err := imaging.Open("test.jpg", imaging.AutoOrientation(true))
145```
146
147### What's the difference between `imaging` and `gift` packages?
148
149[imaging](https://github.com/disintegration/imaging)
150is designed to be a lightweight and simple image manipulation package.
151It provides basic image processing functions and a few helper functions
152such as `Open` and `Save`. It consistently returns *image.NRGBA image
153type (8 bits per channel, RGBA).
154
155[gift](https://github.com/disintegration/gift)
156supports more advanced image processing, for example, sRGB/Linear color
157space conversions. It also supports different output image types
158(e.g. 16 bits per channel) and provides easy-to-use API for chaining
159multiple processing steps together.
160
161## Example code
162
163```go
164package main
165
166import (
167 "image"
168 "image/color"
169 "log"
170
171 "github.com/disintegration/imaging"
172)
173
174func main() {
175 // Open a test image.
176 src, err := imaging.Open("testdata/flowers.png")
177 if err != nil {
178 log.Fatalf("failed to open image: %v", err)
179 }
180
181 // Crop the original image to 300x300px size using the center anchor.
182 src = imaging.CropAnchor(src, 300, 300, imaging.Center)
183
184 // Resize the cropped image to width = 200px preserving the aspect ratio.
185 src = imaging.Resize(src, 200, 0, imaging.Lanczos)
186
187 // Create a blurred version of the image.
188 img1 := imaging.Blur(src, 5)
189
190 // Create a grayscale version of the image with higher contrast and sharpness.
191 img2 := imaging.Grayscale(src)
192 img2 = imaging.AdjustContrast(img2, 20)
193 img2 = imaging.Sharpen(img2, 2)
194
195 // Create an inverted version of the image.
196 img3 := imaging.Invert(src)
197
198 // Create an embossed version of the image using a convolution filter.
199 img4 := imaging.Convolve3x3(
200 src,
201 [9]float64{
202 -1, -1, 0,
203 -1, 1, 1,
204 0, 1, 1,
205 },
206 nil,
207 )
208
209 // Create a new image and paste the four produced images into it.
210 dst := imaging.New(400, 400, color.NRGBA{0, 0, 0, 0})
211 dst = imaging.Paste(dst, img1, image.Pt(0, 0))
212 dst = imaging.Paste(dst, img2, image.Pt(0, 200))
213 dst = imaging.Paste(dst, img3, image.Pt(200, 0))
214 dst = imaging.Paste(dst, img4, image.Pt(200, 200))
215
216 // Save the resulting image as JPEG.
217 err = imaging.Save(dst, "testdata/out_example.jpg")
218 if err != nil {
219 log.Fatalf("failed to save image: %v", err)
220 }
221}
222```
223
224Output:
225
226
227
){kind=link}
){kind=link}
){kind=link}
