Update image docs for 0.58

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
+### Resize
-: Resizes the image to the specified width and height.
+
+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
+### Fit
-: Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required.
+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
+### Fill
-: Resize and crop the image to match the given dimensions. Both height and width are required.
+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
 

content/en/functions/imageConfig.md

@@ -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 }}
-```

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 }}
+```

layouts/shortcodes/funcsig.html

@@ -0,0 +1,4 @@
+<h4 class="minor mb1 pt2 primary-color-dark">Syntax</h4>
+<pre class="f5 mb4 ph3 pv2 bg-light-gray" style="border-left:4px solid #0594CB;">
+    {{- .Inner -}}
+</pre>