[python-dtcwt] 18/497: tidied up docstrings
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Tue Jul 21 18:05:44 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to branch debian/sid
in repository python-dtcwt.
commit 068913cec94596906793c140f395a1a75fbb281a
Author: Rich Wareham <rjw57 at cam.ac.uk>
Date: Wed Aug 7 15:32:27 2013 +0100
tidied up docstrings
---
docs/reference.rst | 10 +--
dtcwt/coeffs.py | 54 ++++++++++-------
dtcwt/lowlevel.py | 87 ++++++++++++++++-----------
dtcwt/transform1d.py | 143 +++++++++++++++++++------------------------
dtcwt/transform2d.py | 167 +++++++++++++++++++++------------------------------
tests/testifm1.py | 8 +++
tests/testxfm1.py | 1 -
tests/testxfm2.py | 7 ++-
8 files changed, 232 insertions(+), 245 deletions(-)
diff --git a/docs/reference.rst b/docs/reference.rst
index 41ea408..827d32c 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -1,14 +1,14 @@
Reference
=========
-Commonly used functions
-```````````````````````
-
.. automodule:: dtcwt
:members:
-Expert interface
-````````````````
+Low-level support functions
+```````````````````````````
+
+A normal user should not need to call these functions but they are documented
+here just in case you do.
.. automodule:: dtcwt.lowlevel
:members:
diff --git a/dtcwt/coeffs.py b/dtcwt/coeffs.py
index f5b9062..3b7e7b4 100644
--- a/dtcwt/coeffs.py
+++ b/dtcwt/coeffs.py
@@ -20,42 +20,52 @@ def _load_from_file(basename, varnames):
raise ValueError('Wavelet does not define ({0}) coefficients'.format(', '.join(varnames)))
def biort(name):
- """Load level 1 wavelet by name:
+ """Load level 1 wavelet by name.
- 'antonini' => Antonini 9,7 tap filters.
- 'legall' => LeGall 5,3 tap filters.
- 'near_sym_a' => Near-Symmetric 5,7 tap filters.
- 'near_sym_b' => Near-Symmetric 13,19 tap filters.
+ :param name: a string specifying the wavelet family name
+ :returns: a tuple of vectors giving filter coefficients
+
+ ============ ============================================
+ Name Wavelet
+ ============ ============================================
+ antonini Antonini 9,7 tap filters.
+ legall LeGall 5,3 tap filters.
+ near_sym_a Near-Symmetric 5,7 tap filters.
+ near_sym_b Near-Symmetric 13,19 tap filters.
+ ============ ============================================
Return a tuple whose elements are a vector specifying the h0o, g0o, h1o and
g1o coefficients.
- Raises IOError if name does not correspond to a set of wavelets known to
- the library.
-
- Raises ValueError if name specifies a qshift wavelet.
+ :raises IOError: if name does not correspond to a set of wavelets known to the library.
+ :raises ValueError: if name specifies a :py:func:`qshift` wavelet.
"""
return _load_from_file(name, ('h0o', 'g0o', 'h1o', 'g1o'))
def qshift(name):
- """Load level >=2 wavelet by name:
-
- 'qshift_06' => Quarter Sample Shift Orthogonal (Q-Shift) 10,10 tap filters,
- (only 6,6 non-zero taps).
- 'qshift_a' => Q-shift 10,10 tap filters,
- (with 10,10 non-zero taps, unlike qshift_06).
- 'qshift_b' => Q-Shift 14,14 tap filters.
- 'qshift_c' => Q-Shift 16,16 tap filters.
- 'qshift_d' => Q-Shift 18,18 tap filters.
+ """Load level >=2 wavelet by name,
+
+ :param name: a string specifying the wavelet family name
+ :returns: a tuple of vectors giving filter coefficients
+
+ ============ ============================================
+ Name Wavelet
+ ============ ============================================
+ qshift_06 Quarter Sample Shift Orthogonal (Q-Shift) 10,10 tap filters,
+ (only 6,6 non-zero taps).
+ qshift_a Q-shift 10,10 tap filters,
+ (with 10,10 non-zero taps, unlike qshift_06).
+ qshift_b Q-Shift 14,14 tap filters.
+ qshift_c Q-Shift 16,16 tap filters.
+ qshift_d Q-Shift 18,18 tap filters.
+ ============ ============================================
Return a tuple whose elements are a vector specifying the h0a, h0b, g0a,
g0b, h1a, h1b, g1a and g1b coefficients.
- Raises IOError if name does not correspond to a set of wavelets known to
- the library.
-
- Raises ValueError if name specifies a biort wavelet.
+ :raises IOError: if name does not correspond to a set of wavelets known to the library.
+ :raises ValueError: if name specifies a :py:func:`biort` wavelet.
"""
return _load_from_file(name, ('h0a', 'h0b', 'g0a', 'g0b', 'h1a', 'h1b', 'g1a', 'g1b'))
diff --git a/dtcwt/lowlevel.py b/dtcwt/lowlevel.py
index ac92eef..8b69346 100644
--- a/dtcwt/lowlevel.py
+++ b/dtcwt/lowlevel.py
@@ -2,7 +2,9 @@ import numpy as np
from scipy.signal import convolve2d
def as_column_vector(v):
- """Return v as a column vector with shape (N,1)."""
+ """Return *v* as a column vector with shape (N,1).
+
+ """
v = np.atleast_2d(v)
if v.shape[0] == 1:
return v.T
@@ -24,7 +26,7 @@ _rfft = np.fft.rfft
_irfft = np.fft.irfft
def _column_convolve(X, h):
- """Convolve the columns of X with h returning only the 'valid' section,
+ """Convolve the columns of *X* with *h* returning only the 'valid' section,
i.e. those values unaffected by zero padding.
"""
@@ -55,13 +57,14 @@ def _column_convolve(X, h):
return Xvalid
def reflect(x, minx, maxx):
- """Reflect the values in matrix x about the scalar values minx and maxx.
- Hence a vector x containing a long linearly increasing series is converted
- into a waveform which ramps linearly up and down between minx and maxx. If
- x contains integers and minx and maxx are (integers + 0.5), the ramps will
- have repeated max and min samples.
+ """Reflect the values in matrix *x* about the scalar values *minx* and
+ *maxx*. Hence a vector *x* containing a long linearly increasing series is
+ converted into a waveform which ramps linearly up and down between *minx* and
+ *maxx*. If *x* contains integers and *minx* and *maxx* are (integers + 0.5), the
+ ramps will have repeated max and min samples.
- Nick Kingsbury, Cambridge University, January 1999.
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, Aug 2013
+ .. codeauthor:: Nick Kingsbury, Cambridge University, January 1999.
"""
@@ -84,13 +87,19 @@ def reflect(x, minx, maxx):
return y
def colfilter(X, h):
- """Filter the columns of image X using filter vector h, without decimation.
- If length(h) is odd, each output sample is aligned with each input sample
- and Y is the same size as X. If length(h) is even, each output sample is
- aligned with the mid point of each pair of input samples, and size(Y) =
- size(X) + [1 0];
+ """Filter the columns of image *X* using filter vector *h*, without decimation.
+ If len(h) is odd, each output sample is aligned with each input sample
+ and *Y* is the same size as *X*. If len(h) is even, each output sample is
+ aligned with the mid point of each pair of input samples, and Y.shape =
+ X.shape + [1 0].
+
+ :param X: an image whose columns are to be filtered
+ :param h: the filter coefficients.
+ :returns Y: the filtered image.
- Cian Shaffrey, Nick Kingsbury Cambridge University, August 2000
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, August 2013
+ .. codeauthor:: Cian Shaffrey, Cambridge University, August 2000
+ .. codeauthor:: Nick Kingsbury, Cambridge University, August 2000
"""
@@ -116,16 +125,18 @@ def coldfilt(X, ha, hb):
"""Filter the columns of image X using the two filters ha and hb =
reverse(ha). ha operates on the odd samples of X and hb on the even
samples. Both filters should be even length, and h should be approx linear
- phase with a quarter sample advance from its mid pt (ie |h(m/2)| > |h(m/2 +
- 1)|).
+ phase with a quarter sample advance from its mid pt (i.e. :math:`|h(m/2)| >
+ |h(m/2 + 1)|`).
- ext top edge bottom edge ext
- Level 1: ! | ! | !
- odd filt on . b b b b a a a a a a a a b b b b
- odd filt on . a a a a b b b b b b b b a a a a
- Level 2: ! | ! | !
- +q filt on x b b a a a a b b
- -q filt on o a a b b b b a a
+ .. code-block:: text
+
+ ext top edge bottom edge ext
+ Level 1: ! | ! | !
+ odd filt on . b b b b a a a a a a a a b b b b
+ odd filt on . a a a a b b b b b b b b a a a a
+ Level 2: ! | ! | !
+ +q filt on x b b a a a a b b
+ -q filt on o a a b b b b a a
The output is decimated by two from the input sample rate and the results
from the two filters, Ya and Yb, are interleaved to give Y. Symmetric
@@ -135,7 +146,9 @@ def coldfilt(X, ha, hb):
Raises ValueError if the number of rows in X is not a multiple of 4, the
length of ha does not match hb or the lengths of ha or hb are non-even.
- Cian Shaffrey, Nick Kingsbury Cambridge University, August 2000
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, August 2013
+ .. codeauthor:: Cian Shaffrey, Cambridge University, August 2000
+ .. codeauthor:: Nick Kingsbury, Cambridge University, August 2000
"""
# Make sure all inputs are arrays
@@ -186,25 +199,27 @@ def colifilt(X, ha, hb):
""" Filter the columns of image X using the two filters ha and hb =
reverse(ha). ha operates on the odd samples of X and hb on the even
samples. Both filters should be even length, and h should be approx linear
- phase with a quarter sample advance from its mid pt (ie |h(m/2)| > |h(m/2 +
- 1)|).
+ phase with a quarter sample advance from its mid pt (i.e `:math:`|h(m/2)| >
+ |h(m/2 + 1)|`).
- ext left edge right edge ext
- Level 2: ! | ! | !
- +q filt on x b b a a a a b b
- -q filt on o a a b b b b a a
- Level 1: ! | ! | !
- odd filt on . b b b b a a a a a a a a b b b b
- odd filt on . a a a a b b b b b b b b a a a a
+ .. code-block:: text
+
+ ext left edge right edge ext
+ Level 2: ! | ! | !
+ +q filt on x b b a a a a b b
+ -q filt on o a a b b b b a a
+ Level 1: ! | ! | !
+ odd filt on . b b b b a a a a a a a a b b b b
+ odd filt on . a a a a b b b b b b b b a a a a
The output is interpolated by two from the input sample rate and the
results from the two filters, Ya and Yb, are interleaved to give Y.
Symmetric extension with repeated end samples is used on the composite X
columns before each filter is applied.
- Cian Shaffrey, Nick Kingsbury Cambridge University, August 2000
-
- Modified to be fast if X = 0, May 2002.
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, August 2013
+ .. codeauthor:: Cian Shaffrey, Cambridge University, August 2000
+ .. codeauthor:: Nick Kingsbury, Cambridge University, August 2000
"""
# Make sure all inputs are arrays
diff --git a/dtcwt/transform1d.py b/dtcwt/transform1d.py
index 28751ad..7e1efa1 100644
--- a/dtcwt/transform1d.py
+++ b/dtcwt/transform1d.py
@@ -6,63 +6,50 @@ from dtcwt.defaults import DEFAULT_BIORT, DEFAULT_QSHIFT
from dtcwt.lowlevel import colfilter, coldfilt, colifilt, as_column_vector
def dtwavexfm(X, nlevels=3, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, include_scale=False):
- """ Function to perform a n-level DTCWT decompostion on a 1-D column vector
- X (or on the columns of a matrix X).
+ """Perform a *n*-level DTCWT decompostion on a 1D column vector *X* (or on
+ the columns of a matrix *X*).
- Yl, Yh = dtwavexfm(X, nlevels, biort, qshift)
- Yl, Yh, Yscale = dtwavexfm(X, nlevels, biort, qshift, include_scale=True)
+ :param X: 1D real matrix/Image or matrix of 1D columns of shape (N, M)
+ :param nlevels: Number of levels of wavelet decomposition
+ :param biort: Level 1 wavelets to use. See :py:func:`biort`.
+ :param qshift: Level >= 2 wavelets to use. See :py:func:`qshift`.
- X -> real 1-D signal column vector (or matrix of vectors)
+ :returns Yl: The real lowpass image from the final level
+ :returns Yh: A tuple containing the (N, M, 6) shape complex highpass subimages for each level.
+ :returns Yscale: If *include_scale* is True, a tuple containing real lowpass coefficients for every scale.
- nlevels -> No. of levels of wavelet decomposition
+ If *biort* or *qshift* are strings, they are used as an argument to the
+ :py:func:`biort` or :py:func:`qshift` functions. Otherwise, they are
+ interpreted as tuples of vectors giving filter coefficients. In the *biort*
+ case, this should be (h0o, g0o, h1o, g1o). In the *qshift* case, this should
+ be (h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b).
- biort -> 'antonini' => Antonini 9,7 tap filters.
- 'legall' => LeGall 5,3 tap filters.
- 'near_sym_a' => Near-Symmetric 5,7 tap filters.
- 'near_sym_b' => Near-Symmetric 13,19 tap filters.
+ Example::
- qshift -> 'qshift_06' => Quarter Sample Shift Orthogonal (Q-Shift) 10,10 tap filters,
- (only 6,6 non-zero taps).
- 'qshift_a' => Q-shift 10,10 tap filters,
- (with 10,10 non-zero taps, unlike qshift_06).
- 'qshift_b' => Q-Shift 14,14 tap filters.
- 'qshift_c' => Q-Shift 16,16 tap filters.
- 'qshift_d' => Q-Shift 18,18 tap filters.
-
+ # Performs a 5-level transform on the real image X using the 13,19-tap
+ # filters for level 1 and the Q-shift 14-tap filters for levels >= 2.
+ Yl, Yh = dtwavexfm(X,5,'near_sym_b','qshift_b')
- Yl -> The real lowpass subband from the final level.
- Yh -> A cell array containing the complex highpass subband for each level.
- Yscale -> This is an OPTIONAL output argument, that is a cell array containing
- real lowpass coefficients for every scale. Only returned if include_scale
- is True.
-
- If biort or qshift are not strings, there are interpreted as tuples of
- vectors giving filter coefficients. In the biort case, this shold be (h0o,
- g0o, h1o, g1o). In the qshift case, this should be (h0a, h0b, g0a, g0b,
- h1a, h1b, g1a, g1b).
-
- Example: Yl, Yh = dtwavexfm(X,5,'near_sym_b','qshift_b')
- performs a 5-level transform on the real image X using the 13,19-tap filters
- for level 1 and the Q-shift 14-tap filters for levels >= 2.
-
- Nick Kingsbury and Cian Shaffrey
- Cambridge University, May 2002
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, Aug 2013
+ .. codeauthor:: Nick Kingsbury, Cambridge University, May 2002
+ .. codeauthor:: Cian Shaffrey, Cambridge University, May 2002
"""
-
# Need this because colfilter and friends assumes input is 2d
- X = as_column_vector(X)
+ X = np.asarray(X)
+ if len(X.shape) == 1:
+ X = np.atleast_2d(X).T
# Try to load coefficients if biort is a string parameter
- if isinstance(biort, basestring):
+ try:
h0o, g0o, h1o, g1o = _biort(biort)
- else:
+ except TypeError:
h0o, g0o, h1o, g1o = biort
# Try to load coefficients if qshift is a string parameter
- if isinstance(qshift, basestring):
+ try:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = _qshift(qshift)
- else:
+ except TypeError:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = qshift
L = np.asarray(X.shape)
@@ -71,9 +58,6 @@ def dtwavexfm(X, nlevels=3, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, include_
if X.shape[0] % 2 != 0:
raise ValueError('Size of input X must be a multiple of 2')
- if len(X.shape) > 1 and np.any(L[1:] != 1):
- raise ValueError('X must be one-dimensional')
-
if nlevels == 0:
if include_scale:
return X, (), ()
@@ -114,45 +98,36 @@ def dtwavexfm(X, nlevels=3, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, include_
return Yl, Yh
def dtwaveifm(Yl, Yh, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, gain_mask=None):
- """Function to perform an n-level dual-tree complex wavelet (DTCWT)
- 1-D reconstruction.
+ """Perform an *n*-level dual-tree complex wavelet (DTCWT) 1D
+ reconstruction.
- Z = dtwaveifm(Yl, Yh, biort, qshift, [gain_mask])
-
- Yl -> The real lowpass subband from the final level
- Yh -> A cell array containing the complex highpass subband for each level.
-
- biort -> 'antonini' => Antonini 9,7 tap filters.
- 'legall' => LeGall 5,3 tap filters.
- 'near_sym_a' => Near-Symmetric 5,7 tap filters.
- 'near_sym_b' => Near-Symmetric 13,19 tap filters.
-
- qshift -> 'qshift_06' => Quarter Sample Shift Orthogonal (Q-Shift) 10,10 tap filters,
- (only 6,6 non-zero taps).
- 'qshift_a' => Q-shift 10,10 tap filters,
- (with 10,10 non-zero taps, unlike qshift_06).
- 'qshift_b' => Q-Shift 14,14 tap filters.
- 'qshift_c' => Q-Shift 16,16 tap filters.
- 'qshift_d' => Q-Shift 18,18 tap filters.
+ :param Yl: The real lowpass subband from the final level
+ :param Yh: A sequence containing the complex highpass subband for each level.
+ :param biort: Level 1 wavelets to use. See :py:func:`biort`.
+ :param qshift: Level >= 2 wavelets to use. See :py:func:`qshift`.
+ :param gain_mask: Gain to be applied to each subband.
- gain_mask -> Gain to be applied to each subband.
- gain_mask(l) is gain for wavelet subband at level l.
- If gain_mask(l) == 0, no computation is performed for band (l).
- Default gain_mask = ones(1,length(Yh)). Note that l is 0-indexed.
+ :returns Z: Reconstructed real signal vector (or matrix).
+
+ The *l*-th element of *gain_mask* is gain for wavelet subband at level l.
+ If gain_mask[l] == 0, no computation is performed for band *l*. Default
+ *gain_mask* is all ones. Note that *l* is 0-indexed.
- Z -> Reconstructed real signal vector (or matrix).
+ If *biort* or *qshift* are strings, they are used as an argument to the
+ :py:func:`biort` or :py:func:`qshift` functions. Otherwise, they are
+ interpreted as tuples of vectors giving filter coefficients. In the *biort*
+ case, this should be (h0o, g0o, h1o, g1o). In the *qshift* case, this should
+ be (h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b).
- If biort or qshift are not strings, there are interpreted as tuples of
- vectors giving filter coefficients. In the biort case, this shold be (h0o,
- g0o, h1o, g1o). In the qshift case, this should be (h0a, h0b, g0a, g0b,
- h1a, h1b, g1a, g1b).
+ Example::
- For example: Z = dtwaveifm(Yl,Yh,'near_sym_b','qshift_b');
- performs a reconstruction from Yl,Yh using the 13,19-tap filters
- for level 1 and the Q-shift 14-tap filters for levels >= 2.
+ # Performs a reconstruction from Yl,Yh using the 13,19-tap filters
+ # for level 1 and the Q-shift 14-tap filters for levels >= 2.
+ Z = dtwaveifm(Yl, Yh, 'near_sym_b', 'qshift_b')
- Nick Kingsbury and Cian Shaffrey
- Cambridge University, May 2002
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, Aug 2013
+ .. codeauthor:: Nick Kingsbury, Cambridge University, May 2002
+ .. codeauthor:: Cian Shaffrey, Cambridge University, May 2002
"""
a = len(Yh) # No of levels.
@@ -161,15 +136,15 @@ def dtwaveifm(Yl, Yh, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, gain_mask=None
gain_mask = np.ones(a) # Default gain_mask.
# Try to load coefficients if biort is a string parameter
- if isinstance(biort, basestring):
+ try:
h0o, g0o, h1o, g1o = _biort(biort)
- else:
+ except TypeError:
h0o, g0o, h1o, g1o = biort
# Try to load coefficients if qshift is a string parameter
- if isinstance(qshift, basestring):
+ try:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = _qshift(qshift)
- else:
+ except TypeError:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = qshift
level = a-1 # No of levels = no of rows in L.
@@ -194,7 +169,11 @@ def dtwaveifm(Yl, Yh, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, gain_mask=None
Hi = c2q1d(Yh[level]*gain_mask[level])
Z = colfilter(Lo,g0o) + colfilter(Hi,g1o)
- return Z.flatten()
+ # Return a 1d vector or a column vector
+ if Z.shape[1] == 1:
+ return Z.flatten()
+ else:
+ return Z
#==========================================================================================
# ********** INTERNAL FUNCTION **********
diff --git a/dtcwt/transform2d.py b/dtcwt/transform2d.py
index bce3edc..12d28b1 100644
--- a/dtcwt/transform2d.py
+++ b/dtcwt/transform2d.py
@@ -6,61 +6,46 @@ from dtcwt.defaults import DEFAULT_BIORT, DEFAULT_QSHIFT
from dtcwt.lowlevel import colfilter, coldfilt, colifilt
def dtwavexfm2(X, nlevels=3, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, include_scale=False):
- """Function to perform a n-level DTCWT-2D decompostion on a 2D matrix X
+ """Perform a *n*-level DTCWT-2D decompostion on a 2D matrix *X*.
- Yl, Yh = dtwavexfm2(X, nlevels, biort, qshift)
- Yl, Yh, Yscale = dtwavexfm2(X, nlevels, biort, qshift, include_scale=True)
+ :param X: 2D real matrix/Image of shape (N, M)
+ :param nlevels: Number of levels of wavelet decomposition
+ :param biort: Level 1 wavelets to use. See :py:func:`biort`.
+ :param qshift: Level >= 2 wavelets to use. See :py:func:`qshift`.
- X -> 2D real matrix/Image of shape (N, M)
+ :returns Yl: The real lowpass image from the final level
+ :returns Yh: A tuple containing the (N, M, 6) shape complex highpass subimages for each level.
+ :returns Yscale: If *include_scale* is True, a tuple containing real lowpass coefficients for every scale.
- nlevels -> No. of levels of wavelet decomposition
+ If *biort* or *qshift* are strings, they are used as an argument to the
+ :py:func:`biort` or :py:func:`qshift` functions. Otherwise, they are
+ interpreted as tuples of vectors giving filter coefficients. In the *biort*
+ case, this should be (h0o, g0o, h1o, g1o). In the *qshift* case, this should
+ be (h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b).
- biort -> 'antonini' => Antonini 9,7 tap filters.
- 'legall' => LeGall 5,3 tap filters.
- 'near_sym_a' => Near-Symmetric 5,7 tap filters.
- 'near_sym_b' => Near-Symmetric 13,19 tap filters.
+ Example::
- qshift -> 'qshift_06' => Quarter Sample Shift Orthogonal (Q-Shift) 10,10 tap filters,
- (only 6,6 non-zero taps).
- 'qshift_a' => Q-shift 10,10 tap filters,
- (with 10,10 non-zero taps, unlike qshift_06).
- 'qshift_b' => Q-Shift 14,14 tap filters.
- 'qshift_c' => Q-Shift 16,16 tap filters.
- 'qshift_d' => Q-Shift 18,18 tap filters.
+ # Performs a 3-level transform on the real image X using the 13,19-tap
+ # filters for level 1 and the Q-shift 14-tap filters for levels >= 2.
+ Yl, Yh = dtwavexfm2(X, 3, 'near_sym_b', 'qshift_b')
-
- Yl -> The real lowpass image from the final level
- Yh -> A tuple containing the (N, M, 6) shape complex highpass subimages for each level.
- Yscale -> This is an OPTIONAL output argument, that is a tuple containing
- real lowpass coefficients for every scale. Only returned if include_scale
- is True.
-
- If biort or qshift are not strings, there are interpreted as tuples of
- vectors giving filter coefficients. In the biort case, this shold be (h0o,
- g0o, h1o, g1o). In the qshift case, this should be (h0a, h0b, g0a, g0b,
- h1a, h1b, g1a, g1b).
-
- Example: Yl,Yh = dtwavexfm2(X,3,'near_sym_b','qshift_b')
- performs a 3-level transform on the real image X using the 13,19-tap filters
- for level 1 and the Q-shift 14-tap filters for levels >= 2.
-
- Nick Kingsbury and Cian Shaffrey
- Cambridge University, Sept 2001
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, Aug 2013
+ .. codeauthor:: Nick Kingsbury, Cambridge University, Sept 2001
+ .. codeauthor:: Cian Shaffrey, Cambridge University, Sept 2001
"""
-
X = np.atleast_2d(X)
# Try to load coefficients if biort is a string parameter
- if isinstance(biort, basestring):
+ try:
h0o, g0o, h1o, g1o = _biort(biort)
- else:
+ except TypeError:
h0o, g0o, h1o, g1o = biort
# Try to load coefficients if qshift is a string parameter
- if isinstance(qshift, basestring):
+ try:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = _qshift(qshift)
- else:
+ except TypeError:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = qshift
original_size = X.shape
@@ -113,31 +98,30 @@ def dtwavexfm2(X, nlevels=3, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, include
if include_scale:
Yscale[0] = LoLo
- if nlevels >= 2:
- for level in xrange(1, nlevels):
- row_size, col_size = LoLo.shape
- if row_size % 4 != 0:
- # Extend by 2 rows if no. of rows of LoLo are not divisable by 4
- LoLo = np.vstack((LoLo[0,:], LoLo, LoLo[-1,:]))
+ for level in xrange(1, nlevels):
+ row_size, col_size = LoLo.shape
+ if row_size % 4 != 0:
+ # Extend by 2 rows if no. of rows of LoLo are not divisable by 4
+ LoLo = np.vstack((LoLo[0,:], LoLo, LoLo[-1,:]))
- if col_size % 4 != 0:
- # Extend by 2 cols if no. of cols of LoLo are not divisable by 4
- LoLo = np.hstack((np.atleast_2d(LoLo[:,0]).T, LoLo, np.atleast_2d(LoLo[:,-1]).T))
+ if col_size % 4 != 0:
+ # Extend by 2 cols if no. of cols of LoLo are not divisable by 4
+ LoLo = np.hstack((np.atleast_2d(LoLo[:,0]).T, LoLo, np.atleast_2d(LoLo[:,-1]).T))
- # Do even Qshift filters on rows.
- Lo = coldfilt(LoLo,h0b,h0a).T
- Hi = coldfilt(LoLo,h1b,h1a).T
+ # Do even Qshift filters on rows.
+ Lo = coldfilt(LoLo,h0b,h0a).T
+ Hi = coldfilt(LoLo,h1b,h1a).T
- # Do even Qshift filters on columns.
- LoLo = coldfilt(Lo,h0b,h0a).T
+ # Do even Qshift filters on columns.
+ LoLo = coldfilt(Lo,h0b,h0a).T
- Yh[level] = np.zeros((LoLo.shape[0]/2, LoLo.shape[1]/2, 6), dtype=np.complex64)
- Yh[level][:,:,[0, 5]] = q2c(coldfilt(Hi,h0b,h0a).T) # Horizontal
- Yh[level][:,:,[2, 3]] = q2c(coldfilt(Lo,h1b,h1a).T) # Vertical
- Yh[level][:,:,[1, 4]] = q2c(coldfilt(Hi,h1b,h1a).T) # Diagonal
+ Yh[level] = np.zeros((LoLo.shape[0]/2, LoLo.shape[1]/2, 6), dtype=np.complex64)
+ Yh[level][:,:,[0, 5]] = q2c(coldfilt(Hi,h0b,h0a).T) # Horizontal
+ Yh[level][:,:,[2, 3]] = q2c(coldfilt(Lo,h1b,h1a).T) # Vertical
+ Yh[level][:,:,[1, 4]] = q2c(coldfilt(Hi,h1b,h1a).T) # Diagonal
- if include_scale:
- Yscale[0] = LoLo
+ if include_scale:
+ Yscale[0] = LoLo
Yl = LoLo
@@ -169,50 +153,39 @@ def dtwavexfm2(X, nlevels=3, biort=DEFAULT_BIORT, qshift=DEFAULT_QSHIFT, include
def dtwaveifm2(Yl,Yh,biort=DEFAULT_BIORT,qshift=DEFAULT_QSHIFT,gain_mask=None):
- """
- Function to perform an n-level dual-tree complex wavelet (DTCWT) 2-D
+ """Perform an *n*-level dual-tree complex wavelet (DTCWT) 2D
reconstruction.
- Z = dtwaveifm2(Yl,Yh,biort,qshift,gain_mask)
-
- Yl -> The real lowpass image from the final level
- Yh -> A tuple containing the 6 complex highpass subimages for each level.
+ :param Yl: The real lowpass subband from the final level
+ :param Yh: A sequence containing the complex highpass subband for each level.
+ :param biort: Level 1 wavelets to use. See :py:func:`biort`.
+ :param qshift: Level >= 2 wavelets to use. See :py:func:`qshift`.
+ :param gain_mask: Gain to be applied to each subband.
- biort -> 'antonini' => Antonini 9,7 tap filters.
- 'legall' => LeGall 5,3 tap filters.
- 'near_sym_a' => Near-Symmetric 5,7 tap filters.
- 'near_sym_b' => Near-Symmetric 13,19 tap filters.
+ :returns Z: Reconstructed real image matrix.
- qshift -> 'qshift_06' => Quarter Sample Shift Orthogonal (Q-Shift) 10,10 tap filters,
- (only 6,6 non-zero taps).
- 'qshift_a' => Q-shift 10,10 tap filters,
- (with 10,10 non-zero taps, unlike qshift_06).
- 'qshift_b' => Q-Shift 14,14 tap filters.
- 'qshift_c' => Q-Shift 16,16 tap filters.
- 'qshift_d' => Q-Shift 18,18 tap filters.
+ The (*d*, *l*)-th element of *gain_mask* is gain for subband with direction
+ *d* at level *l*. If gain_mask[d,l] == 0, no computation is performed for
+ band (d,l). Default *gain_mask* is all ones. Note that both *d* and *l* are
+ zero-indexed.
- gain_mask -> Gain to be applied to each subband.
- gain_mask(d,l) is gain for subband with direction d at level l.
- If gain_mask(d,l) == 0, no computation is performed for band (d,l).
- Default gain_mask = ones(6,length(Yh)). Note that both d and l
- are zero-indexed in this case.
+ If *biort* or *qshift* are strings, they are used as an argument to the
+ :py:func:`biort` or :py:func:`qshift` functions. Otherwise, they are
+ interpreted as tuples of vectors giving filter coefficients. In the *biort*
+ case, this should be (h0o, g0o, h1o, g1o). In the *qshift* case, this should
+ be (h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b).
- Z -> Reconstructed real image matrix
+ Example::
- If biort or qshift are not strings, there are interpreted as tuples of
- vectors giving filter coefficients. In the biort case, this shold be (h0o,
- g0o, h1o, g1o). In the qshift case, this should be (h0a, h0b, g0a, g0b,
- h1a, h1b, g1a, g1b).
+ # Performs a 3-level reconstruction from Yl,Yh using the 13,19-tap
+ # filters for level 1 and the Q-shift 14-tap filters for levels >= 2.
+ Z = dtwaveifm2(Yl, Yh, 'near_sym_b', 'qshift_b')
- For example: Z = dtwaveifm2(Yl,Yh,'near_sym_b','qshift_b')
- performs a 3-level reconstruction from Yl,Yh using the 13,19-tap filters
- for level 1 and the Q-shift 14-tap filters for levels >= 2.
-
- Nick Kingsbury and Cian Shaffrey
- Cambridge University, May 2002
+ .. codeauthor:: Rich Wareham <rjw57 at cantab.net>, Aug 2013
+ .. codeauthor:: Nick Kingsbury, Cambridge University, May 2002
+ .. codeauthor:: Cian Shaffrey, Cambridge University, May 2002
"""
-
a = len(Yh) # No of levels.
if gain_mask is None:
@@ -221,15 +194,15 @@ def dtwaveifm2(Yl,Yh,biort=DEFAULT_BIORT,qshift=DEFAULT_QSHIFT,gain_mask=None):
gain_mask = np.array(gain_mask)
# Try to load coefficients if biort is a string parameter
- if isinstance(biort, basestring):
+ try:
h0o, g0o, h1o, g1o = _biort(biort)
- else:
+ except TypeError:
h0o, g0o, h1o, g1o = biort
# Try to load coefficients if qshift is a string parameter
- if isinstance(qshift, basestring):
+ try:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = _qshift(qshift)
- else:
+ except TypeError:
h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b = qshift
current_level = a
diff --git a/tests/testifm1.py b/tests/testifm1.py
index e658125..f8a9b31 100644
--- a/tests/testifm1.py
+++ b/tests/testifm1.py
@@ -13,4 +13,12 @@ def test_reconstruct():
vec_recon = dtwaveifm(Yl, Yh)
assert np.all(np.abs(vec_recon - vec) < 1e-7)
+ at attr('transform')
+def test_reconstruct_2d():
+ # Reconstruction up to tolerance
+ vec = np.random.rand(630, 20)
+ Yl, Yh = dtwavexfm(vec)
+ vec_recon = dtwaveifm(Yl, Yh)
+ assert np.all(np.abs(vec_recon - vec) < 1e-7)
+
# vim:sw=4:sts=4:et
diff --git a/tests/testxfm1.py b/tests/testxfm1.py
index 9793741..740647a 100644
--- a/tests/testxfm1.py
+++ b/tests/testxfm1.py
@@ -20,7 +20,6 @@ def test_non_multiple_of_two():
vec = np.random.rand(631)
Yl, Yh = dtwavexfm(vec, 1)
- at raises(ValueError)
def test_2d():
Yl, Yh = dtwavexfm(np.random.rand(10,10))
diff --git a/tests/testxfm2.py b/tests/testxfm2.py
index 0b0a31c..8d6e96b 100644
--- a/tests/testxfm2.py
+++ b/tests/testxfm2.py
@@ -3,7 +3,7 @@ from nose.tools import raises
from nose.plugins.attrib import attr
import numpy as np
-from dtcwt import dtwavexfm2
+from dtcwt import dtwavexfm2, biort, qshift
def setup():
global lena
@@ -19,6 +19,10 @@ def test_lena_loaded():
def test_simple():
Yl, Yh = dtwavexfm2(lena)
+ at attr('transform')
+def test_specific_wavelet():
+ Yl, Yh = dtwavexfm2(lena, biort=biort('antonini'), qshift=qshift('qshift_06'))
+
def test_1d():
Yl, Yh = dtwavexfm2(lena[0,:])
@@ -28,7 +32,6 @@ def test_3d():
def test_simple_w_scale():
Yl, Yh, Yscale = dtwavexfm2(lena, include_scale=True)
-
def test_odd_rows():
Yl, Yh = dtwavexfm2(lena[:509,:])
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/python-dtcwt.git
More information about the debian-science-commits
mailing list