## 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.