hugo/docs/content/en/content-management/image-processing/index.md at c054cba0423fa7e677506fcec67d702486dec01e

github/hugo

Fork 0

mirror of https://github.com/gohugoio/hugo.git synced 2024-11-14 20:37:55 -05:00

Bjørn Erik Pedersen e99eba39e7

Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae'

2024-08-09 15:17:43 +02:00

17 KiB

Raw Blame History

title

description

Image resources

To process an image you must access the file as a page resource, global resource, or remote resource.

Page resource

A page resource is a file within a page bundle. A page bundle is a directory with an index.md or _index.md file at its root.

content/
└── posts/
    └── post-1/           <-- page bundle
        ├── index.md
        └── sunset.jpg    <-- page resource

To access an image as a page resource:

{{ $image := .Resources.Get "sunset.jpg" }}

Global resource

A global resource is a file within the assets directory, or within any directory mounted to the assets directory.

assets/
└── images/
    └── sunset.jpg    <-- global resource

To access an image as a global resource:

{{ $image := resources.Get "images/sunset.jpg" }}

Remote resource

A remote resource is a file on a remote server, accessible via HTTP or HTTPS. To access an image as a remote resource:

{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}

Image rendering

Once you have accessed an image as a resource, render it in your templates using the Permalink, RelPermalink, Width, and Height properties.

Example 1: Throws an error if the resource is not found.

{{ $image := .Resources.GetMatch "sunset.jpg" }}
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">

Example 2: Skips image rendering if the resource is not found.

{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ with $image }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

Example 3: A more concise way to skip image rendering if the resource is not found.

