jj2000.j2k.wavelet.analysis

Class AnWTFilter

java.lang.Object

jj2000.j2k.wavelet.analysis.AnWTFilter

All Implemented Interfaces:

WaveletFilter

Direct Known Subclasses:

AnWTFilterFloat, AnWTFilterInt

public abstract class AnWTFilter
extends Object
implements WaveletFilter

This abstract class defines the methods of all analysis wavelet filters. Specialized abstract classes that work on particular data types (int, float) provide more specific method calls while retaining the generality of this one. See the AnWTFilterInt and AnWTFilterFloat classes. Implementations of analysis filters should inherit from one of those classes.

All analysis wavelet filters should follow the following conventions:

- The first sample to filter is the low-pass one. As a consequence, if the input signal is of odd-length then the low-pass output signal is one sample longer than the high-pass output one. Therefore, if the length of input signal is N, the low-pass output signal is of length N/2 if N is even and N/2+1/2 if N is odd, while the high-pass output signal is of length N/2 if N is even and N/2-1/2 if N is odd.

- The normalization is 1 for the DC gain and 2 for the Nyquist gain (Type I normalization), for both reversible and non-reversible filters.

If the length of input signal is N, the low-pass output signal is of length N/2 if N is even and N/2+1/2 if N is odd, while the high-pass output sample is of length N/2 if N is even and N/2-1/2 if N is odd.

The analyze method may seem very complicated, but is designed to minimize the amount of data copying and redundant calculations when used for block-based or line-based wavelet transform implementations, while being applicable to full-frame transforms as well.

All filters should implement the equals() method of the Object class. The call x.equals(y) should test if the 'x' and 'y' filters are the same or not, in what concerns the bit stream header syntax (two filters are the same if the same filter code should be output to the bit stream).

See Also:

AnWTFilterInt, AnWTFilterFloat

Field Summary

Fields

Modifier and Type	Field and Description
static char	OPT_PREFIX The prefix for wavelet filter options: 'F'
private static String[][]	pinfo The list of parameters that is accepted for wavelet filters.

Fields inherited from interface jj2000.j2k.wavelet.WaveletFilter

WT_FILTER_FLOAT_CONVOL, WT_FILTER_FLOAT_LIFT, WT_FILTER_INT_LIFT

Constructor Summary

Constructors

Constructor and Description
AnWTFilter()

Method Summary

Modifier and Type	Method and Description
abstract void	analyze_hpf(Object inSig, int inOff, int inLen, int inStep, Object lowSig, int lowOff, int lowStep, Object highSig, int highOff, int highStep) Filters the input signal by this analysis filter, decomposing it in a low-pass and a high-pass signal.
abstract void	analyze_lpf(Object inSig, int inOff, int inLen, int inStep, Object lowSig, int lowOff, int lowStep, Object highSig, int highOff, int highStep) Filters the input signal by this analysis filter, decomposing it in a low-pass and a high-pass signal.
abstract int	getFilterType() Returns the type of filter used according to the FilterTypes interface.
abstract float[]	getHPSynthesisFilter() Returns the time-reversed high-pass synthesis waveform of the filter, which is the high-pass filter.
float[]	getHPSynWaveForm(float[] in, float[] out) Returns the equivalent high-pass synthesis waveform of a cascade of filters, given the syhthesis waveform of the previous stage.
abstract float[]	getLPSynthesisFilter() Returns the time-reversed low-pass synthesis waveform of the filter, which is the low-pass filter.
float[]	getLPSynWaveForm(float[] in, float[] out) Returns the equivalent low-pass synthesis waveform of a cascade of filters, given the syhthesis waveform of the previous stage.
static String[][]	getParameterInfo() Returns the parameters that are used in this class and implementing classes.
private static float[]	upsampleAndConvolve(float[] in, float[] wf, float[] out) Returns the signal resulting of upsampling (by 2) the input signal 'in' and then convolving it with the time-reversed signal 'wf'.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface jj2000.j2k.wavelet.WaveletFilter

getAnHighNegSupport, getAnHighPosSupport, getAnLowNegSupport, getAnLowPosSupport, getDataType, getImplType, getSynHighNegSupport, getSynHighPosSupport, getSynLowNegSupport, getSynLowPosSupport, isReversible, isSameAsFullWT

Field Detail

OPT_PREFIX

public static final char OPT_PREFIX

The prefix for wavelet filter options: 'F'

See Also:

Constant Field Values

pinfo

private static final String[][] pinfo

The list of parameters that is accepted for wavelet filters. Options for wavelet filters start with a 'F'.

Constructor Detail

AnWTFilter

public AnWTFilter()

Method Detail

analyze_lpf

public abstract void analyze_lpf(Object inSig,
                                 int inOff,
                                 int inLen,
                                 int inStep,
                                 Object lowSig,
                                 int lowOff,
                                 int lowStep,
                                 Object highSig,
                                 int highOff,
                                 int highStep)

