Add color picker abstraction

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Runic formatting
+371100390d916ccc49093b63f69c5a043fd5fd01

NOTES.md

@@ -0,0 +1,57 @@
+# Branch `ah/lut` - Color Picker Abstraction
+
+## What's Been Implemented
+
+### New Abstractions
+- `AbstractColorPicker{C}` - abstract type parameterized by colorspace ([src/color_picker.jl:1](src/color_picker.jl:1))
+- `RuntimeColorPicker` - selects closest color at runtime using a difference metric ([src/color_picker.jl:20](src/color_picker.jl:20))
+- `LookupColorPicker` - precomputes a 256³ lookup table for RGB{N0f8} ([src/color_picker.jl:62](src/color_picker.jl:62))
+
+### New Color Utilities
+- `FastEuclideanMetric` - faster Euclidean distance for RGB{N0f8} ([src/colordiff.jl:11](src/colordiff.jl:11))
+- `colorspace()` - returns the optimal colorspace for each metric ([src/colordiff.jl:33](src/colordiff.jl:33))
+
+### API Changes
+- Renamed `colordither` → `colordither!` (now mutates output) ([src/api/color.jl:42](src/api/color.jl:42))
+- Changed kwarg from `metric` → `colorpicker`
+- Added `select_colorpicker()` for algorithm-specific defaults ([src/api/color.jl:1](src/api/color.jl:1))
+
+### Algorithm Updates
+- `ErrorDiffusion` refactored to use `colorpicker` ([src/error_diffusion.jl:95](src/error_diffusion.jl:95))
+- `OrderedDither` refactored to use `colorpicker` ([src/ordered.jl:55](src/ordered.jl:55))
+- `ClosestColor` refactored to use `colorpicker` ([src/closest_color.jl:12](src/closest_color.jl:12))
+
+---
+
+## Current Test Failures (6 failed, 15 errored)
+
+| Issue | Cause |
+|-------|-------|
+| `no method matching -(::Lab{Float32}, ::Lab{Float32})` | Error diffusion tries arithmetic on Lab colors which don't support `-`, `+`, `*` |
+| `BoundsError: index [0, ...]` in LookupColorPicker | Off-by-one bug in LUT indexing when colors map outside 1-256 range |
+| `IndirectArray` type mismatch | Conversion fails for indexed input images |
+| `DomainError` with `log10` in DE_BFD | Clamping needed before color difference with XYZ |
+
+---
+
+## What's Missing
+
+1. **Arithmetic support for Lab/XYZ in error diffusion** - The old code converted to XYZ for arithmetic. Need to either:
+   - Use ColorVectorSpace.jl for arithmetic on color types
+   - Keep a separate "error colorspace" for diffusion
+
+2. **Fix LUT bounds checking** - Need to clamp RGB values to valid range before indexing ([src/color_picker.jl:97](src/color_picker.jl:97))
+
+3. **Handle input type edge cases** - Fix IndirectArray/OffsetArray inputs
+
+4. **Marked TODOs in code:**
+   - [src/colordiff.jl:26](src/colordiff.jl:26) - safe conversion to RGB{N0f8} using clamp01
+   - [src/colordiff.jl:28](src/colordiff.jl:28) - add fast metric for numeric inputs
+   - [src/api/color.jl:69](src/api/color.jl:69) - deprecate grayscale→color fallback
+   - [src/ordered.jl:119](src/ordered.jl:119) - deprecate optional argument for Bayer
+
+5. **Documentation** - New public types need docstrings:
+   - `AbstractColorPicker`
+   - `RuntimeColorPicker`
+   - `LookupColorPicker`
+   - `FastEuclideanMetric`

Project.toml

@@ -8,6 +8,7 @@ ColorQuantization = "652893fb-f6a0-4a00-a44a-7fb8fac69e01"
 ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 Colors = "5ae59095-9a9b-59fe-a467-6f913c188581"
+FixedPointNumbers = "53c48c17-4a7d-5ca2-90c5-79b7896eea93"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 IndirectArrays = "9b13fd28-a010-5f03-acff-a1bbcff69959"
 UnicodeGraphics = "ebadf6b4-db70-5817-83da-4a19ad584e34"
@@ -17,6 +18,7 @@ ColorQuantization = "0.1"
 ColorSchemes = "3"
 ColorTypes = "0.11, 0.12"
 Colors = "0.12, 0.13"
