mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-22 21:42:50 +02:00
Merge commit '00c4484c7092181729f6f470805bc7d72e8ad17b'
This commit is contained in:
Bjørn Erik Pedersen
@@ -1,16 +1,15 @@
|
||||
---
|
||||
title: "Image Processing"
|
||||
description: "Resize, crop, rotate, filter, and convert images."
|
||||
date: 2018-01-24T13:10:00-05:00
|
||||
categories: ["content management"]
|
||||
title: Image Processing
|
||||
linkTitle: Image Processing
|
||||
description: Resize, crop, rotate, filter, and convert images.
|
||||
categories: [content management]
|
||||
keywords: [resources, images]
|
||||
weight: 4004
|
||||
draft: false
|
||||
toc: true
|
||||
menu:
|
||||
docs:
|
||||
parent: "content-management"
|
||||
weight: 32
|
||||
parent: content-management
|
||||
weight: 90
|
||||
toc: true
|
||||
weight: 90
|
||||
---
|
||||
## Image Resources
|
||||
|
||||
@@ -28,16 +27,6 @@ content/
|
||||
└── sunset.jpg <-- page resource
|
||||
```
|
||||
|
||||
## The Image Resource
|
||||
|
||||
The `image` resource gives you access to image-specific attributes like the picture's `Width` and `Height`, as well as powerful processing methods and filters. More on that below.
|
||||
|
||||
Note that the `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}})
|
||||
|
||||
```go-html-template
|
||||
{{ $image := .Resources.GetMatch "sunset.jpg" }}
|
||||
```
|
||||
|
||||
### Global Resources
|
||||
|
||||
A global resource is a file:
|
||||
@@ -94,10 +83,10 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
|
||||
|
||||
## Image Processing Methods
|
||||
|
||||
The `image` resource implements the `Resize`, `Fit`, `Fill`, `Crop`, `Filter`, and `Exif` methods.
|
||||
The `image` resource implements the [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
|
||||
|
||||
{{% note %}}
|
||||
Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the`Exif` method with the _original_ image to extract Exif metadata from JPEG or TIFF images.
|
||||
Metadata (Exif, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`] method with the _original_ image to extract Exif metadata from JPEG or TIFF images.
|
||||
{{% /note %}}
|
||||
|
||||
### Resize
|
||||
@@ -167,7 +156,7 @@ Sometimes it can be useful to create the filter chain once and then reuse it.
|
||||
|
||||
{{< new-in "0.104.0" >}}
|
||||
|
||||
`.Colors` returns a slice of hex string with the dominant colors in the image using a simple histogram method.
|
||||
`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
|
||||
|
||||
```go-html-template
|
||||
{{ $colors := $image.Colors }}
|
||||
@@ -180,7 +169,7 @@ This method is fast, but if you also scale down your images, it would be good fo
|
||||
|
||||
Provides an [Exif] object containing image metadata.
|
||||
|
||||
You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a `with` statement.
|
||||
You may access Exif data in JPEG and TIFF images. To prevent errors when processing images without Exif data, wrap the access in a [`with`] statement.
|
||||
|
||||
```go-html-template
|
||||
{{ with $image.Exif }}
|
||||
@@ -226,11 +215,11 @@ You may also access Exif fields individually, using the [`lang.FormatNumber`] fu
|
||||
|
||||
## Image Processing Options
|
||||
|
||||
The `Resize`, `Fit`, `Fill`, and `Crop` methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant.
|
||||
The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-separated, case-insensitive list of options. The order of the options within the list is irrelevant.
|
||||
|
||||
### Dimensions
|
||||
|
||||
With the `Resize` method you must specify width, height, or both. The `Fit`, `Fill`, and `Crop` methods require both width and height. All dimensions are in pixels.
|
||||
With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels.
|
||||
|
||||
```go-html-template
|
||||
{{ $image := $image.Resize "600x" }}
|
||||
@@ -265,9 +254,9 @@ In the example above, on the second line, we have reversed width and height to r
|
||||
|
||||
### Anchor
|
||||
|
||||
When using the `Crop` or `Fill` method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
|
||||
When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`,`Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
|
||||
|
||||
The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration](#processing-options).
|
||||
The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration].
|
||||
|
||||
For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird:
|
||||
|
||||
@@ -275,7 +264,7 @@ For example, if you have a 400x200 image with a bird in the upper left quadrant,
|
||||
{{ $image.Crop "200x100 TopLeft" }}
|
||||
```
|
||||
|
||||
If you apply rotation when using the `Crop` or `Fill` method, specify the anchor relative to the rotated image.
|
||||
If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image.
|
||||
|
||||
### Target Format
|
||||
|
||||
@@ -299,7 +288,7 @@ To convert an image without scaling, use the dimensions of the original image:
|
||||
|
||||
Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive.
|
||||
|
||||
The default value is 75. You may override the default value in the [site configuration](#processing-options).
|
||||
The default value is 75. You may override the default value in the [site configuration].
|
||||
|
||||
```go-html-template
|
||||
{{ $image.Resize "600x webp q50" }}
|
||||
@@ -309,7 +298,7 @@ The default value is 75. You may override the default value in the [site configu
|
||||
|
||||
<!-- Specifies a libwebp preset, not a libwebp image hint. -->
|
||||
|
||||
Applicable to WebP images, this option corresponds to a set of pre-defined encoding parameters.
|
||||
Applicable to WebP images, this option corresponds to a set of predefined encoding parameters.
|
||||
|
||||
Value|Example
|
||||
:--|:--
|
||||
@@ -319,7 +308,7 @@ Value|Example
|
||||
`picture`|Indoor photograph such as a portrait
|
||||
`text`|Image that is primarily text
|
||||
|
||||
The default value is `photo`. You may override the default value in the [site configuration](#processing-options).
|
||||
The default value is `photo`. You may override the default value in the [site configuration].
|
||||
|
||||
```go-html-template
|
||||
{{ $image.Resize "600x webp picture" }}
|
||||
@@ -331,7 +320,7 @@ When converting an image from a format that supports transparency (e.g., PNG) to
|
||||
|
||||
Use either a 3-digit or a 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
|
||||
|
||||
The default value is `#ffffff` (white). You may override the default value in the [site configuration](#processing-options).
|
||||
The default value is `#ffffff` (white). You may override the default value in the [site configuration].
|
||||
|
||||
```go-html-template
|
||||
{{ $image.Resize "600x jpg #b31280" }}
|
||||
@@ -350,7 +339,7 @@ Filter|Description
|
||||
`Linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
|
||||
`NearestNeighbor`|Fastest resampling filter, no antialiasing
|
||||
|
||||
The default value is `Box`. You may override the default value in the [site configuration](#processing-options).
|
||||
The default value is `Box`. You may override the default value in the [site configuration].
|
||||
|
||||
```go-html-template
|
||||
{{ $image.Resize "600x400 Lanczos" }}
|
||||
@@ -377,10 +366,10 @@ _The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pe
|
||||
This is the shortcode used to generate the examples above:
|
||||
|
||||
{{< code file="layouts/shortcodes/imgproc.html" >}}
|
||||
{{< readfile file="layouts/shortcodes/imgproc.html" >}}
|
||||
{{< readfile file="layouts/shortcodes/imgproc.html" >}}
|
||||
{{< /code >}}
|
||||
|
||||
Call the shortcode from your markdown like this:
|
||||
Call the shortcode from your Markdown like this:
|
||||
|
||||
```go-html-template
|
||||
{{</* imgproc sunset Resize "300x" /*/>}}
|
||||
@@ -477,3 +466,12 @@ hugo --gc
|
||||
[page bundle]: {{< relref "content-management/page-bundles" >}}
|
||||
[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
|
||||
[time.Format]: {{< relref "functions/dateformat" >}}
|
||||
[`Colors`]: #colors
|
||||
[`Crop`]: #crop
|
||||
[`Exif`]: #exif
|
||||
[`Fill`]: #fill
|
||||
[`Filter`]: #filter
|
||||
[`Fit`]: #fit
|
||||
[`Resize`]: #resize
|
||||
[site configuration]: #processing-options
|
||||
[`with`]: /functions/with/
|
||||
|
||||
Reference in New Issue
Block a user