Subsections
18.2 Filter functions
The functions described in this section all perform some type of spatial
filtering of the the input array: the elements in the output are some function
of the values in the neighborhood of the corresponding input element. We refer
to this neighborhood of elements as the filter kernel, which is often
rectangular in shape but may also have an arbritrary footprint. Many of the
functions described below allow you to define the footprint of the kernel, by
passing a mask through the footprint parameter. For example a cross
shaped kernel can be defined as follows:
>>> footprint = array([[0,1,0],[1,1,1],[0,1,0]])
>>> print footprint
[[0 1 0]
[1 1 1]
[0 1 0]]
Usually the origin of the kernel is at the center calculated by dividing the
dimensions of the kernel shape by two. For instance, the origin of a
one-dimensional kernel of length three is at the second element. Take for
example the correlation of a one-dimensional array with a filter of length 3
consisting of ones:
>>> a = [0, 0, 0, 1, 0, 0, 0]
>>> correlate1d(a, [1, 1, 1])
[0 0 1 1 1 0 0]
Sometimes it is convenient to choose a different origin for the kernel. For
this reason most functions support the origin parameter which gives the
origin of the filter relative to its center. For example:
>>> a = [0, 0, 0, 1, 0, 0, 0]
>>> print correlate1d(a, [1, 1, 1], origin = -1)
[0 1 1 1 0 0 0]
The effect is a shift of the result towards the left. This feature will not be
needed very often, but it may be useful especially for filters that have an
even size. A good example is the calculation of backward and forward
differences:
>>> a = [0, 0, 1, 1, 1, 0, 0]
>>> print correlate1d(a, [-1, 1]) ## backward difference
[ 0 0 1 0 0 -1 0]
>>> print correlate1d(a, [-1, 1], origin = -1) ## forward difference
[ 0 1 0 0 -1 0 0]
We could also have calculated the forward difference as follows:
>>> print correlate1d(a, [0, -1, 1])
[ 0 1 0 0 -1 0 0]
however, using the origin parameter instead of a larger kernel is more
efficient. For multi-dimensional kernels origin can be a number, in which
case the origin is assumed to be equal along all axes, or a sequence giving the
origin along each axis.
Since the output elements are a function of elements in the neighborhood of the
input elements, the borders of the array need to be dealt with appropriately by
providing the values outside the borders. This is done by assuming that the
arrays are extended beyond their boundaries according certain boundary
conditions. In the functions described below, the boundary conditions can be
selected using the mode parameter which must be a string with the name of
the boundary condition. Following boundary conditions are currently supported:
"nearest" |
Use the value at the boundary |
[1 2 3]->[1 1 2 3 3] |
"wrap" |
Periodically replicate the array |
[1 2 3]->[3 1 2 3 1] |
"reflect" |
Reflect the array at the boundary |
[1 2 3]->[1 1 2 3 3] |
"constant" |
Use a constant value, default value is 0.0 |
[1 2 3]->[0 1 2 3 0] |
The "constant" mode is special since it needs an additional
parameter to specify the constant value that should be used.
Note:
The easiest way to implement such boundary conditions would be to copy
the data to a larger array and extend the data at the borders according to
the boundary conditions. For large arrays and large filter kernels, this
would be very memory consuming, and the functions described below therefore
use a different approach that does not require allocating large temporary
buffers.
correlate1d( |
input, weights, axis=-1, output=None,
mode='nearest', cval=0.0, origin=0, output_type=None) |
- The
correlate1d function calculates a one-dimensional correlation
along the given axis. The lines of the array along the given axis are
correlated with the given weights. The weights parameter must be
a one-dimensional sequences of numbers.
correlate( |
input, weights, output=None, mode='nearest',
cval=0.0, origin=0, output_type=None) |
- The function correlate
implements multi-dimensional correlation of the input array with a given
kernel.
convolve1d( |
input, weights, axis=-1, output=None,
mode='nearest', cval=0.0, origin=0, output_type=None) |
- The
convolve1d function calculates a one-dimensional convolution along
the given axis. The lines of the array along the given axis are convoluted
with the given weights. The weights parameter must be a
one-dimensional sequences of numbers.
Note:
A convolution is essentially a correlation after mirroring the kernel.
As a result, the origin parameter behaves differently than in the
case of a correlation: the results in a shift in the opposite directions.
convolve( |
input, weights, output=None, mode='nearest',
cval=0.0, origin=0, output_type=None) |
- The function convolve
implements multi-dimensional convolution of the input array with a given
kernel.
Note:
A convolution is essentially a correlation after mirroring the kernel.
As a result, the origin parameter behaves differently than in the
case of a correlation: it results is shifted in the opposite direction.
18.2.2 Smoothing filters
gaussian_filter1d( |
input, sigma, axis=-1, order=0,
output=None, mode='nearest', cval=0.0, output_type=None) |
- The
gaussian_filter1d function implements a one-dimensional Gaussian
filter. The standard-deviation of the Gaussian filter is passed through the
parameter sigma. A filter order of 0 corresponds to convolution with a
Gaussian kernel. An order of 1, 2, or 3 corresponds to convolution with the
first, second or third derivatives of a Gaussian. Higher order derivatives
are not implemented.
gaussian_filter( |
input, sigma, order=0, output=None,
mode='nearest', cval=0.0, output_type=None) |
- The gaussian_filter
function implements a multi-dimensional Gaussian filter. The
standard-deviations of the Gaussian filter along each axis are passed through
the parameter sigma as a sequence or numbers. If sigma is not a
sequence but a single number, the standard deviation of the filter is equal
along all directions. The order of the filter can be specified separately for
each axis. An order of 0 corresponds to convolution with a Gaussian kernel.
An order of 1, 2, or 3 corresponds to convolution with the first, second or
third derivatives of a Gaussian. Higher order derivatives are not
implemented. The order parameter must be a number, to specify the same
order for all axes, or a sequence of numbers to specify a different order for
each axis.
Note:
The multi-dimensional filter is implemented as a sequence of
one-dimensional Gaussian filters. The intermediate arrays are stored in the
same data type as the output. Therefore, for output types with a lower
precision, the results may be imprecise because intermediate results may be
stored with insufficient precision. This can be prevented by specifying a
more precise output type.
boxcar_filter1d( |
input, size, axis=-1, output=None,
mode='nearest', cval=0.0, origin=0, output_type=None) |
- The
boxcar_filter1d function calculates a one-dimensional boxcar
filter of the given size along the given axis.
boxcar_filter( |
input, size, output=None, mode='nearest',
cval=0.0, origin=0, output_type=None) |
- The boxcar_filter
implements a multi-dimensional boxcar filter. The sizes of the boxcar filter
are given for each axis as a sequence of integers by the size
parameter. If size is not a sequence, but a single number, the sizes
along all axis are assumed to be equal.
Note:
The multi-dimensional filter is implemented as a sequence of
one-dimensional boxcar filters. The intermediate arrays are stored in the
same data type as the output. Therefore, for output types with a lower
precision, the results may be imprecise because intermediate results may be
stored with insufficient precision. This can be prevented by specifying a
more precise output type.
minimum_filter1d( |
input, size, axis=-1, output=None,
mode='nearest', cval=0.0, origin=0) |
- The minimum_filter1d
function calculates a one-dimensional minimum filter of given size
along the given axis.
maximum_filter1d( |
input, size, axis=-1, output=None,
mode='nearest', cval=0.0, origin=0) |
- The maximum_filter1d
function calculates a one-dimensional maximum filter of given size
along the given axis.
minimum_filter( |
input, size=None, footprint=None,
output=None, mode='nearest', cval=0.0, origin=0) |
- The
minimum_filter function calculates a multi-dimensional minimum
filter. Either the sizes of a rectangular kernel or the footprint of the
kernel must be provided. The size parameter, if provided, must be a
sequence of sizes or a single number in which case the size of the filter is
assumed to be equal along each axis. The footprint, if provided, must
be an array that defines the shape of the kernel by its non-zero elements.
maximum_filter( |
input, size=None, footprint=None,
output=None, mode='nearest', cval=0.0, origin=0) |
- The
maximum_filter function calculates a multi-dimensional maximum
filter. Either the sizes of a rectangular kernel or the footprint of the
kernel must be provided. The size parameter, if provided, must be a
sequence of sizes or a single number in which case the size of the filter is
assumed to be equal along each axis. The footprint, if provided, must
be an array that defines the shape of the kernel by its non-zero elements.
rank_filter( |
input, rank, size=None, footprint=None,
output=None, mode='nearest', cval=0.0, origin=0) |
- The rank_filter
function calculates a multi-dimensional rank filter. The rank may be
less then zero, i.e., rank=-1 indicates the largest element. Either the sizes
of a rectangular kernel or the footprint of the kernel must be provided. The
size parameter, if provided, must be a sequence of sizes or a single
number in which case the size of the filter is assumed to be equal along each
axis. The footprint, if provided, must be an array that defines the
shape of the kernel by its non-zero elements.
percentile_filter( |
input, percentile, size=None, mask=None,
output=None, mode='nearest', cval=0.0, origin=0) |
- The
percentile_filter function calculates a multi-dimensional
percentile filter. The percentile may be less then zero, i.e.,
percentile=-20 equals percentile=80. Either the sizes of a rectangular kernel
or the footprint of the kernel must be provided. The size parameter, if
provided, must be a sequence of sizes or a single number in which case the
size of the filter is assumed to be equal along each axis. The
footprint, if provided, must be an array that defines the shape of the
kernel by its non-zero elements.
median_filter( |
input, size=None, mask=None, output=None,
mode='nearest', cval=0.0, origin=0) |
- The median_filter function
calculates a multi-dimensional median filter. Either the sizes of a
rectangular kernel or the footprint of the kernel must be provided. The
size parameter, if provided, must be a sequence of sizes or a single
number in which case the size of the filter is assumed to be equal along each
axis. The footprint if provided, must be an array that defines the
shape of the kernel by its non-zero elements.
Derivative filters can be constructed in several ways. The function
gaussian_filter1d described in section
18.2.2 can be used to calculate
derivatives along a given axis using the order parameter. Other
derivative filters are the Prewitt and Sobel filters:
prewitt( |
input, axis=-1, output=None, mode='nearest',
cval=0.0) |
- The prewitt function calculates a derivative along the
given axis.
sobel( |
input, axis=-1, output=None, mode='nearest',
cval=0.0) |
- The sobel function calculates a derivative along the
given axis.
The Laplace filter is calculated by the sum of the second derivatives along all
axes. Thus, different Laplace filters can be constructed using different second
derivative functions. Therefore we provide a general function that takes a
function argument to calculate the second derivative along a given direction
and to construct the Laplace filter:
generic_laplace( |
input, output=None, mode='nearest',
cval=0.0, output_type=None, derivative2=None) |
-
The function generic_laplace calculates a laplace filter using the
function passed through derivative2 to calculate second derivatives.
The function derivative2 should have the following signature:
derivative2(input, axis, output, mode, cval, output_type)
It should calculate the second derivative along the dimension axis. If
output is not None it should use that for the output and
return None, otherwise it should return the result. mode,
cval and output_type have the usual meaning.
The following two functions are implemented using generic_laplace by
providing appropriate functions for the second derivative function:
laplace( |
input, output=None, mode='nearest',
cval=0.0, output_type=None) |
- The function laplace calculates the
Laplace using discrete differentiation for the second derivative (i.e.
convolution with [1, -2, 1]).
gaussian_laplace( |
input, output=None, mode='nearest',
cval=0.0, output_type=None) |
- The function gaussian_laplace
calculates the Laplace using gaussian_filter to calculate the
second derivatives.
The gradient magnitude is defined as the square root of the sum of the squares
of the gradients in all directions. Similar to the generic Laplace function
there is a generic_gradient_magnitude function that calculated the
gradient magnitude of an array:
-
- The function
generic_gradient_magnitude calculates a gradient magnitude using
the function passed through derivative to calculate first derivatives.
The function derivative should have the following signature:
derivative(input, axis, output, mode, cval, output_type)
It should calculate the derivative along the dimension axis. If
output is not None it should use that for the output and
return None, otherwise it should return the result. mode,
cval and output_type have the usual meaning.
The sobel and prewitt functions fit the required
signature and can therefore directly be used with
generic_gradient_magnitude. The following function implements the
gradient magnitude using Gaussian derivatives:
-
- The function
gaussian_gradient_magnitude calculates the gradient magnitude
using gaussian_filter to calculate the first derivatives.
The functions described in this section perform filtering operations in the
Fourier domain. Thus, the input array of such a function should be compatible
with an inverse Fourier transform function, such as the functions from the
numarray.fft module. We therefore have to deal with arrays that may be
the result of a real or a complex Fourier transform. In the case of a real
Fourier transform only half of the of the symmetric complex transform is
stored. Additionally, it needs to be known what the length of the axis was that
was transformed by the real fft. The functions described here provide a
parameter n that in the case of a real transform must be equal to the
length of the real transform axis before transformation. If this parameter is
less than zero, it is assumed that the input array was the result of a complex
Fourier transform. The parameter axis can be used to indicate along which
axis the real transform was executed.
-
-
The fourier_shift function multiplies the input array with the
multi-dimensional Fourier transform of a shift operation for the given shift.
The shift parameter is a sequences of shifts for each dimension, or a
single value for all dimensions.
-
-
The fourier_gaussian function multiplies the input array with the
multi-dimensional Fourier transform of a Gaussian filter with given
standard-deviations sigma. The sigma parameter is a sequences of
values for each dimension, or a single value for all dimensions.
-
-
The fourier_boxcar function multiplies the input array with the
multi-dimensional Fourier transform of a boxcar filter with given
sizes size. The size parameter is a sequences of
values for each dimension, or a single value for all dimensions.
-
-
The fourier_ellipsoid function multiplies the input array with the
multi-dimensional Fourier transform of a elliptically shaped filter with
given sizes size. The size parameter is a sequences of values for
each dimension, or a single value for all dimensions. Note:
This function is
only implemented for dimensions 1, 2, and 3.
Send comments to the NumArray community.