Leptonica  1.82.0
Image processing and image analysis suite
kernel.c File Reference
#include <string.h>
#include <math.h>
#include "allheaders.h"

Go to the source code of this file.

Functions

L_KERNELkernelCreate (l_int32 height, l_int32 width)
 
void kernelDestroy (L_KERNEL **pkel)
 
L_KERNELkernelCopy (L_KERNEL *kels)
 
l_ok kernelGetElement (L_KERNEL *kel, l_int32 row, l_int32 col, l_float32 *pval)
 
l_ok kernelSetElement (L_KERNEL *kel, l_int32 row, l_int32 col, l_float32 val)
 
l_ok kernelGetParameters (L_KERNEL *kel, l_int32 *psy, l_int32 *psx, l_int32 *pcy, l_int32 *pcx)
 
l_ok kernelSetOrigin (L_KERNEL *kel, l_int32 cy, l_int32 cx)
 
l_ok kernelGetSum (L_KERNEL *kel, l_float32 *psum)
 
l_ok kernelGetMinMax (L_KERNEL *kel, l_float32 *pmin, l_float32 *pmax)
 
L_KERNELkernelNormalize (L_KERNEL *kels, l_float32 normsum)
 
L_KERNELkernelInvert (L_KERNEL *kels)
 
l_float32 ** create2dFloatArray (l_int32 sy, l_int32 sx)
 
L_KERNELkernelRead (const char *fname)
 
L_KERNELkernelReadStream (FILE *fp)
 
l_ok kernelWrite (const char *fname, L_KERNEL *kel)
 
l_ok kernelWriteStream (FILE *fp, L_KERNEL *kel)
 
L_KERNELkernelCreateFromString (l_int32 h, l_int32 w, l_int32 cy, l_int32 cx, const char *kdata)
 
L_KERNELkernelCreateFromFile (const char *filename)
 
L_KERNELkernelCreateFromPix (PIX *pix, l_int32 cy, l_int32 cx)
 
PIXkernelDisplayInPix (L_KERNEL *kel, l_int32 size, l_int32 gthick)
 
NUMAparseStringForNumbers (const char *str, const char *seps)
 
L_KERNELmakeFlatKernel (l_int32 height, l_int32 width, l_int32 cy, l_int32 cx)
 
L_KERNELmakeGaussianKernel (l_int32 halfh, l_int32 halfw, l_float32 stdev, l_float32 max)
 
l_ok makeGaussianKernelSep (l_int32 halfh, l_int32 halfw, l_float32 stdev, l_float32 max, L_KERNEL **pkelx, L_KERNEL **pkely)
 
L_KERNELmakeDoGKernel (l_int32 halfh, l_int32 halfw, l_float32 stdev, l_float32 ratio)
 

Variables

static const l_uint32 MaxArraySize = 100000
 

Detailed Description

     Basic operations on kernels for image convolution
        Create/destroy/copy
           L_KERNEL   *kernelCreate()
           void        kernelDestroy()
           L_KERNEL   *kernelCopy()
        Accessors:
           l_int32     kernelGetElement()
           l_int32     kernelSetElement()
           l_int32     kernelGetParameters()
           l_int32     kernelSetOrigin()
           l_int32     kernelGetSum()
           l_int32     kernelGetMinMax()
        Normalize/invert
           L_KERNEL   *kernelNormalize()
           L_KERNEL   *kernelInvert()
        Helper function
           l_float32 **create2dFloatArray()
        Serialized I/O
           L_KERNEL   *kernelRead()
           L_KERNEL   *kernelReadStream()
           l_int32     kernelWrite()
           l_int32     kernelWriteStream()
        Making a kernel from a compiled string
           L_KERNEL   *kernelCreateFromString()
        Making a kernel from a simple file format
           L_KERNEL   *kernelCreateFromFile()
        Making a kernel from a Pix
           L_KERNEL   *kernelCreateFromPix()
        Display a kernel in a pix
           PIX        *kernelDisplayInPix()
        Parse string to extract numbers
           NUMA       *parseStringForNumbers()
     Simple parametric kernels
           L_KERNEL   *makeFlatKernel()
           L_KERNEL   *makeGaussianKernel()
           L_KERNEL   *makeGaussianKernelSep()
           L_KERNEL   *makeDoGKernel()

