README.md
1Resize
2======
3
4Image resizing for the [Go programming language](http://golang.org) with common interpolation methods.
5
6[](https://travis-ci.org/nfnt/resize)
7
8Installation
9------------
10
11```bash
12$ go get github.com/nfnt/resize
13```
14
15It's that easy!
16
17Usage
18-----
19
20This package needs at least Go 1.1. Import package with
21
22```go
23import "github.com/nfnt/resize"
24```
25
26The resize package provides 2 functions:
27
28* `resize.Resize` creates a scaled image with new dimensions (`width`, `height`) using the interpolation function `interp`.
29 If either `width` or `height` is set to 0, it will be set to an aspect ratio preserving value.
30* `resize.Thumbnail` downscales an image preserving its aspect ratio to the maximum dimensions (`maxWidth`, `maxHeight`).
31 It will return the original image if original sizes are smaller than the provided dimensions.
32
33```go
34resize.Resize(width, height uint, img image.Image, interp resize.InterpolationFunction) image.Image
35resize.Thumbnail(maxWidth, maxHeight uint, img image.Image, interp resize.InterpolationFunction) image.Image
36```
37
38The provided interpolation functions are (from fast to slow execution time)
39
40- `NearestNeighbor`: [Nearest-neighbor interpolation](http://en.wikipedia.org/wiki/Nearest-neighbor_interpolation)
41- `Bilinear`: [Bilinear interpolation](http://en.wikipedia.org/wiki/Bilinear_interpolation)
42- `Bicubic`: [Bicubic interpolation](http://en.wikipedia.org/wiki/Bicubic_interpolation)
43- `MitchellNetravali`: [Mitchell-Netravali interpolation](http://dl.acm.org/citation.cfm?id=378514)
44- `Lanczos2`: [Lanczos resampling](http://en.wikipedia.org/wiki/Lanczos_resampling) with a=2
45- `Lanczos3`: [Lanczos resampling](http://en.wikipedia.org/wiki/Lanczos_resampling) with a=3
46
47Which of these methods gives the best results depends on your use case.
48
49Sample usage:
50
51```go
52package main
53
54import (
55 "github.com/nfnt/resize"
56 "image/jpeg"
57 "log"
58 "os"
59)
60
61func main() {
62 // open "test.jpg"
63 file, err := os.Open("test.jpg")
64 if err != nil {
65 log.Fatal(err)
66 }
67
68 // decode jpeg into image.Image
69 img, err := jpeg.Decode(file)
70 if err != nil {
71 log.Fatal(err)
72 }
73 file.Close()
74
75 // resize to width 1000 using Lanczos resampling
76 // and preserve aspect ratio
77 m := resize.Resize(1000, 0, img, resize.Lanczos3)
78
79 out, err := os.Create("test_resized.jpg")
80 if err != nil {
81 log.Fatal(err)
82 }
83 defer out.Close()
84
85 // write new image to file
86 jpeg.Encode(out, m, nil)
87}
88```
89
90Caveats
91-------
92
93* Optimized access routines are used for `image.RGBA`, `image.NRGBA`, `image.RGBA64`, `image.NRGBA64`, `image.YCbCr`, `image.Gray`, and `image.Gray16` types. All other image types are accessed in a generic way that will result in slow processing speed.
94* JPEG images are stored in `image.YCbCr`. This image format stores data in a way that will decrease processing speed. A resize may be up to 2 times slower than with `image.RGBA`.
95
96
97Downsizing Samples
98-------
99
100Downsizing is not as simple as it might look like. Images have to be filtered before they are scaled down, otherwise aliasing might occur.
101Filtering is highly subjective: Applying too much will blur the whole image, too little will make aliasing become apparent.
102Resize tries to provide sane defaults that should suffice in most cases.
103
104### Artificial sample
105
106Original image
107
108
109<table>
110<tr>
111<th><img src="http://nfnt.github.com/img/rings_300_NearestNeighbor.png" /><br>Nearest-Neighbor</th>
112<th><img src="http://nfnt.github.com/img/rings_300_Bilinear.png" /><br>Bilinear</th>
113</tr>
114<tr>
115<th><img src="http://nfnt.github.com/img/rings_300_Bicubic.png" /><br>Bicubic</th>
116<th><img src="http://nfnt.github.com/img/rings_300_MitchellNetravali.png" /><br>Mitchell-Netravali</th>
117</tr>
118<tr>
119<th><img src="http://nfnt.github.com/img/rings_300_Lanczos2.png" /><br>Lanczos2</th>
120<th><img src="http://nfnt.github.com/img/rings_300_Lanczos3.png" /><br>Lanczos3</th>
121</tr>
122</table>
123
124### Real-Life sample
125
126Original image
127
128
129<table>
130<tr>
131<th><img src="http://nfnt.github.com/img/IMG_3694_300_NearestNeighbor.png" /><br>Nearest-Neighbor</th>
132<th><img src="http://nfnt.github.com/img/IMG_3694_300_Bilinear.png" /><br>Bilinear</th>
133</tr>
134<tr>
135<th><img src="http://nfnt.github.com/img/IMG_3694_300_Bicubic.png" /><br>Bicubic</th>
136<th><img src="http://nfnt.github.com/img/IMG_3694_300_MitchellNetravali.png" /><br>Mitchell-Netravali</th>
137</tr>
138<tr>
139<th><img src="http://nfnt.github.com/img/IMG_3694_300_Lanczos2.png" /><br>Lanczos2</th>
140<th><img src="http://nfnt.github.com/img/IMG_3694_300_Lanczos3.png" /><br>Lanczos3</th>
141</tr>
142</table>
143
144
145License
146-------
147
148Copyright (c) 2012 Jan Schlicht <janschlicht@gmail.com>
149Resize is released under a MIT style license.
150
){kind=link}
){kind=link}
){kind=link}
