8000 Document images.Color.Luminance and images.Color.ColorHex · gohugoio/hugoDocs@0442f82 · GitHub
[go: up one dir, main page]
Skip to content

Commit

Permalink
Document images.Color.Luminance and images.Color.ColorHex
Browse files Browse the repository at this point in the history
  • Loading branch information
@jmooring
jmooring authored Apr 25, 2024
1 parent d58b0b2 commit 0442f82
Show file tree
Hide file tree
Showing 3 changed files with 176 additions and 13 deletions.
24 changes: 16 additions & 8 deletions content/en/content-management/shortcodes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -416,31 +416,39 @@ The youtube shortcode accepts these named parameters:
id
: (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.

allowFullScreen {{< new-in 0.125.0 >}}
allowFullScreen
{{< new-in 0.125.0 >}}
: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.

autoplay {{< new-in 0.125.0 >}}
autoplay
{{< new-in 0.125.0 >}}
: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.

class
: (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.

controls {{< new-in 0.125.0 >}}
controls
{{< new-in 0.125.0 >}}
: (`bool`) Whether to display the video controls. Default is `true`.

end {{< new-in 0.125.0 >}}
end
{{< new-in 0.125.0 >}}
: (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.

loading {{< new-in 0.125.0 >}}
loading
{{< new-in 0.125.0 >}}
: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.

loop {{< new-in 0.125.0 >}}
loop
{{< new-in 0.125.0 >}}
: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.

mute {{< new-in 0.125.0 >}}
mute
{{< new-in 0.125.0 >}}
: (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.

start {{< new-in 0.125.0 >}}
start
{{< new-in 0.125.0 >}}
: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.

title
Expand Down
163 changes: 159 additions & 4 deletions content/en/methods/resource/Colors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,173 @@ categories: []
keywords: []
action:
related: []
returnType: '[]string'
returnType: '[]images.Color'
signatures: [RESOURCE.Colors]
toc: true
math: true
---

{{< new-in 0.104.0 >}}

The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.

{{% include "methods/resource/_common/global-page-remote-resources.md" %}}

## Methods

Each color is an object with the following methods:

8000 ColorHex
{{< new-in 0.125.0 >}}
: (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign.

Luminance
{{< new-in 0.125.0 >}}
: (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.

{{% note %}}
Image filters such as [`images.Overlay`] and [`images.Padding`] will accept either a hexadecimal color value or an `images.Color` object.

Hugo renders an `images.Color` object as a hexadecimal color value.

[`images.Overlay`]: /functions/images/overlay/
[`images.Padding`]: /functions/images/padding/
{{% /note %}}

[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance

## Sorting

As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:

```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974]
<table>
<thead>
<tr>
<th>Color</th>
<th>Relative luminance</th>
</tr>
</thead>
<tbody>
{{ range .Colors }}
<tr>
<td>{{ .ColorHex }}</td>
<td>{{ .Luminance | lang.FormatNumber 4 }}</td>
</tr>
{{ end }}
</tbody>
</table>
{{ end }}
```

This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled image.
Hugo renders this to:

{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
ColorHex|Relative luminance
:--|:--
`#bebebd`|`0.5145`
`#514947`|`0.0697`
`#768a9a`|`0.2436`
`#647789`|`0.1771`
`#90725e`|`0.1877`
`#a48974`|`0.2704`

To sort by dominance with the least dominant color first:

```go-html-template
{{ range .Colors | collections.Reverse }}
```

To sort by relative luminance with the darkest color first:

```go-html-template
{{ range sort .Colors "Luminance" }}
```

To sort by relative luminance with the lightest color first, use either of these constructs:

```go-html-template
{{ range sort .Colors "Luminance" | collections.Reverse }}
{{ range sort .Colors "Luminance" "desc" }}
```

## Examples

### Image borders

To add a 5 pixel border to an image using the most dominant color:

```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ $mostDominant := index .Colors 0 }}
{{ $filter := images.Padding 5 $mostDominant }}
{{ with .Filter $filter }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```

To add a 5 pixel border to an image using the darkest dominant color:

```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ $darkest := index (sort .Colors "Luminance") 0 }}
{{ $filter := images.Padding 5 $darkest }}
{{ with .Filter $filter }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```

### Light text on dark background

To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:

```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ $darkest := index (sort .Colors "Luminance") 0 }}
{{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
<div style="background: {{ $darkest }};">
<div style="color: {{ $lightest }};">
<p>This is light text on a dark background.</p>
</div>
</div>
{{ end }}
```

### WCAG contrast ratio

Check warning on line 143 in content/en/methods/resource/Colors.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (WCAG)

In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?

The WCAG defines the [contrast ratio] as:

Check warning on line 147 in content/en/methods/resource/Colors.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (WCAG)

$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$

where $L_1$ is the relative luminance of the lighest color and $L_2$ is the relative luminance of the darkest color.

Check warning on line 151 in content/en/methods/resource/Colors.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (lighest)

Calculate the contrast ratio to determine WCAG conformance:

Check warning on line 153 in content/en/methods/resource/Colors.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (WCAG)

```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
{{ $darkest := index (sort .Colors "Luminance") 0 }}
{{ $cr := div
(add $lightest.Luminance 0.05)
(add $darkest.Luminance 0.05)
}}
{{ if ge $cr 7.5 }}
{{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
{{ else if ge $cr 4.5 }}
{{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
{{ else }}
{{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
{{ end }}
{{ end }}
```


[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
2 changes: 1 addition & 1 deletion layouts/shortcodes/new-in.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
{{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }}
{{- end }}
{{- else }}
<a class="f5 fw6 ba bw1 b--gray ph2 mr2 mt2" href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
<a class="dib f5 fw6 ba bw1 b--gray ph2 mt1" href="{{ printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}">New in v{{ $version }}</a>
{{- end }}
{{- else }}
{{- errorf "The %q shortcode requires a positional parameter (version). See %s" .Name .Position }}
Expand Down

0 comments on commit 0442f82

Please sign in to comment.
0