Use IndirectArrays

Project.toml

@@ -5,16 +5,15 @@ version = "2.0.1"
 
 [deps]
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
+IndirectArrays = "9b13fd28-a010-5f03-acff-a1bbcff69959"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Requires = "ae029012-a4dd-5104-9daa-d747884805df"
-TiledIteration = "06e1c1a7-607b-532d-9fad-de7d9aa2abac"
 
 [compat]
 ImageCore = "0.8.1, 0.9"
 OffsetArrays = "1"
 Requires = "1"
-TiledIteration = "0.3"
 julia = "1"
 
 [extras]

src/DitherPunk.jl

@@ -1,16 +1,16 @@
 module DitherPunk
 
-using TiledIteration
 using ImageCore
 using ImageCore: NumberLike, Pixel, GenericImage, GenericGrayImage, MappedArrays
 using ImageCore.Colors: DifferenceMetric
 using Random
+using IndirectArrays
 using OffsetArrays
 using Requires
 
 include("compat.jl")
+include("utils.jl")
 include("dither_api.jl")
-include("colorspaces.jl")
 include("threshold.jl")
 include("ordered.jl")
 include("ordered_imagemagick.jl")

src/closest_color.jl

@@ -3,18 +3,16 @@ Simplest form of image quantization by turning each pixel to the closest one
 in the provided color palette `cs`.
 Technically this not a dithering algorithm as the quatization error is not "randomized".
 """
-struct ClosestColor <: AbstractCustomColorDither end
+struct ClosestColor <: AbstractDither end
 
-function binarydither!(::ClosestColor, out::GenericGrayImage, img::GenericGrayImage)
- return out .= img .> 0.5
+function binarydither(::ClosestColor, img::GenericGrayImage)
+ return map(px -> px > 0.5 ? INDEX_WHITE : INDEX_BLACK, img)
 end
 
-function colordither!(
- ::ClosestColor,
- out::GenericImage,
- img::GenericImage,
- cs::AbstractVector{<:Pixel},
- metric::DifferenceMetric,
+function colordither(
+ ::ClosestColor, img::GenericImage, cs::AbstractVector{<:Pixel}, metric::DifferenceMetric
 )
- return out .= eltype(out).(map((px) -> closest_color(px, cs; metric=metric), img))
+ cs = Lab{floattype(eltype(eltype(img)))}.(cs)
+ # return matrix of indices of closest color
+ return map(px -> argmin(colordiff.(px, cs; metric=metric)), img)
 end

src/clustering.jl

@@ -1,16 +1,15 @@
 # These functions are only conditionally loaded with Clustering.jl
 # Code adapted from @cormullion's [ColorSchemeTools](https://github.com/JuliaGraphics/ColorSchemeTools.jl).
 
-function _dither!(
- out,
+function _dither(
+ ::Type{T},
  img,
  alg,
  ncolors::Int;
  maxiter=Clustering._kmeans_default_maxiter,
  tol=Clustering._kmeans_default_tol,
  kwargs...,
-)
- T = eltype(img)
+) where {T}
 
  # Cluster in Lab color space
  data = reshape(channelview(Lab.(img)), 3, :)
@@ -22,7 +21,7 @@ function _dither!(
  push!(cs, Lab(R.centers[i], R.centers[i + 1], R.centers[i + 2]))
  end
 
- return _dither!(out, img, alg, T.(cs); kwargs...)
+ return _dither(T, img, alg, cs; kwargs...)
 end
 
 """

src/colorschemes.jl

@@ -1,9 +1,9 @@
 # These functions are only conditionally loaded with ColorSchemes.jl
-function _dither!(out, img, alg, cs::ColorSchemes.ColorScheme; kwargs...)
- return _dither!(out, img, alg, cs.colors)
+function _dither(T, img, alg, cs::ColorSchemes.ColorScheme; kwargs...)
+ return _dither(T, img, alg, cs.colors)
 end
 
-function _dither!(out, img, alg, csname::Symbol; kwargs...)
+function _dither(T, img, alg, csname::Symbol; kwargs...)
  cs = ColorSchemes.colorschemes[csname]
- return _dither!(out, img, alg, cs.colors; kwargs...)
+ return _dither(T, img, alg, cs.colors; kwargs...)
 end

src/dither_api.jl

@@ -1,13 +1,5 @@
 abstract type AbstractDither end
 
-# Algorithms for which the user can define a custom output color palette.
-# If no palette is specified, algorithms of this type will default to a binary color palette
-# and act similarly to algorithms of type AbstractBinaryDither.
-abstract type AbstractCustomColorDither <: AbstractDither end
-
-# Algorithms which strictly do binary dithering:
-abstract type AbstractBinaryDither <: AbstractDither end
-
 struct ColorNotImplementedError <: Exception
  algname::String
  ColorNotImplementedError(alg::AbstractDither) = new("$alg")
