NAME

     libobject - CVIPtools toolkit library  for  object  analysis
     and identification

SYNOPSIS

     #include <CVIPobject.h>

PATH

     $CVIPHOME/Object

FUNCTIONS: Objects

     =======================================================================
      Object *new_Object(int label_count, Color pixel, int r_pos, int c_pos)
     =======================================================================

      <label_count> - object label
      <pixel> - color of the object
      <r_pos> - vertical position of upper left corner
      <c_pos> - horizontal position of upper left corner

      Returns: pointer to new initialized object
      Description: constructor for object class
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void print_Object(void *thisP, FILE *fileP)
     =======================================================================

      <thisP> -pointer to object
      <fileP> - file pointer

      Returns: nothing
      Description: prints the contents of an object structure
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      int read_Object( void *thisP, FILE *fileP)
     =======================================================================

      <thisP> - pointer to object
      <fileP> - file pointer

      Returns: integer error status (0 or 1)
      Description: reads an object description from a file
      Diagnostics: returns 0 upon failure to read
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void delete_Object(void *objectP)
     =======================================================================

      <objectP> - pointer to Object structure

      Returns: nothing
      Description: detroys an instance of an object structure
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      int match_Object(void *objectP, void *labelP)
     =======================================================================

      <objectP> - pointer to object structure
      <labelP> - pointer to label to match (int)

      Returns: 0 or 1
      Description: returns 1 for a match and 0 otherwise
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void drawBB_Objects(Image *imageP, ObjectList listP)
     =======================================================================

      <imageP> - pointer to Image structure
      <listP> - pointer to object list

      Returns: nothing
      Description: draws a bounding box around each box
        corresponding to each object in the list
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

FUNCTIONS: Chain Codes

     =======================================================================
      short build_ChainCode(ChainCode *ccP, Image *imageP,
       int c_min, int r_min, int c_max, int r_max);

     =======================================================================

      <ccP> - pointer to chain code object
      <imageP> - pointer to input image
      <c_min> - upper left column position of region of interest
      <r_min> - upper left row position of region of interest
      <c_max> - lower right  column position of region of interest
      <r_max> - lower right row position of region of interest
      Returns: 1 if successful else 0
      Description: Builds a Freeman chain of vectors
        describing the edge of the contour with a
        specified elevation. Always follows the contour
        in a clockwise direction.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void report_ChainCode(ChainCode *ccP)
     =======================================================================

      <ccP> - pointer to chain code object

      Returns: nothing
      Description:  Follows the Freeman chain of
        vectors describing the edge of the contour.
        Reports the elevation, start point, direction
        vectors, and the number of vectors in the chain.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      ChainCode *new_ChainCode( int start_r, int start_c, int elev )
     =======================================================================

      <start_r> - row position of tentative starting point
      <start_c> - column position of tentative starting point
      <elev> - elevation (pixel intensity of object of interest)

      Returns: pointer to new ChainCode structure
      Description:  Construct a new chain code object,
        Creates and initializes a chain code structure.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void  delete_ChainCode(ChainCode *ccP)
     =======================================================================

      <ccP> - pointer to Chaincode structure

      Returns: nothing
      Description:  Destroy the memory associated with a
        ChainCode structure.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void  getXY_ChainCode(ChainCode *ccP, int **cP, int **rP)
     =======================================================================

      <ccP> - pointer to Chaincode structure
      <cP> - pointer to array of horizontal integer coordinates
      <rP> - pointer to array of vertical  integer coordinates

      Returns: nothing
      Description:  Express the chain code as a contiguous array
        of column and row coordinates.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void  draw_ChainCode(ChainCode *ccP, Image *imageP)
     =======================================================================

      <ccP> - pointer to Chaincode structure
      <imageP> - pointer to image

      Returns: nothing
      Description:  overlay (draw) a chain code contour onto an
        image
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      int print_ChainCode(ChainCode *ccP, const char *name)
     =======================================================================

      <ccP> - pointer to Chaincode structure
      <name> - string containing file name

      Returns: 1 on success and 0 on failure
      Description:  Print a chain code representation to a file
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      ChainCode *read_ChainCode(const char *name)
     =======================================================================

      <name> - string containing file name

      Returns: pointer a chain code structure
      Description: Read a chain code file representation into a
        chain code structure.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      ChainCode *read_ChainCode(const char *name)
     =======================================================================

      <name> - string containing file name

      Returns: pointer a chain code structure
      Description: Read a chain code file representation into a
        chain code structure.
      Diagnostics: Null pointer on failure
      References: none
      Author(s): Gregory Hance

