package images

import "github.com/gohugoio/hugo/resources/images"

Package images provides template functions for manipulating images.

Index

Constants 

const (
	ActionResize = "resize"
	ActionCrop   = "crop"
	ActionFit    = "fit"
	ActionFill   = "fill"
)
const (
	SmartCropAnchor = 1000
)

Variables 

var Actions = map[string]bool{
	ActionResize: true,
	ActionCrop:   true,
	ActionFit:    true,
	ActionFill:   true,
}

Functions

func AddColorToPalette 

func AddColorToPalette(c color.Color, p color.Palette) color.Palette

AddColorToPalette adds c as the first color in p if not already there. Note that it does no additional checks, so callers must make sure that the palette is valid for the relevant format.

func ColorGoToHexString 

func ColorGoToHexString(c color.Color) string

ColorGoToHexString converts a color.Color to a hex string.

func DecodeConfig 

func DecodeConfig(in map[string]any) (*config.ConfigNamespace[ImagingConfig, ImagingConfigInternal], error)

func IsOpaque 

func IsOpaque(img image.Image) bool

IsOpaque returns false if the image has alpha channel and there is at least 1 pixel that is not (fully) opaque.

func ReplaceColorInPalette 

func ReplaceColorInPalette(c color.Color, p color.Palette)

ReplaceColorInPalette will replace the color in palette p closest to c in Euclidean R,G,B,A space with c.

func ToFilters 

func ToFilters(in any) []gift.Filter

ToFilters converts the given input to a slice of gift.Filter.

func UnwrapFilter 

func UnwrapFilter(in gift.Filter) gift.Filter

UnwrapFilter unwraps the given filter if it is a filter wrapper.

Types

type Color 

type Color struct {
	// contains filtered or unexported fields
}

func ColorGoToColor 

func ColorGoToColor(c color.Color) Color

ColorGoToColor converts a color.Color to a Color.

func HexStringsToColors 

func HexStringsToColors(s ...string) []Color

HexStringsToColors converts a slice of hex strings to a slice of Colors.

func (Color) ColorGo 

func (c Color) ColorGo() color.Color

ColorGo returns the color as a color.Color. For internal use only.

func (Color) ColorHex 

func (c Color) ColorHex() string

ColorHex returns the color as a hex string prefixed with a #.

func (Color) Hash 

func (c Color) Hash() (uint64, error)

For hashstructure. This struct is used in template func options that needs to be able to hash a Color. For internal use only.

func (Color) Luminance 

func (c Color) Luminance() float64

Luminance as defined by w3.org. See https://www.w3.org/TR/WCAG21/#dfn-relative-luminance

func (Color) String 

func (c Color) String() string

String returns the color as a hex string prefixed with a #.

type ExifConfig 

type ExifConfig struct {
	// Regexp matching the Exif fields you want from the (massive) set of Exif info
	// available. As we cache this info to disk, this is for performance and
	// disk space reasons more than anything.
	// If you want it all, put ".*" in this config setting.
	// Note that if neither this or ExcludeFields is set, Hugo will return a small
	// default set.
	IncludeFields string

	// Regexp matching the Exif fields you want to exclude. This may be easier to use
	// than IncludeFields above, depending on what you want.
	ExcludeFields string

	// Hugo extracts the "photo taken" date/time into .Date by default.
	// Set this to true to turn it off.
	DisableDate bool

	// Hugo extracts the "photo taken where" (GPS latitude and longitude) into
	// .Long and .Lat. Set this to true to turn it off.
	DisableLatLong bool
}

type Filters 

type Filters struct{}

func (*Filters) AutoOrient 

func (*Filters) AutoOrient() gift.Filter

AutoOrient creates a filter that rotates and flips an image as needed per its EXIF orientation tag.

func (*Filters) Brightness 

func (*Filters) Brightness(percentage any) gift.Filter

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

func (*Filters) ColorBalance 

func (*Filters) ColorBalance(percentageRed, percentageGreen, percentageBlue any) gift.Filter

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).

func (*Filters) Colorize 

func (*Filters) Colorize(hue, saturation, percentage any) gift.Filter

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).

func (*Filters) Contrast 

func (*Filters) Contrast(percentage any) gift.Filter

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

func (*Filters) Dither 

func (*Filters) Dither(options ...any) gift.Filter

Dither creates a filter that dithers an image.

func (*Filters) Gamma 

func (*Filters) Gamma(gamma any) gift.Filter

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.

func (*Filters) GaussianBlur 

func (*Filters) GaussianBlur(sigma any) gift.Filter

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

func (*Filters) Grayscale 

func (*Filters) Grayscale() gift.Filter

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

func (*Filters) Hue 

func (*Filters) Hue(shift any) gift.Filter

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

func (*Filters) Invert 

