vkmeans(1)

PROGRAM
vkmeans - Performs the kmeans clustering algorithm on an image

SYNTAX

vkmeans

-i1 input image

-o1 output cluster number image

-f2 output file for kmeans statistics

[-o2]
    output image for cluster centers

[-o3]
    output image for variance

[-m]
    Output Image Map Enable

[-n]
    specifies maximum number of iterations (default = 100000)

[-k]
    specifies number of clusters (default = 2)

[-b]
     specifies the border width in pixels (default = 0)

[-c]
    if Yes use First K Vectors As Cluster Centers
    -OR-

[-f1]
    input ASCII file for x-y coordinates of cluster centers
    -OR-

[-i2]
    input image cluster center values

[-V]
    Gives the version for vkmeans

[-U]
    Gives the usage for vkmeans

[-P]
    Prompts for command line options

[-A [file1]]
    Creates the answer file called vkmeans.ans or file1

[-a [file1]]
    Uses vkmeans.ans or file1 as the answer file

DESCRIPTION
vkmeans converts an input image into vectors of equal size and performs the kmeans clustering algorithm on the vectors using the K initial cluster centers. The size of each vector is determined by the number of bands in the input image.

The K-means algorithm is based on the minimization of the sum of the squared distances from all points in a cluster to a cluster center. The user chooses K initial cluster centers and the image vectors are iteratively distributed among the K cluster domains. New cluster centers are computed from these results, such that the sum of the squared distances from all points in a cluster to the new cluster center is minimized.

Although the k-means algorithm does not really converge, a practical upper limit is chosen for convergence. The user has the option of specifying the maximum number of iterations using the -n option. The default is 100000 iterations.

There are three options available for entering initial cluster centers. These are mutually exclusive and optional:

-c  uses the first K vectors as initial cluster centers (default).

-f1 uses an ASCII file as input for the x-y coordinates of the initial cluster centers. The ascii file must contain an xy pair specifying the x-y coordinate for each initial cluster center. The number of xy pairs MUST equal the value of the -k option.

-i2 uses an input image as the initial cluster center values. This image MUST contain the same number of data bands as the input image. The number of cluster centers in the image MUST equal the value of the -k option.

The -o2 optional argument will assign the cluster center image to a file. The cluster center image will always have a row size of 1 and a column size of the number of clusters, the number of data bands will be equal to the dimension of the vectors.

The -o3 optional argument will assign the variance image of the cluster centers to a file. The variance image will follow the same format as the cluster center images.

The Statistics file (-f2) contains statistics obtained during the execution of vkmeans. This file includes the following information:

    Total Number of K-means Iterations
    Total Number of Clusters
    Number of Vectors Per Cluster
    Cluster Center Values
    Cluster Center Variance Values
    Trace of Covariance Matrix

If the -m (map flag) optional argument is set, the cluster number image will contain a map of type FLOAT. The map contains the cluster center values. The number of rows in the map is equal to the number of desired clusters, while the number of columns is equal to the dimensionality of the data. Also, when the -m argument is set, the ispare1 field is set to 0 and the ispare2 is set to the dimension of the vector. By setting the -m argument to true, the output of vkmeans is compatable with the spectrum classification application.

    The border option (-b) allows the user to specify a border width, in pixels, encompassing the desired region of the image to be clustered using the k-means algorithm. The border region will contain the value zero. This region is ignored during the clustering process, and the cluster center values do not reflect this area.

    Results obtained by the k-means algorithm can be influenced by the number and choice of initial cluster centers and the geometrical properties of the data.

    All input images must be of data storage type FLOAT.

    This routine was written with the help of and ideas from Dr. Don Hush, University of New Mexico, Dept. of EECE.

REQUIRED ARGUMENTS

-i1 type: infile
    desc: input image

-o1 type: outfile
    desc: output cluster number image

-f2 type: outfile
    desc: output file for kmeans statistics

OPTIONAL ARGUMENTS

-o2 type: outfile
    desc: output image for cluster centers

-o3 type: outfile
    desc: output image for variance

-m  type: boolean
    desc: Output Image Map Enable
    default: true

-n  type: integer
    desc: specifies maximum number of iterations (default = 100000)
    default: 50000
    bounds: 1 < [-n] < 100000

-k  type: integer
    desc: specifies number of clusters (default = 2)
    default: 2
    bounds: value > 0

-b  type: integer
    desc: specifies the border width in pixels (default = 0)
    default: 0
    bounds: value >= 0

*** These arguments are MUTUALLY EXCLUSIVE ***
 If desired, you may provide ONE AND ONLY ONE of:

-c  desc: if Yes use First K Vectors As Cluster Centers
    default: true

-f1 desc: input ASCII file for x-y coordinates of cluster centers

-i2 desc: input image cluster center values
    ********

EXAMPLES
vkmeans -i1 image1 -c -n 10000 -k 6 -b 4 -o1 image2 -o2 image3

this will apply the k-means clustering algorithm to image1 using the first K vectors as cluster centers. The number of iterations selected is 10000, and the number of clusters selected is 6, and a border width of 4 pixels is specified. Image2 is specifies which vector belongs to what cluster, while image3 is the output image for the cluster centers.

vkmeans -i1 image1 -f1 file1 -k 8 -o1 image2 -o2 image3 -f2 file2

this will apply the k-means clustering algorithm to image1 using the x-y coordinates of cluster centers specified in file1. The -k option specifies 8 cluster centers, which MUST correspond with the number of cluster centers in file1. An ASCII file containing the k-means statistics (file2) is created.

vkmeans -i1 image1 -i2 image2 -k 8 -o1 image3 -o2 image4

this will apply the k-means clustering algorithm to image1 using an input image2 specifying the cluster centers. The -k option specifies 8 cluster centers, which MUST correspond with the number of cluster centers in image2.

SEE ALSO
intro(1), verror(3), vgparms(3), vutils(3), lvkmeans(3)

RESTRICTIONS
All input images must be of data storage type FLOAT.

COPYRIGHT
Copyright 1991, University of New Mexico. All rights reserved.