Filters the input signal by this analysis filter, decomposing it in a low-pass and a high-pass signal. This method performs the filtering and the subsampling with the low pass first filtering convention.

The input signal resides in the inSig array. The index of the first sample to filter (i.e. that will generate the first low-pass output sample) is given by inOff. The number of samples to filter is given by inLen. This array must be of the same type as the one for which the particular implementation works with (which is returned by the getDataType() method).

The input signal can be interleaved with other signals in the same inSig array, and this is determined by the inStep argument. This means that the first sample of the input signal is inSig[inOff], the second is inSig[inOff+inStep], the third is inSig[inOff+2*inStep], and so on. Therefore if inStep is 1 there is no interleaving. This feature allows to filter columns of a 2-D signal, when it is stored in a line by line order in inSig, without having to copy the data, in this case the inStep argument should be the line width.

This method also allows to apply the analysis wavelet filter by parts in the input signal using an overlap and thus producing the same coefficients at the output. The tailOvrlp argument specifies how many samples in the input signal, before the first one to be filtered, can be used for overlap. Then, the filter instead of extending the input signal will use those samples to calculate the first output samples. The argument tailOvrlp can be 0 for no overlap, or some value that provides partial or full overlap. There should be enough samples in the input signal, before the first sample to be filtered, to support the overlap. The headOvrlp provides the same functionality but at the end of the input signal. The inStep argument also applies to samples used for overlap. This overlap feature can be used for line-based wavelet transforms (in which case it will only be used when filtering the columns) or for overlapping block-based wavelet transforms (in which case it will be used when filtering lines and columns).

The low-pass output signal is placed in the lowSig array. The lowOff and lowStep arguments are analogous to the inOff and inStep ones, but they apply to the lowSig array. The lowSig array must be long enough to hold the low-pass output signal.

The high-pass output signal is placed in the highSig array. The highOff and highStep arguments are analogous to the inOff and inStep ones, but they apply to the highSig array. The highSig array must be long enough to hold the high-pass output signal.

Parameters:

inSig - This is the array that contains the input signal. It must be of the correct type (e.g., it must be int[] if getDataType() returns TYPE_INT).

inOff - This is the index in inSig of the first sample to filter.

inLen - This is the number of samples in the input signal to filter.

inStep - This is the step, or interleave factor, of the input signal samples in the inSig array. See above.

lowSig - This is the array where the low-pass output signal is placed. It must be of the same type as inSig and it should be long enough to contain the output signal.

lowOff - This is the index in lowSig of the element where to put the first low-pass output sample.

lowStep - This is the step, or interleave factor, of the low-pass output samples in the lowSig array. See above.

highSig - This is the array where the high-pass output signal is placed. It must be of the same type as inSig and it should be long enough to contain the output signal.

highOff - This is the index in highSig of the element where to put the first high-pass output sample.

highStep - This is the step, or interleave factor, of the high-pass output samples in the highSig array. See above.

See Also:

WaveletFilter.getDataType()

analyze_hpf

public abstract void analyze_hpf(Object inSig,
                                 int inOff,
                                 int inLen,
                                 int inStep,
                                 Object lowSig,
                                 int lowOff,
                                 int lowStep,
                                 Object highSig,
                                 int highOff,
                                 int highStep)

Filters the input signal by this analysis filter, decomposing it in a low-pass and a high-pass signal. This method performs the filtering and the subsampling with the high pass first filtering convention.

The input signal resides in the inSig array. The index of the first sample to filter (i.e. that will generate the first high-pass output sample) is given by inOff. The number of samples to filter is given by inLen. This array must be of the same type as the one for which the particular implementation works with (which is returned by the getDataType() method).

The input signal can be interleaved with other signals in the same inSig array, and this is determined by the inStep argument. This means that the first sample of the input signal is inSig[inOff], the second is inSig[inOff+inStep], the third is inSig[inOff+2*inStep], and so on. Therefore if inStep is 1 there is no interleaving. This feature allows to filter columns of a 2-D signal, when it is stored in a line by line order in inSig, without having to copy the data, in this case the inStep argument should be the line width.

The low-pass output signal is placed in the lowSig array. The lowOff and lowStep arguments are analogous to the inOff and inStep ones, but they apply to the lowSig array. The lowSig array must be long enough to hold the low-pass output signal.

The high-pass output signal is placed in the highSig array. The highOff and highStep arguments are analogous to the inOff and inStep ones, but they apply to the highSig array. The highSig array must be long enough to hold the high-pass output signal.

Parameters:

inSig - This is the array that contains the input signal. It must be of the correct type (e.g., it must be int[] if getDataType() returns TYPE_INT).

inOff - This is the index in inSig of the first sample to filter.

inLen - This is the number of samples in the input signal to filter.

inStep - This is the step, or interleave factor, of the input signal samples in the inSig array. See above.

