images.Process

Returns an image filter that processes an image according to the given processing specification. This versatile filter supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string. Use this as an argument to the Filter method or the images.Filter function.

{{ with resources.Get "images/original.jpg" }}
  {{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

In the example above, "crop 200x200 TopRight webp q50" is the processing specification.

Processing specification

The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence:

action

Specify one of crop, fill, fit, or resize. This is applicable to the Process method and the images.Process filter. If you specify an action, you must also provide dimensions.

anchor

The focal point of the crop box when cropping or filling an image. Valid options include TopLeft, Top, TopRight, Left, Center, Right, BottomLeft, Bottom, BottomRight, or Smart. This defaults to the anchor parameter in your site configuration. The Smart option identifies the most interesting area of the image based on the smart cropping algorithm implemented in the smartcrop.js library.

background color

The background color of the resulting image. This applies when converting an image with transparency to a format that does not support it, such as when converting from PNG to JPEG, or when rotating an image by a non-orthogonal angle into a non-transparent format. In these cases, this color fills the empty space created as the image extents increase to fit the rotated corners. The value must be an RGB hexadecimal color, defaulting to the bgColor parameter in your site configuration.

compression

New in v0.153.5

The compression method used when encoding an image. Valid options include lossless or lossy. The lossless method is only applicable to WebP images. This defaults to the compression parameter in your site configuration.

dimensions

The dimensions of the resulting image, in pixels. The format is WIDTHxHEIGHT where WIDTH and HEIGHT are whole numbers. When resizing an image, you may specify only the width (such as 600x) or only the height (such as x400) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as 600x400.

format

The format of the resulting image. Valid options include bmp, gif, jpeg, png, tiff, or webp. This defaults to the format of the source image.

hint

The encoding preset used when processing WebP images, equivalent to the -preset flag for the cwebp encoder. Valid options include drawing, icon, photo, picture, or text. This defaults to the hint parameter in your site configuration.

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

quality

The quality of the resulting image, applicable to JPEG and WebP images when using lossy compression. The format is qQUALITY where QUALITY is a whole number between 1 and 100, inclusive. This defaults to the quality parameter in your site configuration.

resampling filter

The filter used to calculate new pixels when resizing, fitting, or filling an image. Common options include box, lanczos, catmullRom, mitchellNetravali, linear, or nearestNeighbor. This defaults to the resampleFilter parameter in your site configuration.

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

Refer to the source documentation for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.

rotation

The number of whole degrees to rotate an image counter-clockwise. The format is rDEGREES where DEGREES is a whole number. Hugo performs rotation before any other transformations, so your target dimensions and any anchor point should refer to the image orientation after rotation. Use r90, r180, or r270 for orthogonal rotations, or arbitrary angles such as r45. To rotate clockwise, use a negative number such as r-45. To automatically rotate an image based on its EXIF orientation tag, use the images.AutoOrient filter instead of manual rotation.

Rotating by non-orthogonal values increases the image extents to fit the rotated corners; the resulting empty space is transparent for formats supporting alpha channels, or filled with a background color. This background color defaults to the bgColor parameter in your site configuration unless you include a background color

Usage

Create a filter:

{{ $filter := images.Process "crop 200x200 TopRight webp q50" }}

Apply the filter using the images.Filter function:

{{ with resources.Get "images/original.jpg" }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

You can also apply the filter using the Filter method on a Resource object:

{{ with resources.Get "images/original.jpg" }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

Example

Original

Processed