func (*Filters) Invert() gift.Filter

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

func (*Filters) Mask 

func (*Filters) Mask(mask ImageSource) gift.Filter

Mask creates a filter that applies a mask image to the source image.

func (*Filters) Opacity 

func (*Filters) Opacity(opacity any) gift.Filter

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

func (*Filters) Overlay 

func (*Filters) Overlay(src ImageSource, x, y any) gift.Filter

Overlay creates a filter that overlays src at position x y.

func (*Filters) Padding 

func (*Filters) Padding(args ...any) gift.Filter

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. The signature is images.Padding V1 [V2] [V3] [V4] [COLOR].

func (*Filters) Pixelate 

func (*Filters) Pixelate(size any) gift.Filter

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

func (*Filters) Process 

func (*Filters) Process(spec any) gift.Filter

Process creates a filter that processes an image using the given specification.

func (*Filters) Saturation 

func (*Filters) Saturation(percentage any) gift.Filter

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

func (*Filters) Sepia 

func (*Filters) Sepia(percentage any) gift.Filter

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

func (*Filters) Sigmoid 

func (*Filters) Sigmoid(midpoint, factor any) gift.Filter

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.

func (*Filters) Text 

func (*Filters) Text(text string, options ...any) gift.Filter

Text creates a filter that draws text with the given options.

func (*Filters) UnsharpMask 

func (*Filters) UnsharpMask(sigma, amount, threshold any) gift.Filter

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.

type Format 

type Format int

Format is an image file format. 

const (
	JPEG Format = iota + 1
	PNG
	GIF
	TIFF
	BMP
	WEBP
)

func ImageFormatFromExt 

func ImageFormatFromExt(ext string) (Format, bool)

func ImageFormatFromMediaSubType 

func ImageFormatFromMediaSubType(sub string) (Format, bool)

func (Format) DefaultExtension 

func (f Format) DefaultExtension() string

DefaultExtension returns the default file extension of this format, starting with a dot. For example: .jpg for JPEG

func (Format) MediaType 

func (f Format) MediaType() media.Type

MediaType returns the media type of this image, e.g. image/jpeg for JPEG

func (Format) RequiresDefaultQuality 

func (f Format) RequiresDefaultQuality() bool

RequiresDefaultQuality returns if the default quality needs to be applied to images of this format.

func (Format) SupportsTransparency 

func (f Format) SupportsTransparency() bool

SupportsTransparency reports whether it supports transparency in any form.

func (Format) ToImageMetaImageFormatFormat 

func (f Format) ToImageMetaImageFormatFormat() imagemeta.ImageFormat

type Giphy 

type Giphy interface {
	image.Image    // The first frame.
	GIF() *gif.GIF // All frames.
}

Giphy represents a GIF Image that may be animated.

type Image 

type Image struct {
	Format Format
	Proc   *ImageProcessor
	Spec   Spec
	// contains filtered or unexported fields
}

func NewImage 

func NewImage(f Format, proc *ImageProcessor, img image.Image, s Spec) *Image

func (*Image) EncodeTo 

func (i *Image) EncodeTo(conf ImageConfig, img image.Image, w io.Writer) error

func (*Image) Height 

func (i *Image) Height() int

Height returns i's height.

func (*Image) InitConfig 

func (i *Image) InitConfig(r io.Reader) error

InitConfig reads the image config from the given reader.

func (*Image) Width 

func (i *Image) Width() int

Width returns i's width.

func (Image) WithImage 

func (i Image) WithImage(img image.Image) *Image

func (Image) WithSpec 

func (i Image) WithSpec(s Spec) *Image

type ImageConfig 

type ImageConfig struct {
	// This defines the output format of the output image. It defaults to the source format.
	TargetFormat Format

	Action string

	// If set, this will be used as the key in filenames etc.
	Key string

	// Quality ranges from 1 to 100 inclusive, higher is better.
	// This is only relevant for JPEG and WEBP images.
	// Default is 75.
	Quality int

	// Rotate rotates an image by the given angle counter-clockwise.
	// The rotation will be performed first.
	Rotate int

	// Used to fill any transparency.
	// When set in site config, it's used when converting to a format that does
	// not support transparency.
	// When set per image operation, it's used even for formats that does support
	// transparency.
	BgColor color.Color

	// Hint about what type of picture this is. Used to optimize encoding
	// when target is set to webp.
	Hint webpoptions.EncodingPreset

	Width  int
	Height int

	Filter gift.Resampling

	Anchor gift.Anchor
	// contains filtered or unexported fields
}

ImageConfig holds configuration to create a new image from an existing one, resize etc.

func DecodeImageConfig 

func DecodeImageConfig(options []string, defaults *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal], sourceFormat Format) (ImageConfig, error)

