Image process handling (nice-to-have proposal) #3158

wildhaber · 2017-03-10T07:34:16Z

Introduction

What is this issue all about?

I would like to breathe new life into the whole part of image processing and bring some traction to this topic. Since it is still on the Hugo roadmap, and at least in my opinion a huge puzzle piece to make Hugo more complete. Hope my proposal below helps in this case.

After reading a lot of other issues sometimes just covering one part of the Image processing I try to bring up a complete idea that covers most of the usecases with the same writing style instead of mixing up incompatible implementations together that leads into missunderstandings when using the code.

One of the main goal was, to make usage of available popular and fast Go Packages/Libraries to make the first step easy.

Why I write this issue and do not implement the feature?

Unfortunately I am not a Go-Developer, but I can help at delivering proposals from a Hugo user perspective 🙂

Namings or definitions I use below are just ideas, feel free to have a different opinion on them.

Features

This proposal covers the following features:

Image cropping in with content awareness (SmartCrop)
Simple cropping
Image resize with different interpolations
Image Flip / Rotate (maybe according EXIF-Info?)
Image Manipulation
- Brightness
- Contrast
- Gamma
- Hue
- Saturation
- Blend modes (image overlay / watermarks)
- Blur
- Channel Extraction
- Painting: Flood Fill
Image Effects
- Dilate
- Edge Detection
- Emboss
- Erode
- Grayscale
- Invert
- Median
- Sepia
- Sharpen
- Sobel
- Unsharp Mask
Save images

I know this list looks like a lot of work, but I more or less copied features from existing libraries.

Libraries

Libraries I have in mind solving all the features above.

bild
Purpose: Image manipulation and effects
Documentation: https://godoc.org/github.com/anthonynsimon/bild
Repository: https://github.com/anthonynsimon/bild
License: MIT

resize
Purpose: resize images
Repository: https://github.com/nfnt/resize
License: MIT

smartcrop.go
Purpose: content aware cropping including face-detection
Documentation: https://godoc.org/github.com/muesli/smartcrop
Repository: https://github.com/muesli/smartcrop
License: MIT

Ok, I have to admit having no idea about the size nor performance of these libraries. But they look great in my eyes and are well documented and the API could be used for the implementation 1:1.

Process in the templates

In my eyes, an image process in the template should look like this:

Open/Load source image ==> Process pipeline ==> Save image ==> (returns an image data including a .Permalink that can be used for including)

In code that could look like this:

// imageProcess (ip)

// 1. Open/Load source image
{{ $image := ipOpen "static/great-picture.jpg" }}

// 2. Process pipeline
{{ $grayscaled := ipGrayscale  $image }}
{{ $blurry := ipGaussianBlur $grayscaled 5.0 }}
{{ $crop := ipCrop $blurry 400 200 "smart" }}

// 3. Save image
{{ $processedImage := ipSave $crop }} // => proposal: save it under <public>/[optional: <configuredImageOutputPath>/]<md5hash>.<extension> (this way it would be easy regarding caching)

// 4. Use the image
{{ with $processedImage }}
<img src="{{ .Permalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

I see a lot of potential of creating partials and shortcodes out of it. Going with functions provides amazing flexibility vs the Shortcode-Approach discussed in this issue - #1014.

Basically this is the core way of processing. Below please find a full list of the functionalities specified.

Function specifications

Open & Save

ipOpen

Definition:

ipOpen <path-to-image>

Return:
image.Image

Example:

{{ $image := ipOpen "static/great-picture.jpg" }}

ipSave

Definition:

ipSave  [optional: <output-filename> | default: <public>/[optional: <configuredImageOutputPath>/]<md5hash>.<extension>]

Return:
map[]

{
  "Permalink" : "https://example.com/images/d41d8cd98f00b204e9800998ecf8427e.jpg",
  "RelPermalink" : "/images/d41d8cd98f00b204e9800998ecf8427e.jpg",
  "Width" : 400,
  "Height" : 200
}

It might get necessary to save the define a default output path for processed images in the config.toml like:

image_output_path = "images-generated/"

Example:

{{ $processedImage := ipSave $image }}
{{ $processedImageDefineOutput := ipSave $image "special/output-thumbnail.jpg" }}

{{ with $processedImage }}
<img src="{{ .Permalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}

Transform

ipCrop

Definition:

ipCrop <image.Image> <width> <height> [<position : ["smart" | "topleft" | "topcenter" | "topright" | "middleleft" | "middlecenter" | "middleright" | "bottomleft" | "bottomcenter" | "bottomright"] | (slice x0, y0, x1, y1)> | default: "smart" ]

Library Reference:

SmartCrop returns a crop map like { X, Y, Width, Height, Score } - this needs to be converted into a image.Rectangle.

