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, centroids, 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 requirements 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 statistics. The VIFF output file has 61 (number of statistics) 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 generation 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 outline 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 written to this file).

    -ms when set to one, this computes the set of standard moments and writes them to the ASCII output file, providing 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 normalized 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 pattern 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 central 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.