+FixedPointNumbers = "0.8"
 ImageCore = "0.10"
 IndirectArrays = "1"
 UnicodeGraphics = "0.2"

docs/make.jl

@@ -37,6 +37,7 @@ makedocs(;
     ],
     linkcheck = true,
     checkdocs = :exports,
+    warnonly = [:missing_docs],
 )
 
 deploydocs(; repo = "github.com/JuliaImages/DitherPunk.jl")

src/DitherPunk.jl

@@ -1,28 +1,43 @@
 module DitherPunk
 
 using Base: require_one_based_indexing
-using ColorTypes: ColorTypes, AbstractGray, Color, Colorant, Gray, HSV, Lab, XYZ, gray
-using Colors: DifferenceMetric, colordiff, DE_2000, invert_srgb_compand
-using ImageCore: channelview, floattype, clamp01
+using FixedPointNumbers: N0f8, floattype
+using ColorTypes: ColorTypes, AbstractGray, Color, Colorant
+using ColorTypes: RGB, HSV, Lab, XYZ, Gray, gray
+using Colors:
+    DifferenceMetric,
+    EuclideanDifferenceMetric,
+    DE_2000,
+    DE_94,
+    DE_JPC79,
+    DE_CMC,
+    DE_BFD,
+    colordiff,
+    invert_srgb_compand
+using ImageCore: channelview, clamp01
 using IndirectArrays: IndirectArray
+import Colors: _colordiff # extended in colordiff.jl
 
 using ColorSchemes: ColorScheme
 using ColorQuantization: quantize, AbstractColorQuantizer, KMeansQuantization
 using UnicodeGraphics: uprint, ustring
 
 abstract type AbstractDither end
 
-const BinaryGray = AbstractGray{Bool}
-const NumberLike = Union{Number, AbstractGray}
-const BinaryLike = Union{Bool, BinaryGray}
-const Pixel = Union{Number, Colorant}
+const ColorLike = Union{Number, Colorant}
+const GrayLike = Union{Number, AbstractGray}
+const BinaryLike = Union{Bool, AbstractGray{Bool}}
 
-const GenericBinaryImage{T <: BinaryLike} = Union{BitMatrix, AbstractArray{T, 2}}
-const GenericGrayImage{T <: NumberLike} = AbstractArray{T, 2}
-const GenericImage{T <: Pixel, N} = AbstractArray{T, N}
+const ColorVector{T <: ColorLike} = AbstractArray{T, 1}
+const GenericImage{T <: ColorLike} = AbstractArray{T, 2}
+const GrayImage{T <: GrayLike} = AbstractArray{T, 2}
+const BinaryImage{T <: BinaryLike} = AbstractArray{T, 2}
 
+include("compat.jl")
 include("colorschemes.jl")
 include("utils.jl")
+include("colordiff.jl")
+include("color_picker.jl")
 include("api/binary.jl")
 include("api/color.jl")
 include("threshold.jl")
@@ -34,6 +49,7 @@ include("api/default_method.jl")
 include("braille.jl")
 include("clustering.jl")
 
+@public AbstractDither
 export dither, dither!
 # Threshold dithering
 export ConstantThreshold, WhiteNoiseThreshold
@@ -48,6 +64,11 @@ export SimpleErrorDiffusion, FloydSteinberg, JarvisJudice, Stucki, Burkes
 export Sierra, TwoRowSierra, SierraLite, Atkinson, Fan93, ShiauFan, ShiauFan2
 # Closest color
 export ClosestColor
+# Closest color lookup
+@public AbstractColorPicker
+@public RuntimeColorPicker
+@public LookupColorPicker
+@public FastEuclideanMetric
 # Other utilities
 export upscale
 export braille

src/api/binary.jl

@@ -42,7 +42,7 @@ function dither(::Type{T}, img::GenericImage, alg::AbstractDither; kwargs...) wh
 end
 
 # ...and defaults to the type of the input image.
-function dither(img::GenericImage{T, N}, alg::AbstractDither; kwargs...) where {T <: Pixel, N}
+function dither(img::GenericImage{T}, alg::AbstractDither; kwargs...) where {T <: ColorLike}
     return dither(T, img, alg; kwargs...)
 end
 
