Merge pull request #338 from johnnychen94/colordiff

enhance Colordiff API

Author: cormullion

docs/src/colorspaces.md

@@ -95,22 +95,18 @@ whitebalance
 
 ## Color Difference
 
-The `colordiff()` function gives an approximate value for the difference between two colors.
+The `colordiff` function gives an approximate value for the difference between two colors.
 
 ```
 julia> colordiff(colorant"red", parse(Colorant, HSB(360, 0.75, 1)))
 8.178248292426845
 ```
 
-`colordiff(a::Color, b::Color)`
+`colordiff(a::Color, b::Color; metric::DifferenceMetric=DE_2000())`
 
-Evaluate the [CIEDE2000](http://en.wikipedia.org/wiki/Color_difference#CIEDE2000) color difference formula. This gives an approximate measure of the perceptual difference between two colors to a typical viewer. A larger number is returned for increasingly distinguishable colors.
+Evaluate the [CIEDE2000](http://en.wikipedia.org/wiki/Color_difference#CIEDE2000) color difference formula by default. This gives an approximate measure of the perceptual difference between two colors to a typical viewer. A larger number is returned for increasingly distinguishable colors.
 
-`colordiff(a::Color, b::Color, m::DifferenceMetric)`
-
-Evaluate the color difference formula specified by the supplied `DifferenceMetric`.
-
-Options are as follows:
+Options for `DifferenceMetric` are as follows:
 
 | Option                                                 | Action                                        |
 | ----------                                             | -------                                       |

src/differences.jl

@@ -99,7 +99,7 @@ pow7(x::Integer) = pow7(Float64(x))
 const twentyfive7 = pow7(25)
 
 # Delta E 2000
-function colordiff(ai::Color, bi::Color, m::DE_2000)
+function _colordiff(ai::Color, bi::Color, m::DE_2000)
     # Ensure that the input values are in L*a*b* space
     a_Lab = convert(Lab, ai)
     b_Lab = convert(Lab, bi)
@@ -162,7 +162,7 @@ function colordiff(ai::Color, bi::Color, m::DE_2000)
 end
 
 # Delta E94
-function colordiff(ai::Color, bi::Color, m::DE_94)
+function _colordiff(ai::Color, bi::Color, m::DE_94)
 
     a = convert(LCHab, ai)
     b = convert(LCHab, bi)
@@ -192,7 +192,7 @@ function colordiff(ai::Color, bi::Color, m::DE_94)
 end
 
 # Metric form of jpc79 color difference equation (mostly obsolete)
-function colordiff(ai::Color, bi::Color, m::DE_JPC79)
+function _colordiff(ai::Color, bi::Color, m::DE_JPC79)
 
     # Convert directly into LCh
     a = convert(LCHab, ai)
@@ -242,7 +242,7 @@ end
 
 
 # Metric form of the cmc color difference
-function colordiff(ai::Color, bi::Color, m::DE_CMC)
+function _colordiff(ai::Color, bi::Color, m::DE_CMC)
 
     # Convert directly into LCh
     a = convert(LCHab, ai)
@@ -297,7 +297,7 @@ function colordiff(ai::Color, bi::Color, m::DE_CMC)
 end
 
 # The BFD color difference equation
-function colordiff(ai::Color, bi::Color, m::DE_BFD)
+function _colordiff(ai::Color, bi::Color, m::DE_BFD)
 
     # We have to start back in XYZ because BFD uses a different L equation
     a_XYZ = convert(XYZ, ai, m.wp)
@@ -357,7 +357,7 @@ function colordiff(ai::Color, bi::Color, m::DE_BFD)
 end
 
 # Delta E*ab (the original)
-function colordiff(ai::Color, bi::Color, m::DE_AB)
+function _colordiff(ai::Color, bi::Color, m::DE_AB)
 
     # Convert directly into L*a*b*
     a = convert(Lab, ai)
@@ -377,7 +377,7 @@ end
 #
 # Returns:
 #   The DIN99 color difference metric evaluated between a and b.
-function colordiff(ai::Color, bi::Color, m::DE_DIN99)
+function _colordiff(ai::Color, bi::Color, m::DE_DIN99)
 
     a = convert(DIN99, ai)
     b = convert(DIN99, bi)
@@ -387,7 +387,7 @@ function colordiff(ai::Color, bi::Color, m::DE_DIN99)
 end
 
 # A color difference formula for the DIN99d uniform colorspace
-function colordiff(ai::Color, bi::Color, m::DE_DIN99d)
+function _colordiff(ai::Color, bi::Color, m::DE_DIN99d)
 
     a = convert(DIN99d, ai)
     b = convert(DIN99d, bi)
@@ -397,7 +397,7 @@ function colordiff(ai::Color, bi::Color, m::DE_DIN99d)
 end
 
 # The DIN99o color difference metric evaluated between colors a and b.
-function colordiff(ai::Color, bi::Color, m::DE_DIN99o)
+function _colordiff(ai::Color, bi::Color, m::DE_DIN99o)
 
     a = convert(DIN99o, ai)
     b = convert(DIN99o, bi)
@@ -408,12 +408,18 @@ end
 
 # Default to Delta E 2000
 """
-    colordiff(a, b)
-    colordiff(a, b, metric)
+    colordiff(a, b; metric::DifferenceMetric=DE_2000())
 
 Compute an approximate measure of the perceptual difference between
 colors `a` and `b`.  Optionally, a `metric` may be supplied, chosen
 among `DE_2000` (the default), `DE_94`, `DE_JPC79`, `DE_CMC`,
 `DE_BFD`, `DE_AB`, `DE_DIN99`, `DE_DIN99d`, `DE_DIN99o`.
 """
-colordiff(ai::Color, bi::Color) = colordiff(ai::Color, bi::Color, DE_2000())
+colordiff(ai::Union{Number, Color},
+          bi::Union{Number, Color};
+          metric::DifferenceMetric=DE_2000()) = _colordiff(ai, bi, metric)
+@deprecate colordiff(ai::Color, bi::Color, metric::DifferenceMetric) colordiff(ai, bi; metric=metric)
+
+_colordiff(ai::AbstractGray, bi::Number, metric::DifferenceMetric) = _colordiff(ai, Gray(bi), metric)
+_colordiff(ai::Number, bi::AbstractGray, metric::DifferenceMetric) = _colordiff(Gray(ai), bi, metric)
+_colordiff(ai::Number, bi::Number, metric::DifferenceMetric) = _colordiff(Gray(ai), Gray(bi), metric)

test/colordiff.jl

@@ -51,9 +51,12 @@ using Colors
 
     let a, b
         for (i, (a, b, dexpect)) in enumerate(abds)
-            @test abs(dexpect - colordiff(Lab(a...), Lab(b...), metric)) < eps_cdiff
-            @test abs(dexpect - colordiff(Lab(b...), Lab(a...), metric)) < eps_cdiff
+            @test abs(dexpect - colordiff(Lab(a...), Lab(b...); metric=metric)) < eps_cdiff
+            @test abs(dexpect - colordiff(Lab(b...), Lab(a...); metric=metric)) < eps_cdiff
         end
     end
 
+    a, b = rand(100), rand(100)
+    @test all(@. colordiff(a, b) == colordiff(Gray(a), b) == colordiff(a, Gray(b)) == colordiff(Gray(a), Gray(b)))
+
 end # @testset

test/din99.jl

@@ -39,7 +39,7 @@ using Colors
             # This is not a real test of the color difference metric, but at least
             # makes sure it isn't doing anything really crazy.
             metric = DE_DIN99()
-            @test (abs(colordiff(convert(DIN99, Lab(a...)), DIN99(b...), metric)) < diffeps)
+            @test (abs(colordiff(convert(DIN99, Lab(a...)), DIN99(b...); metric=metric)) < diffeps)
         end
     end
 end  # @testset