func GetDefaultImageConfig 

func GetDefaultImageConfig(defaults *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal]) ImageConfig

func (ImageConfig) Reanchor 

func (cfg ImageConfig) Reanchor(a gift.Anchor) ImageConfig

type ImageFilterFromOrientationProvider 

type ImageFilterFromOrientationProvider interface {
	AutoOrient(exifInfo *exif.ExifInfo) gift.Filter
}

type ImageProcessSpecProvider 

type ImageProcessSpecProvider interface {
	ImageProcessSpec() string
}

type ImageProcessor 

type ImageProcessor struct {
	Cfg *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal]
	// contains filtered or unexported fields
}

func NewImageProcessor 

func NewImageProcessor(warnl logg.LevelLogger, cfg *config.ConfigNamespace[ImagingConfig, ImagingConfigInternal]) (*ImageProcessor, error)

func (*ImageProcessor) ApplyFiltersFromConfig 

func (p *ImageProcessor) ApplyFiltersFromConfig(src image.Image, conf ImageConfig) (image.Image, error)

func (*ImageProcessor) DecodeExif 

func (p *ImageProcessor) DecodeExif(filename string, format imagemeta.ImageFormat, r io.Reader) (*exif.ExifInfo, error)

Filename is only used for logging.

func (*ImageProcessor) Filter 

func (p *ImageProcessor) Filter(src image.Image, filters ...gift.Filter) (image.Image, error)

func (*ImageProcessor) FiltersFromConfig 

func (p *ImageProcessor) FiltersFromConfig(src image.Image, conf ImageConfig) ([]gift.Filter, error)

type ImageResource 

type ImageResource interface {
	resource.Resource
	ImageResourceOps
}

ImageResource represents an image resource.

type ImageResourceOps 

type ImageResourceOps interface {
	// Height returns the height of the Image.
	Height() int

	// Width returns the width of the Image.
	Width() int

	// Process applies the given image processing options to the image.
	Process(spec string) (ImageResource, error)

	// 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" }}
	Crop(spec string) (ImageResource, error)

	// Fill scales the image to the smallest possible size that will cover the specified dimensions in spec,
	// crops the resized image to the specified dimensions using the given anchor point.
	// The spec is space delimited, e.g. `200x300 TopLeft`.
	Fill(spec string) (ImageResource, error)

	// Fit scales down the image using the given spec.
	Fit(spec string) (ImageResource, error)

	// Resize resizes the image to the given spec. If one of width or height is 0, the image aspect
	// ratio is preserved.
	Resize(spec string) (ImageResource, error)

	// Filter applies one or more filters to an Image.
	//    {{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
	Filter(filters ...any) (ImageResource, error)

	// Exif returns an ExifInfo object containing Image metadata.
	Exif() *exif.ExifInfo

	// Colors returns a slice of the most dominant colors in an image
	// using a simple histogram method.
	Colors() ([]Color, error)

	// For internal use.
	DecodeImage() (image.Image, error)
}

type ImageSource 

type ImageSource interface {
	DecodeImage() (image.Image, error)
	Key() string
}

ImageSource identifies and decodes an image.

type ImagingConfig 

type ImagingConfig struct {
	// Default image quality setting (1-100). Only used for JPEG images.
	Quality int

	// Resample filter to use in resize operations.
	ResampleFilter string

	// Hint about what type of image this is.
	// Currently only used when encoding to Webp.
	// Default is "photo".
	// Valid values are "picture", "photo", "drawing", "icon", or "text".
	Hint string

	// The anchor to use in Fill. Default is "smart", i.e. Smart Crop.
	Anchor string

	// Default color used in fill operations (e.g. "fff" for white).
	BgColor string

	Exif ExifConfig
}

ImagingConfig contains default image processing configuration. This will be fetched from site (or language) config.

type ImagingConfigInternal 

type ImagingConfigInternal struct {
	BgColor        color.Color
	Hint           webpoptions.EncodingPreset
	ResampleFilter gift.Resampling
	Anchor         gift.Anchor

	Imaging ImagingConfig
}

func (*ImagingConfigInternal) Compile 

func (i *ImagingConfigInternal) Compile(externalCfg *ImagingConfig) error

type Spec 

type Spec interface {
	// Loads the image source.
	ReadSeekCloser() (hugio.ReadSeekCloser, error)
}

Source Files

auto_orient.go color.go config.go dither.go filters.go image.go image_resource.go mask.go opacity.go overlay.go padding.go process.go resampling.go smartcrop.go text.go

Directories

PathSynopsis
resources/images/exif
resources/images/imagetesting
resources/images/webp
Version
v0.144.2 (latest)
Published
Feb 19, 2025
Platform
linux/amd64
Imports
38 packages
Last checked
13 hours ago –

Tools for package owners.