Main Page | Data Structures | File List | Data Fields | Globals

lsd.h

Go to the documentation of this file.
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 /*----------------------------------------------------------------------------*/

Generated on Fri Nov 11 11:11:11 2011 for LSD by doxygen 1.3.4