00001 /*---------------------------------------------------------------------------- 00002 00003 LSD - Line Segment Detector on digital images 00004 00005 This code is part of the following publication and was subject 00006 to peer review: 00007 00008 "LSD: a Line Segment Detector" by Rafael Grompone von Gioi, 00009 Jeremie Jakubowicz, Jean-Michel Morel, and Gregory Randall, 00010 Image Processing On Line, 2012. DOI:10.5201/ipol.2012.gjmr-lsd 00011 http://dx.doi.org/10.5201/ipol.2012.gjmr-lsd 00012 00013 Copyright (c) 2007-2011 rafael grompone von gioi <grompone@gmail.com> 00014 00015 This program is free software: you can redistribute it and/or modify 00016 it under the terms of the GNU Affero General Public License as 00017 published by the Free Software Foundation, either version 3 of the 00018 License, or (at your option) any later version. 00019 00020 This program is distributed in the hope that it will be useful, 00021 but WITHOUT ANY WARRANTY; without even the implied warranty of 00022 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00023 GNU Affero General Public License for more details. 00024 00025 You should have received a copy of the GNU Affero General Public License 00026 along with this program. If not, see <http://www.gnu.org/licenses/>. 00027 00028 ----------------------------------------------------------------------------*/ 00029 00030 /*----------------------------------------------------------------------------*/ 00031 /** @file lsd.h 00032 LSD module header 00033 @author rafael grompone von gioi <grompone@gmail.com> 00034 */ 00035 /*----------------------------------------------------------------------------*/ 00036 #ifndef LSD_HEADER 00037 #define LSD_HEADER 00038 00039 /*----------------------------------------------------------------------------*/ 00040 /** LSD Full Interface 00041 00042 @param n_out Pointer to an int where LSD will store the number of 00043 line segments detected. 00044 00045 @param img Pointer to input image data. It must be an array of 00046 doubles of size X x Y, and the pixel at coordinates 00047 (x,y) is obtained by img[x+y*X]. 00048 00049 @param X X size of the image: the number of columns. 00050 00051 @param Y Y size of the image: the number of rows. 00052 00053 @param scale When different from 1.0, LSD will scale the input image 00054 by 'scale' factor by Gaussian filtering, before detecting 00055 line segments. 00056 Example: if scale=0.8, the input image will be subsampled 00057 to 80% of its size, before the line segment detector 00058 is applied. 00059 Suggested value: 0.8 00060 00061 @param sigma_scale When scale!=1.0, the sigma of the Gaussian filter is: 00062 sigma = sigma_scale / scale, if scale < 1.0 00063 sigma = sigma_scale, if scale >= 1.0 00064 Suggested value: 0.6 00065 00066 @param quant Bound to the quantization error on the gradient norm. 00067 Example: if gray levels are quantized to integer steps, 00068 the gradient (computed by finite differences) error 00069 due to quantization will be bounded by 2.0, as the 00070 worst case is when the error are 1 and -1, that 00071 gives an error of 2.0. 00072 Suggested value: 2.0 00073 00074 @param ang_th Gradient angle tolerance in the region growing 00075 algorithm, in degrees. 00076 Suggested value: 22.5 00077 00078 @param log_eps Detection threshold, accept if -log10(NFA) > log_eps. 00079 The larger the value, the more strict the detector is, 00080 and will result in less detections. 00081 (Note that the 'minus sign' makes that this 00082 behavior is opposite to the one of NFA.) 00083 The value -log10(NFA) is equivalent but more 00084 intuitive than NFA: 00085 - -1.0 gives an average of 10 false detections on noise 00086 - 0.0 gives an average of 1 false detections on noise 00087 - 1.0 gives an average of 0.1 false detections on nose 00088 - 2.0 gives an average of 0.01 false detections on noise 00089 . 00090 Suggested value: 0.0 00091 00092 @param density_th Minimal proportion of 'supporting' points in a rectangle. 00093 Suggested value: 0.7 00094 00095 @param n_bins Number of bins used in the pseudo-ordering of gradient 00096 modulus. 00097 Suggested value: 1024 00098 00099 @param reg_img Optional output: if desired, LSD will return an 00100 int image where each pixel indicates the line segment 00101 to which it belongs. Unused pixels have the value '0', 00102 while the used ones have the number of the line segment, 00103 numbered 1,2,3,..., in the same order as in the 00104 output list. If desired, a non NULL int** pointer must 00105 be assigned, and LSD will make that the pointer point 00106 to an int array of size reg_x x reg_y, where the pixel 00107 value at (x,y) is obtained with (*reg_img)[x+y*reg_x]. 00108 Note that the resulting image has the size of the image 00109 used for the processing, that is, the size of the input 00110 image scaled by the given factor 'scale'. If scale!=1 00111 this size differs from XxY and that is the reason why 00112 its value is given by reg_x and reg_y. 00113 Suggested value: NULL 00114 00115 @param reg_x Pointer to an int where LSD will put the X size 00116 'reg_img' image, when asked for. 00117 Suggested value: NULL 00118 00119 @param reg_y Pointer to an int where LSD will put the Y size 00120 'reg_img' image, when asked for. 00121 Suggested value: NULL 00122 00123 @return A double array of size 7 x n_out, containing the list 00124 of line segments detected. The array contains first 00125 7 values of line segment number 1, then the 7 values 00126 of line segment number 2, and so on, and it finish 00127 by the 7 values of line segment number n_out. 00128 The seven values are: 00129 - x1,y1,x2,y2,width,p,-log10(NFA) 00130 . 00131 for a line segment from coordinates (x1,y1) to (x2,y2), 00132 a width 'width', an angle precision of p in (0,1) given 00133 by angle_tolerance/180 degree, and NFA value 'NFA'. 00134 If 'out' is the returned pointer, the 7 values of 00135 line segment number 'n+1' are obtained with 00136 'out[7*n+0]' to 'out[7*n+6]'. 00137 */ 00138 double * LineSegmentDetection( int * n_out, 00139 double * img, int X, int Y, 00140 double scale, double sigma_scale, double quant, 00141 double ang_th, double log_eps, double density_th, 00142 int n_bins, 00143 int ** reg_img, int * reg_x, int * reg_y ); 00144 00145 /*----------------------------------------------------------------------------*/ 00146 /** LSD Simple Interface with Scale and Region output. 00147 00148 @param n_out Pointer to an int where LSD will store the number of 00149 line segments detected. 00150 00151 @param img Pointer to input image data. It must be an array of 00152 doubles of size X x Y, and the pixel at coordinates 00153 (x,y) is obtained by img[x+y*X]. 00154 00155 @param X X size of the image: the number of columns. 00156 00157 @param Y Y size of the image: the number of rows. 00158 00159 @param scale When different from 1.0, LSD will scale the input image 00160 by 'scale' factor by Gaussian filtering, before detecting 00161 line segments. 00162 Example: if scale=0.8, the input image will be subsampled 00163 to 80% of its size, before the line segment detector 00164 is applied. 00165 Suggested value: 0.8 00166 00167 @param reg_img Optional output: if desired, LSD will return an 00168 int image where each pixel indicates the line segment 00169 to which it belongs. Unused pixels have the value '0', 00170 while the used ones have the number of the line segment, 00171 numbered 1,2,3,..., in the same order as in the 00172 output list. If desired, a non NULL int** pointer must 00173 be assigned, and LSD will make that the pointer point 00174 to an int array of size reg_x x reg_y, where the pixel 00175 value at (x,y) is obtained with (*reg_img)[x+y*reg_x]. 00176 Note that the resulting image has the size of the image 00177 used for the processing, that is, the size of the input 00178 image scaled by the given factor 'scale'. If scale!=1 00179 this size differs from XxY and that is the reason why 00180 its value is given by reg_x and reg_y. 00181 Suggested value: NULL 00182 00183 @param reg_x Pointer to an int where LSD will put the X size 00184 'reg_img' image, when asked for. 00185 Suggested value: NULL 00186 00187 @param reg_y Pointer to an int where LSD will put the Y size 00188 'reg_img' image, when asked for. 00189 Suggested value: NULL 00190 00191 @return A double array of size 7 x n_out, containing the list 00192 of line segments detected. The array contains first 00193 7 values of line segment number 1, then the 7 values 00194 of line segment number 2, and so on, and it finish 00195 by the 7 values of line segment number n_out. 00196 The seven values are: 00197 - x1,y1,x2,y2,width,p,-log10(NFA) 00198 . 00199 for a line segment from coordinates (x1,y1) to (x2,y2), 00200 a width 'width', an angle precision of p in (0,1) given 00201 by angle_tolerance/180 degree, and NFA value 'NFA'. 00202 If 'out' is the returned pointer, the 7 values of 00203 line segment number 'n+1' are obtained with 00204 'out[7*n+0]' to 'out[7*n+6]'. 00205 */ 00206 double * lsd_scale_region( int * n_out, 00207 double * img, int X, int Y, double scale, 00208 int ** reg_img, int * reg_x, int * reg_y ); 00209 00210 /*----------------------------------------------------------------------------*/ 00211 /** LSD Simple Interface with Scale 00212 00213 @param n_out Pointer to an int where LSD will store the number of 00214 line segments detected. 00215 00216 @param img Pointer to input image data. It must be an array of 00217 doubles of size X x Y, and the pixel at coordinates 00218 (x,y) is obtained by img[x+y*X]. 00219 00220 @param X X size of the image: the number of columns. 00221 00222 @param Y Y size of the image: the number of rows. 00223 00224 @param scale When different from 1.0, LSD will scale the input image 00225 by 'scale' factor by Gaussian filtering, before detecting 00226 line segments. 00227 Example: if scale=0.8, the input image will be subsampled 00228 to 80% of its size, before the line segment detector 00229 is applied. 00230 Suggested value: 0.8 00231 00232 @return A double array of size 7 x n_out, containing the list 00233 of line segments detected. The array contains first 00234 7 values of line segment number 1, then the 7 values 00235 of line segment number 2, and so on, and it finish 00236 by the 7 values of line segment number n_out. 00237 The seven values are: 00238 - x1,y1,x2,y2,width,p,-log10(NFA) 00239 . 00240 for a line segment from coordinates (x1,y1) to (x2,y2), 00241 a width 'width', an angle precision of p in (0,1) given 00242 by angle_tolerance/180 degree, and NFA value 'NFA'. 00243 If 'out' is the returned pointer, the 7 values of 00244 line segment number 'n+1' are obtained with 00245 'out[7*n+0]' to 'out[7*n+6]'. 00246 */ 00247 double * lsd_scale(int * n_out, double * img, int X, int Y, double scale); 00248 00249 /*----------------------------------------------------------------------------*/ 00250 /** LSD Simple Interface 00251 00252 @param n_out Pointer to an int where LSD will store the number of 00253 line segments detected. 00254 00255 @param img Pointer to input image data. It must be an array of 00256 doubles of size X x Y, and the pixel at coordinates 00257 (x,y) is obtained by img[x+y*X]. 00258 00259 @param X X size of the image: the number of columns. 00260 00261 @param Y Y size of the image: the number of rows. 00262 00263 @return A double array of size 7 x n_out, containing the list 00264 of line segments detected. The array contains first 00265 7 values of line segment number 1, then the 7 values 00266 of line segment number 2, and so on, and it finish 00267 by the 7 values of line segment number n_out. 00268 The seven values are: 00269 - x1,y1,x2,y2,width,p,-log10(NFA) 00270 . 00271 for a line segment from coordinates (x1,y1) to (x2,y2), 00272 a width 'width', an angle precision of p in (0,1) given 00273 by angle_tolerance/180 degree, and NFA value 'NFA'. 00274 If 'out' is the returned pointer, the 7 values of 00275 line segment number 'n+1' are obtained with 00276 'out[7*n+0]' to 'out[7*n+6]'. 00277 */ 00278 double * lsd(int * n_out, double * img, int X, int Y); 00279 00280 #endif /* !LSD_HEADER */ 00281 /*----------------------------------------------------------------------------*/