These functions provide APIlevel compatibility with MATLAB.
Note
The functionality of dtwavexfm2b and dtwaveifm2b have been folded into dtwavexfm2 and dtwaveifm2. For convenience of porting MATLAB scripts, the original function names are available in the dtcwt module as aliases but they should not be used in new code.
Perform a nlevel DTCWT decompostion on a 1D column vector X (or on the columns of a matrix X).
Parameters:  

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. 
If biort or qshift are strings, they are used as an argument to the biort() or 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).
Example:
# Performs a 5level transform on the real image X using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Yl, Yh = dtwavexfm(X,5,'near_sym_b','qshift_b')
Perform an nlevel dualtree complex wavelet (DTCWT) 1D reconstruction.
Parameters:  

Returns Z:  Reconstructed real array. 
The lth 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 0indexed.
If biort or qshift are strings, they are used as an argument to the biort() or 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).
Example:
# Performs a reconstruction from Yl,Yh using the 13,19tap filters
# for level 1 and the Qshift 14tap filters for levels >= 2.
Z = dtwaveifm(Yl, Yh, 'near_sym_b', 'qshift_b')
Perform a nlevel DTCWT2D decompostion on a 2D matrix X.
Parameters:  

Returns Yl:  The real lowpass image from the final level 
Returns Yh:  A tuple containing the complex highpass subimages for each level. 
Returns Yscale:  If include_scale is True, a tuple containing real lowpass coefficients for every scale. 
If biort or qshift are strings, they are used as an argument to the biort() or 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).
Example:
# Performs a 3level transform on the real image X using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Yl, Yh = dtwavexfm2(X, 3, 'near_sym_b', 'qshift_b')
Perform an nlevel dualtree complex wavelet (DTCWT) 2D reconstruction.
Parameters:  

Returns Z:  Reconstructed real array 
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 zeroindexed.
If biort or qshift are strings, they are used as an argument to the biort() or 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).
Example:
# Performs a 3level reconstruction from Yl,Yh using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Z = dtwaveifm2(Yl, Yh, 'near_sym_b', 'qshift_b')
Perform a nlevel DTCWT2D decompostion on a 2D matrix X.
Parameters:  

Returns Yl:  The real lowpass image from the final level 
Returns Yh:  A tuple containing the complex highpass subimages for each level. 
Returns Yscale:  If include_scale is True, a tuple containing real lowpass coefficients for every scale. 
If biort or qshift are strings, they are used as an argument to the biort() or 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).
Example:
# Performs a 3level transform on the real image X using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Yl, Yh = dtwavexfm2(X, 3, 'near_sym_b', 'qshift_b')
Perform an nlevel dualtree complex wavelet (DTCWT) 2D reconstruction.
Parameters:  

Returns Z:  Reconstructed real array 
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 zeroindexed.
If biort or qshift are strings, they are used as an argument to the biort() or 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).
Example:
# Performs a 3level reconstruction from Yl,Yh using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Z = dtwaveifm2(Yl, Yh, 'near_sym_b', 'qshift_b')
Perform a nlevel DTCWT3D decompostion on a 3D matrix X.
Parameters:  

Returns Yl:  The real lowpass image from the final level 
Returns Yh:  A tuple containing the complex highpass subimages for each level. 
Each element of Yh is a 4D complex array with the 4th dimension having size 28. The 3D slice Yh[l][:,:,:,d] corresponds to the complex higpass coefficients for direction d at level l where d and l are both 0indexed.
If biort or qshift are strings, they are used as an argument to the biort() or 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).
There are two values for ext_mode, either 4 or 8. If ext_mode = 4, check whether 1st level is divisible by 2 (if not we raise a ValueError). Also check whether from 2nd level onwards, the coefs can be divided by 4. If any dimension size is not a multiple of 4, append extra coefs by repeating the edges. If ext_mode = 8, check whether 1st level is divisible by 4 (if not we raise a ValueError). Also check whether from 2nd level onwards, the coeffs can be divided by 8. If any dimension size is not a multiple of 8, append extra coeffs by repeating the edges twice.
If discard_level_1 is True the highpass coefficients at level 1 will be discarded. (And, in fact, will never be calculated.) This turns the transform from being 8:1 redundant to being 1:1 redundant at the cost of nolonger allowing perfect reconstruction. If this option is selected then Yh[0] will be None. Note that dtwaveifm3() will accepts Yh[0] being None and will treat it as being zero.
Example:
# Performs a 3level transform on the real 3D array X using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Yl, Yh = dtwavexfm3(X, 3, 'near_sym_b', 'qshift_b')
Perform an nlevel dualtree complex wavelet (DTCWT) 3D reconstruction.
Parameters:  