Definition in file kernel.c.

Function Documentation

◆ create2dFloatArray()

l_float32** create2dFloatArray ( l_int32  sy,
l_int32  sx 
)

create2dFloatArray()

Parameters
[in]syrows == height
[in]sxcolumns == width
Returns
doubly indexed array i.e., an array of sy row pointers, each of which points to an array of sx floats
Notes:
     (1) The array[sy][sx] is indexed in standard "matrix notation",
         with the row index first.
     (2) The caller kernelCreate() limits the size to < 2^29 pixels.

Definition at line 503 of file kernel.c.

Referenced by kernelCreate().

◆ kernelCopy()

L_KERNEL* kernelCopy ( L_KERNEL kels)

kernelCopy()

Parameters
[in]kelssource kernel
Returns
keld copy of kels, or NULL on error

Definition at line 179 of file kernel.c.

References L_Kernel::cx, L_Kernel::cy, L_Kernel::data, kernelCreate(), and kernelGetParameters().

Referenced by fpixConvolve(), and kernelNormalize().

◆ kernelCreate()

L_KERNEL* kernelCreate ( l_int32  height,
l_int32  width 
)

kernelCreate()

Parameters
[in]height,width
Returns
kernel, or NULL on error
Notes:
     (1) kernelCreate() initializes all values to 0.
     (2) After this call, (cy,cx) and nonzero data values must be
         assigned.
     (2) The number of kernel elements must be less than 2^29.

Definition at line 112 of file kernel.c.

References create2dFloatArray(), L_Kernel::data, L_Kernel::sx, and L_Kernel::sy.

Referenced by kernelCopy(), kernelCreateFromPix(), kernelCreateFromString(), kernelInvert(), kernelNormalize(), makeDoGKernel(), makeFlatKernel(), makeGaussianKernel(), and makeRangeKernel().

◆ kernelCreateFromFile()

L_KERNEL* kernelCreateFromFile ( const char *  filename)

kernelCreateFromFile()

