
vlabel(1)                    Khoros                     vlabel(1)

PROGRAM
     vlabel - Performs a Labeling on Multiband or Cluster Images

SYNTAX
     vlabel

     -o             output image after the labelling process

     -merge         if flag= 1 the small regions will be merged
                    together in connex regions, or will be
                    included to existing labelled regions

     -m             1 for euclidean distance, 2 for city block:
                    1 (Use the Euclidean Distance),
                    or 2 (Use the City block Distance)

     -c             1 for the 4 connectivity, 2 for 8 connec-
                    tivity:
                    1 (if Yes use the 4 Connectivity),
                    or 2 (if Yes use the 8 Connectivity)

                           -------------------------------

     -i1            input image
                                        -OR-

     -i2            input image for cluster centers
                           -------------------------------

                           -------------------------------

     -n             Number of region that the user wishes to get
                    from the labelling process
                                        -OR-

     -f             the higher the factor the finer the regions
                           -------------------------------

     [-i3]          input image for cluster numbers

     [-asc]         output file for vlabel result display

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

     [-s]           Minimum number of pixel to keep in label
                    region

     [-V]           Gives the version for vlabel

     [-U]           Gives the usage for vlabel

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     vlabel performs a labeling on a multiband image or a cluster
     image by attempting to merge connected pixels.

     The principal of the algorithm is as follows: A pixel
     receives the same label as its neighbor if the likelihood
     distance between the two pixels is acceptable.  The label
     process is propagated for a given region number until it is
     no longer possible to find a candidate.

     Three different types of labeling choices exist:

     1    First choice: uses a single or multi band image, where
          the data storage can be any of the following types:
          VFF_TYP_1_BYTE, VFF_TYP_2_BYTE, VFF_TYP_4_BYTE, or
          VFF_TYP_FLOAT.

          The input image corresponds to the -i1 argument.

          The distance is computed using all the bands of the
          image.

     2.   Second choice: uses a cluster number and cluster center
          image obtained from an algorithm like vkmeans or
          vquant.  For this case, the cluster center represents
          the value of a class of pixels that have been grouped
          together.  Therefore, the distance between two neigh-
          bors will be the distance between their clusters.

          This case will require less computation time because
          the algorithm will only compute the inter-class dis-
          tance, instead of computing the distance of two neigh-
          bors for the entire image.

          An additional advantage with this choice, is that the
          output from algorithms such as vkmeans or vquant may be
          utilized, which may lead to better results.

          The cluster center image corresponds to -i2 argument
          The cluster number image corresponds to -i3 argument in
          the command line.

     3.   The final possibility is to use a single or multiband
          input image (argument -i1) associated with a cluster
          number image (argument -i3).

          The advantage of this choice is that the results of a
          clustering algorithm are used to keep the neighbor pix-
          els that have the same cluster number in the same
          class, and to rely on the distance in the single or
          multi band image to group two neighbors that do not
          belong to the same cluster.

     In summary, the three possible choices are:

          -i1 image.xv

          -i2 cluster_center.xv -i3 cluster_number.xv

          -i1 image.xv -i3 cluster_number.xv

     The algorithm also requires the following parameters:

     Metric distance:  There are 2 different metric distances
     that can be used.

          -d 1 uses  Euclidean distance: sqrt[(x-s)^2 + (y-t)^2].

          -d 2 uses  City Block distance: |x-s| + |y-t|.

     Connectivity:  There are two possible neighborhoods:

          -c 1  uses the 4 connectivity to link pixels together.

          -c 2  uses the 8 connectivity.

     Minimum size of a region:

          -s  (float_value)  determines the number of pixels
          required for a region to be retained.  The minimum
          number of pixels is equal to:
          Total number of pixels in image * float_value / 100.0
          (-s corresponds to a percentage of the total number of
          pixels in the image).

     Border Size:
     Each pixel in the image is updated except those outside of
     the border.  The size of the border is specified by the -w
     argument.

     Merging Process:
     When the labeling process is computed, the user can expect
     that the small rejected region will be merged together in a
     bigger acceptable region or will be included inside another
     connected region.
     This choice is selected by setting the logical argument
     -merge to TRUE.  If -merge is set to FALSE, the small
     regions will be ignored and labeled as an UNDEFINED REGION
     (label number 0), the same as the border.

     The AUTOMATIC or MANUAL OPTION:
     This option allows the user either to fix a threshold, or to
     give an approximate number of regions.
     If the AUTOMATIC option is used, the algorithm will iterate
     on the threshold until the number of regions labeled by the
     process is comparable to the number of expected regions.
     In fact, if the expected number is not reached after 30
     iterations, the threshold that gives the closest number of
     regions is used for the final labeling.

     Although this option is easy to use, the function:

          number of regions = F(Threshold)  is not a monotoni-
          cally increasing function, and the convergence toward a
          solution may not exist.

          -n  int_value   (AUTOMATIC OPTION) determines the
          approximate final number of regions expected.
          -f  float_value (MANUAL OPTION) determines the thres-
          hold used by the labeling process.

          THESE TWO OPTIONS ARE MUTUALLY EXCLUSIVE

          The default threshold value is 0.07. This value gen-
          erally gives good results on noiseless images with
          large uniform regions.
          Decreasing this value will increase the number of
          regions found during the labeling process, but these
          regions will get smaller and could be rejected by the
          minimum size threshold.
          Increasing this value will decrease the number of
          regions found during the labeling process. At the same
          time, the number of small regions will decrease which
          means that this area of the curve, number of regions =
          F(Threshold), is more stable than the other one.

          Once the user becomes accustomed to this routine, good
          results are generally obtained.  One way to become fam-
          iliar with the routine, is to use the automatic option
          and analyze the output ASCII file (Statistics on the
          iteration process). This file contains the number of
          regions labeled for each iteration, allowing the user
          to see how the number of regions changes as the THRES-
          HOLD is changed.

     Output Files

     1    Output image:  The resulting image, which corresponds
          to the -o1 argument, contains the labeled image in
          which every pixel has a region number as its value.
          This image is of data storage type VFF_TYP_4_BYTE.
          The region label numbers are 1 to N.  The region number
          0 is reserved as an UNDEFINED label or for the border.

     2    Output Statistic ASCII File:  This file contains all
          the information relative to the labeling process.

