Rust port of Derrick Coetzee’s
scolorq, based on the 1998 paper “On spatial quantization of color images” by Jan Puzicha, Markus Held, Jens Ketterer, Joachim M. Buhmann, & Dieter Fellner. Spatial quantization is defined as simultaneously performing halftoning (dithering) and color quantization (limiting the colors in an image). For more information, visit the original implementation’s website.
The algorithm is excellent for retaining image detail and minimizing visual distortions for color palettes in the neighborhood of 4, 8, or 16 colors, especially as the image size is reduced. It combines limiting the color palette and dithering the image into a simultaneous process as opposed to sequentially limiting the colors then dithering. Colors are chosen based on their context in the image, hence the “spatial” aspect of spatial color quantization. As in Pointillism, the colors are selected based on their neighbors to mix as an average illusory color in the human eye.
To use as a library, add the following to your
Cargo.toml; add the
palette_color feature to enable Lab color quantization. Executable builds can be found at https://github.com/okaneco/rscolorq/releases.
[dependencies.rscolorq] version = "0.2" default-features = false
Images are best viewed at 100% magnification.
rscolorq -i mandrill.jpg -o mandrill-rgb2.png -n 2 --auto -s 0 --iters 5 rscolorq -i mandrill.jpg -o mandrill-rgb4.png -n 4 --auto -s 0 --repeats 3 rscolorq -i mandrill.jpg -o mandrill-rgb8.png -n 8 --auto -s 0 --iters 5
--repeats options can be used to increase their values over the default to improve the quality of output.
--auto sets the dithering level based on the image size and desired palette size. The
-s option sets the random number generator seed; otherwise, it’s seeded randomly.
2) Palette swatches and fixed palette
Palette swatches can be generated by passing
--op plus a filename.
--height can be passed to specify the width and height of the resulting palette image. The following swatches are the colors that comprise 4 and 8 color dithered images in the bottom row of the previous image.
rscolorq -i mandrill-resize.jpg --op mandrill-rgb4-pal.png -n 4 --auto -s 0 --repeats 3 rscolorq -i mandrill-resize.jpg --op mandrill-rgb8-pal.png -n 8 --auto -s 0 --iters 5 -p
-p flag will print the hexadecimal colors to the terminal as seen in the second example above. If no
-o is passed, the dithered image will not be saved to a file.
Custom color palette
You can supply your own palette to dither with by passing
-c followed by a list of hexadecimal colors as in the following example.
rscolorq -i scenic.jpg -o mountain-pal.png -c FFBF82,09717E --auto -s 0 --iters 5`
rscolorq -i rainbow.png -o rainbow-rgb4.png -n 4 rscolorq -i rainbow.png -o rainbow-rgb8.png -n 8 --iters 8 --repeats 2 rscolorq -i rainbow.png -o rainbow-lab4.png -n 4 --lab rscolorq -i rainbow.png -o rainbow-lab8.png -n 8 --lab --iters 8 --repeats 2
- use RGB or Lab color space for calculations
- option to dither based on fixed color palette supplied by the user
- seedable RNG for reproducible results
- print the palette colors to the command line in hexadecimal
- create a palette swatch image from the dither colors
- Larger images or images with smooth transitions/gradients will take longer. Higher palette sizes will take longer.
- The algorithm is suited towards retaining detail with smaller color palettes. You can still use it on larger images but be aware it’s not close to real-time unless the image is small.
Filter size 1×1
- Doesn’t produce an image resembling the input, nor does the original.
Filter size 5×5
- Doesn’t always converge.
- I’m unsure if this is an error in this implementation or a problem with the random number generator being used. The original implementation may take a while but eventually completes with filter size 5.
- Any help on this would be appreciated.
If you get an invalid color error or hex color length error with the command line tool, try enclosing the color string in quotes.
For example, instead of
-c 000000,ffffff use
This crate is licensed under either
- the , or
- the Apache License (Version 2.0)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Copyright of the original images is property of their respective owners.