Introduces the Crop method for image processing which implements gift.CropToSize. Also allows a smartCrop without resizing, and updates the documentation.
Fixes #9499
## Image Processing Methods
-The `image` resource implements the `Resize`, `Fit`, `Fill`, and `Filter` methods, each returning a transformed image using the specified dimensions and processing options.
+The `image` resource implements the `Resize`, `Fit`, `Fill`, `Crop`, and `Filter` methods, each returning a transformed image using the specified dimensions and processing options.
{{% note %}}
Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the [`Exif`](#exif) method with the _original_ image to extract EXIF metadata from JPEG or TIFF images.
### Fill
-Resize and crop the image to match the given dimensions. Both height and width are required.
+Crop and resize the image to match the given dimensions. Both height and width are required.
```go
{{ $image := $resource.Fill "600x400" }}
```
+### Crop
+
+Crop the image to match the given dimensions without resizing. Both height and width are required.
+
+```go
+{{ $image := $resource.Crop "400x400" }}
+```
+
### Filter
Apply one or more filters to your image. See [Image Filters](/functions/images/#image-filters) for a full list.
### Anchor
-Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner.
+Only relevant for the `Crop` and `Fill` methods. This is useful for thumbnail generation where the main motive is located in, say, the left corner.
Valid values are `Smart`, `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`.
{{< imgproc sunset Fit "90x90" />}}
+{{< imgproc sunset Crop "250x250 center" />}}
+
{{< imgproc sunset Resize "300x q10" />}}
This is the shortcode used in the examples above:
# Valid values are "picture", "photo", "drawing", "icon", or "text".
hint = "photo"
-# Anchor used when cropping pictures.
+# Anchor used when cropping pictures with either .Fill or .Crop
# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop
# Smart Cropping is content aware and tries to find the best crop for each image.
# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight
## Smart Cropping of Images
-By default, Hugo will use [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future.
+By default, Hugo will use [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill` or `.Crop`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future.
-An example using the sunset image from above:
+Examples using the sunset image from above:
{{< imgproc sunset Fill "200x200 smart" />}}
+{{< imgproc sunset Crop "200x200 smart" />}}
+
## Image Processing Performance Consideration
Processed images are stored below `<project-dir>/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused.
{{ .Scratch.Set "image" ($original.Resize $options) }}
{{ else if eq $command "Fill"}}
{{ .Scratch.Set "image" ($original.Fill $options) }}
+{{ else if eq $command "Crop"}}
+{{ .Scratch.Set "image" ($original.Crop $options) }}
{{ else }}
-{{ errorf "Invalid image processing command: Must be one of Fit, Fill or Resize."}}
+{{ errorf "Invalid image processing command: Must be one of Crop, Fit, Fill or Resize."}}
{{ end }}
{{ $image := .Scratch.Get "image" }}
<figure style="padding: 0.25rem; margin: 2rem 0; background-color: #cccc">
panic(e.error)
}
+func (e *errorResource) Crop(spec string) (resource.Image, error) {
+ panic(e.error)
+}
+
func (e *errorResource) Fill(spec string) (resource.Image, error) {
panic(e.error)
}
})
}
+// Crop the image to the specified dimensions without resizing using the given anchor point.
+// Space delimited config: 200x300 TopLeft
+func (i *imageResource) Crop(spec string) (resource.Image, error) {
+ conf, err := i.decodeImageConfig("crop", spec)
+ if err != nil {
+ return nil, err
+ }
+
+ return i.doWithImageConfig(conf, func(src image.Image) (image.Image, error) {
+ return i.Proc.ApplyFiltersFromConfig(src, conf)
+ })
+}
+
// Fit scales down the image using the specified resample filter to fit the specified
// maximum width and height.
func (i *imageResource) Fit(spec string) (resource.Image, error) {
filledAgain, err := image.Fill("200x100 bottomLeft")
c.Assert(err, qt.IsNil)
c.Assert(filled, eq, filledAgain)
+
+ cropped, err := image.Crop("300x300 topRight")
+ c.Assert(err, qt.IsNil)
+ c.Assert(cropped.RelPermalink(), qt.Equals, "/a/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_300x300_crop_q68_linear_topright.jpg")
+ assertWidthHeight(cropped, 300, 300)
+
+ smartcropped, err := image.Crop("200x200 smart")
+ c.Assert(err, qt.IsNil)
+ c.Assert(smartcropped.RelPermalink(), qt.Equals, fmt.Sprintf("/a/sunset_hu59e56ffff1bc1d8d122b1403d34e039f_90587_200x200_crop_q68_linear_smart%d.jpg", 1))
+ assertWidthHeight(smartcropped, 200, 200)
+
+ // Check cache
+ croppedAgain, err := image.Crop("300x300 topRight")
+ c.Assert(err, qt.IsNil)
+ c.Assert(cropped, eq, croppedAgain)
+
}
func TestImageTransformFormat(t *testing.T) {
k += "_" + i.FilterStr
- if strings.EqualFold(i.Action, "fill") {
+ if strings.EqualFold(i.Action, "fill") || strings.EqualFold(i.Action, "crop") {
k += "_" + anchor
}
switch conf.Action {
case "resize":
filters = append(filters, gift.Resize(conf.Width, conf.Height, conf.Filter))
+ case "crop":
+ if conf.AnchorStr == smartCropIdentifier {
+ bounds, err := p.smartCrop(src, conf.Width, conf.Height, conf.Filter)
+ if err != nil {
+ return nil, err
+ }
+
+ // First crop using the bounds returned by smartCrop.
+ filters = append(filters, gift.Crop(bounds))
+ // Then center crop the image to get an image the desired size without resizing.
+ filters = append(filters, gift.CropToSize(conf.Width, conf.Height, gift.CenterAnchor))
+
+ } else {
+ filters = append(filters, gift.CropToSize(conf.Width, conf.Height, conf.Anchor))
+ }
case "fill":
if conf.AnchorStr == smartCropIdentifier {
bounds, err := p.smartCrop(src, conf.Width, conf.Height, conf.Filter)
type ImageOps interface {
Height() int
Width() int
+ Crop(spec string) (Image, error)
Fill(spec string) (Image, error)
Fit(spec string) (Image, error)
Resize(spec string) (Image, error)
return r.target.Data()
}
+func (r *resourceAdapter) Crop(spec string) (resource.Image, error) {
+ return r.getImageOps().Crop(spec)
+}
+
func (r *resourceAdapter) Fill(spec string) (resource.Image, error) {
return r.getImageOps().Fill(spec)
}
projects / brevno-suite / hugo / commitdiff