#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 halfheight, l_int32 halfwidth, l_float32 stdev, l_float32 max)

l_ok	makeGaussianKernelSep (l_int32 halfheight, l_int32 halfwidth, l_float32 stdev, l_float32 max, L_KERNEL pkelx, L_KERNEL pkely)

L_KERNEL *	makeDoGKernel (l_int32 halfheight, l_int32 halfwidth, l_float32 stdev, l_float32 ratio)

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 499 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 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 106 of file kernel.c.

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

Referenced by kernelCopy(), kernelCreateFromFile(), 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 765 of file kernel.c.

References kernelCreate(), kernelSetElement(), kernelSetOrigin(), l_binaryRead(), L_NOCOPY, numaCreate(), numaDestroy(), numaGetCount(), numaGetFValue(), numaJoin(), parseStringForNumbers(), sarrayCreateLinesFromString(), sarrayDestroy(), sarrayGetCount(), and sarrayGetString().

◆ 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 865 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,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 679 of file kernel.c.

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

◆ kernelDestroy()

void kernelDestroy ( L_KERNEL ** pkel )

kernelDestroy()

Parameters

[in,out] pkel to be nulled

Returns: void

Definition at line 144 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 926 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 211 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 354 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 270 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]	kel	kernel
[out]	psum	sum of all kernel values

Returns: 0 if OK, 1 on error

Definition at line 322 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 456 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]	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 410 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] fname filename

Returns: kernel, or NULL on error

Definition at line 526 of file kernel.c.

References fopenReadStream(), and kernelReadStream().

◆ kernelReadStream()

L_KERNEL* kernelReadStream ( FILE * fp )

kernelReadStream()

Parameters

[in] fp file stream

Returns: kernel, or NULL on error

Definition at line 555 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]	kel	kernel
[in]	row
[in]	col
[in]	val

Returns: 0 if OK; 1 on error

Definition at line 243 of file kernel.c.

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

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

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

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

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

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

References fopenWriteStream(), and 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 627 of file kernel.c.

References kernelGetParameters().

Referenced by kernelWrite().

◆ makeDoGKernel()

L_KERNEL* makeDoGKernel	(	l_int32	halfheight,
		l_int32	halfwidth,
		l_float32	stdev,
		l_float32	ratio
	)

makeDoGKernel()

Parameters

[in]	halfheight,halfwidth	sx = 2 * halfwidth + 1, etc
[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 * halfwidth + 1, 2 * halfheight + 1).
     (3) The kernel center (cx, cy) = (halfwidth, halfheight).
     (4) The halfwidth and halfheight are typically equal, and
         are typically several times larger than the standard deviation.
     (5) The 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 1236 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 1092 of file kernel.c.

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

◆ makeGaussianKernel()

L_KERNEL* makeGaussianKernel	(	l_int32	halfheight,
		l_int32	halfwidth,
		l_float32	stdev,
		l_float32	max
	)

makeGaussianKernel()

Parameters

[in]	halfheight,halfwidth	sx = 2 * halfwidth + 1, etc
[in]	stdev	standard deviation
[in]	max	value at (cx,cy)

Returns: kernel, or NULL on error

Notes:
     (1) The kernel size (sx, sy) = (2 * halfwidth + 1, 2 * halfheight + 1).
     (2) The kernel center (cx, cy) = (halfwidth, halfheight).
     (3) The halfwidth and halfheight 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 1137 of file kernel.c.

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

Referenced by makeGaussianKernelSep().

◆ makeGaussianKernelSep()

l_ok makeGaussianKernelSep	(	l_int32	halfheight,
		l_int32	halfwidth,
		l_float32	stdev,
		l_float32	max,
		L_KERNEL **	pkelx,
		L_KERNEL **	pkely
	)

makeGaussianKernelSep()

Parameters

[in]	halfheight,halfwidth	sx = 2 * halfwidth + 1, etc
[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 elemets at (cx,cy) be equal to max,
         not max**2.  That's why the 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 1191 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 1040 of file kernel.c.

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

Referenced by kernelCreateFromFile(), kernelCreateFromString(), and pixThresholdGrayArb().

Functions

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()