lvlabel(3)

LIBRARY ROUTINE
lvlabel - Performs a Labeling on Multiband or Cluster xvimage Structures

LIBRARY CALL
#include "vinclude.h"
int lvlabel(ima,
            cc,
            cn,
            typ,
            dist,
            connec,
            bord,
            lab,
            surf,
            opt_auto,
            reg_num,
            split,
            merge,
            printdev)
struct xvimage *ima;  /* initial image if present                      */
struct xvimage *cc;   /* cluster center image if present               */
struct xvimage *cn;   /* cluster number image "   "                    */
struct xvimage *lab;  /* labelled image                                */
int typ;              /* case of labelling.............................*/
                      /*      if 0:  label from a multi/mono band only.*/
                      /*      if 1:  label from cluster images only....*/
                      /*      if 2:  label form cluster & mono/multi...*/
float surf;           /* nc * nr * surf_min = surface minimum under    */
                      /* which a labelled region is rejected during    */
                      /* the first pass of the algorithm...............*/
int dist;             /* 1: use euclidean distance to link pixel.......*/
                      /* 2: use city blocks distance...................*/
int connec;           /* type of connectivity used:                    */
                      /*        value = 1 for the ...... 4 connectivity*/
                      /*         ....   2 .............. 8 connectivity*/
int bord;             /* define the width of the border around the imag*/
                      /* that you do not process.......................*/
int opt_auto;         /* boolean, if true converge toward number of re-*/
                      /* gion expected by the user.....................*/
int reg_num;          /* number of labelled regions wanted.............*/
float split;          /* split and merge coefficient used to determine */
                      /* the threshold to label pixels in a connex reg.*/
int merge;            /* boolean, indicates if the small region should */
                      /* be merged together or with bigger ones, or if */
                      /* they should only be classified as undefined...*/
FILE *printdev;       /* Pointer on ASCII FIle for labelling info .....*/
                      /* storage.......................................*/

INPUT

OUTPUT

MODIFICATIONS

DESCRIPTION
lvlabel performs a labeling in 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: typ = 0 uses a single or multi band image, where the data storage must be VFF_TYP_FLOAT.

    The input image corresponds to the xvimage structure ima.

    The distance will be computed using all the bands of the image.

2.  Second choice: typ = 1 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 neighbors will be the distance between their clusters.

    This case will require less computation time because the algorithm will only compute the inter-class distance, instead of computing the distance of two neighbors 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 the xvimage structure cc and must be FLOAT.
    The cluster number image corresponds to the xvimage structure cn and must be VFF_TYP_4_BYTE compatible with either cc or ima depending on typ.

3.  The last choice: typ = 2 is to use a single or multiband input image associated with a cluster number image.

    The advantage of this choice is that the results of a clustering algorithm are used to keep the neighbor pixels 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.

The algorithm also requires the following parameters:

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

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

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

Connectivity: There are two possible neighborhoods:

    connect = 1 uses 4 connectivity to link the pixels together.

    connect = 2 uses 8 connectivity.

Minimum size of a region:

    surf: 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 * surf / 100.0 (surf 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 parameter bord.

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 used by passing the parameter merge set 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. The user can choose these options by passing a value TRUE or FALSE in the parameter opt_auto.
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.
This option is easy to use, nevertheless, the function:

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

    reg_num (only used when opt_auto equals 1 or TRUE)
     determines the approximate final number of regions expected.

    split (only used when opt_auto equals 0 or FALSE) determines the threshold used by the labeling process.
    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 region = 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 familiar 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 THRESHOLD is changed.

printdev File descriptor of the ascii file that will contain all the information relative to the labeling process.

Output File lab will hold the labeled image in which every pixel has as its region number a value. This image is of VFF_TYP_4_BYTE data storage type. The region label numbers are 1 to N. The region number 0 is reserved as an UNDEFINED label or for the border.

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

RESTRICTIONS
ima must be of VFF_TYP_FLOAT data storage type.
cc must be of VFF_TYP_FLOAT data storage type and compatible with cn.
cn must be of VFF_TYP_4_BYTE data storage type and compatible with cc or ima.

AUTHOR
Pascal ADAM

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