From d087cf30682d4a45ff32bfffa06c69fbc02c16e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 4 Sep 2019 12:48:51 +0200 Subject: [PATCH] Update image docs for 0.58 --- .../image-processing/index.md | 99 ++++++++-- content/en/functions/imageConfig.md | 25 --- content/en/functions/images/index.md | 174 ++++++++++++++++++ layouts/shortcodes/funcsig.html | 4 + 4 files changed, 262 insertions(+), 40 deletions(-) delete mode 100644 content/en/functions/imageConfig.md create mode 100644 content/en/functions/images/index.md create mode 100644 layouts/shortcodes/funcsig.html diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index b83a6c103..7f96bcd44 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -5,7 +5,7 @@ date: 2018-01-24T13:10:00-05:00 lastmod: 2018-01-26T15:59:07-05:00 linktitle: "Image Processing" categories: ["content management"] -keywords: [bundle,content,resources,images] +keywords: [resources,images] weight: 4004 draft: false toc: true @@ -19,10 +19,8 @@ menu: The `image` is a [Page Resource]({{< relref "/content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder. - To get all images in a [Page Bundle]({{< relref "/content-management/organization#page-bundles" >}}): - ```go-html-template {{ with .Resources.ByType "image" }} {{ end }} @@ -32,10 +30,11 @@ To get all images in a [Page Bundle]({{< relref "/content-management/organizatio ## Image Processing Methods -The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. +The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. The `image` resource also, since Hugo 0.58, implements the method `Exif` and `Filter`. -Resize -: Resizes the image to the specified width and height. +### Resize + +Resizes the image to the specified width and height. ```go // Resize to a width of 600px and preserve ratio @@ -48,24 +47,75 @@ Resize {{ $image := $resource.Resize "600x400" }} ``` -Fit -: Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. +### Fit +Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. ```go {{ $image := $resource.Fit "600x400" }} ``` -Fill -: Resize and crop the image to match the given dimensions. Both height and width are required. +### Fill +Resize and crop the image to match the given dimensions. Both height and width are required. ```go {{ $image := $resource.Fill "600x400" }} ``` +### Filter + +Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list. + +```go-html-template +{{ $img = $img.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The above can also be written in a more functional style using pipes: + +```go-html-template +{{ $img = $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +The filters will be applied in the given order. + +Sometimes it can be useful to create the filter chain once and then reuse it: + +```go-html-template +{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }} +{{ $img1 = $img1.Filter $filters }} +{{ $img2 = $img2.Filter $filters }} +``` + +### Exif + +Provides an [Exif](https://en.wikipedia.org/wiki/Exif) object with metadata about the image. + +Note that this is only suported for JPG and TIFF images, so it's recommended to wrap the access with a `with`, e.g.: + +```go-html-template +{{ with $img.Exif }} +Date: {{ .Date }} +Lat/Long: {{ .Lat}}/{{ .Long }} +Tags: +{{ range $k, $v := .Tags }} +TAG: {{ $k }}: {{ $v }} +{{ end }} +``` + +#### Exif fields + +Data +: "photo taken" date/time + +Lat +: "photo taken where", GPS latitude + +Long +: "photo taken where", GPS longitude + +See [Image Processing Config](#image-processing-config) for how to configure what gets included in Exif. + + -{{% note %}} -Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. -{{% /note %}} ## Image Processing Options @@ -160,9 +210,28 @@ quality = 75 # Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight anchor = "smart" -``` +[imaging.exif] + # Regexp matching the fields you want to Exclude 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 = "" -All of the above settings can also be set per image procecssing. + # Regexp matching the Exif fields you want to exclude. This may be easier to use +# than IncludeFields above, depending on what you want. +excludeFields = "" + + # Hugo extracts the "photo taken" date/time into .Date by default. +# Set this to true to turn it off. +disableDate = false + + # Hugo extracts the "photo taken where" (GPS latitude and longitude) into +# .Long and .Lat. Set this to true to turn it off. +disableLatLong = false + +``` ## Smart Cropping of Images diff --git a/content/en/functions/imageConfig.md b/content/en/functions/imageConfig.md deleted file mode 100644 index 3952448c6..000000000 --- a/content/en/functions/imageConfig.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: imageConfig -linktitle: imageConfig -description: Parses the image and returns the height, width, and color model. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [images] -signature: ["imageConfig PATH"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false ---- - -``` -{{ with (imageConfig "favicon.ico") }} -favicon.ico: {{.Width}} x {{.Height}} -{{ end }} -``` diff --git a/content/en/functions/images/index.md b/content/en/functions/images/index.md new file mode 100644 index 000000000..e83d41154 --- /dev/null +++ b/content/en/functions/images/index.md @@ -0,0 +1,174 @@ +--- +title: Image Functions +description: The images namespace provides a list of filters and other image related functions. +godocref: +date: 2017-02-01 +categories: [functions] +aliases: [/functions/imageconfig/] +menu: + docs: + parent: "functions" +keywords: [images] +toc: true +--- + + +## Image Filters + +See [images.Filter](#filter) for how to apply these filters to an image. + +### Brightness + +{{% funcsig %}} +images.Brightness PERCENTAGE +{{% /funcsig %}} + +Brightness creates a filter that changes the brightness of an image. +The percentage parameter must be in range (-100, 100). + +### ColorBalance + +{{% funcsig %}} +images.ColorBalance PERCENTAGERED PERCENTAGEGREEN PERCENTAGEBLUE +{{% /funcsig %}} + +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 + +{{% funcsig %}} +images.Colorize HUE SATURATION PERCENTAGE +{{% /funcsig %}} + +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 + +{{% funcsig %}} +images.Contrast PERCENTAGE +{{% /funcsig %}} + +Contrast creates a filter that changes the contrast of an image. +The percentage parameter must be in range (-100, 100). + +### Gamma + +{{% funcsig %}} +images.Gamma GAMMA +{{% /funcsig %}} + +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 + +{{% funcsig %}} +images.GaussianBlur SIGMA +{{% /funcsig %}} + +GaussianBlur creates a filter that applies a gaussian blur to an image. + +### Grayscale + +{{% funcsig %}} +images.Grayscale +{{% /funcsig %}} + +Grayscale creates a filter that produces a grayscale version of an image. + +### Hue + +{{% funcsig %}} +images.Hue SHIFT +{{% /funcsig %}} + +Hue creates a filter that rotates the hue of an image. +The hue angle shift is typically in range -180 to 180. + +### Invert + +{{% funcsig %}} +images.Invert +{{% /funcsig %}} + +Invert creates a filter that negates the colors of an image. + +### Pixelate + +{{% funcsig %}} +images.Pixelate SIZE +{{% /funcsig %}} + +Pixelate creates a filter that applies a pixelation effect to an image. + +### Saturation + +{{% funcsig %}} +images.Saturation PERCENTAGE +{{% /funcsig %}} + +Saturation creates a filter that changes the saturation of an image. + +### Sepia + +{{% funcsig %}} +images.Sepia PERCENTAGE +{{% /funcsig %}} + +Sepia creates a filter that produces a sepia-toned version of an image. + +### Sigmoid + +{{% funcsig %}} +images.Sigmoid MIDPOINT FACTOR +{{% /funcsig %}} + +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 + +{{% funcsig %}} +images.UnsharpMask SIGMA AMOUNT THRESHOLD +{{% /funcsig %}} + +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 + +{{% funcsig %}} +IMAGE | images.Filter FILTERS... +{{% /funcsig %}} + +Can be used to apply a set of filters to an image: + +```go-html-template +{{ $img := $img | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }} +``` + +Also see the [Filter Method](/content-management/image-processing/#filter). + +### ImageConfig + +Parses the image and returns the height, width, and color model. + +{{% funcsig %}} +images.ImageConfig PATH +{{% /funcsig %}} + +```go-html-template +{{ with (imageConfig "favicon.ico") }} +favicon.ico: {{.Width}} x {{.Height}} +{{ end }} +``` diff --git a/layouts/shortcodes/funcsig.html b/layouts/shortcodes/funcsig.html new file mode 100644 index 000000000..1709c60b0 --- /dev/null +++ b/layouts/shortcodes/funcsig.html @@ -0,0 +1,4 @@ +

Syntax

+
+    {{- .Inner -}}
+
\ No newline at end of file