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