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.6 2005/12/11 23:41:25 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);
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);
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