Returns Z:  Reconstructed real image matrix. 
If biort or qshift are strings, they are used as an argument to the biort() or 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).
There are two values for ext_mode, either 4 or 8. If ext_mode = 4, check whether 1st level is divisible by 2 (if not we raise a ValueError). Also check whether from 2nd level onwards, the coefs can be divided by 4. If any dimension size is not a multiple of 4, append extra coefs by repeating the edges. If ext_mode = 8, check whether 1st level is divisible by 4 (if not we raise a ValueError). Also check whether from 2nd level onwards, the coeffs can be divided by 8. If any dimension size is not a multiple of 8, append extra coeffs by repeating the edges twice.
Example:
# Performs a 3level reconstruction from Yl,Yh using the 13,19tap
# filters for level 1 and the Qshift 14tap filters for levels >= 2.
Z = dtwaveifm3(Yl, Yh, 'near_sym_b', 'qshift_b')
Load level 1 wavelet by name.
Parameters:  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  NearSymmetric 5,7 tap filters. 
near_sym_b  NearSymmetric 13,19 tap filters. 
near_sym_b_bp  NearSymmetric 13,19 tap filters + BP filter 
Return a tuple whose elements are a vector specifying the h0o, g0o, h1o and g1o coefficients.
See Rotational symmetry modified wavelet transform for an explanation of the near_sym_b_bp wavelet filters.
Raises: 


Load level >=2 wavelet by name,
Parameters:  name – a string specifying the wavelet family name 

Returns:  a tuple of vectors giving filter coefficients 
Name  Wavelet 

qshift_06  Quarter Sample Shift Orthogonal (QShift) 10,10 tap filters, (only 6,6 nonzero taps). 
qshift_a  Qshift 10,10 tap filters, (with 10,10 nonzero taps, unlike qshift_06). 
qshift_b  QShift 14,14 tap filters. 
qshift_c  QShift 16,16 tap filters. 
qshift_d  QShift 18,18 tap filters. 
qshift_b_bp  QShift 18,18 tap filters + BP 
Return a tuple whose elements are a vector specifying the h0a, h0b, g0a, g0b, h1a, h1b, g1a and g1b coefficients.
See Rotational symmetry modified wavelet transform for an explanation of the qshift_b_bp wavelet filters.
Raises: 


A representation of the reconstructed signal from the inverse transform. A backend is free to implement their own version of this class providing it corresponds to the interface documented.
A NumPycompatible array containing the reconstructed signal.
An implementation of a 2D DTCWT transformation. Backends must provide a transform class which provides an interface compatible with this base class.
Parameters: 


If biort or qshift are strings, they are used as an argument to the biort() or 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).
In some cases the tuples may have more elements. This is used to represent the Rotational symmetry modified wavelet transform.
Perform a nlevel DTCWT2D decompostion on a 2D matrix X.
Parameters: 


Returns:  A dtcwt.backend.TransformDomainSignal compatible object representing the transformdomain signal 
Perform an nlevel dualtree complex wavelet (DTCWT) 2D reconstruction.
Parameters: 


