
vshape(1)                    Khoros                     vshape(1)

PROGRAM
     vshape - Performs shape analysis on images.

SYNTAX
     vshape

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

     -i1            input Clust/Label Image
                                        -OR-

     -i2            input Grey Level Image
                           -------------------------------

     [-o1]          output Axis image

     [-o2]          output outline image

     [-o3]          output VIFF file

     [-f]           output ASCII file

     [-ms]          if yes, compute standard moments

     [-mc]          if yes, compute central moments

     [-mi]          if yes, compute invariant moments

     [-mr]          if no computes axis of bounded box

     [-col]         if no color = white, with black background

     [-V]           Gives the version for vshape

     [-U]           Gives the usage for vshape

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     vshape performs a shape analysis on two different types of
     images, by extracting features like moments, area, cen-
     troids, etc.

     The input images can be:

     1.   A labeled or clustered image. The grey level of a pixel
          in a labeled or clustered image is specifically used to
          assign a pixel to a particular labeled region. For a
          labeled image (output of vlabel ipl routine), the
          classes or regions are connected, however this is not
          true for a cluster number image (output of vquant,
          vkmeans or visodata). This difference can confuse a
          novice user, because vshape will not differentiate
          between connected or non-connected regions.

     2.   A grey level image.  In this particular case, the
          features will be computed for the entire image.  Some
          of these features may not appear to make sense,
          nevertheless they will still contribute significant
          information to the regions.

     Before providing more information on vshape, the require-
     ments for the input image are:

     -    The data storage type can range from VFF_TYP_1_BYTE to
          VFF_TYP_FLOAT.

     -    The number of bands MUST be 1.

     -    The map enable MUST be VFF_MAP_OPTIONAL.

     Description of vshape outputs.

     The features listed below are computed for each region or
     for the entire image, depending on the input image.

          - Centroid on x and y axis.

          - Variances on x and y.

          - Area or weighted area.

          - Orientation of the principal axis.

          - Eccentricity of the shape.

          - Bounded box coordinates.

          The following features are optional.

          - Standard Moments.

          - Central Moments and Normalized Central Moments.

          - Invariant Moments.

     These features are provided in an optional ASCII file.

     As mentioned above, the centroid coordinates of the grey
     level input image provides more information than the general
     sense of the centroid of a region.

     In addition to the ASCII file, three other output files can
     be generated.

     1.   The Axis Image. This image contains a representation of
          the moments of the regions contained in the input
          image. It can only be generated when the input image is
          a not a grey level image.  There are two possibilities
          for representing the moment.

          The first one is an image containing a cross for each
          region. The cross center is located at the centroid of
          the region and the horizontal and vertical axes stop
          outside of the bounded box of the region.

          The second one is an image still containing a cross for
          each region but this time the cross is representative
          of the moment value in the principal axis system. The
          principal axis is the coordinate system in which the
          cross moment, m11 (cf reference for theory on moment
          below), is equal to zero. Therefore, this cross forms
          an angle (theta) with the x axis, and its length in
          both directions are proportional to the "length" of the
          shape is that direction.

     2.   The Outline Image.  This image contains the outlines of
          all the regions contained in this image. Again, this
          can only be generated if this input image is not a grey
          level image.

     3.   The VIFF Image.  The image contains all of the statis-
          tics.  The VIFF output file has 61 (number of statis-
          tics) bands and the number of vectors in this file
          depends on the number of regions specified in the input
          image. If the statistics flags are not set, the
          corresponding statistics will default to zero.

     For these three output images there is a final possibility,
     which is to assign all outlines or crosses a grey level of
     255, or their previous region number.  This enables the user
     to visualize the input image, the outline image, and the
     axis image using pseudo color to assign a different color to
     each region.  This aids in interpreting the regions, and
     yields an artistic view of the image.

     The options to vshape are listed below:

          -i1 cluster number or labeled image. The region number
          zero (the label or cluster number that equals zero) is
          ignored because it is non-representative or is due to a
          border requirement from vlabel, vquant, vkmeans, etc.

          -i2 grey_level image file. This option is mutually
          exclusive with -i1.  Using -i1 will cancel the genera-
          tion of outline and axis images even if they were
          specified.

          -o2 outline image. This image contains the outline of
          every region in the image except region 0. If the color
          of the outline was specified as white (255), the out-
          line thickness will be two pixels wide. This is due to
          the fact that if region n and region m are next to each
          other, the outline of n will belong to the pixels of n
          that have at least one neighbor not belonging to n. The
          same principle applies to region m, and results in an
          edge between regions n and m comprised of a pixel
          belonging to n and one belonging to m.  When using a
          different color for each outline, this phenomenon
          doesn't occur.

          -o3 viff format output file.  If the -o3, VIFF output
          file, option is selected, all of the statistics will be
          stored in the VIFF output file.  If the statistics
          flags are not set, the corresponding statistics will
          default to zero.

          Currently there are 61 statistics bands:

             0. surf_image:       Number of pixels in the entire
                                  image.
             1. area:             Number of pixels in the object
                                  = m00.
             2. percent_area:     Ratio area / surf_image.
             3. real_area:        Area in square meters.
             4. xcent:            x_cent of object.
             5. ycent:            y_cent of object.
             6. sigma_x:          variance = sqrt [ mu20 / m00 ].
             7. sigma_y:          variance = sqrt [ mu02 / m00 ].
             8. sigma_MX:         sqrt [ MX / m00 ].
             9. sigma_MY:         sqrt [ MY / m00 ].
            10. theta:            angle between the major axis of
                                  the shape.
            11. eccentricity:     Measures the eccentricity of
                                  the figure.

            12. m00:              STANDARD MOMENTS
            13. m01:
            14. m10:
            15. m11:
            16. m20:
            17. m02:
            18. m21:
            19. m12:
            20. m03:
            21. m30:

            22. mu00:             CENTRAL MOMENTS
            23. mu10:
            24. mu01:
            25. mu20:
            26. mu02:
            27. mu11:
            28. mu30:
            29. mu03:
            30. mu21:
            31. mu12:

            32. nu00:             NORMALIZED CENTRAL MOMENTS
            33. nu10:
            34. nu01:
            35. nu20:
            36. nu02:
            37. nu11:
            38. nu30:
            39. nu03:
            40. nu21:
            41. nu12:

            42. M1:               INVARIANT MOMENTS
            43. M2:
            44. M3:
            45. M4:
            46. M5:
            47. M6:
            48. M7:

            49. right:            gives the rightmost point of
                                  the object
            50. left:             gives the leftmost point of
                                  the object
            51. top:              gives the uppermost point of
                                  the object
            52. bottom:           gives the lowest point of the
                                  object
            53. axis_x1deb:       moment on principal axis 1.
            54. axis_x1end:       moment on principal axis 1.
            55. axis_y1deb:       moment on principal axis 1.
            56. axis_y1end:       moment on principal axis 1.
            57. axis_x2deb:       moment on principal axis 2.
            58. axis_x2end:       moment on principal axis 2.
            59. axis_y2deb:       moment on principal axis 2.
            60. axis_y2end:       moment on principal axis 2.

          -f name of ASCII file (record of feature values for
          every region, only the specified features will be writ-
          ten to this file).

          -ms when set to one, this computes the set of standard
          moments and writes them to the ASCII output file, pro-
          viding the ASCII output file was specified.

          -mc when set to one, this computes the set of central
          moments and normalized central moments. The central
          moments are invariant to translation, and the normal-
          ized central moments are invariant to both size and
          translation.

          -mi when set to one, this computes the set of invariant
          moments. This set is invariant to size, position
          (translation), rotation, and reflection. (Only the last
          moment, M7, isn't invariant to reflection, which can be
          used to discriminate an object from its reflection in a
          mirror). This set can be used on a grey level image of
          a particular object and can be sent as input to a pat-
          tern recognition algorithm.

          -mr when set to 0, the axis image will contain crosses
          with horizontal and vertical axes inside of the bounded
          box of the region. When set to 1, the axes are along
          the principal axis (giving the general orientation and
          length of the region).

          -col when set to 0, the outline and axis images, if
          specified, will be black and white images.  When set to
          1, the background will be black 0, and each cross or
          outline will take on the "color" of that region.

     The output images are of data storage type VFF_4_BYTE, to
     allow a sufficient number of distinct regions in the image.

     References:

     1.   Vision In Man And Machine  by Martin D. Levine. Chapter
          10. "Shape". Page 480.

     2.   Digital Image Processing by R.C. Gonzales & P. Wintz.
          Chapter "Representation and description".  Page 418.

     3.   IRE Transactions on information theory,vol IT-8,1962
          "Visual Pattern Recognition by Moment Invariants" by
          Ming_Kuei Hu. Page 179.