{{ with .Resources.GetMatch "sunset.jpg" }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

Example 4: Skips rendering if there's problem accessing a remote resource.

{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
{{ with resources.GetRemote $u }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ else }}
  {{ errorf "Unable to get remote resource %q" $u }}
{{ end }}

Image processing methods

The image resource implements the Process, 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, PNG, TIFF, and WebP images. {{% /note %}}

Process

{{% note %}} The Process method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See Process filter. {{% /note %}}

Process processes the image with the given specification. The specification can contain an optional action, one of resize, crop, fit or fill. This means that you can use this method instead of Resize, Fit, Fill, or Crop.

See Options for available options.

You can also use this method apply image processing that does not need any scaling, e.g. format conversions:

{{/* Convert the image from JPG to PNG. */}}
{{ $png := $jpg.Process "png" }}

Some more examples:

{{/* Rotate the image 90 degrees counter-clockwise. */}}
{{ $image := $image.Process "r90" }}

{{/* Scaling actions. */}}
{{ $image := $image.Process "resize 600x" }}
{{ $image := $image.Process "crop 600x400" }}
{{ $image := $image.Process "fit 600x400" }}
{{ $image := $image.Process "fill 600x400" }}

Resize

Resize an image to the given width and/or height.

If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.

{{/* Resize to a width of 600px and preserve aspect ratio */}}
{{ $image := $image.Resize "600x" }}

{{/* Resize to a height of 400px and preserve aspect ratio */}}
{{ $image := $image.Resize "x400" }}

{{/* Resize to a width of 600px and a height of 400px */}}
{{ $image := $image.Resize "600x400" }}

Fit

Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.

{{ $image := $image.Fit "600x400" }}

Fill

Crop and resize an image to match the given dimensions. You must provide both width and height. Use the anchor option to change the crop box anchor point.

{{ $image := $image.Fill "600x400" }}

Crop

Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the anchor option to change the crop box anchor point.

{{ $image := $image.Crop "600x400" }}

Filter

Apply one or more filters to an image.

{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

Write this in a more functional style using pipes. Hugo applies the filters in the order given.

{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}

Sometimes it can be useful to create the filter chain once and then reuse it.

{{ $filters := slice  (images.GaussianBlur 6) (images.Pixelate 8) }}
{{ $image1 := $image1.Filter $filters }}
{{ $image2 := $image2.Filter $filters }}

Colors

.Colors returns a slice of hex strings with the dominant colors in the image using a simple histogram method.

{{ $colors := $image.Colors }}

This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image.

EXIF

Provides an EXIF object containing image metadata.

You may access EXIF data in JPEG, PNG, TIFF, and WebP images. To prevent errors when processing images without EXIF data, wrap the access in a with statement.

{{ with $image.Exif }}
  Date: {{ .Date }}
  Lat/Long: {{ .Lat }}/{{ .Long }}
  Tags:
  {{ range $k, $v := .Tags }}
    TAG: {{ $k }}: {{ $v }}
  {{ end }}
{{ end }}

You may also access EXIF fields individually, using the lang.FormatNumber function to format the fields as needed.

{{ with $image.Exif }}
  <ul>
    {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
    {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
    {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
    {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
    {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
    {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
    {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
  </ul>
{{ end }}

EXIF methods

Date: (time.Time) Returns the image creation date/time. Format with the [time.Format]function.

Lat: (float64) Returns the GPS latitude in degrees.
Long: (float64) Returns the GPS longitude in degrees.
Tags: (exif.Tags) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the site configuration.

Image processing options

The Resize, Fit, Fill, and Crop methods accept a space-delimited, 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.

{{ $image := $image.Resize "600x" }}
{{ $image := $image.Resize "x400" }}
{{ $image := $image.Resize "600x400" }}
{{ $image := $image.Fit "600x400" }}
{{ $image := $image.Fill "600x400" }}
{{ $image := $image.Crop "600x400" }}

Rotation

Rotates an image counter-clockwise by the given angle. Hugo performs rotation before scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%:

{{ $image = $image.Resize "200x r90" }}

In the example above, the width represents the desired width after rotation.

To rotate an image without scaling, use the dimensions of the original image:

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

In the example above, on the second line, we have reversed width and height to reflect the desired dimensions after rotation.

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.

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:

{{ $image.Crop "200x100 TopLeft" }}

If you apply rotation when using the Crop or Fill method, specify the anchor relative to the rotated image.

Target format

By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying bmp, gif, jpeg, jpg, png, tif, tiff, or webp.

{{ $image.Resize "600x webp" }}

To convert an image without scaling, use the dimensions of the original image:

{{ with .Resources.GetMatch "sunset.jpg" }}
  {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
  {{ end }}
{{ end }}

Quality

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.

{{ $image.Resize "600x webp q50" }}

Hint

Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the -preset flag for the cwebp encoder.

Value	Example
`drawing`	Hand or line drawing with high-contrast details
`icon`	Small colorful image
`photo`	Outdoor photograph with natural lighting
`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.

{{ $image.Resize "600x webp picture" }}

Background color

When converting an image from a format that supports transparency (e.g., PNG) to a format that does not support transparency (e.g., JPEG), you may specify the background color of the resulting image.

Use either a 3-digit or 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.

{{ $image.Resize "600x jpg #b31280" }}

Resampling filter

You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:

Filter	Description
`Box`	Simple and fast averaging filter appropriate for downscaling
`Lanczos`	High-quality resampling filter for photographic images yielding sharp results
`CatmullRom`	Sharp cubic filter that is faster than the Lanczos filter while providing similar results
`MitchellNetravali`	Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
`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.

{{ $image.Resize "600x400 Lanczos" }}

See github.com/disintegration/imaging for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.

Image processing examples

The photo of the sunset used in the examples below is Copyright Bjørn Erik Pedersen (Creative Commons Attribution-Share Alike 4.0 International license)

This is the shortcode used to generate the examples above:

{{< readfile file=layouts/shortcodes/imgproc.html highlight=go-html-template >}}

Call the shortcode from your Markdown like this:

{{</* imgproc "sunset.jpg" "resize 300x" /*/>}}

{{% note %}} Note the self-closing shortcode syntax above. You may call the imgproc shortcode with or without inner content. {{% /note %}}

Imaging configuration

Processing options

Define an imaging section in your site configuration to set the default image processing options.

anchor: See image processing options: anchor.
bgColor: See image processing options: background color.
hint: See image processing options: hint.
quality: See image processing options: quality.
resampleFilter: See image processing options: resampling filter.

EXIF data

Define an imaging.exif section in your site configuration to control the availability of EXIF data.

{{< code-toggle file=hugo >}} [imaging.exif] includeFields = "" excludeFields = "" disableDate = false disableLatLong = false {{< /code-toggle >}}

disableDate: Hugo extracts the image creation date/time into .Date. Set this to true to disable. Default is false.
disableLatLong: Hugo extracts the GPS latitude and longitude into .Lat and .Long. Set this to true to disable. Default is false.
excludeFields: Regular expression matching the EXIF tags to exclude from the .Tags collection. Default is "".
includeFields: Regular expression matching the EXIF tags to include in the .Tags collection. Default is "". To include all available tags, set this value to ".*".

{{% note %}} To improve performance and decrease cache size, Hugo excludes the following tags: ColorSpace, Contrast, Exif, Exposure[M|P|B], Flash, GPS, JPEG, Metering, Resolution, Saturation, Sensing, Sharp, and WhiteBalance.

To control tag availability, change the excludeFields or includeFields settings as described above. {{% /note %}}

Smart cropping of images

By default, Hugo uses the Smartcrop library when cropping images with the Crop orFill methods. You can set the anchor point manually, but in most cases the Smart option will make a good choice.

Examples using the sunset image from above:

Image processing performance consideration

Hugo caches processed images in the resources directory. If you include this directory in source control, Hugo will not have to regenerate the images in a CI/CD workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.

If you change image processing methods or options, or if you rename or remove images, the resources directory will contain unused images. To remove the unused images, perform garbage collection with:

hugo --gc

17 KiB Raw Blame History