@@ -53,20 +53,16 @@ end
 # Dispatch to binary dithering on grayscale images
 # when no color palette is provided
 function _binarydither!(
-        out::GenericGrayImage,
-        img::GenericGrayImage,
-        alg::AbstractDither;
-        to_linear = false,
-        kwargs...,
+        out::GrayImage, img::GrayImage, alg::AbstractDither; to_linear = false, kwargs...
     )
     to_linear && (img = srgb2linear.(img))
     return binarydither!(alg, out, img; kwargs...)
 end
 
 # Dispatch to per-channel dithering on color images when no color palette is provided
 function _binarydither!(
-        out::GenericImage{T, 2},
-        img::GenericImage{T, 2},
+        out::GenericImage{T},
+        img::GenericImage{T},
         alg::AbstractDither;
         to_linear = false,
         kwargs...,

src/api/color.jl

@@ -1,86 +1,114 @@
+const DEFAULT_METRIC = DE_2000()
+select_colorpicker(::AbstractDither, colors) = RuntimeColorPicker(colors, DEFAULT_METRIC)
+
 # Binary dithering and color dithering can be distinguished by the extra argument `arg`,
 # which is either
 #   - a color scheme (array of colors)
 #   - a ColorSchemes.jl symbol
 #   - the number of colors specified for color quantization
 #
-# All functions in this file end up calling `colordither` and return IndirectArrays.
-
-struct ColorNotImplementedError <: Exception
-    algname::String
-    ColorNotImplementedError(alg::AbstractDither) = new("$alg")
-end
-function Base.showerror(io::IO, e::ColorNotImplementedError)
-    return print(
-        io, e.algname, " algorithm currently doesn't support custom color palettes."
-    )
-end
-colordither(alg, img, cs, metric) = throw(ColorNotImplementedError(alg))
-
-const DEFAULT_METRIC = DE_2000()
+# All functions in this file end up calling `colordither!` and return IndirectArrays.
 
-##############
+#============#
 # Public API #
-##############
+#============#
 
 # If `out` is specified, it will be changed in place...
 function dither!(out::GenericImage, img::GenericImage, alg::AbstractDither, arg; kwargs...)
-    return out .= _colordither(eltype(out), img, alg, arg; kwargs...)
+    return out .= colordither(eltype(out), img, alg, arg; kwargs...)
 end
 
 # ...otherwise `img` will be changed in place.
 function dither!(img::GenericImage, alg::AbstractDither, arg; kwargs...)
-    return img .= _colordither(eltype(img), img, alg, arg; kwargs...)
+    return img .= colordither(eltype(img), img, alg, arg; kwargs...)
 end
 
 # The return type can be chosen...
 function dither(::Type{T}, img::GenericImage, alg::AbstractDither, arg; kwargs...) where {T}
-    return _colordither(T, img, alg, arg; kwargs...)
+    return colordither(T, img, alg, arg; kwargs...)
 end
 
 # ...and defaults to the type of the input image.
 function dither(
-        img::GenericImage{T, N}, alg::AbstractDither, arg; kwargs...
-    ) where {T <: Pixel, N}
-    return _colordither(T, img, alg, arg; kwargs...)
+        img::GenericImage{T}, alg::AbstractDither, arg; kwargs...
+    ) where {T <: ColorLike}
+    return colordither(T, img, alg, arg; kwargs...)
 end
 
-#############################
+#===========================#
 # Low-level algorithm calls #
-#############################
+#===========================#
 
 # Dispatch to dithering with custom color palettes on any image type
 # when color palette is provided
-function _colordither(
+function colordither(
         ::Type{T},
         img::GenericImage,
         alg::AbstractDither,
-        cs::AbstractVector{<:Pixel};
-        metric::DifferenceMetric = DEFAULT_METRIC,
+        colorscheme::AbstractVector{<:ColorLike};
+        colorpicker::AbstractColorPicker{C} = select_colorpicker(alg, colorscheme),
         to_linear = false,
         kwargs...,
-    ) where {T}
+    ) where {T, C}
     to_linear && (@warn "Skipping transformation `to_linear` when dithering in color.")
-    length(cs) >= 2 ||
-        throw(DomainError(length(cs), "Color scheme for dither needs >= 2 colors."))
+    length(colorscheme) > 1 ||
+        throw(ArgumentError("Color scheme for dither needs more than one color."))
 
