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