1 /*---------------------------------------------------------------------------- 2 3 LSD - Line Segment Detector on digital images 4 5 This code is part of the following publication and was subject 6 to peer review: 7 8 "LSD: a Line Segment Detector" by Rafael Grompone von Gioi, 9 Jeremie Jakubowicz, Jean-Michel Morel, and Gregory Randall, 10 Image Processing On Line, 2012. DOI:10.5201/ipol.2012.gjmr-lsd 11 http://dx.doi.org/10.5201/ipol.2012.gjmr-lsd 12 13 Copyright (c) 2007-2011 rafael grompone von gioi <grompone@gmail.com> 14 15 This program is free software: you can redistribute it and/or modify 16 it under the terms of the GNU Affero General Public License as 17 published by the Free Software Foundation, either version 3 of the 18 License, or (at your option) any later version. 19 20 This program is distributed in the hope that it will be useful, 21 but WITHOUT ANY WARRANTY; without even the implied warranty of 22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 23 GNU Affero General Public License for more details. 24 25 You should have received a copy of the GNU Affero General Public License 26 along with this program. If not, see <http://www.gnu.org/licenses/>. 27 28 ----------------------------------------------------------------------------*/ 29 30 /*----------------------------------------------------------------------------*/ 31 /** @file lsd.h 32 LSD module header 33 @author rafael grompone von gioi <grompone@gmail.com> 34 */ 35 /*----------------------------------------------------------------------------*/ 36 #ifndef LSD_HEADER 37 #define LSD_HEADER 38 39 /*----------------------------------------------------------------------------*/ 40 /** LSD Full Interface 41 42 @param n_out Pointer to an int where LSD will store the number of 43 line segments detected. 44 45 @param img Pointer to input image data. It must be an array of 46 doubles of size X x Y, and the pixel at coordinates 47 (x,y) is obtained by img[x+y*X]. 48 49 @param X X size of the image: the number of columns. 50 51 @param Y Y size of the image: the number of rows. 52 53 @param scale When different from 1.0, LSD will scale the input image 54 by 'scale' factor by Gaussian filtering, before detecting 55 line segments. 56 Example: if scale=0.8, the input image will be subsampled 57 to 80% of its size, before the line segment detector 58 is applied. 59 Suggested value: 0.8 60 61 @param sigma_scale When scale!=1.0, the sigma of the Gaussian filter is: 62 sigma = sigma_scale / scale, if scale < 1.0 63 sigma = sigma_scale, if scale >= 1.0 64 Suggested value: 0.6 65 66 @param quant Bound to the quantization error on the gradient norm. 67 Example: if gray levels are quantized to integer steps, 68 the gradient (computed by finite differences) error 69 due to quantization will be bounded by 2.0, as the 70 worst case is when the error are 1 and -1, that 71 gives an error of 2.0. 72 Suggested value: 2.0 73 74 @param ang_th Gradient angle tolerance in the region growing 75 algorithm, in degrees. 76 Suggested value: 22.5 77 78 @param log_eps Detection threshold, accept if -log10(NFA) > log_eps. 79 The larger the value, the more strict the detector is, 80 and will result in less detections. 81 (Note that the 'minus sign' makes that this 82 behavior is opposite to the one of NFA.) 83 The value -log10(NFA) is equivalent but more 84 intuitive than NFA: 85 - -1.0 gives an average of 10 false detections on noise 86 - 0.0 gives an average of 1 false detections on noise 87 - 1.0 gives an average of 0.1 false detections on nose 88 - 2.0 gives an average of 0.01 false detections on noise 89 . 90 Suggested value: 0.0 91 92 @param density_th Minimal proportion of 'supporting' points in a rectangle. 93 Suggested value: 0.7 94 95 @param n_bins Number of bins used in the pseudo-ordering of gradient 96 modulus. 97 Suggested value: 1024 98 99 @param reg_img Optional output: if desired, LSD will return an 100 int image where each pixel indicates the line segment 101 to which it belongs. Unused pixels have the value '0', 102 while the used ones have the number of the line segment, 103 numbered 1,2,3,..., in the same order as in the 104 output list. If desired, a non NULL int** pointer must 105 be assigned, and LSD will make that the pointer point 106 to an int array of size reg_x x reg_y, where the pixel 107 value at (x,y) is obtained with (*reg_img)[x+y*reg_x]. 108 Note that the resulting image has the size of the image 109 used for the processing, that is, the size of the input 110 image scaled by the given factor 'scale'. If scale!=1 111 this size differs from XxY and that is the reason why 112 its value is given by reg_x and reg_y. 113 Suggested value: NULL 114 115 @param reg_x Pointer to an int where LSD will put the X size 116 'reg_img' image, when asked for. 117 Suggested value: NULL 118 119 @param reg_y Pointer to an int where LSD will put the Y size 120 'reg_img' image, when asked for. 121 Suggested value: NULL 122 123 @return A double array of size 7 x n_out, containing the list 124 of line segments detected. The array contains first 125 7 values of line segment number 1, then the 7 values 126 of line segment number 2, and so on, and it finish 127 by the 7 values of line segment number n_out. 128 The seven values are: 129 - x1,y1,x2,y2,width,p,-log10(NFA) 130 . 131 for a line segment from coordinates (x1,y1) to (x2,y2), 132 a width 'width', an angle precision of p in (0,1) given 133 by angle_tolerance/180 degree, and NFA value 'NFA'. 134 If 'out' is the returned pointer, the 7 values of 135 line segment number 'n+1' are obtained with 136 'out[7*n+0]' to 'out[7*n+6]'. 137 */ 138 double * LineSegmentDetection( int * n_out, 139 double * img, int X, int Y, 140 double scale, double sigma_scale, double quant, 141 double ang_th, double log_eps, double density_th, 142 int n_bins, 143 int ** reg_img, int * reg_x, int * reg_y ); 144 145 /*----------------------------------------------------------------------------*/ 146 /** LSD Simple Interface with Scale and Region output. 147 148 @param n_out Pointer to an int where LSD will store the number of 149 line segments detected. 150 151 @param img Pointer to input image data. It must be an array of 152 doubles of size X x Y, and the pixel at coordinates 153 (x,y) is obtained by img[x+y*X]. 154 155 @param X X size of the image: the number of columns. 156 157 @param Y Y size of the image: the number of rows. 158 159 @param scale When different from 1.0, LSD will scale the input image 160 by 'scale' factor by Gaussian filtering, before detecting 161 line segments. 162 Example: if scale=0.8, the input image will be subsampled 163 to 80% of its size, before the line segment detector 164 is applied. 165 Suggested value: 0.8 166 167 @param reg_img Optional output: if desired, LSD will return an 168 int image where each pixel indicates the line segment 169 to which it belongs. Unused pixels have the value '0', 170 while the used ones have the number of the line segment, 171 numbered 1,2,3,..., in the same order as in the 172 output list. If desired, a non NULL int** pointer must 173 be assigned, and LSD will make that the pointer point 174 to an int array of size reg_x x reg_y, where the pixel 175 value at (x,y) is obtained with (*reg_img)[x+y*reg_x]. 176 Note that the resulting image has the size of the image 177 used for the processing, that is, the size of the input 178 image scaled by the given factor 'scale'. If scale!=1 179 this size differs from XxY and that is the reason why 180 its value is given by reg_x and reg_y. 181 Suggested value: NULL 182 183 @param reg_x Pointer to an int where LSD will put the X size 184 'reg_img' image, when asked for. 185 Suggested value: NULL 186 187 @param reg_y Pointer to an int where LSD will put the Y size 188 'reg_img' image, when asked for. 189 Suggested value: NULL 190 191 @return A double array of size 7 x n_out, containing the list 192 of line segments detected. The array contains first 193 7 values of line segment number 1, then the 7 values 194 of line segment number 2, and so on, and it finish 195 by the 7 values of line segment number n_out. 196 The seven values are: 197 - x1,y1,x2,y2,width,p,-log10(NFA) 198 . 199 for a line segment from coordinates (x1,y1) to (x2,y2), 200 a width 'width', an angle precision of p in (0,1) given 201 by angle_tolerance/180 degree, and NFA value 'NFA'. 202 If 'out' is the returned pointer, the 7 values of 203 line segment number 'n+1' are obtained with 204 'out[7*n+0]' to 'out[7*n+6]'. 205 */ 206 double * lsd_scale_region( int * n_out, 207 double * img, int X, int Y, double scale, 208 int ** reg_img, int * reg_x, int * reg_y ); 209 210 /*----------------------------------------------------------------------------*/ 211 /** LSD Simple Interface with Scale 212 213 @param n_out Pointer to an int where LSD will store the number of 214 line segments detected. 215 216 @param img Pointer to input image data. It must be an array of 217 doubles of size X x Y, and the pixel at coordinates 218 (x,y) is obtained by img[x+y*X]. 219 220 @param X X size of the image: the number of columns. 221 222 @param Y Y size of the image: the number of rows. 223 224 @param scale When different from 1.0, LSD will scale the input image 225 by 'scale' factor by Gaussian filtering, before detecting 226 line segments. 227 Example: if scale=0.8, the input image will be subsampled 228 to 80% of its size, before the line segment detector 229 is applied. 230 Suggested value: 0.8 231 232 @return A double array of size 7 x n_out, containing the list 233 of line segments detected. The array contains first 234 7 values of line segment number 1, then the 7 values 235 of line segment number 2, and so on, and it finish 236 by the 7 values of line segment number n_out. 237 The seven values are: 238 - x1,y1,x2,y2,width,p,-log10(NFA) 239 . 240 for a line segment from coordinates (x1,y1) to (x2,y2), 241 a width 'width', an angle precision of p in (0,1) given 242 by angle_tolerance/180 degree, and NFA value 'NFA'. 243 If 'out' is the returned pointer, the 7 values of 244 line segment number 'n+1' are obtained with 245 'out[7*n+0]' to 'out[7*n+6]'. 246 */ 247 double * lsd_scale(int * n_out, double * img, int X, int Y, double scale); 248 249 /*----------------------------------------------------------------------------*/ 250 /** LSD Simple Interface 251 252 @param n_out Pointer to an int where LSD will store the number of 253 line segments detected. 254 255 @param img Pointer to input image data. It must be an array of 256 doubles of size X x Y, and the pixel at coordinates 257 (x,y) is obtained by img[x+y*X]. 258 259 @param X X size of the image: the number of columns. 260 261 @param Y Y size of the image: the number of rows. 262 263 @return A double array of size 7 x n_out, containing the list 264 of line segments detected. The array contains first 265 7 values of line segment number 1, then the 7 values 266 of line segment number 2, and so on, and it finish 267 by the 7 values of line segment number n_out. 268 The seven values are: 269 - x1,y1,x2,y2,width,p,-log10(NFA) 270 . 271 for a line segment from coordinates (x1,y1) to (x2,y2), 272 a width 'width', an angle precision of p in (0,1) given 273 by angle_tolerance/180 degree, and NFA value 'NFA'. 274 If 'out' is the returned pointer, the 7 values of 275 line segment number 'n+1' are obtained with 276 'out[7*n+0]' to 'out[7*n+6]'. 277 */ 278 double * lsd(int * n_out, double * img, int X, int Y); 279 280 #endif /* !LSD_HEADER */ 281 /*----------------------------------------------------------------------------*/ 282