Add normalize_hue and Enhance hue handling in range

[kimikage]

This adds a new function normalize_hue, which simply wraps the hue angles to [0,360].
This PR does not solve the issue #379, but adding the hue normalization to weighted_color_mean helps handle hues in range.

[timholy]

Technically correct but I worry "exceptionally support" may be misunderstood as implying "exceptional support" (in the sense of "really great support"). Is the unusual nature of this support worthy of such a mention? We're not normalizing construction in general, right?

[kimikage]

Sorry, I'm not good with words.

We're not normalizing construction in general, right?

Thats's right.
There are probably two perspectives. Some people may think that we "can use" the hues out of the range [0,360] because there is no normalization in constructors, Other people may think that we "should not use" the hues out of the range because there is no normalization in constructors.

I'm in the latter because we have problems like #379. However, range and weighted_color_mean can "safely" use out-of-range hues. This is an exceptional case.

How should that be expressed in words?

[timholy]

How about just say that they support them (get rid of the word "exceptionally"), and then after your examples say

While sometimes useful in particular circumstances, typically it is recommended that the hue be within [0, 360] (see [`normalize_hue`](@ref)).

[kimikage]

At the moment, I have not exported normalize_hue, so it is not included in the documentation. Should we export it?

Edit:
I exported normalize_hue and added its docstring to the docs.
I have no objection to extending it if necessary. (cf. #379 (comment))

Edit2:
I un-exported normalize_hue, but left its docstring in the docs. Sorry for the indecision.:sweat_smile:

[timholy]

Probably not, but you can say "see ColorTypes.normalize_hue".

[kimikage]

I'm very sorry, I tried to push the un-exported version, but it failed.:scream:
Please use normalize_hue a lot.:sob:

[codecov]

Codecov Report

Merging #405 into master will increase coverage by 0.11%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #405      +/-   ##
==========================================
+ Coverage   80.27%   80.38%   +0.11%     
==========================================
  Files          11       11              
  Lines         877      877              
==========================================
+ Hits          704      705       +1     
+ Misses        173      172       -1     

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 41bb9bb...3c37547. Read the comment docs.

[kimikage]

Note to self:

julia> versioninfo()
Julia Version 1.3.1
Commit 2d5741174c (2019-12-30 21:36 UTC)
Platform Info:
  OS: Linux (x86_64-pc-linux-gnu)
  CPU: Intel(R) Core(TM) i7-8565U CPU @ 1.80GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-6.0.1 (ORCJIT, skylake)

julia> mod360(c::C) where {C <: HSV} = C(mod(c.h, 360), c.s, c.v)
mod360 (generic function with 1 method)

julia> @benchmark mod360.(view(mat32,:,:))
BenchmarkTools.Trial:
  memory estimate:  48.34 KiB
  allocs estimate:  11
  --------------
  minimum time:     15.100 μs (0.00% GC)
  median time:      15.400 μs (0.00% GC)
  mean time:        20.468 μs (2.66% GC)
  maximum time:     721.500 μs (88.51% GC)
  --------------
  samples:          10000
  evals/sample:     1

julia> @benchmark Colors.normalize_hue.(view(mat32,:,:))
BenchmarkTools.Trial:
  memory estimate:  48.34 KiB
  allocs estimate:  11
  --------------
  minimum time:     4.557 μs (0.00% GC)
  median time:      4.943 μs (0.00% GC)
  mean time:        5.927 μs (7.83% GC)
  maximum time:     101.286 μs (54.57% GC)
  --------------
  samples:          10000
  evals/sample:     7