Parameters
[in]filename
Returns
kernel, or NULL on error
Notes:
     (1) The file contains, in the following order:
          ~ Any number of comment lines starting with '#' are ignored
          ~ The height and width of the kernel
          ~ The y and x values of the kernel origin
          ~ The kernel data, formatted as lines of numbers (integers
            or floats) for the kernel values in row-major order,
            and with no other punctuation.
            (Note: this differs from kernelCreateFromString(),
            where each line must begin and end with a double-quote
            to tell the compiler it's part of a string.)
          ~ The kernel specification ends when a blank line,
            a comment line, or the end of file is reached.
     (2) All lines must be left-justified.
     (3) See kernelCreateFromString() for a description of the string
         format for the kernel data.  As an example, here are the lines
         of a valid kernel description file  In the file, all lines
         are left-justified:
# small 3x3 kernel
3 3
1 1
25.5 51 24.3
70.2 146.3 73.4
20 50.9 18.4

Definition at line 775 of file kernel.c.

References l_binaryRead(), L_NOCOPY, sarrayCreateLinesFromString(), sarrayDestroy(), sarrayGetCount(), and sarrayGetString().

◆ kernelCreateFromPix()

L_KERNEL* kernelCreateFromPix ( PIX pix,
l_int32  cy,
l_int32  cx 
)

kernelCreateFromPix()

Parameters
[in]pix
[in]cy,cxorigin of kernel
Returns
kernel, or NULL on error
Notes:
     (1) The origin must be positive and within the dimensions of the pix.

Definition at line 880 of file kernel.c.

References kernelCreate(), kernelSetElement(), kernelSetOrigin(), pixGetDimensions(), and pixGetPixel().

◆ kernelCreateFromString()

L_KERNEL* kernelCreateFromString ( l_int32  h,
l_int32  w,
l_int32  cy,
l_int32  cx,
const char *  kdata 
)

kernelCreateFromString()

Parameters
[in]h,wheight, width
[in]cy,cxorigin
[in]kdata
Returns
kernel of the given size, or NULL on error
Notes:
     (1) The data is an array of chars, in row-major order, giving
         space separated integers in the range [-255 ... 255].
     (2) The only other formatting limitation is that you must
         leave space between the last number in each row and
         the double-quote.  If possible, it's also nice to have each
         line in the string represent a line in the kernel; e.g.,
             static const char *kdata =
                 " 20   50   20 "
                 " 70  140   70 "
                 " 20   50   20 ";

Definition at line 689 of file kernel.c.

References kernelCreate(), kernelDestroy(), kernelSetElement(), kernelSetOrigin(), lept_stderr(), numaDestroy(), numaGetCount(), numaGetFValue(), and parseStringForNumbers().

◆ kernelDestroy()

void kernelDestroy ( L_KERNEL **  pkel)

kernelDestroy()

Parameters
[in,out]pkelwill be set to null before returning
Returns
void

Definition at line 150 of file kernel.c.

References L_Kernel::data, and L_Kernel::sy.

Referenced by kernelCreateFromString().

◆ kernelDisplayInPix()

PIX* kernelDisplayInPix ( L_KERNEL kel,
l_int32  size,
l_int32  gthick 
)

kernelDisplayInPix()

Parameters
[in]kelkernel
[in]sizeof grid interiors; odd; either 1 or a minimum size of 17 is enforced
[in]gthickgrid thickness; either 0 or a minimum size of 2 is enforced
Returns
pix display of kernel, or NULL on error
Notes:
     (1) This gives a visual representation of a kernel.
     (2) There are two modes of display:
         (a) Grid lines of minimum width 2, surrounding regions
             representing kernel elements of minimum size 17,
             with a "plus" mark at the kernel origin, or
         (b) A pix without grid lines and using 1 pixel per kernel element.
     (3) For both cases, the kernel absolute value is displayed,
         normalized such that the maximum absolute value is 255.
     (4) Large 2D separable kernels should be used for convolution
         with two 1D kernels.  However, for the bilateral filter,
         the computation time is independent of the size of the
         2D content kernel.

Definition at line 941 of file kernel.c.

References kernelGetElement(), kernelGetMinMax(), kernelGetParameters(), L_FLIP_PIXELS, L_SET_PIXELS, PIX_DST, PIX_NOT, pixCreate(), pixDestroy(), pixPaintThroughMask(), pixRasterop(), pixRenderLine(), pixSetAll(), pixSetMaskedGeneral(), and pixSetPixel().

◆ kernelGetElement()

l_ok kernelGetElement ( L_KERNEL kel,
l_int32  row,
l_int32  col,
l_float32 *  pval 
)

kernelGetElement()

Parameters
[in]kel
[in]row
[in]col
[out]pval
Returns
0 if OK; 1 on error

Definition at line 215 of file kernel.c.

References L_Kernel::data, L_Kernel::sx, and L_Kernel::sy.

Referenced by kernelDisplayInPix().

◆ kernelGetMinMax()

l_ok kernelGetMinMax ( L_KERNEL kel,
l_float32 *  pmin,
l_float32 *  pmax 
)

kernelGetMinMax()

Parameters
[in]kelkernel
[out]pmin[optional] minimum value
[out]pmax[optional] maximum value
Returns
0 if OK, 1 on error

Definition at line 358 of file kernel.c.

References L_Kernel::data, and kernelGetParameters().

Referenced by kernelDisplayInPix().

◆ kernelGetParameters()

l_ok kernelGetParameters ( L_KERNEL kel,
l_int32 *  psy,
l_int32 *  psx,
l_int32 *  pcy,
l_int32 *  pcx 
)

kernelGetParameters()

Parameters
[in]kelkernel
[out]psy,psx,pcy,pcx[optional] each can be null
Returns
0 if OK, 1 on error

Definition at line 274 of file kernel.c.

References L_Kernel::cx, L_Kernel::cy, L_Kernel::sx, and L_Kernel::sy.

Referenced by fpixConvolve(), kernelCopy(), kernelDisplayInPix(), kernelGetMinMax(), kernelGetSum(), kernelInvert(), kernelNormalize(), kernelWriteStream(), and pixMultMatrixColor().

◆ kernelGetSum()

l_ok kernelGetSum ( L_KERNEL kel,
l_float32 *  psum 
)

kernelGetSum()

Parameters
[in]kelkernel
[out]psumsum of all kernel values
Returns
0 if OK, 1 on error

Definition at line 326 of file kernel.c.

References L_Kernel::data, and kernelGetParameters().

Referenced by kernelNormalize().

◆ kernelInvert()

L_KERNEL* kernelInvert ( L_KERNEL kels)

kernelInvert()

Parameters
[in]kelssource kel, to be inverted
Returns
keld spatially inverted, about the origin, or NULL on error
Notes:
     (1) For convolution, the kernel is spatially inverted before
         a "correlation" operation is done between the kernel and the image.

Definition at line 460 of file kernel.c.

References L_Kernel::cx, L_Kernel::cy, L_Kernel::data, kernelCreate(), and kernelGetParameters().

Referenced by fpixConvolve().

◆ kernelNormalize()

L_KERNEL* kernelNormalize ( L_KERNEL kels,
l_float32  normsum 
)

kernelNormalize()

Parameters
[in]kelssource kel, to be normalized
[in]normsumdesired sum of elements in keld
Returns
keld normalized version of kels, or NULL on error or if sum of elements is very close to 0)
Notes:
     (1) If the sum of kernel elements is close to 0, do not
         try to calculate the normalized kernel.  Instead,
         return a copy of the input kernel, with a warning.

