NAME

     split_merge_segment - Setup for Split and Merge Segmentation

SYNOPSIS

      #include <stdio.h>
      #include <stdlib.h>
      #include "CVIPdef.h"
      #include "CVIPtoolkit.h"
      #include "split_merge.h"
      #include "CVIPtexture.h"

      Image *split_merge_segment(Image *imgP, unsigned int level,
      unsigned  int  choice,   void   *parameters,   CVIP_BOOLEAN
     Run_PCT)

      Image *multi_resolution_segment(Image *imgP,
      unsigned  int  choice,   void   *parameters,   CVIP_BOOLEAN
     Run_PCT)

      <srcImage> - pointer to source Image structure
      <level> - the level to begin procedure
      <choice> - Predicate test chosen
         (1) pure uniformity
         (2) local mean vs. global
         (3) local std. deviation vs. global mean
         (4) Number of pixels within 2 x standard deviation
         (5) Weighted gray level distance test
         (6) Texture Homogeneity Test
      <parameters> - Parameters used determined by predicate test
      <Run_PCT> - Choice to run PCT on color images

      QUAD_LIST split_merge_generic(Image *srcImage,
      CVIP_BOOLEAN (*const pt)(Image *, QUAD *, void *),
      void *pt_paramP, unsigned int level)

      <srcImage> - pointer to source Image structure
      <pt> - pointer to the homogeneity test function
      <pt_paramP> - pointer to the parameters required by <pt>
      <level> - the level to begin procedure

PATH

     $CVIPHOME/SEGMENTATION/split_merge.c,
     splitnMerge.c(split_merge_generic)

DESCRIPTION

     split_merge_generic  is   the   basic   function   for   the
     split_and_merge  algorithm.   A  homogeneity test is used to
     determine if the Region of Interest is homogeneous, if it is
     then  all  the pixels in that region are replaced with their
     average (in the segmented image).

     The level to begin the split and merge  is  related  to  the
     size  of the beginning region, specifically, the smaller the
     number the larger the beginning region.

     The chosen homogeneity test is the test that is to  be  used
     throughout the split and merge segmentation process.

     split_merge_segment is the most frequently  used  one  among
     the  three  functions,  which provides six homgeneity tests.
     Some of the tests require additional parameters, The 6 tests
     (and their additional parameter descriptions) available are:
          (1) Pure Uniformity:  Region is considered  homogeneous
     if  the  region  is  completely uniform, i.e. all the pixels
     have the same gray value. (Additional Parameters - None).
          (2) Local Mean vs. Global Mean:  Region  is  considered
     homogeneous  if  the  local  mean is greater than the global
     mean. (Additional Parameters - None).
          (3) Local Standard Deviation vs. Global  Mean:   Region
     is considered homogeneous if the local standard deviation is
     less than 10% of the global mean. (Additional  Parameters  -
     None).
          (4) Variance Test:  Region is considered homogeneous if
     at  least  X%  of the pixels are within 2 sigma of the local
     mean, unless the standard deviation exceeds a maximum thres-
     hold. (Additional Parameters - 'X' percentage (float *) e.g.
     X = .80 for 80%, Threshold (float *) e.g. 80)
          (5)  Weighted  Gray  Level  Distance  Test:   A   total
     weighted  gray level value is computed based on the mode and
     the gray level distance from the mode weighted by  the  gray
     level distribution.  If this value is less than a threshold,
     then they region  is  considered  homogeneous.   (Additional
     Parameters - Threshold (float *) e.g. 30)
          (6) Texture Homogeneity test:  Compares the  four  qua-
     drants  of the Region, using 5 of the textural features (See
     GUI_Texture_SetUp(...)), if the  quadrants  are  similar  to
     each  other then the region is considered homogenous. (Addi-
     tional Parameters - Similarity measure (float *)  e.g.  .40,
     Pixel distance (float *) e.g. 3)

     To choose the homogeneity test, pass the number of the test.

     <parameters> refer to the parameters as illustrated  in  the
     test descriptions above.

     <RUN_PCT>: if the image is a multi-band image and RUN_PCT is
     CVIP_YES,  a  PCT_Image(...)  will  be  done on the image to
     transform it down to a single band image, prior to doing the
     split and merge segmentation. If RUN_PCT is CVIP_NO then the
     split and merge segmentation will be performed on each band,
     all bands must pass the homogeneity test in order to be con-
     sidered homogeneous.

     multi_resolution_segment   is   exactly    the    same    as
     split_merge_segment,  except that the level is fixed to 0 in
     multi_resolution_segment.

