git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/imaging/README.md (about) 1 # Imaging 2 3 [](https://pkg.go.dev/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 https://pkg.go.dev/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 ### Hue adjustment 133 134 ```go 135 dstImage := imaging.AdjustHue(srcImage, 20) 136 ``` 137 138 Original image | Hue = 60 | Hue = -60 139 -----------------------------------|----------------------------------------------|--------------------------------------------- 140  |  |  141 142 ## FAQ 143 144 ### Incorrect image orientation after processing (e.g. an image appears rotated after resizing) 145 146 Most probably, the given image contains the EXIF orientation tag. 147 The standard `image/*` packages do not support loading and saving 148 this kind of information. To fix the issue, try opening images with 149 the `AutoOrientation` decode option. If this option is set to `true`, 150 the image orientation is changed after decoding, according to the 151 orientation tag (if present). Here's the example: 152 153 ```go 154 img, err := imaging.Open("test.jpg", imaging.AutoOrientation(true)) 155 ``` 156 157 ### What's the difference between `imaging` and `gift` packages? 158 159 [imaging](https://github.com/disintegration/imaging) 160 is designed to be a lightweight and simple image manipulation package. 161 It provides basic image processing functions and a few helper functions 162 such as `Open` and `Save`. It consistently returns *image.NRGBA image 163 type (8 bits per channel, RGBA). 164 165 [gift](https://github.com/disintegration/gift) 166 supports more advanced image processing, for example, sRGB/Linear color 167 space conversions. It also supports different output image types 168 (e.g. 16 bits per channel) and provides easy-to-use API for chaining 169 multiple processing steps together. 170 171 ## Example code 172 173 ```go 174 package main 175 176 import ( 177 "image" 178 "image/color" 179 "log" 180 181 "github.com/disintegration/imaging" 182 ) 183 184 func main() { 185 // Open a test image. 186 src, err := imaging.Open("testdata/flowers.png") 187 if err != nil { 188 log.Fatalf("failed to open image: %v", err) 189 } 190 191 // Crop the original image to 300x300px size using the center anchor. 192 src = imaging.CropAnchor(src, 300, 300, imaging.Center) 193 194 // Resize the cropped image to width = 200px preserving the aspect ratio. 195 src = imaging.Resize(src, 200, 0, imaging.Lanczos) 196 197 // Create a blurred version of the image. 198 img1 := imaging.Blur(src, 5) 199 200 // Create a grayscale version of the image with higher contrast and sharpness. 201 img2 := imaging.Grayscale(src) 202 img2 = imaging.AdjustContrast(img2, 20) 203 img2 = imaging.Sharpen(img2, 2) 204 205 // Create an inverted version of the image. 206 img3 := imaging.Invert(src) 207 208 // Create an embossed version of the image using a convolution filter. 209 img4 := imaging.Convolve3x3( 210 src, 211 [9]float64{ 212 -1, -1, 0, 213 -1, 1, 1, 214 0, 1, 1, 215 }, 216 nil, 217 ) 218 219 // Create a new image and paste the four produced images into it. 220 dst := imaging.New(400, 400, color.NRGBA{0, 0, 0, 0}) 221 dst = imaging.Paste(dst, img1, image.Pt(0, 0)) 222 dst = imaging.Paste(dst, img2, image.Pt(0, 200)) 223 dst = imaging.Paste(dst, img3, image.Pt(200, 0)) 224 dst = imaging.Paste(dst, img4, image.Pt(200, 200)) 225 226 // Save the resulting image as JPEG. 227 err = imaging.Save(dst, "testdata/out_example.jpg") 228 if err != nil { 229 log.Fatalf("failed to save image: %v", err) 230 } 231 } 232 ``` 233 234 Output: 235 236 