@@ -17,7 +9,7 @@ function Base.showerror(io::IO, e::ColorNotImplementedError)
  io, e.algname, " algorithm currently doesn't support custom color palettes."
  )
 end
-colordither!(alg, out, img, cs, metric) = throw(ColorNotImplementedError(alg))
+colordither(alg, img, cs, metric) = throw(ColorNotImplementedError(alg))
 
 ##############
 # Public API #
@@ -44,38 +36,22 @@ If no return type is specified, `dither` will default to the type of the input i
 dither
 
 # If `out` is specified, it will be changed in place...
-function dither!(
- out::GenericImage, img::GenericImage, alg::AbstractDither, args...; kwargs...
-)
- if size(out) != size(img)
- throw(
- ArgumentError(
- "out and img should have the same shape, instead they are $(size(out)) and $(size(img))",
- ),
- )
- end
- return _dither!(out, img, alg, args...; kwargs...)
-end
-
-# ...otherwise `img` will be changed in place.
 function dither!(img::GenericImage, alg::AbstractDither, args...; kwargs...)
- tmp = copy(img)
- return _dither!(img, tmp, alg, args...; kwargs...)
+ return img .= _dither(eltype(img), img, alg, args...; kwargs...)
 end
 
-# The return type can be chosen...
+# Otherwise the return type can be chosen...
 function dither(
  ::Type{T}, img::GenericImage, alg::AbstractDither, args...; kwargs...
 ) where {T}
- out = similar(Array{T}, axes(img))
- return _dither!(out, img, alg, args...; kwargs...)
+ return _dither(T, img, alg, args...; kwargs...)
 end
 
 # ...and defaults to the type of the input image.
 function dither(
  img::GenericImage{T,N}, alg::AbstractDither, args...; kwargs...
 ) where {T<:Pixel,N}
- return dither(T, img, alg, args...; kwargs...)
+ return _dither(T, img, alg, args...; kwargs...)
 end
 
 #############################
@@ -84,59 +60,67 @@ end
 
 # Dispatch to binary dithering on grayscale images
 # when no color palette is provided
-function _dither!(
- out::GenericGrayImage, img::GenericGrayImage, alg::AbstractDither; to_linear=false
-)
+function _dither(
+ ::Type{T}, img::GenericGrayImage, alg::AbstractDither; to_linear=false, kwargs...
+) where {T}
  to_linear && (img = srgb2linear.(img))
- return binarydither!(alg, out, img)
+ index = binarydither(alg, img; kwargs...)
+ return IndirectArray(index, bwcolors(T))
 end
 
-# Dispatch to per-channel dithering on color images
-# when no color palette is provided
-function _dither!(
- out::GenericImage{<:Color{<:Real,3},2},
+# Dispatch to per-channel dithering on color images when no color palette is provided
+function _dither(
+ ::Type{T},
  img::GenericImage{<:Color{<:Real,3},2},
  alg::AbstractDither;
  to_linear=false,
-)
+ kwargs...,
+) where {T}
  to_linear && (@warn "Skipping transformation `to_linear` when dithering color images.")
 
- cvout = channelview(out)
- cvimg = channelview(img)
- for c in axes(cvout, 1)
- # Note: the input `out` will be modified
- # since the dithering algorithms modify the view of the channelview of `out`.
- binarydither!(alg, view(cvout, c, :, :), view(cvimg, c, :, :))
+ cs = perchannelbinarycolors(T) # color scheme with binary respresentation
+
+ # We want to reconstruct indices 1..8 from binary colorscheme indices 1,2.
+ # Let's assume three channels r, g, b. Using `perchannelbinarycolors`, the color scheme
+ # can be reconstructed as:
+ # 2^2 * (r-1) + 2^1 * (g-1) + 2^0 * (b-1) + 1
+ # We can skip subtracting 1 from each channel by doing:
+ # 4*r + 2*g + b - 6
+ index = fill(Int(-6), size(img)...)
+ for c in 1:3
+ channelindex = binarydither(alg, view(channelview(img), c, :, :), kwargs...)
+ index += 2^(3 - c) * channelindex
  end
- return out
+ return IndirectArray(index, cs)
 end
 
 # Dispatch to dithering with custom color palettes on any image type
 # when color palette is provided
-function _dither!(
- out::GenericImage,
+function _dither(
+ ::Type{T},
  img::GenericImage,
  alg::AbstractDither,
  cs::AbstractVector{<:Pixel};
  metric::DifferenceMetric=DE_2000(),
  to_linear=false,
-)
+) where {T}
  to_linear && (@warn "Skipping transformation `to_linear` when dithering in color.")
  length(cs) >= 2 ||
  throw(DomainError(steps, "Color scheme for dither needs >= 2 colors."))