REQUIRED ARGUMENTS
     -o     type: outfile
            desc: output image after the labelling process

     -merge type: boolean
            desc: if flag= 1 the small regions will be merged
            together in connex regions, or will be included to
            existing labelled regions

     -m     type: integer
            desc: 1 for euclidean distance, 2 for city block
            allowed values:
            1 (Use the Euclidean Distance),
            or 2 (Use the City block Distance)

     -c     type: integer
            desc: 1 for the 4 connectivity, 2 for 8 connectivity
            allowed values:
            1 (if Yes use the 4 Connectivity),
            or 2 (if Yes use the 8 Connectivity)

     ***   These arguments are MUTUALLY EXCLUSIVE   ***
            You MUST provide ONE AND ONLY ONE of:

     -i1    type: infile
            desc: input image

     -i2    type: infile
            desc: input image for cluster centers

     Default argument of mutually exclusive group: -i1

     ********

     ***   These arguments are MUTUALLY EXCLUSIVE   ***
            You MUST provide ONE AND ONLY ONE of:

     -n     type: integer
            desc: Number of region that the user wishes to get
            from the labelling process

     -f     type: float
            desc: the higher the factor the finer the regions

     Default argument of mutually exclusive group: -f 0.07

     ********

OPTIONAL ARGUMENTS
     -i3    type: infile
            desc: input image for cluster numbers

     -asc   type: outfile
            desc: output file for vlabel result display

     -w     type: integer
            desc: specifies the border width in pixels (default =
            0)
            default: 0
            bounds: 0 < [-w] < 16

     -s     type: float
            desc: Minimum number of pixel to keep in label region
            default: 1
            bounds: 0.000000 < [-s] < 100.000000

EXAMPLES
     vlabel -i1 image.xv -d 1 c 1 -merge 0 -f 0.07 -s 0.7 -w 2 -o
     image1.xv -asc stats

     This command will label image.xv using the Euclidean dis-
     tance, the 4 connectivity, a split and merge factor equal to
     0.07, a minimum size for the regions equal to 0.7 percent of
     the total number of pixels in image.xv, and a border size of
     2. The merge option is not used which means that the small
     regions will not be labeled. The labeled image will be
     stored in image1.xv and the statistics will be written in
     the ASCII file, stats.

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), lvlabel(3)
     lvkmeans(3), lviso2(3), lvquant(3), vkmeans(1), viso2(1),
     vquant(1).

RESTRICTIONS
     vlabel works only with cluster number and cluster center
     images conforming to the convention established by the set
     of clustering algorithms.

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

Khoros                    Release: 1.0                          1