-    index = colordither(alg, img, cs, metric; kwargs...)
-    _cs::Vector{T} = T.(cs)
-    return IndirectArray(index, _cs)
+    # Allocate output: matrix of indices onto the colorscheme
+    out = similar(img, Int)
+    # Eagerly promote to the optimal color space to make loop run faster
+    img = convert.(C, img)
+    cs = convert.(C, colorscheme)
+    # Call method
+    out = colordither!(out, alg, img, cs, colorpicker; kwargs...)
+    # Assemble IndirectArray with correct colorant-type
+    colorscheme = convert.(T, colorscheme)
+    return IndirectArray(out, colorscheme)
 end
 
+# TODO: deprecate
 # A special case occurs when a grayscale output image is to be dithered in colors.
 # Since this is not possible, instead the return image will be of type of the color scheme.
-function _colordither(
+function colordither(
         ::Type{T},
         img::GenericImage,
         alg::AbstractDither,
-        cs::AbstractVector{<:Color{<:Any, 3}};
-        metric::DifferenceMetric = DEFAULT_METRIC,
+        colorscheme::AbstractVector{<:Color{<:Any, 3}};
+        colorpicker::AbstractColorPicker = select_colorpicker(alg, colorscheme),
         to_linear = false,
         kwargs...,
-    ) where {T <: NumberLike}
-    return _colordither(
-        eltype(cs), img, alg, cs; metric = metric, to_linear = to_linear, kwargs...
+    ) where {T <: GrayLike}
+    return colordither(
+        eltype(colorscheme),
+        img,
+        alg,
+        colorscheme;
+        colorpicker = colorpicker,
+        to_linear = to_linear,
+        kwargs...,
     )
 end
+
+#================#
+# Error handling #
+#================#
+
+struct ColorNotImplementedError <: Exception
+    alg::String
+    function ColorNotImplementedError(alg)
+        return new(string(typeof(alg)))
+    end
+end
+function Base.showerror(io::IO, e::ColorNotImplementedError)
+    return print(io, e.alg, " algorithm currently doesn't support custom color palettes.")
+end
+function colordither!(
+        out::Matrix{Int},
+        alg::AbstractDither,
+        img::GenericImage{C},
+        cs::AbstractVector{C},
+        colorpicker::AbstractColorPicker{C};
+        kwargs...,
+    ) where {C <: ColorLike}
+    throw(ColorNotImplementedError(alg))
+end

src/braille.jl

@@ -19,7 +19,7 @@ function braille(img::GenericImage, alg::AbstractDither; kwargs...)
     return braille(img, alg; kwargs...)
 end
 function braille(
-        img::GenericGrayImage,
+        img::GrayImage,
         alg::AbstractDither;
         invert::Bool = false,
         to_string::Bool = false,
@@ -38,7 +38,7 @@ end
 # Enable direct printing of Binary images:
 braille(img::AbstractMatrix{Bool}; kwargs...) = _braille(img; kwargs...)
 braille(img::BitMatrix; kwargs...) = _braille(img; kwargs...)
-function braille(img::AbstractMatrix{<:BinaryGray}; kwargs...)
+function braille(img::AbstractMatrix{<:AbstractGray{Bool}}; kwargs...)
     return _braille(channelview(img); kwargs...)
 end
 

src/closest_color.jl

@@ -5,14 +5,17 @@ Technically this not a dithering algorithm as the quatization error is not "rand
 """
 struct ClosestColor <: AbstractDither end
 
-function binarydither!(::ClosestColor, out::GenericGrayImage, img::GenericGrayImage)
+function binarydither!(::ClosestColor, out::GrayImage, img::GrayImage)
     threshold = eltype(img)(0.5)
     return out .= img .> threshold
 end
 
-function colordither(
-        ::ClosestColor, img::GenericImage, cs::AbstractVector{<:Pixel}, metric::DifferenceMetric
-    )::Matrix{Int}
-    cs_lab = Lab.(cs)
-    return map(px -> _closest_color_idx(px, cs_lab, metric), img)
+function colordither!(
+        out::Matrix{Int},
+        ::ClosestColor,
+        img::GenericImage{C},
+        cs::AbstractVector{C},
+        colorpicker::AbstractColorPicker{C},
+    ) where {C <: ColorLike}
+    return map!(colorpicker, out, img)
 end