Definition at line 414 of file kernel.c.

References L_Kernel::cx, L_Kernel::cy, L_Kernel::data, kernelCopy(), kernelCreate(), kernelGetParameters(), and kernelGetSum().

Referenced by fpixConvolve().

◆ kernelRead()

L_KERNEL* kernelRead ( const char *  fname)

kernelRead()

Parameters
[in]fnamefilename
Returns
kernel, or NULL on error

Definition at line 533 of file kernel.c.

References fopenReadStream(), and kernelReadStream().

◆ kernelReadStream()

L_KERNEL* kernelReadStream ( FILE *  fp)

kernelReadStream()

Parameters
[in]fpfile stream
Returns
kernel, or NULL on error

Definition at line 562 of file kernel.c.

Referenced by kernelRead().

◆ kernelSetElement()

l_ok kernelSetElement ( L_KERNEL kel,
l_int32  row,
l_int32  col,
l_float32  val 
)

kernelSetElement()

Parameters
[in]kelkernel
[in]row
[in]col
[in]val
Returns
0 if OK; 1 on error

Definition at line 247 of file kernel.c.

References L_Kernel::data, L_Kernel::sx, and L_Kernel::sy.

Referenced by kernelCreateFromPix(), kernelCreateFromString(), makeDoGKernel(), makeFlatKernel(), makeGaussianKernel(), and makeRangeKernel().

◆ kernelSetOrigin()

l_ok kernelSetOrigin ( L_KERNEL kel,
l_int32  cy,
l_int32  cx 
)

kernelSetOrigin()

Parameters
[in]kelkernel
[in]cy,cx
Returns
0 if OK; 1 on error

Definition at line 304 of file kernel.c.

References L_Kernel::cx, and L_Kernel::cy.

Referenced by kernelCreateFromPix(), kernelCreateFromString(), makeDoGKernel(), makeFlatKernel(), makeGaussianKernel(), and makeRangeKernel().

◆ kernelWrite()

l_ok kernelWrite ( const char *  fname,
L_KERNEL kel 
)

kernelWrite()

Parameters
[in]fnameoutput file
[in]kelkernel
Returns
0 if OK, 1 on error

Definition at line 608 of file kernel.c.

References fopenWriteStream(), and kernelWriteStream().

◆ kernelWriteStream()

l_ok kernelWriteStream ( FILE *  fp,
L_KERNEL kel 
)

kernelWriteStream()

Parameters
[in]fpfile stream
[in]kel
Returns
0 if OK, 1 on error

Definition at line 637 of file kernel.c.

References kernelGetParameters().

Referenced by kernelWrite().

◆ makeDoGKernel()

L_KERNEL* makeDoGKernel ( l_int32  halfh,
l_int32  halfw,
l_float32  stdev,
l_float32  ratio 
)

makeDoGKernel()