BUGS

     Runs somewhat  slowly  dependent  on  the  homogeneity  test
     chosen.  The weighted Gray level distance test is noticeably
     slower than the first 4 tests.

     The Texture Test runs extremely slow compared to the other 5
     tests,  the  more  non-homogeneous  the  image the slower it
     runs.

     The Texture Test also does a very poor job of memory manage-
     ment.   Will  consume  a large amount of memory and then not
     release it until the entire program  is  exited.   The  more
     non-homogeneous the image the more memory is consumed.

TYPES AND CONSTANTS

     #include <stdio.h>
     #include <stdlib.h>
     #include "CVIPdef.h"
     #include "CVIPtoolkit.h"
     #include "split_merge.h"
     #include "CVIPtexture.h"

     typedef struct  {
      /* [0] -> 0 degree, [1] -> 45 degree, [2] -> 90 degree, [3] -> 135 degree, [4] -> average, [5] -> range (max - min) */
      float ASM[6];          /*  (1) Angular Second Moment */
      float contrast[6];     /*  (2) Contrast */
      float correlation[6];  /*  (3) Correlation */
      float variance[6];     /*  (4) Variance */
      float IDM[6];          /*  (5) Inverse Diffenence Moment */
      float sum_avg[6];      /*  (6) Sum Average */
      float sum_var[6];      /*  (7) Sum Variance */
      float sum_entropy[6];  /*  (8) Sum Entropy */
      float entropy[6];      /*  (9) Entropy */
      float diff_var[6];     /* (10) Difference Variance */
      float diff_entropy[6]; /* (11) Diffenence Entropy */
      float meas_corr1[6];   /* (12) Measure of Correlation 1 */
      float meas_corr2[6];   /* (13) Measure of Correlation 2 */
      float max_corr_coef[6];/* (14) Maximal Correlation Coefficient */
      } TEXTURE;

     typedef struct {
      /* Allows the user to choose which features to extract, a zero will cause
        the feature to be ignored, the returned feature value will be 0.0 */
      int ASM;               /*  (1) Angular Second Moment */
      int contrast;          /*  (2) Contrast */
      int correlation;       /*  (3) Correlation */
      int variance;          /*  (4) Variance */
      int IDM;               /*  (5) Inverse Diffenence Moment */
      int sum_avg;           /*  (6) Sum Average */
      int sum_var;           /*  (7) Sum Variance */
      int sum_entropy;       /*  (8) Sum Entropy */
      int entropy;           /*  (9) Entropy */
      int diff_var;          /* (10) Difference Variance  */
      int diff_entropy;      /* (11) Diffenence Entropy  */
      int meas_corr1;        /* (12) Measure of Correlation 1 */
      int meas_corr2;        /* (13) Measure of Correlation 2 */
      int max_corr_coef;     /* (14) Maximal Correlation Coefficient */
      } TEXTURE_FEATURE_MAP;

     typedef struct quad QUAD;
      struct quad {  /* quadrant definitions */
      byte data[3];
      unsigned int x;
      unsigned int y;
      unsigned int dx;
      unsigned int dy;
      QUAD *lower_right;
      QUAD *lower_left;
      QUAD *upper_right;
      QUAD *upper_left;
     };

     typedef struct stack STACK;
      struct stack {
      QUAD *key;
      STACK *next;
     } ;

     typedef struct quad_list_item* QUAD_LIST;
      struct quad_list_item {
      QUAD *q;
      QUAD_LIST next;
     };

RETURN VALUES

     Pointer to Image structure  containing  segmented  image  on
     success; a NULL pointer on failure.

HISTORY

     History information recorded: None

EXAMPLE

     The   following   example   uses    the    setup    function
     "split_merge_setup"  to  get  keyboard input for the parame-
     ters. Refer $CVIPHOME/split_merge.c for  more  detail  about
     the function.

      #include "CVIPtoolkit.h"
      #include "CVIPdef.h"
      #include "CVIPconvert.h"
      #include "CVIPsegment.h"

      void main()
      {
      Image *cvipImage;
      IMAGE_FORMAT format;
      char *inputfile, *outputfile;

      setDisplay_Image("picture", "Default");
      print_CVIP("0Enter the Input File Name:  ");
      inputfile =(char *) getString_CVIP();
      format = getFormat_CVIP(inputfile);
      cvipImage = read_Image(inputfile, 1);
      view_Image(cvipImage, inputfile);
      cvipImage = (Image *) split_merge_setup(cvipImage);
      print_CVIP("0Enter the Output File Name:  ");
      outputfile = getString_CVIP();
      view_Image(cvipImage, outputfile);
      write_Image(cvipImage,outputfile,CVIP_NO,CVIP_NO,format,1);
      free(inputfile);
      free(outputfile);
      }

SEE ALSO

     libsegment, predicate_test, quadtree2ras

AUTHOR

     Copyright (C) 1996 SIUE - by Scott E. Umbaugh,  Greg  Hance,
     and Steven M. Costello.