- return colordither!(alg, out, img, cs, metric)
+
+ index = colordither(alg, img, cs, metric)
+ return IndirectArray(index, T.(cs))
 end
 
 # 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 _dither!(
- out::GenericGrayImage,
- img::GenericGrayImage,
+function _dither(
+ ::Type{T},
+ img::GenericImage,
  alg::AbstractDither,
  cs::AbstractVector{<:Color{<:Any,3}};
  metric::DifferenceMetric=DE_2000(),
  to_linear=false,
-)
- T = eltype(cs)
- return _dither!(T.(out), T.(img), alg, cs; metric=metric, to_linear=to_linear)
+) where {T<:NumberLike}
+ return _dither(eltype(cs), img, alg, cs; metric=metric, to_linear=to_linear)
 end

src/error_diffusion.jl

@@ -21,39 +21,42 @@ julia> cs = ColorSchemes.PuOr_7.colors; # using ColorSchemes.jl for color palett
 julia> dither!(img, alg, cs);
 ```
 """
-struct ErrorDiffusion{T<:AbstractMatrix} <: AbstractCustomColorDither
+struct ErrorDiffusion{T<:AbstractMatrix} <: AbstractDither
  filter::T
  clamp_error::Bool
 end
 ErrorDiffusion(filter; clamp_error=true) = ErrorDiffusion(filter, clamp_error)
 
-function binarydither!(alg::ErrorDiffusion, out::GenericGrayImage, img::GenericGrayImage)
+function binarydither(alg::ErrorDiffusion, img::GenericGrayImage)
  # this function does not yet support OffsetArray
  require_one_based_indexing(img)
 
  # Change from normalized intensities to Float as error will get added!
- FT = floattype(eltype(out))
-
  # eagerly promote to the same type to make loop run faster
+ FT = floattype(eltype(img))
  img = FT.(img)
  filter = eltype(FT).(alg.filter)
 
- h, w = size(img)
- fill!(out, zero(eltype(out)))
-
  drs = axes(alg.filter, 1)
  dcs = axes(alg.filter, 2)
  FT0, FT1 = FT(0), FT(1)
 
+ out = Matrix{Int}(undef, size(img)...)
+
  @inbounds for r in axes(img, 1)
  for c in axes(img, 2)
  px = img[r, c]
  alg.clamp_error && (px = clamp01(px))
 
- px >= 0.5 ? (col = FT1) : (col = FT0) # round to closest color
- out[r, c] = col # apply pixel to dither
- err = px - col # diffuse "error" to neighborhood in filter
+ if px > 0.5
+ out[r, c] = INDEX_WHITE
+ col = FT1 # round to closest color
+ else
+ out[r, c] = INDEX_BLACK
+ col = FT0
+ end
 
+ err = px - col # diffuse "error" to neighborhood in filter
  for dr in drs
  for dc in dcs
  if (r + dr) in axes(img, 1) && (c + dc) in axes(img, 2)
@@ -67,26 +70,26 @@ function binarydither!(alg::ErrorDiffusion, out::GenericGrayImage, img::GenericG
  return out
 end
 
-function colordither!(
+function colordither(
  alg::ErrorDiffusion,
- out::GenericImage,
  img::GenericImage,
  cs::AbstractVector{<:Pixel},
  metric::DifferenceMetric,
 )
  # this function does not yet support OffsetArray
  require_one_based_indexing(img)
 
- # Change from normalized intensities to Float as error will get added!
- FT = floattype(eltype(out))
+ out = Matrix{Int}(undef, size(img)...) # allocate matrix of color indices
 
- # eagerly promote to the same type to make loop run faster
- img = FT.(img)
- cs = FT.(cs)
- filter = eltype(FT).(alg.filter)
+ # Change from normalized intensities to Float as error will get added!
+ # Eagerly promote to the same type to make loop run faster.
+ FT = floattype(eltype(eltype(img))) # type of Float
+ CT = floattype(eltype(img)) # type of colorant
 
- h, w = size(img)
- fill!(out, zero(eltype(out)))
+ img = CT.(img)
+ cs = CT.(cs)
+ labcs = Lab{FT}.(cs) # otherwise each call to colordiff converts cs to Lab
+ filter = FT.(alg.filter)
 
  drs = axes(alg.filter, 1)
  dcs = axes(alg.filter, 2)
@@ -96,9 +99,9 @@ function colordither!(
  px = img[r, c]
  alg.clamp_error && (px = clamp01(px))
 
- col = closest_color(px, cs; metric=metric) # round to closest color
- out[r, c] = col # apply pixel to dither
- err = px - col # diffuse "error" to neighborhood in filter
+ colorindex = argmin(colordiff.(px, labcs; metric=metric)) # find closest color
+ out[r, c] = colorindex # apply pixel to dither, which is an IndirectArray
+ err = px - cs[colorindex] # diffuse "error" to neighborhood in filter
 
  for dr in drs
  for dc in dcs