kernelCopy

kernelCreate

kernelCreate()
Input: height, width
Return: 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.

kernelCreateFromFile

L_KERNEL * kernelCreateFromFile ( const char *filename )

kernelCreateFromFile()
Input: filename
Return: 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

kernelCreateFromPix

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

kernelCreateFromPix()
Input: pix
cy, cx (origin of kernel)
Return: kernel, or null on error
Notes:
(1) The origin must be positive and within the dimensions of the pix.

kernelCreateFromString

kernelCreateFromString()
Input: height, width
cy, cx (origin)
kdata
Return: 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 ";

kernelDestroy

void kernelDestroy ( L_KERNEL **pkel )

kernelDestroy()
Input: &kel (<to be nulled>)
Return: void

kernelDisplayInPix

kernelDisplayInPix()
Input: kernel
size (of grid interiors; odd; either 1 or a minimum size
of 17 is enforced)
gthick (grid thickness; either 0 or a minimum size of 2
is enforced)
Return: 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.

kernelGetSum

kernelInvert

L_KERNEL * kernelInvert ( L_KERNEL *kels )

kernelInvert()
Input: kels (source kel, to be inverted)
Return: 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.

kernelNormalize

L_KERNEL * kernelNormalize ( L_KERNEL *kels, l_float32 normsum )

kernelNormalize()
Input: kels (source kel, to be normalized)
normsum (desired sum of elements in keld)
Return: 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.

makeDoGKernel

makeDoGKernel()
Input: halfheight, halfwidth (sx = 2 * halfwidth + 1, etc)
stdev (standard deviation of narrower gaussian)
ratio (of stdev for wide filter to stdev for narrow one)
Return: 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().

makeFlatKernel

makeFlatKernel()
Input: height, width
cy, cx (origin of kernel)
Return: 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.

makeGaussianKernelSep

makeGaussianKernelSep()
Input: halfheight, halfwidth (sx = 2 * halfwidth + 1, etc)
stdev (standard deviation)
max (value at (cx,cy))
&kelx (<return> x part of kernel)
&kely (<return> y part of kernel)
Return: 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().

parseStringForNumbers

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

parseStringForNumbers()
Input: string (containing numbers; not changed)
seps (string of characters that can be used between ints)
Return: numa (of numbers found), or null on error
Note:
(1) The numbers can be ints or floats.

AUTHOR

Zakariyya Mughal <zmughal@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Zakariyya Mughal.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.