IM: im_process_ana.h Source File

IM - An Imaging Tool

im_process_ana.h

Go to the documentation of this file.
00001 /** \file
00002  * \brief Image Statistics and Analysis
00003  *
00004  * See Copyright Notice in im_lib.h
00005  * $Id: im_process_ana.h,v 1.7 2006/11/20 13:18:51 scuri Exp $
00006  */
00007 
00008 #ifndef __IM_PROC_ANA_H
00009 #define __IM_PROC_ANA_H
00010 
00011 #include "im_image.h"
00012 
00013 #if defined(__cplusplus)
00014 extern "C" {
00015 #endif
00016 
00017 
00018 
00019 /** \defgroup stats Image Statistics Calculations
00020  * \par
00021  * Operations to calculate some statistics over images.
00022  * \par
00023  * See \ref im_process_ana.h
00024  * \ingroup process */
00025 
00026 /** Calculates the RMS error between two images (Root Mean Square Error).
00027  *
00028  * \verbatim im.CalcRMSError(image1: imImage, image2: imImage) -> rms: number [in Lua 5] \endverbatim
00029  * \ingroup stats */
00030 float imCalcRMSError(const imImage* image1, const imImage* image2);
00031 
00032 /** Calculates the SNR of an image and its noise (Signal Noise Ratio).
00033  *
00034  * \verbatim im.CalcSNR(src_image: imImage, noise_image: imImage) -> snr: number [in Lua 5] \endverbatim
00035  * \ingroup stats */
00036 float imCalcSNR(const imImage* src_image, const imImage* noise_image);
00037 
00038 /** Count the number of different colors in an image. \n
00039  * Image must be IM_BYTE, but all color spaces except IM_CMYK.
00040  *
00041  * \verbatim im.CalcCountColors(image: imImage) -> count: number [in Lua 5] \endverbatim
00042  * \ingroup stats */
00043 unsigned long imCalcCountColors(const imImage* image);
00044 
00045 /** Calculates the histogram of a IM_BYTE data. \n
00046  * Histogram is always 256 positions long. \n
00047  * When cumulative is different from zero it calculates the cumulative histogram.
00048  *
00049  * \verbatim im.CalcHistogram(image: imImage, plane: number, cumulative: number) -> histo: table of numbers [in Lua 5] \endverbatim
00050  * Where plane is the depth plane to calculate the histogram. \n
00051  * The returned table is zero indexed. image can be IM_USHORT or IM_BYTE.
00052  * \ingroup stats */
00053 void imCalcHistogram(const unsigned char* data, int count, unsigned long* histo, int cumulative);
00054 
00055 /** Calculates the histogram of a IM_USHORT data. \n
00056  * Histogram is always 65535 positions long. \n
00057  * When cumulative is different from zero it calculates the cumulative histogram. \n
00058  * Use \ref imCalcHistogram in Lua.
00059  * \ingroup stats */
00060 void imCalcUShortHistogram(const unsigned short* data, int count, unsigned long* histo, int cumulative);
00061 
00062 /** Calculates the gray histogram of an image. \n
00063  * Image must be IM_BYTE/(IM_RGB, IM_GRAY, IM_BINARY or IM_MAP). \n
00064  * If the image is IM_RGB then the histogram of the luma component is calculated. \n
00065  * Histogram is always 256 positions long. \n
00066  * When cumulative is different from zero it calculates the cumulative histogram.
00067  *
00068  * \verbatim im.CalcGrayHistogram(image: imImage, cumulative: number) -> histo: table of numbers [in Lua 5] \endverbatim
00069  * \ingroup stats */
00070 void imCalcGrayHistogram(const imImage* image, unsigned long* histo, int cumulative);
00071 
00072 /** Numerical Statistics Structure
00073  * \ingroup stats */
00074 typedef struct _imStats
00075 {
00076   float max;                /**< Maximum value              */
00077   float min;                /**< Minimum value              */
00078   unsigned long positive;   /**< Number of Positive Values  */
00079   unsigned long negative;   /**< Number of Negative Values  */
00080   unsigned long zeros;      /**< Number of Zeros            */
00081   float mean;               /**< Mean                       */
00082   float stddev;             /**< Standard Deviation         */
00083 } imStats;
00084 
00085 /** Calculates the statistics about the image data. \n
00086  * There is one stats for each depth plane. For ex: stats[0]=red stats, stats[0]=green stats, ... \n
00087  * Supports all data types except IM_CFLOAT. \n
00088  *
00089  * \verbatim im.CalcImageStatistics(image: imImage) -> stats: table [in Lua 5] \endverbatim
00090  * Table contains the following fields: max, min, positive, negative, zeros, mean, stddev. 
00091  * The same as the \ref imStats structure.
00092  * \ingroup stats */
00093 void imCalcImageStatistics(const imImage* image, imStats* stats);
00094 
00095 /** Calculates the statistics about the image histogram data.\n
00096  * There is one stats for each depth plane. For ex: stats[0]=red stats, stats[0]=green stats, ... \n
00097  * Only IM_BYTE images are supported.
00098  *
00099  * \verbatim im.CalcHistogramStatistics(image: imImage) -> stats: table [in Lua 5] \endverbatim
00100  * \ingroup stats */
00101 void imCalcHistogramStatistics(const imImage* image, imStats* stats);
00102 
00103 /** Calculates some extra statistics about the image histogram data.\n
00104  * There is one stats for each depth plane. \n
00105  * Only IM_BYTE images are supported. \n
00106  * mode will be -1 if more than one max is found.
00107  *
00108  * \verbatim im.CalcHistoImageStatistics(image: imImage) -> median: number, mode: number [in Lua 5] \endverbatim
00109  * \ingroup stats */
00110 void imCalcHistoImageStatistics(const imImage* image, int* median, int* mode);
00111 
00112 
00113 
00114 /** \defgroup analyze Image Analysis
00115  * \par
00116  * See \ref im_process_ana.h
00117  * \ingroup process */
00118 
00119 /** Find white regions in binary image. \n
00120  * Result is IM_GRAY/IM_USHORT type. Regions can be 4 connected or 8 connected. \n
00121  * Returns the number of regions found. Background is marked as 0. \n
00122  * Regions touching the border are considered only if touch_border=1.
00123  *
00124  * \verbatim im.AnalyzeFindRegions(src_image: imImage, dst_image: imImage, connect: number, touch_border: number) -> count: number [in Lua 5] \endverbatim
00125  * \verbatim im.AnalyzeFindRegionsNew(image: imImage, connect: number, touch_border: number) -> count: number, new_image: imImage [in Lua 5] \endverbatim
00126  * \ingroup analyze */
00127 int imAnalyzeFindRegions(const imImage* src_image, imImage* dst_image, int connect, int touch_border);
00128 
00129 /** Measure the actual area of all regions. Holes are not included. \n
00130  * This is the number of pixels of each region. \n
00131  * Source image is IM_GRAY/IM_USHORT type (the result of \ref imAnalyzeFindRegions). \n
00132  * area has size the number of regions.
00133  *
00134  * \verbatim im.AnalyzeMeasureArea(image: imImage, [region_count: number]) -> area: table of numbers [in Lua 5] \endverbatim
00135  * The returned table is zero indexed. 
00136  * \ingroup analyze */
00137 void imAnalyzeMeasureArea(const imImage* image, int* area, int region_count);
00138 
00139 /** Measure the polygonal area limited by the perimeter line of all regions. Holes are not included. \n
00140  * Notice that some regions may have polygonal area zero. \n
00141  * Source image is IM_GRAY/IM_USHORT type (the result of \ref imAnalyzeFindRegions). \n
00142  * perimarea has size the number of regions.
00143  *
00144  * \verbatim im.AnalyzeMeasurePerimArea(image: imImage, [region_count: number]) -> perimarea: table of numbers [in Lua 5] \endverbatim
00145  * The returned table is zero indexed. 
00146  * \ingroup analyze */
00147 void imAnalyzeMeasurePerimArea(const imImage* image, float* perimarea);
00148 
00149 /** Calculate the centroid position of all regions. Holes are not included. \n
00150  * Source image is IM_GRAY/IM_USHORT type (the result of \ref imAnalyzeFindRegions). \n
00151  * area, cx and cy have size the number of regions. If area is NULL will be internally calculated.
00152  *
00153  * \verbatim im.AnalyzeMeasureCentroid(image: imImage, [area: table of numbers], [region_count: number]) -> cx: table of numbers, cy: table of numbers [in Lua 5] \endverbatim
00154  * The returned tables are zero indexed. 
00155  * \ingroup analyze */
00156 void imAnalyzeMeasureCentroid(const imImage* image, const int* area, int region_count, float* cx, float* cy);
00157 
00158 /** Calculate the principal major axis slope of all regions. \n
00159  * Source image is IM_GRAY/IM_USHORT type (the result of \ref imAnalyzeFindRegions). \n
00160  * data has size the number of regions. If area or centroid are NULL will be internally calculated. \n
00161  * Principal (major and minor) axes are defined to be those axes that pass through the
00162  * centroid, about which the moment of inertia of the region is, respectively maximal or minimal.
00163  *
00164  * \verbatim im.AnalyzeMeasurePrincipalAxis(image: imImage, [area: table of numbers], [cx: table of numbers], [cy: table of numbers], [region_count: number]) 
00165                               -> major_slope: table of numbers, major_length: table of numbers, minor_slope: table of numbers, minor_length: table of numbers [in Lua 5] \endverbatim
00166  * The returned tables are zero indexed. 
00167  * \ingroup analyze */
00168 void imAnalyzeMeasurePrincipalAxis(const imImage* image, const int* area, const float* cx, const float* cy, 
00169                                    const int region_count, float* major_slope, float* major_length, 
00170                                                            float* minor_slope, float* minor_length);
00171 
00172 /** Measure the number and area of holes of all regions. \n
00173  * Source image is IM_USHORT type (the result of \ref imAnalyzeFindRegions). \n
00174  * area and perim has size the number of regions, if some is NULL it will be not calculated.
00175  *
00176  * \verbatim im.AnalyzeMeasureHoles(image: imImage, connect: number, [region_count: number]) -> holes_count: number, area: table of numbers, perim: table of numbers [in Lua 5] \endverbatim
00177  * The returned tables are zero indexed. 
00178  * \ingroup analyze */
00179 void imAnalyzeMeasureHoles(const imImage* image, int connect, int *holes_count, int* area, float* perim);
00180 
00181 /** Measure the total perimeter of all regions (external and internal). \n
00182  * Source image is IM_GRAY/IM_USHORT type (the result of imAnalyzeFindRegions). \n
00183  * It uses a half-pixel inter distance for 8 neighboors in a perimeter of a 4 connected region. \n
00184  * This function can also be used to measure line lenght. \n
00185  * perim has size the number of regions.
00186  *
00187  * \verbatim im.AnalyzeMeasurePerimeter(image: imImage) -> perim: table of numbers [in Lua 5] \endverbatim
00188  * \ingroup analyze */
00189 void imAnalyzeMeasurePerimeter(const imImage* image, float* perim, int region_count);
00190 
00191 /** Isolates the perimeter line of gray integer images. Background is defined as being black (0). \n
00192  * It just checks if at least one of the 4 connected neighboors is non zero. Image borders are extended with zeros.
00193  *
00194  * \verbatim im.ProcessPerimeterLine(src_image: imImage, dst_image: imImage) [in Lua 5] \endverbatim
00195  * \verbatim im.ProcessPerimeterLineNew(image: imImage) -> new_image: imImage [in Lua 5] \endverbatim
00196  * \ingroup analyze */
00197 void imProcessPerimeterLine(const imImage* src_image, imImage* dst_image);
00198 
00199 /** Eliminates regions that have size outside the given interval. \n
00200  * Source and destiny are a binary images. Regions can be 4 connected or 8 connected. \n
00201  * Can be done in-place. end_size can be zero to ignore big objects.
00202  *
00203  * \verbatim im.ProcessPrune(src_image: imImage, dst_image: imImage, connect: number, start_size: number, end_size: number) [in Lua 5] \endverbatim
00204  * \verbatim im.ProcessPruneNew(image: imImage, connect: number, start_size: number, end_size: number) -> new_image: imImage [in Lua 5] \endverbatim
00205  * \ingroup analyze */
00206 void imProcessPrune(const imImage* src_image, imImage* dst_image, int connect, int start_size, int end_size);
00207 
00208 /** Fill holes inside white regions. \n
00209  * Source and destiny are a binary images. Regions can be 4 connected or 8 connected. \n
00210  * Can be done in-place. 
00211  *
00212  * \verbatim im.ProcessFillHoles(src_image: imImage, dst_image: imImage, connect: number) [in Lua 5] \endverbatim
00213  * \verbatim im.ProcessFillHolesNew(image: imImage, connect: number) -> new_image: imImage [in Lua 5] \endverbatim
00214  * \ingroup analyze */
00215 void imProcessFillHoles(const imImage* src_image, imImage* dst_image, int connect);
00216 
00217 
00218 #if defined(__cplusplus)
00219 }
00220 #endif
00221 
00222 #endif