Return:
image.Image

Example:

{{ $crop := ipCrop $image 400 200 }}

{{ $crop := ipCrop $image 400 200 "topleft" }}

ipResize

Definition:

ipResize <image.Image> <width> <height> [<interpolation : "NearestNeighbor" | "Bilinear" | "Bicubic" | "MitchellNetravali" | "Lanczos2" | "Lanczos3" > | default: "Bilinear" ]

Library Reference:

Return:
image.Image

Example:

{{ $resize := ipResize $image 400 200 }}

{{ $resize := ipResize $image 400 200 "Lanczos3" }}

ipThumbnail

Definition:

ipThumbnail <image.Image> <maxWidth> <maxHeight> [<interpolation : "NearestNeighbor" | "Bilinear" | "Bicubic" | "MitchellNetravali" | "Lanczos2" | "Lanczos3" > | default: "Bilinear" ]

Library Reference:

Return:
image.Image

Example:

{{ $thumbnail := ipThumbnail $image 40 20 }}

{{ $thumbnail := ipThumbnail $image 40`
20 "Lanczos3" }}

ipFlip

Definition:

ipFlip <image.Image> <flipAxis : "horizontal" | "vertical">

Library Reference:

Return:
image.Image

Example:

{{ $flip := ipFlip $image "horizontal" }}

{{ $flip := ipFlip $image "vertical" }}

ipRotate

Definition:

ipFlip <image.Image> <angle>

Library Reference:

Return:
image.Image

Example:

{{ $rotate := ipRotat`
 $image 60 }}

Image adjustments

ipBrightness

Definition:

ipBrightness <image.Image> <change>

Library Reference:

Return:
image.Image

Example:

