From a0e44458fb81fc65b66bbff6dd8f64792442bb1a Mon Sep 17 00:00:00 2001 From: Regis Philibert Date: Thu, 25 Jan 2018 12:46:19 -0500 Subject: [PATCH] Image processing first draft, Resources second read/fix --- .../bundles/image-processing/index.md | 76 ++++++++++++++++++- .../bundles/resources/index.md | 27 +++---- 2 files changed, 89 insertions(+), 14 deletions(-) diff --git a/content/content-management/bundles/image-processing/index.md b/content/content-management/bundles/image-processing/index.md index 3895a5a6e..6976bcb88 100644 --- a/content/content-management/bundles/image-processing/index.md +++ b/content/content-management/bundles/image-processing/index.md @@ -10,4 +10,78 @@ toc : true linktitle : "Image Processing" --- -Content in "Image Processing" +Image processing is available on Page Resources. + +## Methods + +The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. They take one parameter. + +Resize +: Resizes the image to the specified width and height. + +```go +// Resize to a width of 600px and preserve ratio +{{ $image := $resource.Resize "600x" }} + +// Resize to a height of 400px and preserve ratio +{{ $image := $resource.Resize "x400" }} + +// Resize to a width 600px and a height of 400px +{{ $image := $resource.Resize "600x400" }} +``` + +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. + +```go +{{ $image := $resource.Fill "600x400" }} +``` + + +{{% 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 %}} + + +## Options + +In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. + + +JPEG Quality +: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. + +```go +{{ $image.Resize "600x q50" }} +``` + +Rotate +: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +```go +{{ $image.Resize "600x r90" }} +``` + +Anchor +: Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. +Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. + +```go +{{ $image.Fill "300x200 BottomLeft" }} +``` + +Resample Filter +: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. +Among them: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. +See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + +```go +{{ $image.Resize "600x400 Gaussian" }} +``` \ No newline at end of file diff --git a/content/content-management/bundles/resources/index.md b/content/content-management/bundles/resources/index.md index 49ff98d5a..183ac28a4 100644 --- a/content/content-management/bundles/resources/index.md +++ b/content/content-management/bundles/resources/index.md @@ -14,10 +14,10 @@ linktitle : "Resources" ## Properties ResourceType -: The main type of the resource. For exemple a file of MIME type `image/jpg` has for type `image`. +: The main type of the resource. For exemple a file of MIME type `image/jpg` has for ResourceType `image`. Name -: The filename. (relative path to the bundle) It can be overwritten with the resource's Front Matter metadata. +: The filename (relative path to the bundle). It can be overwritten with the resource's Front Matter metadata. Title : Same as filename. It can be overwritten with the resource's Front Matter metadata. @@ -28,7 +28,7 @@ Permalink RelPermalink : The relative URL of the resource. -## Methods / Functions +## Methods ByType : Retrieve the page resources of the passed type. @@ -74,34 +74,35 @@ resources: params: credits: Hugo Doe license:CC BY - - src: "*/tokyo-sunset.jpg" + - src: "*/japan-sunset.jpg" params: - credits: Jiro Ashima + credits: 森山大道 ~~~ -In the exemple above, we use glob to target several files and groups of file. +In the example above: -- `sunset.jpg` will receive a distinct Title -- `sunrise.jpg` will receive a distinct Title and Name and won't be retrieved by `.Match "*/sunrise.jpg"` anymore but something like `.Match "sunrise-*"`. +- `sunset.jpg` will receive a distinct `Title` +- `sunrise.jpg` will receive a distinct `Title` and `Name` and won't be retrieved by `.Match "*/sunrise.jpg"` anymore but something like `.Match "sunrise-*"`. - Every jpg in the bundle will receive the same `credits` and `license` parameter. -- `tokyo-sunset.jpg` will receive a distinct `credits` +- `japan-sunset.jpg` will receive a distinct `credits` -The __order matters__, each rule overwriting the params assigned by the previous one on their shared target. The rule for `*/tokyo-sunset.jpg` has to be declared after the more generic `*/*.jpg`. +The __order matters__, each rule overwriting the params assigned by the previous one on their shared target. The specific rule for `*/japan-sunset.jpg` has to be declared after the more generic `*/*.jpg`. ## Available metadata name : Will overwrite Name -{{< warning >}} +{{% warning %}} The methods Match and GetMatch use Name to match the resource. Overwrite wisely. -{{}} +{{%/ warning %}} title : Will overwrite Title params -: An array of custom params to be retrieve much like page params
`{{ .Params.credits }}` +: An array of custom params to be retrieve much like page params +`{{ .Params.credits }}`