lowSig - This is the array where the low-pass output signal is placed. It must be of the same type as inSig and it should be long enough to contain the output signal.

lowOff - This is the index in lowSig of the element where to put the first low-pass output sample.

lowStep - This is the step, or interleave factor, of the low-pass output samples in the lowSig array. See above.

highSig - This is the array where the high-pass output signal is placed. It must be of the same type as inSig and it should be long enough to contain the output signal.

highOff - This is the index in highSig of the element where to put the first high-pass output sample.

highStep - This is the step, or interleave factor, of the high-pass output samples in the highSig array. See above.

See Also:

WaveletFilter.getDataType()

getLPSynthesisFilter

public abstract float[] getLPSynthesisFilter()

Returns the time-reversed low-pass synthesis waveform of the filter, which is the low-pass filter. This is the time-reversed impulse response of the low-pass synthesis filter. It is used to calculate the L2-norm of the synthesis basis functions for a particular subband (also called energy weight).

The returned array may not be modified (i.e. a reference to the internal array may be returned by the implementation of this method).

Returns:

The time-reversed low-pass synthesis waveform of the filter.

getHPSynthesisFilter

public abstract float[] getHPSynthesisFilter()

Returns the time-reversed high-pass synthesis waveform of the filter, which is the high-pass filter. This is the time-reversed impulse response of the high-pass synthesis filter. It is used to calculate the L2-norm of the synthesis basis functions for a particular subband (also called energy weight).

The returned array may not be modified (i.e. a reference to the internal array may be returned by the implementation of this method).

Returns:

The time-reversed high-pass synthesis waveform of the filter.

getLPSynWaveForm

public float[] getLPSynWaveForm(float[] in,
                                float[] out)

Returns the equivalent low-pass synthesis waveform of a cascade of filters, given the syhthesis waveform of the previous stage. This is the result of upsampling 'in' by 2, and concolving it with the low-pass synthesis waveform of the filter. The length of the returned signal is 2*in_l+lp_l-2, where in_l is the length of 'in' and 'lp_l' is the lengthg of the low-pass synthesis filter.

The length of the low-pass synthesis filter is getSynLowNegSupport()+getSynLowPosSupport().

Parameters:

in - The synthesis waveform of the previous stage.

out - If non-null this array is used to store the resulting signal. It must be long enough, or an IndexOutOfBoundsException is thrown.

See Also:

WaveletFilter.getSynLowNegSupport(), WaveletFilter.getSynLowPosSupport()

getHPSynWaveForm

public float[] getHPSynWaveForm(float[] in,
                                float[] out)

Returns the equivalent high-pass synthesis waveform of a cascade of filters, given the syhthesis waveform of the previous stage. This is the result of upsampling 'in' by 2, and concolving it with the high-pass synthesis waveform of the filter. The length of the returned signal is 2*in_l+hp_l-2, where in_l is the length of 'in' and 'hp_l' is the lengthg of the high-pass synthesis filter.

The length of the high-pass synthesis filter is getSynHighNegSupport()+getSynHighPosSupport().

Parameters:

in - The synthesis waveform of the previous stage.

out - If non-null this array is used to store the resulting signal. It must be long enough, or an IndexOutOfBoundsException is thrown.

See Also:

WaveletFilter.getSynHighNegSupport(), WaveletFilter.getSynHighPosSupport()

upsampleAndConvolve

private static float[] upsampleAndConvolve(float[] in,
                                           float[] wf,
                                           float[] out)

Returns the signal resulting of upsampling (by 2) the input signal 'in' and then convolving it with the time-reversed signal 'wf'. The returned signal is of length l_in*2+l_wf-2, where l_in is the length of 'in', and l_wf is the length of 'wf'.

The 'wf' signal has to be already time-reversed, therefore only a dot-product is performed (instead of a convolution). This is equivalent to convolving with the non-time-reversed 'wf' signal.

Parameters:

in - The signal to upsample and filter. If null it is considered to be a dirac.

wf - The time-reversed impulse response used for filtering.

out - If non-null this array is used to store the resulting signal, it must be of length in.length*2+wf.length-2 at least. An IndexOutOfBoundsException is thrown if this is not the case.

Returns:

The resulting signal, of length in.length*2+wf.length-2

getFilterType

public abstract int getFilterType()

Returns the type of filter used according to the FilterTypes interface.

Returns:

The filter type.

See Also:

FilterTypes

getParameterInfo

public static String[][] getParameterInfo()

Returns the parameters that are used in this class and implementing classes. It returns a 2D String array. Each of the 1D arrays is for a different option, and they have 3 elements. The first element is the option name, the second one is the synopsis, the third one is a long description of what the parameter is and the fourth is its default value. The synopsis or description may be 'null', in which case it is assumed that there is no synopsis or description of the option, respectively. Null may be returned if no options are supported.

Returns:

the options name, their synopsis and their explanation, or null if no options are supported.