Improve conversions and support ImageCore (#4)

These are required for compatibility with ImageView and generally fill out the package.

This also changes the design to always use `RGB{N0f8}` for the colors.

Author: timholy

.github/workflows/CI.yml

@@ -18,7 +18,8 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.6'
+          - '1.6'     # 1.6 lacks `@constprop :aggressive` so it's a bit poorly-supported
+          - '1.7'     # therefore make sure we directly test 1.7 as well as more current versions
           - '1'
           - 'nightly'
         os:

.gitignore

@@ -2,4 +2,5 @@
 *.jl.cov
 *.jl.mem
 /Manifest.toml
+/docs/Manifest.toml
 /docs/build/

Project.toml

@@ -13,18 +13,18 @@ Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
 
 [compat]
-ColorTypes = "0.11"
+ColorTypes = "0.11.1"
 ColorVectorSpace = "0.9"
 Colors = "0.12"
-Compat = "3.36"
 FixedPointNumbers = "0.8"
 Reexport = "1"
 Requires = "1"
 julia = "1.6"
 
 [extras]
+ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["StructArrays", "Test"]
+test = ["ImageCore", "StructArrays", "Test"]

README.md

@@ -33,7 +33,33 @@ julia> convert(RGB, c)
 RGB{N0f16}(0.75,0.87549,0.09117)
 ```
 
-The latter is how this color would be rendered in a viewer; embedded in a function, the conversion is extremely well optimized (~2.2ns on the author's machine).
+The latter is how this color would be rendered in a viewer.
+
+## Overflow protection
+
+Depending on the colors you pick for conversion to RGB (e.g., `channels`), it is possible to exceed the 0-to-1 bounds of RGB.
+With the choice above,
+
+```julia
+julia> c = ctemplate(0.99, 0.99)
+(0.99001N0f16₁, 0.99001N0f16₂)
+
+julia> convert(RGB, c)
+ERROR: ArgumentError: component type N0f16 is a 16-bit type representing 65536 values from 0.0 to 1.0,
+  but the values (0.9900053f0, 1.7664759f0, 0.36105898f0) do not lie within this range.
+  See the READMEs for FixedPointNumbers and ColorTypes for more information.
+Stacktrace:
+[...]
+```
+
+If you want to guard against such errors, one good choice would be
+
+```julia
+julia> convert(RGB{Float32}, c)
+RGB{Float32}(0.9900053, 1.7664759, 0.36105898)
+```
+
+Conversions to floating-point types also tend to be faster, since the values do not have to be checked.
 
 ## Advanced usage
 
@@ -43,9 +69,15 @@ However, constructing `ctemplate` as above is an inherently non-inferrable opera
 inferrably, you can use the macro version:
 
 ```julia
-f(i1, i2) = ColorMixture{N0f8}((fluorophore_rgb"EGFP", fluorophore_rgb"tdTomato"), (i1, i2))
+f(i1, i2) = ColorMixture{N0f16}((fluorophore_rgb"EGFP", fluorophore_rgb"tdTomato"), (i1, i2))
 ```
 
-Note the absence of `[]` brackets around the fluorophore names. For such constructors, `N0f8` is the only option if you're
-looking up the RGB values with `fluorophore_rgb`; however, if you hard-code the RGB values there is no restriction
-on the element type.
+Note the absence of `[]` brackets around the fluorophore names.
+
+## Why are the RGB colors encoded in the *type*? Why not a value field?
+
+In many places, JuliaImages assumes that you can convert from one color space to another purely from knowing the type you want to convert to. This would not be possible if the RGB colors were encoded as a second field of the color.
+
+## I wrote some code and got lousy performance. How can I fix it?
+
+To achieve good performance, in some cases the RGB *values* must be aggressively constant-propagated, a feature available only on Julia 1.7 and higher. So if you're experiencing this problem on Julia 1.6, try a newer version.

docs/Manifest.toml

@@ -1,6 +1,6 @@
 module FluorophoreColors
 
-using Compat   # for Compat.@constprop
+using Compat
 
 using Reexport
 @reexport using FixedPointNumbers
@@ -17,6 +17,7 @@ include("utils.jl")
 
 function __init__()
     @require StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a" include("structarrays.jl")
+    @require ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534" include("imagecore.jl")
 end
 
 end

src/FluorophoreColors.jl

@@ -0,0 +1,3 @@
+# clamp01 is designed to work on RGB colors (a major usage is for display), so convert first
+ImageCore.clamp01(c::ColorMixture{T}) where T = convert(RGB{T}, ImageCore.clamp01(convert(RGB{floattype(T)}, c)))
+ImageCore.clamp01nan(c::ColorMixture{T}) where T = convert(RGB{T}, ImageCore.clamp01nan(convert(RGB{floattype(T)}, c)))

src/imagecore.jl

@@ -32,7 +32,7 @@ julia> c = ColorMixture{N0f16}(channelcolors, #= GFP intensity =# 0.2, #= tdToma
 (0.2N0f16₁, 0.85N0f16₂)
 
 julia> convert(RGB, c)
-RGB{N0f16}(0.85,0.9151,0.07294)
+RGB{N0f16}(0.85, 0.9151, 0.07294)
 ```
 
 If you must construct colors inferrably inside a function body, use
@@ -51,30 +51,21 @@ struct ColorMixture{T,N,Cs} <: Color{T,N}
     channels::NTuple{N,T}
 
     Compat.@constprop :aggressive function ColorMixture{T,N,Cs}(channels::NTuple{N}) where {T,N,Cs}
-        Cs isa NTuple{N,RGB{T}} || throw(TypeError(:ColorMixture, "incompatible color types", NTuple{N,RGB{T}}, typeof(Cs)))
+        Cs isa NTuple{N,RGB{N0f8}} || throw(TypeError(:ColorMixture, "", NTuple{N,RGB{N0f8}}, Cs))
         return new{T,N,Cs}(channels)
     end
 end
 ColorMixture{T,N,Cs}(channels::Vararg{Real,N}) where {T,N,Cs} = ColorMixture{T,N,Cs}(channels)
-Compat.@constprop :aggressive ColorMixture{T}(Cs::NTuple{N,RGB{T}}, channels::NTuple{N,Real}) where {T,N} = ColorMixture{T,N,Cs}(channels)
-ColorMixture{T}(Cs::NTuple{N,AbstractRGB}, channels::NTuple{N,Real}) where {T,N} = ColorMixture{T,N,RGB{T}.(Cs)}(channels)
-ColorMixture{T}(Cs::NTuple{N,AbstractRGB}, channels::Vararg{Real,N}) where {T,N} = ColorMixture{T}(Cs, channels)
+Compat.@constprop :aggressive ColorMixture{T}(Cs::NTuple{N,RGB{N0f8}}, channels::NTuple{N,Real}) where {T,N} = ColorMixture{T,N,Cs}(channels)
+Compat.@constprop :aggressive ColorMixture{T}(Cs::NTuple{N,AbstractRGB}, channels::NTuple{N,Real}) where {T,N} = ColorMixture{T,N,RGB{N0f8}.(Cs)}(channels)
+Compat.@constprop :aggressive ColorMixture{T}(Cs::NTuple{N,AbstractRGB}, channels::Vararg{Real,N}) where {T,N} = ColorMixture{T}(Cs, channels)
 
-@inline _promote_typeof(::Type{C1}, ::Type{C2}) where {C1,C2} = promote_type(C1, C2)
-@inline _promote_typeof(::Type{C1}, ::Type{C2}, obj, objs...) where {C1,C2} =
-    _promote_typeof(promote_type(C1, C2), typeof(obj), objs...)
-
-@inline promote_typeof(obj) = typeof(obj)
-@inline promote_typeof(obj1, obj2) = promote_type(typeof(obj1), typeof(obj2))
-@inline promote_typeof(obj1, obj2, objs...) = _promote_type(typeof(obj1), typeof(obj2), objs...)
-
-computeT(Cs::NTuple{N,AbstractRGB}, channels::NTuple{N,Real}) where {N} = eltype(promote_typeof(map(*, Cs, channels)...))
-ColorMixture(Cs::NTuple{N,AbstractRGB}, channels::NTuple{N,Real}) where {N} = ColorMixture{computeT(Cs, channels)}(Cs, channels)
-ColorMixture(Cs::NTuple{N,AbstractRGB}, channels::Vararg{Real,N}) where {N} = ColorMixture{computeT(Cs, channels)}(Cs, channels)
+Compat.@constprop :aggressive ColorMixture(Cs::NTuple{N,AbstractRGB}, channels::NTuple{N,Real}) where {N} = ColorMixture{eltype(map(z -> zero(N0f8)*z, channels))}(Cs, channels)
+Compat.@constprop :aggressive ColorMixture(Cs::NTuple{N,AbstractRGB}, channels::Vararg{Real,N}) where {N} = ColorMixture(Cs, channels)
 
 """
-    cobj = ColorMixture((rgb₁, rgb₂))        # create an all-zeros ColorMixture
-    cobj = ColorMixture{T}((rgb₁, rgb₂))     # same, but coerce the element type
+    cobj = ColorMixture((rgb₁, rgb₂))        # create an all-zeros ColorMixture with N0f8 channel intensities
+    cobj = ColorMixture{T}((rgb₁, rgb₂))     # same, but specify the element type
     c = cobj((i₁, i₂))                       # Construct non-zero ColorMixture (inferrably)
 
 Create a ColorMixture `c` from a "template" `cobj`. `c` will be the same type as `cobj`.
@@ -83,15 +74,15 @@ Create a ColorMixture `c` from a "template" `cobj`. `c` will be the same type as
 is known. In conjunction with a [function barrier](https://docs.julialang.org/en/v1/manual/performance-tips/#kernel-functions),
 this form can be used to circumvent performance problems due to poor inferrability.
 """
-ColorMixture(Cs::NTuple{N,RGB{T}}) where {T,N} = ColorMixture{T}(Cs, ntuple(_ -> zero(T), N))
 ColorMixture{T}(Cs::NTuple{N,AbstractRGB}) where {T,N} = ColorMixture{T}(Cs, ntuple(_ -> zero(T), N))
+ColorMixture(Cs::NTuple{N,RGB{N0f8}}) where {N} = ColorMixture{N0f8}(Cs)
 
 (::ColorMixture{T,N,Cs})(channels::NTuple{N,Real}) where {T,N,Cs} = ColorMixture{T,N,Cs}(channels)
 (::ColorMixture{T,N,Cs})(channels::Vararg{Real,N}) where {T,N,Cs} = ColorMixture{T,N,Cs}(channels)
 
 
-Base.:(==)(a::ColorMixture{Ta,N,Csa}, b::ColorMixture{Tb,N,Csb}) where {Ta,Tb,N,Csa,Csb} =
-    Csa == Csb && a.channels == b.channels
+Base.:(==)(a::ColorMixture{Ta,N,Cs}, b::ColorMixture{Tb,N,Cs}) where {Ta,Tb,N,Cs} = a.channels == b.channels
+Base.:(==)(a::ColorMixture, b::ColorMixture) = false
 
 function Base.show(io::IO, c::ColorMixture)
     print(io, '(')
@@ -103,7 +94,17 @@ function Base.show(io::IO, c::ColorMixture)
     print(io, ')')
 end
 
+# These definitions use floats to avoid overflow
 function Base.convert(::Type{RGB{T}}, c::ColorMixture{T,N,Cs}) where {T,N,Cs}
-    sum(map(*, c.channels, Cs))
+    convert(RGB{T}, sum(map(*, c.channels, Cs); init=zero(RGB{floattype(T)})))
+end
+function Base.convert(::Type{RGB{T}}, c::ColorMixture{R,N,Cs}) where {T,R,N,Cs}
+    convert(RGB{T}, sum(map((w, rgb) -> convert(RGB{floattype(T)}, w*rgb), c.channels, Cs)))
 end
 Base.convert(::Type{RGB}, c::ColorMixture{T}) where T = convert(RGB{T}, c)
+Base.convert(::Type{RGB24}, c::ColorMixture) = convert(RGB24, convert(RGB, c))
+
+ColorTypes._comp(::Val{N}, c::ColorMixture) where N = c.channels[N]
+Compat.@constprop :aggressive ColorTypes.mapc(f, c::ColorMixture{T,N,Cs}) where {T,N,Cs} = ColorMixture(Cs, map(f, c.channels))
+Compat.@constprop :aggressive ColorTypes.mapreducec(f, op, v0, c::ColorMixture{T,N,Cs}) where {T,N,Cs} = mapreduce(f, op, v0, c.channels)
+Compat.@constprop :aggressive ColorTypes.reducec(op, v0, c::ColorMixture{T,N,Cs}) where {T,N,Cs} = reduce(op, c.channels; init=v0)

src/types.jl

@@ -3,6 +3,7 @@ using Test
 
 # interacts via @require
 using StructArrays
+using ImageCore
 
 @testset "FluorophoreColors.jl" begin
     @test isempty(detect_ambiguities(FluorophoreColors))
@@ -30,6 +31,27 @@ using StructArrays
         @test c.channels[1] == c.channels[2] == 0.5
         @test convert(RGB, c) ≈ 0.5*channels[1] + 0.5*channels[2]
 
+        fchannels = float.(channels)
+        if Base.VERSION >= v"1.8.0-DEV.363"
+            @test_throws r"ColorMixture.*expected Tuple{RGB{N0f8}, +RGB{N0f8}}.*got a value of type Tuple{RGB{Float32}, +RGB{Float32}}" ColorMixture{Float32,2,fchannels}(0.1, 0.2)
+        else
+            @test_throws TypeError ColorMixture{Float32,2,fchannels}(0.1, 0.2)
+        end
+
+        # Overflow behavior
+        ctemplate = ColorMixture{N0f8}((RGB(1, 0, 0), RGB(0.5, 0.5, 0)))
+        c = ctemplate(0.8, 0.8)
+        if Base.VERSION >= v"1.8.0-DEV.363"
+            @test_throws "the values (1.2f0, 0.4f0, 0.0f0) do not lie within this range" convert(RGB{N0f8}, c)
+            @test_throws "the values (1.2f0, 0.4f0, 0.0f0) do not lie within this range" convert(RGB24, c)
+            @test_throws "the values (1.2f0, 0.4f0, 0.0f0) do not lie within this range" convert(RGB, c)
+        else
+            @test_throws ArgumentError convert(RGB{N0f8}, c)
+            @test_throws ArgumentError convert(RGB24, c)
+            @test_throws ArgumentError convert(RGB, c)
+        end
+        @test convert(RGB{Float32}, c) === RGB{Float32}(1.2, 0.4, 0)
+
         # Macro syntax & inferrability
         f_infer(i1, i2) = ColorMixture{N0f8}((fluorophore_rgb"EGFP", fluorophore_rgb"tdTomato"), (i1, i2))
         f_noinfer(i1, i2) = ColorMixture((fluorophore_rgb["EGFP"], fluorophore_rgb["tdTomato"]), (i1, i2))
@@ -47,6 +69,19 @@ using StructArrays
         @test @inferred(ctmpl(1, 0)) === ColorMixture{N0f8}(channels, (1, 0))
     end
 
+    @testset "mapc etc" begin
+        channels = (fluorophore_rgb["EGFP"], fluorophore_rgb["tdTomato"])
+        ctemplate = ColorMixture{N0f8}(channels)
+        c = ctemplate(0.4, 0.2)
+        if Base.VERSION >= v"1.7"
+            @test @inferred(mapc(x->2x, c)) === ColorMixture{Float32}(channels, (0.8, 0.4))
+        else
+            @test_broken @inferred(mapc(x->2x, c)) === ColorMixture{Float32}(channels, (0.8, 0.4))
+        end
+        @test @inferred(mapreducec(x->2x, +, c)) === 1.2f0
+        @test @inferred(reducec(+, c)) === reduce(+, (0.4N0f8, 0.2N0f8))
+    end
+
     @testset "StructArrays" begin
         channels = (fluorophore_rgb["EGFP"], fluorophore_rgb["tdTomato"])
         ctemplate = ColorMixture(channels)
@@ -72,6 +107,19 @@ using StructArrays
         @test soa[1] == ctemplate(ntuple(i->(i-1)/32, 16))
     end
 
+    @testset "ImageCore" begin
+        # Integration with the rest of the JuliaImages ecosystem
+        ctemplate = ColorMixture{N0f8}((RGB(1, 0, 0), RGB(0.5, 0.5, 0)))
+        c = ctemplate(0.8, 0.8)
+        @test convert(RGB{Float32}, c) === RGB{Float32}(1.2, 0.4, 0)
+        @test clamp01(c)    === RGB{N0f8}(1, 0.4, 0)
+        @test clamp01nan(c) === RGB{N0f8}(1, 0.4, 0)
+        ctemplate = ColorMixture{Float32}((RGB(1, 0, 0), RGB(0.5, 0.5, 0)))
+        c = ctemplate(0.8, NaN)
+        @test isequal(convert(RGB, c), RGB{Float32}(NaN,NaN,NaN))
+        @test clamp01nan(c) === RGB{Float32}(0, 0, 0)
+    end
+
     @testset "IO" begin
         channels = (fluorophore_rgb["EGFP"], fluorophore_rgb["tdTomato"])
         c = ColorMixture(channels, (1, 0))