Image filters

See images.Filter for how to apply these filters to an image.

Process

Syntax

images.Process SRC SPEC

A general purpose image processing function.

This filter has all the same options as the Process method, but using it as a filter may be more effective if you need to apply multiple filters to an image:

{{ $filters := slice 
  images.Grayscale
  (images.GaussianBlur 8)
  (images.Process "resize 200x jpg q30") 
}}
{{ $img = $img | images.Filter $filters }}

Overlay

Syntax

images.Overlay SRC X Y

Overlay creates a filter that overlays the source image at position x y, e.g:

{{ $logoFilter := (images.Overlay $logo 50 50 ) }}
{{ $img := $img | images.Filter $logoFilter }}

A shorter version of the above, if you only need to apply the filter once:

{{ $img := $img.Filter (images.Overlay $logo 50 50 )}}

The above will overlay $logo in the upper left corner of $img (at position x=50, y=50).

Opacity

Syntax

images.Opacity SRC OPACITY

Opacity creates a filter that changes the opacity of an image. The OPACITY parameter must be in range (0, 1).

{{ $img := $img.Filter (images.Opacity 0.5 )}}

This filter is most useful for target formats that support transparency, e.g. PNG. If the source image is e.g. JPG, the most effective way would be to combine it with the Process filter:

{{ $png := $jpg.Filter 
  (images.Opacity 0.5)
  (images.Process "png") 
}}

Text

Using the Text filter, you can add text to an image.

Syntax

images.Text TEXT MAP)

The following example will add the text Hugo rocks! to the image with the specified color, size and position.

{{ $img := resources.Get "/images/background.png" }}
{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict
    "color" "#ffffff"
    "size" 60
    "linespacing" 2
    "x" 10
    "y" 20
))}}

You can load a custom font if needed. Load the font as a Hugo Resource and set it as an option:

{{ $font := resources.GetRemote "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }}
{{ $img := resources.Get "/images/background.png" }}
{{ $img = $img.Filter (images.Text "Hugo rocks!" (dict
    "font" $font
))}}

Padding

Padding creates a filter that resizes the image canvas without resizing the image. The last argument is the canvas color, expressed as an RGB or RGBA hexadecimal color. The default value is ffffffff (opaque white). The preceding arguments are the padding values, in pixels, using the CSS shorthand property syntax. Negative padding values will crop the image.

This example resizes the image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity.

{{ $img := resources.Get "images/a.jpg" }}
{{ $filters := slice
  (images.Process "resize 300x webp")
  (images.Padding 20 50 "#0705")
}}
{{ $img = $img.Filter $filters }}

To add a 2px gray border to an image:

{{ $img = $img.Filter (images.Padding 2 "#777") }}

Brightness

Syntax

images.Brightness PERCENTAGE

Brightness creates a filter that changes the brightness of an image. The percentage parameter must be in range (-100, 100).

ColorBalance

Syntax

images.ColorBalance PERCENTAGERED PERCENTAGEGREEN PERCENTAGEBLUE

ColorBalance creates a filter that changes the color balance of an image. The percentage parameters for each color channel (red, green, blue) must be in range (-100, 500).

Colorize

Syntax

images.Colorize HUE SATURATION PERCENTAGE

Colorize creates a filter that produces a colorized version of an image. The hue parameter is the angle on the color wheel, typically in range (0, 360). The saturation parameter must be in range (0, 100). The percentage parameter specifies the strength of the effect, it must be in range (0, 100).

Contrast

Syntax

images.Contrast PERCENTAGE

Contrast creates a filter that changes the contrast of an image. The percentage parameter must be in range (-100, 100).

Gamma

Syntax

images.Gamma GAMMA

Gamma creates a filter that performs a gamma correction on an image. The gamma parameter must be positive. Gamma = 1 gives the original image. Gamma less than 1 darkens the image and gamma greater than 1 lightens it.

GaussianBlur

Syntax

images.GaussianBlur SIGMA

GaussianBlur creates a filter that applies a gaussian blur to an image.

Grayscale

Syntax

images.Grayscale

Grayscale creates a filter that produces a grayscale version of an image.

Hue

Syntax

images.Hue SHIFT

Hue creates a filter that rotates the hue of an image. The hue angle shift is typically in range -180 to 180.

Invert

Syntax

images.Invert

Invert creates a filter that negates the colors of an image.

Pixelate

Syntax

images.Pixelate SIZE

Pixelate creates a filter that applies a pixelation effect to an image.

Saturation

Syntax

images.Saturation PERCENTAGE

Saturation creates a filter that changes the saturation of an image.

Sepia

Syntax

images.Sepia PERCENTAGE

Sepia creates a filter that produces a sepia-toned version of an image.

Sigmoid

Syntax

images.Sigmoid MIDPOINT FACTOR

Sigmoid creates a filter that changes the contrast of an image using a sigmoidal function and returns the adjusted image. It’s a non-linear contrast change useful for photo adjustments as it preserves highlight and shadow detail.

UnsharpMask

Syntax

images.UnsharpMask SIGMA AMOUNT THRESHOLD

UnsharpMask creates a filter that sharpens an image. The sigma parameter is used in a gaussian function and affects the radius of effect. Sigma must be positive. Sharpen radius roughly equals 3 * sigma. The amount parameter controls how much darker and how much lighter the edge borders become. Typically between 0.5 and 1.5. The threshold parameter controls the minimum brightness change that will be sharpened. Typically between 0 and 0.05.

Other Functions

Filter

Syntax

IMAGE | images.Filter FILTERS...

Can be used to apply a set of filters to an image:

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

Also see the Filter Method.

ImageConfig

Parses the image and returns the height, width, and color model.

The imageConfig function takes a single parameter, a file path (string) relative to the project’s root directory, with or without a leading slash.

Syntax

images.ImageConfig PATH

{{ with (imageConfig "favicon.ico") }}
favicon.ico: {{ .Width }} x {{ .Height }}
{{ end }}