Returns:  A dtcwt.backend.ReconstructedSignal compatible instance with the reconstruction. 
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 zeroindexed.
A representation of a transform domain signal.
Backends are free to implement any class which respects this interface for storing transformdomain signals. The inverse transform may accept a backendspecific version of this class but should always accept any class which corresponds to this interface.
A NumPycompatible array containing the coarsest scale lowpass signal.
A tuple where each element is the complex subband coefficients for corresponding scales finest to coarsest.
(optional) A tuple where each element is a NumPycompatible array containing the lowpass signal for corresponding scales finest to coarsest. This is not required for the inverse and may be None.
A backend which uses NumPy to perform the filtering. This backend should always be available.
A representation of a transform domain signal.
Backends are free to implement any class which respects this interface for storing transformdomain signals. The inverse transform may accept a backendspecific version of this class but should always accept any class which corresponds to this interface.
A NumPycompatible array containing the coarsest scale lowpass signal.
A tuple where each element is the complex subband coefficients for corresponding scales finest to coarsest.
(optional) A tuple where each element is a NumPycompatible array containing the lowpass signal for corresponding scales finest to coarsest. This is not required for the inverse and may be None.
An implementation of the 2D DTCWT via NumPy. biort and qshift are the wavelets which parameterise the transform. Valid values are documented in dtcwt.dtwavexfm2().
Perform a nlevel DTCWT2D decompostion on a 2D matrix X.
Parameters: 


Returns:  A dtcwt.backend.TransformDomainSignal compatible object representing the transformdomain signal 
Perform an nlevel dualtree complex wavelet (DTCWT) 2D reconstruction.
Parameters: 


Returns:  A dtcwt.backend.ReconstructedSignal compatible instance with the reconstruction. 
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 zeroindexed.
Provide lowlevel OpenCL accelerated operations. This backend requires that PyOpenCL be installed.
An interfacecompatible version of dtcwt.backend.TransformDomainSignal where the initialiser arguments are assumed to by pyopencl.array.Array instances.
The attributes defined in dtcwt.backend.TransformDomainSignal are implemented via properties. The original OpenCL arrays may be accessed via the cl_... attributes.
Note
The copy from device to host is performed once and then memoized. This makes repeated access to the hostside attributes efficient but will mean that any changes to the deviceside arrays will not be reflected in the hostside attributes after their first access. You should not be modifying the arrays once you return an instance of this class anyway but if you do, beware!
The CL array containing the lowpass image.
A tuple of CL arrays containing the subband images.
(optional) Either None or a tuple of lowpass images for each scale.
An implementation of the 2D DTCWT via OpenCL. biort and qshift are the wavelets which parameterise the transform. Valid values are documented in dtcwt.dtwavexfm2().
If queue is nonNone it is an instance of pyopencl.CommandQueue which is used to compile and execute the OpenCL kernels which implement the transform. If it is None, the first available compute device is used.
Note
At the moment only the forward transform is accelerated. The inverse transform uses the NumPy backend.
Perform a nlevel DTCWT2D decompostion on a 2D matrix X.
Parameters: 


Returns:  A dtcwt.backend.TransformDomainSignal compatible object representing the transformdomain signal 
Note
X may be a pyopencl.array.Array instance which has already been copied to the device. In which case, it must be 2D. (I.e. a vector will not be autopromoted.)
Perform an nlevel dualtree complex wavelet (DTCWT) 2D reconstruction.
Parameters: 


Returns:  A dtcwt.backend.ReconstructedSignal compatible instance with the reconstruction. 
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 zeroindexed.
Parameters: 


Returns:  (Px4) array of P keypoints in image coordinates 
Warning
The interface and behaviour of this function is the subject of an open research project. It is provided in this release as a preview of forthcoming functionality but it is subject to change between releases.
The rows of the returned keypoint array give the x coordinate, y coordinate, scale and keypoint energy. The rows are sorted in order of decreasing keypoint energy.
If refine_positions is True then the positions (and energy) of the keypoints will be refined to subpixel accuracy by fitting a quadratic patch. If refine_positions is False then the keypoint locations will be those corresponding directly to pixelwise maxima of the subband images.
The max_points and threshold parameters are cumulative: if both are specified then the max_points greatest energy keypoints with energy greater than threshold will be returned.
Usually the keypoint energies returned from the finest scale level are dominated by noise and so one usually wants to specify skip_levels to be 1 or 2. If skip_levels is 0 then all levels will be used to compute keypoint energy.
The upsample_subbands and upsample_keypoint_energy parameters are used to control whether the individual subband coefficients and/org the keypoint energy map are upscaled by 2 before finding keypoints. If these parameters are None then no corresponding upscaling is performed. If nonNone they specify the upscale method as outlined in dtcwt.sampling.upsample().
If method is None, the default 'fauqueur' method is used.
Name  Description  Parameters used 

