README.md (9147B)
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 8 Package imaging provides basic image processing functions (resize, rotate, crop, brightness/contrast adjustments, etc.). 9 10 All the image processing functions provided by the package accept any image type that implements `image.Image` interface 11 as 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 19 http://godoc.org/github.com/disintegration/imaging 20 21 ## Usage examples 22 23 A 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. 29 dstImage128 := imaging.Resize(srcImage, 128, 128, imaging.Lanczos) 30 31 // Resize srcImage to width = 800px preserving the aspect ratio. 32 dstImage800 := imaging.Resize(srcImage, 800, 0, imaging.Lanczos) 33 34 // Scale down srcImage to fit the 800x600px bounding box. 35 dstImageFit := imaging.Fit(srcImage, 800, 600, imaging.Lanczos) 36 37 // Resize and crop the srcImage to fill the 100x100px area. 38 dstImageFill := imaging.Fill(srcImage, 100, 100, imaging.Center, imaging.Lanczos) 39 ``` 40 41 Imaging 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 49 The 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 53 Original image: 54 55  56 57 The same image resized from 600x400px to 150x100px using different resampling filters. 58 From faster (lower quality) to slower (higher quality): 59 60 Filter | Resize result 61 --------------------------|--------------------------------------------- 62 `imaging.NearestNeighbor` |  63 `imaging.Linear` |  64 `imaging.CatmullRom` |  65 `imaging.Lanczos` |  66 67 68 ### Gaussian Blur 69 70 ```go 71 dstImage := imaging.Blur(srcImage, 0.5) 72 ``` 73 74 Sigma parameter allows to control the strength of the blurring effect. 75 76 Original image | Sigma = 0.5 | Sigma = 1.5 77 -----------------------------------|----------------------------------------|--------------------------------------- 78  |  |  79 80 ### Sharpening 81 82 ```go 83 dstImage := 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 88 Original image | Sigma = 0.5 | Sigma = 1.5 89 -----------------------------------|-------------------------------------------|------------------------------------------ 90  |  |  91 92 ### Gamma correction 93 94 ```go 95 dstImage := imaging.AdjustGamma(srcImage, 0.75) 96 ``` 97 98 Original image | Gamma = 0.75 | Gamma = 1.25 99 -----------------------------------|------------------------------------------|----------------------------------------- 100  |  |  101 102 ### Contrast adjustment 103 104 ```go 105 dstImage := imaging.AdjustContrast(srcImage, 20) 106 ``` 107 108 Original image | Contrast = 15 | Contrast = -15 109 -----------------------------------|--------------------------------------------|------------------------------------------- 110  |  |  111 112 ### Brightness adjustment 113 114 ```go 115 dstImage := imaging.AdjustBrightness(srcImage, 20) 116 ``` 117 118 Original image | Brightness = 10 | Brightness = -10 119 -----------------------------------|----------------------------------------------|--------------------------------------------- 120  |  |  121 122 ### Saturation adjustment 123 124 ```go 125 dstImage := imaging.AdjustSaturation(srcImage, 20) 126 ``` 127 128 Original 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 136 Most probably, the given image contains the EXIF orientation tag. 137 The stadard `image/*` packages do not support loading and saving 138 this kind of information. To fix the issue, try opening images with 139 the `AutoOrientation` decode option. If this option is set to `true`, 140 the image orientation is changed after decoding, according to the 141 orientation tag (if present). Here's the example: 142 143 ```go 144 img, 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) 150 is designed to be a lightweight and simple image manipulation package. 151 It provides basic image processing functions and a few helper functions 152 such as `Open` and `Save`. It consistently returns *image.NRGBA image 153 type (8 bits per channel, RGBA). 154 155 [gift](https://github.com/disintegration/gift) 156 supports more advanced image processing, for example, sRGB/Linear color 157 space conversions. It also supports different output image types 158 (e.g. 16 bits per channel) and provides easy-to-use API for chaining 159 multiple processing steps together. 160 161 ## Example code 162 163 ```go 164 package main 165 166 import ( 167 "image" 168 "image/color" 169 "log" 170 171 "github.com/disintegration/imaging" 172 ) 173 174 func 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 224 Output: 225 226 