{{ $brighter := ipBrightness `
image 0.25 }}

ipContrast

Definition:

ipContrast <image.Image> <change>

Library Reference:

Return:
image.Image

Example:

{{ $contrast := ipContrast $image -0.5 }}

ipGamma

Definition:

ipGamma <image.Image> <gamma>

Library Reference:

Return:
image.Image

Example:

{{ $gamma := ipGamma $image 0.4 }}

ipHue

Definition:

ipHue <image.Image> <change>

Library Reference:

Return:
image.Image

Example:

{{ $hue := ipHue $image -42 }}

ipBlendMode

Definition:

ipBlendMode <background-image> <foreground-image> [<blendmode : "Add" | "ColorBurn" | "ColorDodge" | "Darken" | "Difference" | "Divide" | "Exclusion" | "Lighten" | "LinearBurn" | "LinearLight" | "Multiply" | "Normal" | "Opacity" | "Overlay" | "Screen" | "SoftLight" | "Subtract"> | default: "Normal"] [<percentage (necessary for Opacity)> : default: 1]

Library Reference:

Return:
image.Image

Example:

{{ $blend := ipBlendMode $background $foreground "Multiply" }}

{{ $blend := ipBlendMode $background $foreground "Opacity" 0.5 }}

ipBlur

Definition:

ipBlur <image.Image> <radius> [<method : "Box" | "Gaussian"> | default: "Gaussian"]

Library Reference:

Return:
image.Image

Example:

{{ $blurry := ipBlurry $image 5 }}

{{ $blurry := ipBlurry $image 17 "Box" }}

ipExtractChannel

Definition:

ipExtractChannel <image.Image> <channel : "Red" "Green" "Blue" "Alpha">

Library Reference:

Return:
image.Image

Example:

{{ $extractNoRed := ipExtractChannel $image "Red" }}

ipFloodFill

Definition:

ipFloodFill <image.Image> <point : (slice X Y)> <color : (slice R G B A)> <fuzzy>

Library Reference:

Return:
image.Image

Example:

{{ $floodFill := ipFloodFill $image (slice 15 366) (slice 255, 0, 45, 255) 15 }}

Effects

ipDilate

Definition:

ipDilate <image.Image> <radius>

Library Reference:

Return:
image.Image

Example:

{{ $dilate := ipDilat
e $image 3 }}

ipEdgeDetection

Definition:

ipEdgeDetection <image.Image> <radius>

Library Reference:

Return:
image.Image

Example:

{{ $ipEdgeDetection := ipEdgeDetection $image 1.0 }}

ipEmboss

Definition:

ipEmboss <image.Image>

Library Reference:

Return:
image.Image

Example:

{{ $ipEmboss := ipEmboss $image }}

ipErode

Definition:

ipErode <image.Image> <radius>

Library Reference:

Return:
image.Image

Example:

{{ $ipErode := ipErode $image 3 }}

ipGrayscale

Definition:

ipGrayscale <image.Image>

Library Reference:

Return:
image.Image

Example:

{{ $grayscale := ipGrayscale $image }}

ipInvert

Definition:

ipInvert <image.Image>

Library Reference:

Return:
image.Image

Example:

{{ $inverted := ipInvert $image }}

ipMedian

Definition:

ipMedian <image.Image> <radius>

Library Reference:

Return:
image.Image

Example:

{{ $median := ipMedian $image 10.0 }}

ipSepia

Definition:

ipSepia <image.Image>

Library Reference:

Return:
image.Image

Example:

{{ $sepia := ipSepia $image }}

ipSharpen

Definition:

ipSharpen <image.Image>

Library Reference:

Return:
image.Image

Example:

{{ $sharpen := ipSharpen $image }}

ipSobel

Definition:

ipSharpen <image.Image>

Library Reference:

Return:
image.Image

Example:

{{ $sobel := ipSobel $image }}

ipUnsharpMask

Definition:

ipUnsharpMask <image.Image> <radius> <amount>

Library Reference:

Return:
image.Image

Example:

{{ $unsharpMask := ipUnsharpMask $image 0.6 1.2 }}

Conclusion

Ok, sorry, for this looooong issue / wishlist. For sure not every function is weighted with the same priority. And obviously all the implementation descriptions above sould be treated as an idea / proposal and not as expected. Any thoughts are highly appreciated 😄

Final thoughts not covered above:

How to deal with different file formats?
How to deal with JPEG-Quality?

I really hope, this issue help the Hugo-Project on it's roadmap.

Update

Finally, I made my first babyfeetsteps in Go and tried to implement the functionalities above.

You can find the current progress in this Branch / wildhaber:rw-3158-image-process and a Live Demo of the output is so far.

Currently I'm at the end of my knowledge in go and I don't think I should develop this feature any further. There are places where I would need some help and I'm not even sure, if this is the proper approach to deal with images. My question is now if I should make a very incomplete Pull Request or leave it here in the Issues-Section?

The text was updated successfully, but these errors were encountered:

Add image manipulation functions according to draft proposal gohugoio#3158

nilsnh · 2017-03-18T21:03:18Z

Hi there, :) I have not yet contributed to Hugo. But I'm interested in this image processing feature and I see that there's a contribution guide. 👍 ⚡️ I have done very little Go programming really but I can help out if needed.

stale · 2017-12-06T12:55:26Z

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

This commit also improves on the following: * Symbolic links are now allowed anywhere inside /content Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014 Closes gohugoio#2021 Updates gohugoio#3757

This commit also improves on the following: * Symbolic links are now allowed anywhere inside /content Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014 Closes gohugoio#2021 Fixes gohugoio#1240 Updates gohugoio#3757

This commit is not the smallest in Hugo's history. Some hightlights include: * Page bundles (for complete articles, keeping images and content together etc.). * Bundled images can be processed in as many versions/sizes as you need with the three methods `Resize`, `Fill` and `Fit`. * Processed images are cached inside `resources/_gen/images` (default) in your project. * Symbolic links (both files and dirs) are now allowed anywhere inside /content * A new table based build summary * The "Total in nn ms" now reports the total including the handling of the files inside /static. So if it now reports more than you're used to, it is just **more real** and probably faster than before (see below). Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014 Closes gohugoio#2021 Fixes gohugoio#1240 Updates gohugoio#3757

This commit is not the smallest in Hugo's history. Some hightlights include: * Page bundles (for complete articles, keeping images and content together etc.). * Bundled images can be processed in as many versions/sizes as you need with the three methods `Resize`, `Fill` and `Fit`. * Processed images are cached inside `resources/_gen/images` (default) in your project. * Symbolic links (both files and dirs) are now allowed anywhere inside /content * A new table based build summary * The "Total in nn ms" now reports the total including the handling of the files inside /static. So if it now reports more than you're used to, it is just **more real** and probably faster than before (see below). A site building benchmark run compared to `v0.31.1` shows that this should be slightly faster and use less memory: ```bash ▶ ./benchSite.sh "TOML,num_langs=.*,num_root_sections=5,num_pages=(500|1000),tags_per_page=5,shortcodes,render" benchmark old ns/op new ns/op delta BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 101785785 78067944 -23.30% BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 185481057 149159919 -19.58% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 103149918 85679409 -16.94% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 203515478 169208775 -16.86% benchmark old allocs new allocs delta BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 532464 391539 -26.47% BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 1056549 772702 -26.87% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 555974 406630 -26.86% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 1086545 789922 -27.30% benchmark old bytes new bytes delta BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 53243246 43598155 -18.12% BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 105811617 86087116 -18.64% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 54558852 44545097 -18.35% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 106903858 86978413 -18.64% ``` Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014 Closes gohugoio#2021 Fixes gohugoio#1240 Updates gohugoio#3757

This commit is not the smallest in Hugo's history. Some hightlights include: * Page bundles (for complete articles, keeping images and content together etc.). * Bundled images can be processed in as many versions/sizes as you need with the three methods `Resize`, `Fill` and `Fit`. * Processed images are cached inside `resources/_gen/images` (default) in your project. * Symbolic links (both files and dirs) are now allowed anywhere inside /content * A new table based build summary * The "Total in nn ms" now reports the total including the handling of the files inside /static. So if it now reports more than you're used to, it is just **more real** and probably faster than before (see below). A site building benchmark run compared to `v0.31.1` shows that this should be slightly faster and use less memory: ```bash ▶ ./benchSite.sh "TOML,num_langs=.*,num_root_sections=5,num_pages=(500|1000),tags_per_page=5,shortcodes,render" benchmark old ns/op new ns/op delta BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 101785785 78067944 -23.30% BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 185481057 149159919 -19.58% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 103149918 85679409 -16.94% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 203515478 169208775 -16.86% benchmark old allocs new allocs delta BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 532464 391539 -26.47% BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 1056549 772702 -26.87% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 555974 406630 -26.86% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 1086545 789922 -27.30% benchmark old bytes new bytes delta BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 53243246 43598155 -18.12% BenchmarkSiteBuilding/TOML,num_langs=1,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 105811617 86087116 -18.64% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=500,tags_per_page=5,shortcodes,render-4 54558852 44545097 -18.35% BenchmarkSiteBuilding/TOML,num_langs=3,num_root_sections=5,num_pages=1000,tags_per_page=5,shortcodes,render-4 106903858 86978413 -18.64% ``` Fixes #3651 Closes #3158 Fixes #1014 Closes #2021 Fixes #1240 Updates #3757

github-actions · 2022-03-10T02:03:28Z

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

wildhaber added a commit to wildhaber/hugo that referenced this issue Mar 10, 2017

tpl: Add image process template functions (draft)

6b3210a

Add image manipulation functions according to draft proposal gohugoio#3158

bep added the Wish label Mar 18, 2017

bademux mentioned this issue May 11, 2017

Add support for .tmpl file extension in template lookup order #3230

Closed

stale bot added the Stale label Dec 6, 2017

bep added a commit to bep/hugo that referenced this issue Dec 13, 2017

Implement Page bundling and image handling

160c6b3

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 16, 2017

Implement Page bundling and image handling

7c2f4fc

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 17, 2017

Implement Page bundling and image handling

857c7bb

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 17, 2017

Implement Page bundling and image handling

7fcb287

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 17, 2017

Implement Page bundling and image handling

9d20a33

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 20, 2017

Implement Page bundling and image handling

60e65ce

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 20, 2017

Implement Page bundling and image handling

a145d96

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 20, 2017

Implement Page bundling and image handling

ba9058d

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 20, 2017

Implement Page bundling and image handling

8e0f6a0

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

bep added a commit to bep/hugo that referenced this issue Dec 20, 2017

Implement Page bundling and image handling

a581667

Fixes gohugoio#3651 Closes gohugoio#3158 Fixes gohugoio#1014

stale bot closed this as completed Dec 27, 2017

dependencies bot mentioned this issue Dec 31, 2017

Update https://github.com/gohugoio/hugo in repo_dependencies.yml from v0.31 to v0.32 matrixik/dobek.pro#5

Closed

github-actions bot added the Outdated label Mar 10, 2022

github-actions bot locked as resolved and limited conversation to collaborators Mar 10, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Image process handling (nice-to-have proposal) #3158

Image process handling (nice-to-have proposal) #3158

wildhaber commented Mar 10, 2017 •

edited

Loading

nilsnh commented Mar 18, 2017

stale bot commented Dec 6, 2017

github-actions bot commented Mar 10, 2022

Image process handling (nice-to-have proposal) #3158

Image process handling (nice-to-have proposal) #3158

Comments

wildhaber commented Mar 10, 2017 • edited Loading

Introduction

What is this issue all about?

Why I write this issue and do not implement the feature?

Features

Libraries

Process in the templates

Function specifications

Open & Save

ipOpen

ipSave

Transform

ipCrop

ipResize

ipThumbnail

ipFlip

ipRotate

Image adjustments

ipBrightness

ipContrast

ipGamma

ipHue

ipBlendMode

ipBlur

ipExtractChannel

ipFloodFill

Effects

ipDilate

ipEdgeDetection

ipEmboss

ipErode

ipGrayscale

ipInvert

ipMedian

ipSepia

ipSharpen

ipSobel

ipUnsharpMask

Conclusion

Update

nilsnh commented Mar 18, 2017

stale bot commented Dec 6, 2017

github-actions bot commented Mar 10, 2022

wildhaber commented Mar 10, 2017 •

edited

Loading