API Reference
DitherPunk.dither — Functiondither([T::Type,] img, alg::AbstractDither, args...; kwargs...)Dither image img using algorithm alg.
Output
If no return type is specified, dither will default to the type of the input image.
DitherPunk.dither! — Functiondither!([out,] img, alg::AbstractDither, args...; kwargs...)Dither image img using algorithm alg.
Output
If out is specified, it will be changed in place. Otherwise img will be changed in place.
DitherPunk.braille — Functionbraille(img; kwargs...)
-braille(img, alg; kwargs...)Binary dither with algorithm alg, then print image in braille.
Keyword arguments
invert: invert Unicode output, defaults tofalseto_string: return a string instead of printing to terminal. Defaults tofalse.method: method used to print in unicode. Either:brailleor:block. Defaults to:braille.
All keyword arguments for binary dithering methods can be used.
Algorithm types
Error diffusion
DitherPunk.ErrorDiffusion — TypeErrorDiffusion(filter, offset)Generalized error diffusion algorithm. When calling dither using a color palette cs, this will iterate over pixels and round them to the closest color in cs. The rounding error is then "diffused" over the neighborhood defined by the matrix filter centered around an integer offset.
When using dither or dither! with an ErrorDiffusion method, the keyword argument clamp_error can be passed, which defaults to true. When true, the accumulated error on each pixel is clamped within limits of the image's colorant type before looking up the closest color. Setting clamp_error=false might be desired to achieve a glitchy effect.
Example
julia> alg = FloydSteinberg() # returns ErrorDiffusion instance
+API Reference · DitherPunk.jl API Reference
DitherPunk.dither — Functiondither([T::Type,] img, alg::AbstractDither, args...; kwargs...)
Dither image img using algorithm alg.
Output
If no return type is specified, dither will default to the type of the input image.
sourceDitherPunk.dither! — Functiondither!([out,] img, alg::AbstractDither, args...; kwargs...)
Dither image img using algorithm alg.
Output
If out is specified, it will be changed in place. Otherwise img will be changed in place.
sourceDitherPunk.braille — Functionbraille(img; kwargs...)
+braille(img, alg; kwargs...)
Binary dither with algorithm alg, then print image in braille.
Keyword arguments
invert: invert Unicode output, defaults to falseto_string: return a string instead of printing to terminal. Defaults to false.method: method used to print in unicode. Either :braille or :block. Defaults to :braille.
All keyword arguments for binary dithering methods can be used.
sourceAlgorithm types
Error diffusion
DitherPunk.ErrorDiffusion — TypeErrorDiffusion(filter, offset)
Generalized error diffusion algorithm. When calling dither using a color palette cs, this will iterate over pixels and round them to the closest color in cs. The rounding error is then "diffused" over the neighborhood defined by the matrix filter centered around an integer offset.
When using dither or dither! with an ErrorDiffusion method, the keyword argument clamp_error can be passed, which defaults to true. When true, the accumulated error on each pixel is clamped within limits of the image's colorant type before looking up the closest color. Setting clamp_error=false might be desired to achieve a glitchy effect.
Example
julia> alg = FloydSteinberg() # returns ErrorDiffusion instance
ErrorDiffusion{Rational{Int64}, UnitRange{Int64}}(CartesianIndex{2}[CartesianIndex(1, 0), CartesianIndex(-1, 1), CartesianIndex(0, 1), CartesianIndex(1, 1)], Rational{Int64}[7//16, 3//16, 5//16, 1//16], (-1:1, 0:1))
julia> cs = ColorSchemes.PuOr_7 # using ColorSchemes.jl for color palette presets
julia> dither(img, alg, cs)
-julia> dither(img, alg, cs; clamp_error=false)
sourceDitherPunk.FloydSteinberg — FunctionFloydSteinberg()
Error diffusion algorithm using the filter
* 7
-3 5 1 (1//16)
References
[1] Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray Scale." SID 1975, International Symposium Digest of Technical Papers, vol 1975m, pp. 36-37.
sourceDitherPunk.JarvisJudice — FunctionJarvisJudice()
Error diffusion algorithm using the filter
* 7 5
+julia> dither(img, alg, cs; clamp_error=false)
sourceDitherPunk.FloydSteinberg — FunctionFloydSteinberg()
Error diffusion algorithm using the filter
* 7
+3 5 1 (1//16)
References
[1] Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray Scale." SID 1975, International Symposium Digest of Technical Papers, vol 1975m, pp. 36-37.
sourceDitherPunk.JarvisJudice — FunctionJarvisJudice()
Error diffusion algorithm using the filter
* 7 5
3 5 7 5 3
-1 3 5 3 1 (1//48)
Also known as the Jarvis, Judice, and Ninke filter.
References
[1] Jarvis, J.F., C.N. Judice, and W.H. Ninke, "A Survey of Techniques for the Display of Continuous Tone Pictures on Bi-Level Displays," Computer Graphics and Image Processing, vol. 5, pp. 13-40, 1976.
sourceDitherPunk.Atkinson — FunctionAtkinson()
Error diffusion algorithm using the filter
* 1 1
+1 3 5 3 1 (1//48)
Also known as the Jarvis, Judice, and Ninke filter.
References
[1] Jarvis, J.F., C.N. Judice, and W.H. Ninke, "A Survey of Techniques for the Display of Continuous Tone Pictures on Bi-Level Displays," Computer Graphics and Image Processing, vol. 5, pp. 13-40, 1976.
sourceDitherPunk.Atkinson — FunctionAtkinson()
Error diffusion algorithm using the filter
* 1 1
1 1 1
- 1 (1//8)
sourceDitherPunk.Sierra — FunctionSierra()
Error diffusion algorithm using the filter
* 5 3
+ 1 (1//8)
sourceDitherPunk.Sierra — FunctionSierra()
Error diffusion algorithm using the filter
* 5 3
2 4 5 4 2
- 2 3 2 (1//32)
Also known as Sierra3 or three-row Sierra due to the filter shape.
sourceDitherPunk.TwoRowSierra — FunctionTwoRowSierra()
Error diffusion algorithm using the filter
* 4 3
-1 2 3 2 1 (1//16)
Also known as Sierra2.
sourceDitherPunk.SierraLite — FunctionSierraLite()
Error diffusion algorithm using the filter
* 2
-1 1 (1//4)
Also known as Sierra-2-4A filter.
sourceDitherPunk.Stucki — FunctionStucki()
Error diffusion algorithm using the filter
* 8 4
+ 2 3 2 (1//32)
Also known as Sierra3 or three-row Sierra due to the filter shape.
sourceDitherPunk.TwoRowSierra — FunctionTwoRowSierra()
Error diffusion algorithm using the filter
* 4 3
+1 2 3 2 1 (1//16)
Also known as Sierra2.
sourceDitherPunk.SierraLite — FunctionSierraLite()
Error diffusion algorithm using the filter
* 2
+1 1 (1//4)
Also known as Sierra-2-4A filter.
sourceDitherPunk.Stucki — FunctionStucki()
Error diffusion algorithm using the filter
* 8 4
2 4 8 4 2
-1 2 4 2 1 (1//42)
References
[1] Stucki, P., "MECCA - a multiple-error correcting computation algorithm for bilevel image hardcopy reproduction." Research Report RZ1060, IBM Research Laboratory, Zurich, Switzerland, 1981.
sourceDitherPunk.Burkes — FunctionBurkes()
Error diffusion algorithm using the filter
* 8 4
+1 2 4 2 1 (1//42)
References
[1] Stucki, P., "MECCA - a multiple-error correcting computation algorithm for bilevel image hardcopy reproduction." Research Report RZ1060, IBM Research Laboratory, Zurich, Switzerland, 1981.
sourceDitherPunk.Burkes — FunctionBurkes()
Error diffusion algorithm using the filter
* 8 4
2 4 8 4 2
-1 2 4 2 1 (1//42)
References
[1] Burkes, D., "Presentation of the Burkes error filter for use in preparing continuous-tone images for presentation on bi-level devices." Unpublished, 1988.
sourceDitherPunk.Fan93 — FunctionFan93()
Error diffusion algorithm using the filter
* 7
-1 3 5 (1//16)
A modification of the weights used in the Floyd-Steinberg algorithm.
References
[1] Z. Fan, "A Simple Modification of Error Diffusion Weights", IS&T's 46th Annual Conference, May 9-14, 1993, Final Program and Advanced Printing of Paper Summaries, pp 113-115 (1993).
sourceDitherPunk.ShiauFan — FunctionShiauFan()
Error diffusion algorithm using the filter
* 4
-1 1 2 (1//8)
References
[1] J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993
sourceDitherPunk.ShiauFan2 — FunctionShiauFan2()
Error diffusion algorithm using the filter
* 8
-1 1 2 4 (1//16)
References
[1] J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993 [2] J. N. Shiau and Z. Fan. "A set of easily implementable coefficients in error-diffusion with reduced worm artifacts" Color Imaging: Device-Independent Color, Color Hard Copy, and Graphics Arts, volume 2658, pages 222–225. SPIE, March 1996.
sourceDitherPunk.SimpleErrorDiffusion — FunctionSimpleErrorDiffusion()
Error diffusion algorithm using the filter
* 1
-1 0 (1//2)
References
[1] Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray Scale." SID 1975, International Symposium Digest of Technical Papers, vol 1975m, pp. 36-37.
sourceOrdered dithering
DitherPunk.OrderedDither — TypeOrderedDither(mat::AbstractMatrix, [max::Integer])
Generalized ordered dithering algorithm using a threshold map. Takes an unnormalized threshold matrix mat and optionally a normalization quotient max (defaults to length(mat)+1).
When applying the algorithm to an image, the threshold matrix is repeatedly tiled to match the size of the image. It is then applied as a per-pixel threshold map. Optionally, this final threshold map can be inverted by selecting invert_map=true.
sourceBayer
DitherPunk.Bayer — FunctionBayer([level=1]; kwargs...)
Ordered dithering using the Bayer matrix as a threshold matrix. The Bayer matrix is of dimension $2^{n+1} \times 2^{n+1}$, where $n$ is the level, which defaults to 1.
[1] Bayer, B.E., "An Optimum Method for Two-Level Rendition of Continuous Tone Pictures," IEEE International Conference on Communications, Conference Records, 1973, pp. 26-11 to 26-15.
sourceHalftoning
DitherPunk.ClusteredDots — FunctionClusteredDots()
Clustered dots ordered dithering. Uses $6 \times 6$ threshold matrix CLUSTERED_DOTS_MAT.
sourceDitherPunk.CentralWhitePoint — FunctionCentralWhitePoint()
Central white point ordered dithering. Uses $6 \times 6$ threshold matrix CENTRAL_WHITE_POINT_MAT.
sourceDitherPunk.BalancedCenteredPoint — FunctionBalancedCenteredPoint()
Balanced centered point ordered dithering. Uses $6 \times 6$ threshold matrix BALANCED_CENTERED_POINT_MAT.
sourceDitherPunk.Rhombus — FunctionRhombus()
Diagonal ordered matrix with balanced centered points. Uses $8 \times 8$ threshold matrix RHOMBUS_MAT.
sourceDitherPunk.IM_checks — FunctionIM_checks()
ImageMagick's Checkerboard 2x2 dither
sourceDitherPunk.IM_h4x4a — FunctionIM_h4x4a()
ImageMagick's Halftone 4x4 - Angled 45 degrees
sourceDitherPunk.IM_h6x6a — FunctionIM_h6x6a()
ImageMagick's Halftone 6x6 - Angled 45 degrees
sourceDitherPunk.IM_h8x8a — FunctionIM_h8x8a()
ImageMagick's Halftone 8x8 - Angled 45 degrees
sourceDitherPunk.IM_h4x4o — FunctionIM_h4x4o()
ImageMagick's Halftone 4x4 - Orthogonally Aligned
sourceDitherPunk.IM_h6x6o — FunctionIM_h6x6o()
ImageMagick's Halftone 6x6 - Orthogonally Aligned
sourceDitherPunk.IM_h8x8o — FunctionIM_h8x8o()
ImageMagick's Halftone 8x8 - Orthogonally Aligned
sourceDitherPunk.IM_c5x5 — FunctionIM_c5x5()
ImageMagick's Halftone 5x5 - Orthogonally Expanding Circle Patterns
sourceDitherPunk.IM_c6x6 — FunctionIM_c6x6()
ImageMagick's Halftone 6x6 - Orthogonally Expanding Circle Patterns
sourceDitherPunk.IM_c7x7 — FunctionIM_c7x7()
ImageMagick's Halftone 7x7 - Orthogonally Expanding Circle Patterns
sourceThreshold methods
DitherPunk.ConstantThreshold — TypeConstantThreshold(threshold)
Use a constant threshold map. Defaults to 0.5 if threshold isn't specified.
sourceDitherPunk.WhiteNoiseThreshold — TypeWhiteNoiseThreshold()
Use white noise as a threshold map.
sourceDitherPunk.ClosestColor — TypeSimplest 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".
sourceOther
Utilities
DitherPunk.upscale — Functionupscale(img, scale)
Upscale image by repeating individual pixels scale times.
sourceIndex
DitherPunk.ClosestColorDitherPunk.ConstantThresholdDitherPunk.ErrorDiffusionDitherPunk.OrderedDitherDitherPunk.WhiteNoiseThresholdDitherPunk.AtkinsonDitherPunk.BalancedCenteredPointDitherPunk.BayerDitherPunk.BurkesDitherPunk.CentralWhitePointDitherPunk.ClusteredDotsDitherPunk.Fan93DitherPunk.FloydSteinbergDitherPunk.IM_c5x5DitherPunk.IM_c6x6DitherPunk.IM_c7x7DitherPunk.IM_checksDitherPunk.IM_h4x4aDitherPunk.IM_h4x4oDitherPunk.IM_h6x6aDitherPunk.IM_h6x6oDitherPunk.IM_h8x8aDitherPunk.IM_h8x8oDitherPunk.JarvisJudiceDitherPunk.RhombusDitherPunk.ShiauFanDitherPunk.ShiauFan2DitherPunk.SierraDitherPunk.SierraLiteDitherPunk.SimpleErrorDiffusionDitherPunk.StuckiDitherPunk.TwoRowSierraDitherPunk.brailleDitherPunk.ditherDitherPunk.dither!DitherPunk.upscale
Settings
This document was generated with Documenter.jl version 1.7.0 on Saturday 14 September 2024. Using Julia version 1.10.5.
References
[1] Burkes, D., "Presentation of the Burkes error filter for use in preparing continuous-tone images for presentation on bi-level devices." Unpublished, 1988.
DitherPunk.Fan93 — FunctionFan93()Error diffusion algorithm using the filter
* 7
+1 3 5 (1//16)A modification of the weights used in the Floyd-Steinberg algorithm.
References
[1] Z. Fan, "A Simple Modification of Error Diffusion Weights", IS&T's 46th Annual Conference, May 9-14, 1993, Final Program and Advanced Printing of Paper Summaries, pp 113-115 (1993).
DitherPunk.ShiauFan — FunctionShiauFan()Error diffusion algorithm using the filter
* 4
+1 1 2 (1//8)References
[1] J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993
DitherPunk.ShiauFan2 — FunctionShiauFan2()Error diffusion algorithm using the filter
* 8
+1 1 2 4 (1//16)References
[1] J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993 [2] J. N. Shiau and Z. Fan. "A set of easily implementable coefficients in error-diffusion with reduced worm artifacts" Color Imaging: Device-Independent Color, Color Hard Copy, and Graphics Arts, volume 2658, pages 222–225. SPIE, March 1996.
DitherPunk.SimpleErrorDiffusion — FunctionSimpleErrorDiffusion()Error diffusion algorithm using the filter
* 1
+1 0 (1//2)References
[1] Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray Scale." SID 1975, International Symposium Digest of Technical Papers, vol 1975m, pp. 36-37.
Ordered dithering
DitherPunk.OrderedDither — TypeOrderedDither(mat::AbstractMatrix, [max::Integer])Generalized ordered dithering algorithm using a threshold map. Takes an unnormalized threshold matrix mat and optionally a normalization quotient max (defaults to length(mat)+1).
When applying the algorithm to an image, the threshold matrix is repeatedly tiled to match the size of the image. It is then applied as a per-pixel threshold map. Optionally, this final threshold map can be inverted by selecting invert_map=true.
Bayer
DitherPunk.Bayer — FunctionBayer([level=1]; kwargs...)Ordered dithering using the Bayer matrix as a threshold matrix. The Bayer matrix is of dimension $2^{n+1} \times 2^{n+1}$, where $n$ is the level, which defaults to 1.
[1] Bayer, B.E., "An Optimum Method for Two-Level Rendition of Continuous Tone Pictures," IEEE International Conference on Communications, Conference Records, 1973, pp. 26-11 to 26-15.
Halftoning
DitherPunk.ClusteredDots — FunctionClusteredDots()Clustered dots ordered dithering. Uses $6 \times 6$ threshold matrix CLUSTERED_DOTS_MAT.
DitherPunk.CentralWhitePoint — FunctionCentralWhitePoint()Central white point ordered dithering. Uses $6 \times 6$ threshold matrix CENTRAL_WHITE_POINT_MAT.
DitherPunk.BalancedCenteredPoint — FunctionBalancedCenteredPoint()Balanced centered point ordered dithering. Uses $6 \times 6$ threshold matrix BALANCED_CENTERED_POINT_MAT.
DitherPunk.Rhombus — FunctionRhombus()Diagonal ordered matrix with balanced centered points. Uses $8 \times 8$ threshold matrix RHOMBUS_MAT.
DitherPunk.IM_checks — FunctionIM_checks()ImageMagick's Checkerboard 2x2 dither
DitherPunk.IM_h4x4a — FunctionIM_h4x4a()ImageMagick's Halftone 4x4 - Angled 45 degrees
DitherPunk.IM_h6x6a — FunctionIM_h6x6a()ImageMagick's Halftone 6x6 - Angled 45 degrees
DitherPunk.IM_h8x8a — FunctionIM_h8x8a()ImageMagick's Halftone 8x8 - Angled 45 degrees
DitherPunk.IM_h4x4o — FunctionIM_h4x4o()ImageMagick's Halftone 4x4 - Orthogonally Aligned
DitherPunk.IM_h6x6o — FunctionIM_h6x6o()ImageMagick's Halftone 6x6 - Orthogonally Aligned
DitherPunk.IM_h8x8o — FunctionIM_h8x8o()ImageMagick's Halftone 8x8 - Orthogonally Aligned
DitherPunk.IM_c5x5 — FunctionIM_c5x5()ImageMagick's Halftone 5x5 - Orthogonally Expanding Circle Patterns
DitherPunk.IM_c6x6 — FunctionIM_c6x6()ImageMagick's Halftone 6x6 - Orthogonally Expanding Circle Patterns
DitherPunk.IM_c7x7 — FunctionIM_c7x7()ImageMagick's Halftone 7x7 - Orthogonally Expanding Circle Patterns
Threshold methods
DitherPunk.ConstantThreshold — TypeConstantThreshold(threshold)Use a constant threshold map. Defaults to 0.5 if threshold isn't specified.
DitherPunk.WhiteNoiseThreshold — TypeWhiteNoiseThreshold()Use white noise as a threshold map.
DitherPunk.ClosestColor — TypeSimplest 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".
Other
Utilities
DitherPunk.upscale — Functionupscale(img, scale)Upscale image by repeating individual pixels scale times.
Index
DitherPunk.ClosestColorDitherPunk.ConstantThresholdDitherPunk.ErrorDiffusionDitherPunk.OrderedDitherDitherPunk.WhiteNoiseThresholdDitherPunk.AtkinsonDitherPunk.BalancedCenteredPointDitherPunk.BayerDitherPunk.BurkesDitherPunk.CentralWhitePointDitherPunk.ClusteredDotsDitherPunk.Fan93DitherPunk.FloydSteinbergDitherPunk.IM_c5x5DitherPunk.IM_c6x6DitherPunk.IM_c7x7DitherPunk.IM_checksDitherPunk.IM_h4x4aDitherPunk.IM_h4x4oDitherPunk.IM_h6x6aDitherPunk.IM_h6x6oDitherPunk.IM_h8x8aDitherPunk.IM_h8x8oDitherPunk.JarvisJudiceDitherPunk.RhombusDitherPunk.ShiauFanDitherPunk.ShiauFan2DitherPunk.SierraDitherPunk.SierraLiteDitherPunk.SimpleErrorDiffusionDitherPunk.StuckiDitherPunk.TwoRowSierraDitherPunk.brailleDitherPunk.ditherDitherPunk.dither!DitherPunk.upscale