
vkmeans(1)                   Khoros                    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 clus-
                    ter 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 vec-
     tor 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 com-
     puted 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 itera-
     tions using the -n option.  The default is 100000 itera-
     tions.

     There are three options available for entering initial clus-
     ter 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 con-
          tain 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 fol-
     low the same format as the cluster center images.

     The Statistics file (-f2) contains statistics obtained dur-
     ing the execution of vkmeans. This file includes the follow-
     ing 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 con-
     tains 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 pro-
          cess, and the cluster center values do not reflect this
          area.

          Results obtained by the k-means algorithm can be influ-
          enced 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.

Khoros                    Release: 1.0                          1