REQUIRED ARGUMENTS

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

     -i1    type: infile
            desc: input Clust/Label Image

     -i2    type: infile
            desc: input Grey Level Image

     Default argument of mutually exclusive group: -i1

     ********

OPTIONAL ARGUMENTS
     -o1    type: outfile
            desc: output Axis image

     -o2    type: outfile
            desc: output outline image

     -o3    type: outfile
            desc: output VIFF file

     -f     type: outfile
            desc: output ASCII file

     -ms    type: boolean
            desc: if yes, compute standard moments
            default: false

     -mc    type: boolean
            desc: if yes, compute central moments
            default: false

     -mi    type: boolean
            desc: if yes, compute invariant moments
            default: false

     -mr    type: boolean
            desc: if no computes axis of bounded box
            default: false

     -col   type: boolean
            desc: if no color = white, with black background
            default: false

EXAMPLES
     vshape -i1 image 1 -o1 image2 -o2 image3 -o3 image4 -f file
     -ms 1 -mc 0 -mi 1 -mr 1 -col 1

     This example will produce an ASCII file containing the
     information for each region, and an outline and principal
     axis representation image, with a color equal to the region
     number.  The information will contain general features and
     the set of standard and invariant moments but not the cen-
     tral set, in ascii file format and in viff file format.

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

RESTRICTIONS
     vshape will not work with an image which type is:

          VFF_TYP_COMPLEX

          VFF_TYP_DOUBLE

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

Khoros                    Release: 1.0                          1