FUNCTIONS: Labeled Objects and object properties

     =======================================================================
      ObjectList label_Objects( Image *imageP, Image **labelP,
          unsigned                                    background)
     =======================================================================

      <imageP> - pointer to input image
      <labelP> - set to point to labelled image
      <background> - background pixel

      Returns: pointer to object list structure describing
        objects in labelled image
      Description: Perform sequential labelling on input image.
        The image may be binary, grayscale or color. A color
        image is limited to a color map of 256 colors or less.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      ObjectVector *listToVector_Objects(ObjectList listP)
     =======================================================================

      <listP> - pointer to object list structure

      Returns: pointer to object vector
      Description: Create a vector of objects from an object
        vector.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void printLabel_Objects( ObjectList listP, const char *name)
     =======================================================================
      <listP> - pointer to object list structure
      <name> - name of file to print to

      Returns: nothing
      Description: Print object list representation to file
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      int readLabel_Objects( ObjectList listP, const char *name )
     =======================================================================

      <listP> - pointer to object list structure
      <name> - name of file to print to

      Returns: 1 on success and 0 on failure
      Description: Read object list representation from file
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void getProp_Object(Object *objP, ROI *roiP)
     =======================================================================

      <objP> - pointer to object list
      <roiP> - Pointer to ROI image

      Returns: nothing
      Description: Obtain object properties for a region of
        interest in an image. Properties calculated are:
        (1) zero-order moment (area), (2) horizontal center
        of gravity, (3) vertical center of gravity, (4)
        orientation angle (degrees), (5) eigenvalue ratio.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
     void getProp_Objects(ObjectList listP, Image *labelP)
     =======================================================================

      <listP> - pointer to object list
      <labelP> - Pointer to labelled image

      Returns: nothing
      Description: Obtain the object properties for each object
        in the object list for the specified labelled image.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void printProp_Object( void *thisP, FILE *fileP)
     =======================================================================

      <thisP> - pointer to object
      <fileP> - open file pointer for output

      Returns: nothing
      Description: Print the properties of an object
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      void printProp_Objects(ObjectList listP, const char *name)
     =======================================================================

      <listP> - pointer to object list
      <fileP> - open file pointer for output

      Returns: nothing
      Description: Print an object list representation to a file
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      int readProp_Objects( ObjectList listP, const char *name )
     =======================================================================

      <listP> - pointer to object list
      <name> - name of file to read from

      Returns: 1 on success and 0 on failure
      Description: Read an object list representation from a file
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

     =======================================================================
      int trimList_Objects( ObjectList listP,
        unsigned width, unsigned height,
        float p_area_min, float p_area_max,
        float eig_r_min, float eig_r_max,
        float angle_min, float angle_max,
        float p_width, float p_height,
        CVIP_BOOLEAN no_edge)
     =======================================================================

      <listP> - pointer to object list
      <width, height> - width, height of image
      <p_area_min, p_area_max> - percentabe minimum/maximum area of object
        relative to image
      <eig_r_min, eig_r_max> - minimum/maximum eigenvalue ratio
      <angle_min, angle_max> - minimum/maximum angle for principal axis
      <p_width, p_height> - pencentage minimum width/height of object
        relative to image
      <no_edge> - set to CVIP_TRUE is object should not touch boundary
        of image

      Returns: 1 on success and 0 on failure
      Description: Remove objects from a list that do not meet
        the specified requirements.
      Diagnostics: none
      References: none
      Author(s): Gregory Hance

SEE ALSO

     Object.c,          ObjectContour.c,           ObjectLabel.c,
     ObjectProperties.c, TrimList.c

AUTHOR

     Copyright (C) 1996 SIUE - by Scott E Umbaugh, Greg Hance.