Parameters
[in]halfhsy = 2 * halfh + 1
[in]halfwsx = 2 * halfw + 1
[in]stdevstandard deviation of narrower gaussian
[in]ratioof stdev for wide filter to stdev for narrow one
Returns
kernel, or NULL on error
Notes:
     (1) The DoG (difference of gaussians) is a wavelet mother
         function with null total sum.  By subtracting two blurred
         versions of the image, it acts as a bandpass filter for
         frequencies passed by the narrow gaussian but stopped
         by the wide one.See:
              http://en.wikipedia.org/wiki/Difference_of_Gaussians
     (2) The kernel size (sx, sy) = (2 * halfw + 1, 2 * halfh + 1).
     (3) The kernel center (cx, cy) = (halfw, halfh).
     (4) halfw and halfh are typically equal, and are typically
         several times larger than the standard deviation.
     (5) ratio is the ratio of standard deviations of the wide
         to narrow gaussian.  It must be >= 1.0; 1.0 is a no-op.
     (6) Because the kernel is a null sum, it must be invoked without
         normalization in pixConvolve().

Definition at line 1254 of file kernel.c.

References kernelCreate(), kernelSetElement(), and kernelSetOrigin().

◆ makeFlatKernel()

L_KERNEL* makeFlatKernel ( l_int32  height,
l_int32  width,
l_int32  cy,
l_int32  cx 
)

makeFlatKernel()

Parameters
[in]height,width
[in]cy,cxorigin of kernel
Returns
kernel, or NULL on error
Notes:
     (1) This is the same low-pass filtering kernel that is used
         in the block convolution functions.
     (2) The kernel origin (cy, cx) is typically placed as near
         the center of the kernel as possible.  If height and
         width are odd, then using cy = height / 2 and
         cx = width / 2 places the origin at the exact center.
     (3) This returns a normalized kernel.

Definition at line 1107 of file kernel.c.

References kernelCreate(), kernelSetElement(), and kernelSetOrigin().

◆ makeGaussianKernel()

L_KERNEL* makeGaussianKernel ( l_int32  halfh,
l_int32  halfw,
l_float32  stdev,
l_float32  max 
)

makeGaussianKernel()

Parameters
[in]halfhsy = 2 * halfh + 1
[in]halfwsx = 2 * halfw + 1
[in]stdevstandard deviation
[in]maxvalue at (cx,cy)
Returns
kernel, or NULL on error
Notes:
     (1) The kernel size (sx, sy) = (2 * halfw + 1, 2 * halfh + 1)
     (2) The kernel center (cx, cy) = (halfw, halfh).
     (3) halfw and halfh are typically equal, and
         are typically several times larger than the standard deviation.
     (4) If pixConvolve() is invoked with normalization (the sum of
         kernel elements = 1.0), use 1.0 for max (or any number that's
         not too small or too large).

Definition at line 1153 of file kernel.c.

References kernelCreate(), kernelSetElement(), and kernelSetOrigin().

Referenced by makeGaussianKernelSep().

◆ makeGaussianKernelSep()

l_ok makeGaussianKernelSep ( l_int32  halfh,
l_int32  halfw,
l_float32  stdev,
l_float32  max,
L_KERNEL **  pkelx,
L_KERNEL **  pkely 
)

makeGaussianKernelSep()

Parameters
[in]halfhsy = 2 * halfh + 1
[in]halfwsx = 2 * halfw + 1
[in]stdevstandard deviation
[in]maxvalue at (cx,cy)
[out]pkelxx part of kernel
[out]pkelyy part of kernel
Returns
0 if OK, 1 on error
Notes:
     (1) See makeGaussianKernel() for description of input parameters.
     (2) These kernels are constructed so that the result of both
         normalized and un-normalized convolution will be the same
         as when convolving with pixConvolve() using the full kernel.
     (3) The trick for the un-normalized convolution is to have the
         product of the two kernel elements at (cx,cy) be equal to max,
         not max**2.  That's why max for kely is 1.0.  If instead
         we use sqrt(max) for both, the results are slightly less
         accurate, when compared to using the full kernel in
         makeGaussianKernel().

Definition at line 1208 of file kernel.c.

References makeGaussianKernel().

◆ parseStringForNumbers()

NUMA* parseStringForNumbers ( const char *  str,
const char *  seps 
)

parseStringForNumbers()

Parameters
[in]strstring containing numbers; not changed
[in]sepsstring of characters that can be used between ints
Returns
numa of numbers found, or NULL on error
Notes:
    (1) The numbers can be ints or floats.

Definition at line 1055 of file kernel.c.

References numaAddNumber(), numaCreate(), stringNew(), and strtokSafe().

Referenced by kernelCreateFromString(), and pixThresholdGrayArb().