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: number) -> 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: number) -> 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: number) -> count: number [in Lua 5] \endverbatim
00124 * \verbatim im.AnalyzeFindRegionsNew(image: imImage, connect: number, touch_border: number) -> 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 size outside 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 ignore big objects.
00201 *
00202 * \verbatim im.ProcessPrune(src_image: imImage, dst_image: imImage, connect: number, start_size: number, end_size: number) [in Lua 5] \endverbatim
00203 * \verbatim im.ProcessPruneNew(image: imImage, connect: number, start_size: number, end_size: number) -> new_image: imImage [in Lua 5] \endverbatim
00204 * \ingroup analyze */
00205 void imProcessPrune(const imImage* src_image, imImage* dst_image, int connect, int start_size, int end_size);
00206
00207 /** Fill holes inside white regions. \n
00208 * Source and destiny are a binary images. Regions can be 4 connected or 8 connected. \n
00209 * Can be done in-place.
00210 *
00211 * \verbatim im.ProcessFillHoles(src_image: imImage, dst_image: imImage, connect: number) [in Lua 5] \endverbatim
00212 * \verbatim im.ProcessFillHolesNew(image: imImage, connect: number) -> new_image: imImage [in Lua 5] \endverbatim
00213 * \ingroup analyze */
00214 void imProcessFillHoles(const imImage* src_image, imImage* dst_image, int connect);
00215
00216
00217 #if defined(__cplusplus)
00218 }
00219 #endif
00220
00221 #endif