#include <string.h>
#include <math.h>
#include "allheaders.h"

Functions
L_KERNEL *	kernelCreate (l_int32 height, l_int32 width)

void	kernelDestroy (L_KERNEL **pkel)

L_KERNEL *	kernelCopy (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_KERNEL *	kernelNormalize (L_KERNEL *kels, l_float32 normsum)

L_KERNEL *	kernelInvert (L_KERNEL *kels)

l_float32 **	create2dFloatArray (l_int32 sy, l_int32 sx)

L_KERNEL *	kernelRead (const char *fname)

L_KERNEL *	kernelReadStream (FILE *fp)

l_ok	kernelWrite (const char fname, L_KERNEL kel)

l_ok	kernelWriteStream (FILE fp, L_KERNEL kel)

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

L_KERNEL *	kernelCreateFromFile (const char *filename)

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

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

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

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

L_KERNEL *	makeGaussianKernel (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_KERNEL *	makeDoGKernel (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]	sy	rows == height
[in]	sx	columns == 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 481 of file kernel.c.

Referenced by kernelCreate().

◆ kernelCopy()

L_KERNEL * kernelCopy ( L_KERNEL * kels )

kernelCopy()

Parameters

[in] kels source kernel

Returns: keld copy of kels, or NULL on error

Definition at line 175 of file kernel.c.

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

Referenced by 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(), kernelCreateFromFile(), kernelCreateFromPix(), kernelCreateFromString(), kernelInvert(), kernelNormalize(), kernelReadStream(), makeDoGKernel(), makeFlatKernel(), and makeGaussianKernel().

◆ 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 743 of file kernel.c.

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

◆ kernelCreateFromPix()

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

kernelCreateFromPix()

Parameters

[in]	pix
[in]	cy,cx	origin 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 848 of file kernel.c.

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

◆ kernelCreateFromString()

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

kernelCreateFromString()

Parameters

[in]	h,w	height, width
[in]	cy,cx	origin
[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 659 of file kernel.c.

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

◆ kernelDestroy()

void kernelDestroy ( L_KERNEL ** pkel )

kernelDestroy()

Parameters

[in,out] pkel will be set to null before returning

Returns: void

Definition at line 148 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]	kel	kernel
[in]	size	of grid interiors; odd; either 1 or a minimum size of 17 is enforced
[in]	gthick	grid 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 907 of file kernel.c.

References kernelGetElement(), kernelGetMinMax(), kernelGetParameters(), L_FLIP_PIXELS, L_SET_PIXELS, PIX_DST, and PIX_NOT.

◆ 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 209 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]	kel	kernel
[out]	pmin	[optional] minimum value
[out]	pmax	[optional] maximum value

Returns: 0 if OK, 1 on error

Definition at line 342 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]	kel	kernel
[out]	psy,psx,pcy,pcx	[optional] each can be null

Returns: 0 if OK, 1 on error

Definition at line 264 of file kernel.c.

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

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

◆ kernelGetSum()

l_ok kernelGetSum	(	L_KERNEL *	kel,
		l_float32 *	psum )

kernelGetSum()

Parameters

[in]	kel	kernel
[out]	psum	sum of all kernel values

Returns: 0 if OK, 1 on error

Definition at line 312 of file kernel.c.

References L_Kernel::data, and kernelGetParameters().

Referenced by kernelNormalize().

◆ kernelInvert()

L_KERNEL * kernelInvert ( L_KERNEL * kels )

kernelInvert()

Parameters

[in] kels source 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 440 of file kernel.c.

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

◆ kernelNormalize()

L_KERNEL * kernelNormalize	(	L_KERNEL *	kels,
		l_float32	normsum )

kernelNormalize()

Parameters

[in]	kels	source kel, to be normalized
[in]	normsum	desired 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 396 of file kernel.c.

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

◆ kernelRead()

L_KERNEL * kernelRead ( const char * fname )

kernelRead()

Parameters

[in] fname filename

Returns: kernel, or NULL on error

Definition at line 509 of file kernel.c.

References kernelReadStream().

◆ kernelReadStream()

L_KERNEL * kernelReadStream ( FILE * fp )

kernelReadStream()

Parameters

[in] fp file stream

Returns: kernel, or NULL on error

Definition at line 538 of file kernel.c.

References L_Kernel::data, kernelCreate(), and kernelSetOrigin().

Referenced by kernelRead().

◆ kernelSetElement()

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

kernelSetElement()

Parameters

[in]	kel	kernel
[in]	row
[in]	col
[in]	val

Returns: 0 if OK; 1 on error

Definition at line 239 of file kernel.c.

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

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

◆ kernelSetOrigin()

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

kernelSetOrigin()

Parameters

[in]	kel	kernel
[in]	cy,cx

Returns: 0 if OK; 1 on error

Definition at line 292 of file kernel.c.

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

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

◆ kernelWrite()

l_ok kernelWrite	(	const char *	fname,
		L_KERNEL *	kel )

kernelWrite()

Parameters

[in]	fname	output file
[in]	kel	kernel

Returns: 0 if OK, 1 on error

Definition at line 582 of file kernel.c.

References kernelWriteStream().

◆ kernelWriteStream()

l_ok kernelWriteStream	(	FILE *	fp,
		L_KERNEL *	kel )

kernelWriteStream()

Parameters

[in]	fp	file stream
[in]	kel

Returns: 0 if OK, 1 on error

Definition at line 609 of file kernel.c.

References L_Kernel::data, and kernelGetParameters().

Referenced by kernelWrite().

◆ makeDoGKernel()

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

makeDoGKernel()

Parameters

[in]	halfh	sy = 2 * halfh + 1
[in]	halfw	sx = 2 * halfw + 1
[in]	stdev	standard deviation of narrower gaussian
[in]	ratio	of 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 1210 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,cx	origin 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 1069 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]	halfh	sy = 2 * halfh + 1
[in]	halfw	sx = 2 * halfw + 1
[in]	stdev	standard deviation
[in]	max	value 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 1113 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]	halfh	sy = 2 * halfh + 1
[in]	halfw	sx = 2 * halfw + 1
[in]	stdev	standard deviation
[in]	max	value at (cx,cy)
[out]	pkelx	x part of kernel
[out]	pkely	y 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 1166 of file kernel.c.

References makeGaussianKernel().

◆ parseStringForNumbers()

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

parseStringForNumbers()

Parameters

[in]	str	string containing numbers; not changed
[in]	seps	string 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 1019 of file kernel.c.

Referenced by kernelCreateFromFile(), and kernelCreateFromString().

Variable Documentation

◆ MaxArraySize

const l_uint32 MaxArraySize = 100000

static

Definition at line 92 of file kernel.c.

Functions

Variables

Detailed Description

Function Documentation

◆ create2dFloatArray()

◆ kernelCopy()

◆ kernelCreate()

◆ kernelCreateFromFile()

◆ kernelCreateFromPix()

◆ kernelCreateFromString()

◆ kernelDestroy()

◆ kernelDisplayInPix()

◆ kernelGetElement()

◆ kernelGetMinMax()

◆ kernelGetParameters()

◆ kernelGetSum()

◆ kernelInvert()

◆ kernelNormalize()

◆ kernelRead()

◆ kernelReadStream()

◆ kernelSetElement()

◆ kernelSetOrigin()

◆ kernelWrite()

◆ kernelWriteStream()

◆ makeDoGKernel()

◆ makeFlatKernel()

◆ makeGaussianKernel()

◆ makeGaussianKernelSep()

◆ parseStringForNumbers()

Variable Documentation

◆ MaxArraySize