USAGE: kmeans [-n numcolors] [-s seedcolors] [-m maxiters] [-a area] [-c convergence] [-t type] [-C colorspace] [-v view] [-A adjoin] [-k compression] 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)
-A ... adjoin ........ adjoin layered output images into a single multi-page
...................... image; choices are: yes (y) or no (n); default=yes
-k ... compression ... compression type if saved to tif; choices are: none (n),
...................... lzw (l), or zip (z); default=zip

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 multi-page layered option, unless -A adjoin is set to no. 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.

-A adjoin ... ADJOIN layered output images into a single multi-page image. The choices are: yes (y) or no (n). The default=yes.

-k compression ... COMPRESSION type if saved to tif. The choices are: none (n), lzw (l), or zip (z); default=zip

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.