Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial use, ONLY.

    For use of my scripts in commercial (for-profit) environments or non-free applications, please contact me (Fred Weinhaus) for licensing arrangements. My email address is fmw at alink dot net.

    If you: 1) redistribute, 2) incorporate any of these scripts into other free applications or 3) reprogram them in another scripting language, then you must contact me for permission, especially if the result might be used in a commercial or for-profit environment.

    Usage, whether stated or not in the script, is restricted to the above licensing arrangements. It is also subject, in a subordinate manner, to the ImageMagick license, which can be found at: http://www.imagemagick.org/script/license.php

KMEANS


Applies k-means color reduction to an image.

Download Script

last modified: September 26, 2017



USAGE: kmeans [-n numcolors] [-s seedcolors] [-m maxiters] [-a area] [-c convergence] [-t type] [-C colorspace] [-v view] infile outfile
USAGE: kmeans [-h or -help]

-n ... numcolors ..... number of colors to use as seeds; integer>1; default=5
-s ... seedcolors .... list of seed colors rather than selecting a number of
...................... colors; space separate list of opaque color; default
...................... is to use the number of colors
-m ... maxiters ...... maximum number of iterations before stopping;
...................... integer>0; default=40
-c ... convergence ... minimum rmse (times 100) between previous and current
...................... set of colors to stop iterating; default=0.05
-a ... area .......... largest pixel area of a cluster to be merged into
...................... its background; integer>=0; default=0 (no merging)
-t ... type .......... type of output; choices are flattened (f) or
...................... layered (l); default=flattened
-C ... colorspace .... colorspace in which to do processing; default=sRGB
-v ... view .......... hexcolors (only), swatches (and hex colors),
...................... progress (and hex colors), all (progress, hexcolors
...................... swatches) and dominant (dominant color)

PURPOSE: To apply k-means color reduction to an image.

DESCRIPTION: KMEANS applies k-means color reduction to an image. This is a colorspace clustering or segmentation technique. The user must specify either a number of desired final colors or a set of initial seed colors. If a list of seed colors is not provided, then seed colors will be estimated using IM -colors (color quantization). The algorithm uses the seed colors to group (cluster) each pixel in the image according to the smallest rmse value to each seed color. Then it computes the new mean colors from the clusters. This process iterates until either the convergence value is reached or the maximum number of iterations is reached. The script is limited to fully opaque images. Optionally, connected components labeling may be use to remove small isolated clusters for IM versions 6.8.9-10 or later. The final list of colors will be sorted by histogram count so that the first color in the list will be the dominant color in the image.

Arguments:

-n numcolors ... NUMCOLORS is the number of colors to use as seeds. Values are integer>1. The default=5.

-s seedcolors ... SEEDCOLORS is a space delimited list of opaque seed colors. It is used rather than just selecting a given number of colors. Providing a well selected list of colors can make the iteration process quicker. Any valid set of opaque IM colors may be used. This includes rgb, hex or color names. However, there must not be any spaces in the color, especially for rgb color definitions. The default is to just use the desired number of colors.

-m maxiters ... MAXITERS is the maximum number of iterations before stopping. Values are integer>0. The default=40

-c convergence ... CONVERGENCE is the minimum rmse (times 100) between the previous and current set of colors to stop iterating. Values are floats>=0. Larger convergence values will run faster and converge to slightly different colors. The default=0.05, but runs rather slow due to many iterations. A value of 0.3 will run much faster with much fewer iterations, though the colors will be slightly different and thus the clusters will be different.

-a area ... AREA is the largest pixel area of a cluster to be merged into its surrounding or largest neighboring cluster (color). Any cluster of this area or smaller will be merged. Value are integers>=0. The default=0 is no merging.

-t type ... TYPE of output image. The choices are flattened (f) or layered (l). The default=flattened. Note the format of the output must be either GIF or TIF or TIFF to support the layered option. Suffixes may be all upper case or all lower case. If other formats are used, then multiple output images will be created rather than a layered image.

-C colorspace ... COLORSPACE in which to do processing; default=sRGB; other colorspaces that do well are YCbCr and LAB.

-v view ... VIEW permits one to list to the terminal or display any of the following options: hexcolors, swatches (and hex colors), progress (and hex colors), all (progress, hexcolors swatches) and dominant (dominant color). Hexcolors will list to the terminal for both the initial seed and final cluster colors in hex notation. The final colors will be sorted by histogram count with the first color the dominant color in the resulting image. Swatches will display the initial and final cluster colors as images to the display. It will also list the hex colors to the terminal. Progress will list each iteration and rmse value to the terminal in addition to the list of initial and final hex colors. All will do all of the above. Dominant will list only the hexcolor value of the dominant color in the image. The default is none of the above. Note that hexcolors and swatches will be presented in the working colorspace and not converted to sRGB.

REQUIREMENTS: IM version 6.8.9-10 or higher to use option -a with connected components labeling to remove small isolated clusters.

References: http://en.wikipedia.org/wiki/Kmeans

NOTE: the script may be slow due to its iterative nature. Also GIF files cannot be made transparent in IM 6.9.1.7.

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.


EXAMPLES

Example 1 -- Variation Number of Colors Vs Seed Colors
( results should be identical )

Original Image
(source image)

Arguments:
-n 4

Arguments:
-s "blue green1 orange black"



Example 2 -- Variation in Colorspace

Original Image
(source image)

Arguments:
-n 5 -C sRGB

Arguments:
-n 5 -C YCbCr

Arguments:
-n 5 -C YIQ

Arguments:
-n 5 -C LAB



Example 3 -- Variation in Colorspace

Original Image

Arguments:
-n 5 -C sRGB

Arguments:
-n 5 -C YCbCr

Arguments:
-n 5 -C LAB



Example 4 -- Variation in Colorspace

Original Image

Arguments:
-n 7 -C sRGB

Arguments:
-n 7 -C YCbCr

Arguments:
-n 7 -C LAB



Example 5 -- IM -colors Vs Kmeans for Various Number of Colors

Original Image
(source image)

Arguments:
-colors 3

Arguments:
-n 3

Arguments:
-colors 5

Arguments:
-n 5

Arguments:
-colors 7

Arguments:
-n 7

Arguments:
-colors 9

Arguments:
-n 9

Arguments:
-colors 11

Arguments:
-n 11

Arguments:
-colors 15

Arguments:
-n 15



Example 6 -- Small Cluster Removal and Layered Image Animation

Original Image

Arguments:
-n 7 -c 0.3 -C sRGB -t flattened

Arguments:
-n 7 -c 0.3 -C sRGB -t flattened -a 20

Arguments:
-n 7 -c 0.3 -C sRGB -t layered
layers animation 1

Arguments:
-n 7 -c 0.3 -C sRGB -t layered
layers animation 2



What the script does is as follows:

  • User specifies a number of desired colors
  • The input image is reduced to that many seed colors as cluster means
  • Every pixel is compared to each seed color and that seed color with the smallest
    rmse difference to the pixel color is selected
  • Masks are created for each seed color from the processed image
  • The masks are used to find new mean colors for each cluster
  • The new mean colors are compared to the previous mean colors and the rmse differences
    are compute and compared to the convergence value.
  • If convergence or maxiters is reached, then the iterations are stopped; otherwise
    another iterations of clustering is processed.

See the script for code details