github.com/jbramsden/hugo@v0.47.1/docs/content/en/content-management/image-processing/index.md (about) 1 --- 2 title: "Image Processing" 3 description: "Image Page resources can be resized and cropped." 4 date: 2018-01-24T13:10:00-05:00 5 lastmod: 2018-01-26T15:59:07-05:00 6 linktitle: "Image Processing" 7 categories: ["content management"] 8 keywords: [bundle,content,resources,images] 9 weight: 4004 10 draft: false 11 toc: true 12 menu: 13 docs: 14 parent: "content-management" 15 weight: 32 16 --- 17 18 ## The Image Page Resource 19 20 The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder. 21 22 23 To get all images in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}): 24 25 26 ```go-html-template 27 {{ with .Resources.ByType "image" }} 28 {{ end }} 29 30 ``` 31 32 ## Image Processing Methods 33 34 35 The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. 36 37 Resize 38 : Resizes the image to the specified width and height. 39 40 ```go 41 // Resize to a width of 600px and preserve ratio 42 {{ $image := $resource.Resize "600x" }} 43 44 // Resize to a height of 400px and preserve ratio 45 {{ $image := $resource.Resize "x400" }} 46 47 // Resize to a width 600px and a height of 400px 48 {{ $image := $resource.Resize "600x400" }} 49 ``` 50 51 Fit 52 : Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. 53 54 ```go 55 {{ $image := $resource.Fit "600x400" }} 56 ``` 57 58 Fill 59 : Resize and crop the image to match the given dimensions. Both height and width are required. 60 61 ```go 62 {{ $image := $resource.Fill "600x400" }} 63 ``` 64 65 66 {{% note %}} 67 Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. 68 {{% /note %}} 69 70 71 ## Image Processing Options 72 73 In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. 74 75 76 JPEG Quality 77 : Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. 78 79 ```go 80 {{ $image.Resize "600x q50" }} 81 ``` 82 83 Rotate 84 : Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. 85 86 ```go 87 {{ $image.Resize "600x r90" }} 88 ``` 89 90 Anchor 91 : Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. 92 Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. 93 94 ```go 95 {{ $image.Fill "300x200 BottomLeft" }} 96 ``` 97 98 Resample Filter 99 : Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. 100 101 Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. 102 103 See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. 104 105 ```go 106 {{ $image.Resize "600x400 Gaussian" }} 107 ``` 108 109 ## Image Processing Examples 110 111 _The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ 112 113 114 {{< imgproc sunset Resize "300x" />}} 115 116 {{< imgproc sunset Fill "90x120 left" />}} 117 118 {{< imgproc sunset Fill "90x120 right" />}} 119 120 {{< imgproc sunset Fit "90x90" />}} 121 122 {{< imgproc sunset Resize "300x q10" />}} 123 124 125 This is the shortcode used in the examples above: 126 127 128 {{< code file="layouts/shortcodes/imgproc.html" >}} 129 {{< readfile file="layouts/shortcodes/imgproc.html" >}} 130 {{< /code >}} 131 132 And it is used like this: 133 134 ```go-html-template 135 {{</* imgproc sunset Resize "300x" /*/>}} 136 ``` 137 138 139 {{% note %}} 140 **Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**. 141 {{% /note %}} 142 143 ## Image Processing Config 144 145 You can configure an `imaging` section in `config.toml` with default image processing options: 146 147 ```toml 148 [imaging] 149 # Default resample filter used for resizing. Default is Box, 150 # a simple and fast averaging filter appropriate for downscaling. 151 # See https://github.com/disintegration/imaging 152 resampleFilter = "box" 153 154 # Defatult JPEG quality setting. Default is 75. 155 quality = 75 156 157 # Anchor used when cropping pictures. 158 # Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop 159 # Smart Cropping is content aware and tries to find the best crop for each image. 160 # Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight 161 anchor = "smart" 162 163 ``` 164 165 All of the above settings can also be set per image procecssing. 166 167 ## Smart Cropping of Images 168 169 By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. 170 171 An example using the sunset image from above: 172 173 174 {{< imgproc sunset Fill "200x200 smart" />}} 175 176 177 ## Image Processing Performance Consideration 178 179 Processed images are stored below `<project-dir>/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. 180 181 If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. 182 183 To clean up, run: 184 185 ```bash 186 hugo --gc 187 ``` 188 189 190 {{% note %}} 191 **GC** is short for **Garbage Collection**. 192 {{% /note %}} 193 194 195