fauqueur  Geometric mean of absolute values[1]  alpha, beta 
bendale  Minimum absolute value[2]  none 
kingsbury  Crossproduct of orthogonal subbands  kappa 
[1] Julien Fauqueur, Nick Kingsbury, and Ryan Anderson. Multiscale Keypoint Detection using the DualTree Complex Wavelet Transform. 2006 International Conference on Image Processing, pages 16251628, October 2006. ISSN 15224880. doi: 10.1109/ICIP.2006.312656. http://ieeexplore.ieee.org/lpdocs/epic03/wrapper.htm?arnumber=4106857.
[2] Pashmina Bendale, Bill Triggs, and Nick Kingsbury. Multiscale Keypoint Analysis based on Complex Wavelets. In British Machine Vision Conference (BMVC), 2010. http://wwwsigproc.eng.cam.ac.uk/~pb397/publications/BTK_BMVC_2010_abstract.pdf.
Rescaling and resampling high and lowpass subbands.
Sample image at (x,y) given by elements of xs and ys. Both xs and ys must have identical shape and output will have this same shape. The location (x,y) refers to the centre of im[y,x]. Samples at fractional locations are calculated using the method specified by method (or 'lanczos' if method is None.)
Parameters: 


Raises ValueError:  
if xs and ys have differing shapes 
As sample() except that the highpass image is first phase shifted to be centred on approximately DC.
Return a resampled version of im scaled to shape.
Since the centre of pixel (x,y) has coordinate (x,y) the extent of im is actually \(x \in (0.5, w0.5]\) and \(y \in (0.5, h0.5]\) where (y,x) is im.shape. This returns a sampled version of im that has the same extent as a shapesized array.
As rescale() except that the highpass image is first phase shifted to be centred on approximately DC.
Specialised function to upsample an image by a factor of two using a specified sampling method. If image is an array of shape (NxMx...) then the output will have shape (2Nx2Mx...). Only rows and columns are upsampled, depth axes and greater are interpolated but are not upsampled.
Parameters: 


If method is None, the default sampling method 'lanczos' is used. The following sampling methods are supported:
Name  Description 

nearest  Nearestneighbour sampling 
bilinear  Bilinear sampling 
lanczos  Lanczos sampling with window radius of 3 
As upsample() except that the highpass image is first phase rolled so that the filter has approximate DC centre frequency. The upshot is that this is the function to use when resampling complex subband images.
A normal user should not need to call these functions but they are documented here just in case you do.
Useful utilities for testing the 2D DTCWT with synthetic images
Return an appropriate complex data type depending on the type of X. If X is already complex, return that, if it is floating point return a complex type of the appropriate size and if it is integer, choose an complex floating point type depending on the result of numpy.asfarray().
Return v as a column vector with shape (N,1).
Similar to numpy.asfarray() except that this function tries to preserve the original datatype of X if it is already a floating point type and will pass floating point arrays through directly without copying.
Generate an image of size N*N pels, containing a circle radius r pels and centred at du,dv relative to the centre of the image. The edge of the circle is a cosine shaped edge of width w (from 10 to 90% points).
Python implementation by S. C. Forshaw, November 2013.
Generate an image of size N * N pels, of an edge going from 0 to 1 in height at theta degrees to the horizontal (top of image = 1 if angle = 0). r is a twoelement vector, it is a coordinate in ij coords through which the step should pass. The shape of the intensity step is half a raised cosine w pels wide (w>=1).
T. E . Gale’s enhancement to drawedge() for MATLAB, transliterated to Python by S. C. Forshaw, Nov. 2013.
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.
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 (i.e. \(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
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 extension with repeated end samples is used on the composite X columns before each filter is applied.
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 noneven.
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].
Parameters: 


Returns Y:  the filtered image. 
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 (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
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.