1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
\chapter{Convolution}
\label{cha:convolve}
%begin{latexonly}
\makeatletter
\py@reset
\makeatother
%end{latexonly}
\declaremodule{extension}{numarray.convolve}
\moduleauthor{The numarray team}{numpy@lists.sourceforge.net}
\modulesynopsis{Convolution,correlation}
\begin{quote}
This package (numarray.convolve) provides functions for one- and
two-dimensional convolutions and correlations of \class{numarray}s.
Each of the following examples assumes that the following code has been
executed:
\begin{verbatim}
import numarray.convolve as conv
\end{verbatim}
\end{quote}
\section{Convolution functions}
\label{sec:CONV:convolution-functions}
\begin{funcdesc}{boxcar}{data, boxshape, output=None, mode='nearest', cval=0.0}
\function{boxcar} computes a 1-D or 2-D boxcar filter on every 1-D or
2-D subarray of \constant{data}. \constant{boxshape} is a tuple of integers
specifying the dimensions of the filter, e.g. \code{(3,3)}. If
\constant{output} is specified, it should be the same shape as
\constant{data} and the result will be stored in it. In that case
\class{None} will be returned.
\constant{mode} can be any of the following values:
\begin{description}
\item[\var{nearest}]: Elements beyond boundary come from nearest edge pixel.
\item[\var{wrap}]: Elements beyond boundary come from the opposite array
edge.
\item[\var{reflect}]: Elements beyond boundary come from reflection on same
array edge.
\item[\var{constant}]: Elements beyond boundary are set to what is specified
in \constant{cval}, an optional numerical parameter; the default value is
\code{0.0}.
\end{description}
\end{funcdesc}
\begin{verbatim}
>>> print a
[1 5 4 7 2 9 3 6]
>>> print conv.boxcar(a,(3,))
[ 2.33333333 3.33333333 5.33333333 4.33333333 6. 4.66666667
6. 5. ]
# for even number box size, it will take the extra point from the lower end
>>> print conv.boxcar(a,(2,))
[ 1. 3. 4.5 5.5 4.5 5.5 6. 4.5]
\end{verbatim}
\begin{funcdesc}{convolve}{data, kernel, mode=FULL}
\label{func:CONV:convolve}
Returns the discrete, linear convolution of 1-D sequences \constant{data}
and \constant{kernel}; \constant{mode} can be \class{VALID}, \class{SAME},
or \code{FULL} to specify the size of the resulting sequence. See section
\ref{sec:CONV:global-constants}.
\end{funcdesc}
\begin{funcdesc}{convolve2d}{data, kernel, output=None, fft=0, mode='nearest',
cval=0.0} Return the 2-dimensional convolution of \constant{data} and
\constant{kernel}. If \constant{output} is not \class{None}, the result is
stored in \constant{output} and \class{None} is returned. \constant{fft} is
used to switch between FFT-based convolution and the naive algorithm,
defaulting to naive. Using \constant{fft} mode becomes more beneficial as
the size of the kernel grows; for small kernels, the naive algorithm is more
efficient. \constant{mode} has the same choices as those of
\function{boxcar}. A number of storage considerations come into play with
large arrays: (1) boundary modes are implemented by making an oversized
temporary copy of the \constant{data} array which has a shape equal to the
sum of the \constant{data} and \constant{kernel} shapes. (2) likewise, the
\constant{kernel} is copied into an array with the same shape as the
oversized \constant{data} array. (3) In FFT mode, the fourier transforms of
the \constant{data} and \constant{kernel} arrays are stored in double
precision complex temporaries. The aggregate effect is that storage roughly
equal to a factor of eight (x2 from 2 and x4 from 3) times the size of the
\constant{data} is required to compute the convolution of a Float32
\constant{data} array.
\end{funcdesc}
\begin{funcdesc}{correlate}{data, kernel, mode=FULL}
Return the cross-correlation of \constant{data} and \constant{kernel};
\constant{mode} can be \class{VALID}, \class{SAME}, or \code{FULL} to
specify the size of the resulting sequence. \function{correlate} is
very closely related to \function{convolve} in implementation.
See section \ref{sec:CONV:global-constants}.
\end{funcdesc}
\begin{funcdesc}{correlate2d}{data, kernel, output=None, fft=0, mode='nearest', cval=0.0}
\label{func:CONV:correlate2d}
Return the 2-dimensional convolution of \constant{data} and
\constant{kernel}. If \constant{output} is not \class{None}, the result is
stored in \constant{output} and \class{None} is returned. \constant{fft} is
used to switch between FFT-based convolution and the naive algorithm,
defaulting to naive. Using \constant{fft} mode becomes more beneficial as
the size of the kernel grows; for small kernels, the naive algorithm is more
efficient. \constant{mode} has the same choices as those of
\function{boxcar}. See also \function{convolve2d} for notes regarding
storage consumption.
\end{funcdesc}
\note{\function{cross_correlate} is deprecated and should not be used.}
\section{Global constants}
\label{sec:CONV:global-constants}
These constants specify what part of the result the \function{convolve} and
\function{correlate} functions of this module return. Each of the following
examples assumes that the following code has been executed:
\begin{verbatim}
arr = numarray.arange(8)
\end{verbatim}
\begin{datadesc}{FULL}
Return the full convolution or correlation of two arrays.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.FULL)
array([ 0, 3, 8, 14, 20, 26, 32, 38, 20, 7])
\end{verbatim}
\end{datadesc}
\begin{datadesc}{PASS}
Correlate the arrays without padding the data.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.PASS)
array([ 0, 8, 14, 20, 26, 32, 38, 7])
\end{verbatim}
\end{datadesc}
\begin{datadesc}{SAME}
Return the part of the convolution or correlation of two arrays that
corresponds to an array of the same shape as the input data.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.SAME)
array([ 3, 8, 14, 20, 26, 32, 38, 20])
\end{verbatim}
\end{datadesc}
\begin{datadesc}{VALID}
Return the valid part of the convolution or correlation of two arrays.
\begin{verbatim}
>>> conv.correlate(arr, [1, 2, 3], mode=conv.VALID)
array([ 8, 14, 20, 26, 32, 38])
\end{verbatim}
\end{datadesc}
%% Local Variables:
%% mode: LaTeX
%% mode: auto-fill
%% fill-column: 79
%% indent-tabs-mode: nil
%% ispell-dictionary: "american"
%% reftex-fref-is-default: nil
%% TeX-auto-save: t
%% TeX-command-default: "pdfeLaTeX"
%% TeX-master: "numarray"
%% TeX-parse-self: t
%% End:
|
