001: /*
002: * $RCSfile: AnWTFilter.java,v $
003: * $Revision: 1.1 $
004: * $Date: 2005/02/11 05:02:28 $
005: * $State: Exp $
006: *
007: * Class: AnWTFilter
008: *
009: * Description: The abstract class for all analysis wavelet filters
010: *
011: *
012: *
013: * COPYRIGHT:
014: *
015: * This software module was originally developed by Raphaël Grosbois and
016: * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
017: * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
018: * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
019: * Centre France S.A) in the course of development of the JPEG2000
020: * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
021: * software module is an implementation of a part of the JPEG 2000
022: * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
023: * Systems AB and Canon Research Centre France S.A (collectively JJ2000
024: * Partners) agree not to assert against ISO/IEC and users of the JPEG
025: * 2000 Standard (Users) any of their rights under the copyright, not
026: * including other intellectual property rights, for this software module
027: * with respect to the usage by ISO/IEC and Users of this software module
028: * or modifications thereof for use in hardware or software products
029: * claiming conformance to the JPEG 2000 Standard. Those intending to use
030: * this software module in hardware or software products are advised that
031: * their use may infringe existing patents. The original developers of
032: * this software module, JJ2000 Partners and ISO/IEC assume no liability
033: * for use of this software module or modifications thereof. No license
034: * or right to this software module is granted for non JPEG 2000 Standard
035: * conforming products. JJ2000 Partners have full right to use this
036: * software module for his/her own purpose, assign or donate this
037: * software module to any third party and to inhibit third parties from
038: * using this software module for non JPEG 2000 Standard conforming
039: * products. This copyright notice must be included in all copies or
040: * derivative works of this software module.
041: *
042: * Copyright (c) 1999/2000 JJ2000 Partners.
043: *
044: *
045: *
046: */
047: package jj2000.j2k.wavelet.analysis;
048:
049: import jj2000.j2k.codestream.writer.*;
050: import jj2000.j2k.wavelet.*;
051: import jj2000.j2k.image.*;
052: import jj2000.j2k.util.*;
053:
054: import java.util.*;
055: import java.io.*;
056:
057: /**
058: * This abstract class defines the methods of all analysis wavelet
059: * filters. Specialized abstract classes that work on particular data
060: * types (int, float) provide more specific method calls while
061: * retaining the generality of this one. See the AnWTFilterInt
062: * and AnWTFilterFloat classes. Implementations of analysis
063: * filters should inherit from one of those classes.
064: *
065: * <P>All analysis wavelet filters should follow the following conventions:
066: *
067: * <P>- The first sample to filter is the low-pass one. As a
068: * consequence, if the input signal is of odd-length then the low-pass
069: * output signal is one sample longer than the high-pass output
070: * one. Therefore, if the length of input signal is N, the low-pass
071: * output signal is of length N/2 if N is even and N/2+1/2 if N is
072: * odd, while the high-pass output signal is of length N/2 if N is
073: * even and N/2-1/2 if N is odd.
074: *
075: * <P>- The normalization is 1 for the DC gain and 2 for the Nyquist
076: * gain (Type I normalization), for both reversible and non-reversible
077: * filters.
078: *
079: * <P>If the length of input signal is N, the low-pass output signal
080: * is of length N/2 if N is even and N/2+1/2 if N is odd, while the
081: * high-pass output sample is of length N/2 if N is even and N/2-1/2
082: * if N is odd.
083: *
084: * <P>The analyze method may seem very complicated, but is designed to
085: * minimize the amount of data copying and redundant calculations when
086: * used for block-based or line-based wavelet transform
087: * implementations, while being applicable to full-frame transforms as
088: * well.
089: *
090: * <P>All filters should implement the equals() method of the Object
091: * class. The call x.equals(y) should test if the 'x' and 'y' filters are the
092: * same or not, in what concerns the bit stream header syntax (two filters are
093: * the same if the same filter code should be output to the bit stream).
094: *
095: * @see AnWTFilterInt
096: *
097: * @see AnWTFilterFloat
098: * */
099: public abstract class AnWTFilter implements WaveletFilter {
100:
101: /** The prefix for wavelet filter options: 'F' */
102: public final static char OPT_PREFIX = 'F';
103:
104: /** The list of parameters that is accepted for wavelet filters. Options
105: * for wavelet filters start with a 'F'. */
106: private final static String[][] pinfo = { {
107: "Ffilters",
108: "[<tile-component idx>] <id> "
109: + "[ [<tile-component idx>] <id> ...]",
110: "Specifies which filters to use for specified tile-component.\n"
111: + "<tile-component idx>: see general note\n"
112: + "<id>: ',' separates horizontal and vertical filters, ':' separates"
113: + " decomposition levels filters. JPEG 2000 part I only supports w5x3"
114: + " and w9x7 filters.", null }, };
115:
116: /**
117: * Filters the input signal by this analysis filter, decomposing
118: * it in a low-pass and a high-pass signal. This method performs
119: * the filtering and the subsampling with the low pass first
120: * filtering convention.
121: *
122: * <P>The input signal resides in the inSig array. The index of
123: * the first sample to filter (i.e. that will generate the first
124: * low-pass output sample) is given by inOff. The number of
125: * samples to filter is given by inLen. This array must be of the
126: * same type as the one for which the particular implementation
127: * works with (which is returned by the getDataType() method).
128: *
129: * <P>The input signal can be interleaved with other signals in
130: * the same inSig array, and this is determined by the inStep
131: * argument. This means that the first sample of the input signal
132: * is inSig[inOff], the second is inSig[inOff+inStep], the third
133: * is inSig[inOff+2*inStep], and so on. Therefore if inStep is 1
134: * there is no interleaving. This feature allows to filter columns
135: * of a 2-D signal, when it is stored in a line by line order in
136: * inSig, without having to copy the data, in this case the inStep
137: * argument should be the line width.
138: *
139: * <P>This method also allows to apply the analysis wavelet filter
140: * by parts in the input signal using an overlap and thus
141: * producing the same coefficients at the output. The tailOvrlp
142: * argument specifies how many samples in the input signal, before
143: * the first one to be filtered, can be used for overlap. Then,
144: * the filter instead of extending the input signal will use those
145: * samples to calculate the first output samples. The argument
146: * tailOvrlp can be 0 for no overlap, or some value that provides
147: * partial or full overlap. There should be enough samples in the
148: * input signal, before the first sample to be filtered, to
149: * support the overlap. The headOvrlp provides the same
150: * functionality but at the end of the input signal. The inStep
151: * argument also applies to samples used for overlap. This overlap
152: * feature can be used for line-based wavelet transforms (in which
153: * case it will only be used when filtering the columns) or for
154: * overlapping block-based wavelet transforms (in which case it
155: * will be used when filtering lines and columns).
156: *
157: * <P>The low-pass output signal is placed in the lowSig
158: * array. The lowOff and lowStep arguments are analogous to the
159: * inOff and inStep ones, but they apply to the lowSig array. The
160: * lowSig array must be long enough to hold the low-pass output
161: * signal.
162: *
163: * <P>The high-pass output signal is placed in the highSig
164: * array. The highOff and highStep arguments are analogous to the
165: * inOff and inStep ones, but they apply to the highSig array. The
166: * highSig array must be long enough to hold the high-pass output
167: * signal.
168: *
169: * @param inSig This is the array that contains the input
170: * signal. It must be of the correct type (e.g., it must be int[]
171: * if getDataType() returns TYPE_INT).
172: *
173: * @param inOff This is the index in inSig of the first sample to
174: * filter.
175: *
176: * @param inLen This is the number of samples in the input signal
177: * to filter.
178: *
179: * @param inStep This is the step, or interleave factor, of the
180: * input signal samples in the inSig array. See above.
181: *
182: * @param tailOvrlp This is the number of samples in the input
183: * signal before the first sample to filter that can be used for
184: * overlap. See above.
185: *
186: * @param headOvrlp This is the number of samples in the input
187: * signal after the last sample to filter that can be used for
188: * overlap. See above.
189: *
190: * @param lowSig This is the array where the low-pass output
191: * signal is placed. It must be of the same type as inSig and it
192: * should be long enough to contain the output signal.
193: *
194: * @param lowOff This is the index in lowSig of the element where
195: * to put the first low-pass output sample.
196: *
197: * @param lowStep This is the step, or interleave factor, of the
198: * low-pass output samples in the lowSig array. See above.
199: *
200: * @param highSig This is the array where the high-pass output
201: * signal is placed. It must be of the same type as inSig and it
202: * should be long enough to contain the output signal.
203: *
204: * @param highOff This is the index in highSig of the element where
205: * to put the first high-pass output sample.
206: *
207: * @param highStep This is the step, or interleave factor, of the
208: * high-pass output samples in the highSig array. See above.
209: *
210: * @see WaveletFilter#getDataType
211: *
212: *
213: *
214: *
215: * */
216: public abstract void analyze_lpf(Object inSig, int inOff,
217: int inLen, int inStep, Object lowSig, int lowOff,
218: int lowStep, Object highSig, int highOff, int highStep);
219:
220: /**
221: * Filters the input signal by this analysis filter, decomposing
222: * it in a low-pass and a high-pass signal. This method performs
223: * the filtering and the subsampling with the high pass first filtering
224: * convention.
225: *
226: * <P>The input signal resides in the inSig array. The index of
227: * the first sample to filter (i.e. that will generate the first
228: * high-pass output sample) is given by inOff. The number of
229: * samples to filter is given by inLen. This array must be of the
230: * same type as the one for which the particular implementation
231: * works with (which is returned by the getDataType() method).
232: *
233: * <P>The input signal can be interleaved with other signals in
234: * the same inSig array, and this is determined by the inStep
235: * argument. This means that the first sample of the input signal
236: * is inSig[inOff], the second is inSig[inOff+inStep], the third
237: * is inSig[inOff+2*inStep], and so on. Therefore if inStep is 1
238: * there is no interleaving. This feature allows to filter columns
239: * of a 2-D signal, when it is stored in a line by line order in
240: * inSig, without having to copy the data, in this case the inStep
241: * argument should be the line width.
242: *
243: * <P>The low-pass output signal is placed in the lowSig
244: * array. The lowOff and lowStep arguments are analogous to the
245: * inOff and inStep ones, but they apply to the lowSig array. The
246: * lowSig array must be long enough to hold the low-pass output
247: * signal.
248: *
249: * <P>The high-pass output signal is placed in the highSig
250: * array. The highOff and highStep arguments are analogous to the
251: * inOff and inStep ones, but they apply to the highSig array. The
252: * highSig array must be long enough to hold the high-pass output
253: * signal.
254: *
255: * @param inSig This is the array that contains the input
256: * signal. It must be of the correct type (e.g., it must be int[]
257: * if getDataType() returns TYPE_INT).
258: *
259: * @param inOff This is the index in inSig of the first sample to
260: * filter.
261: *
262: * @param inLen This is the number of samples in the input signal
263: * to filter.
264: *
265: * @param inStep This is the step, or interleave factor, of the
266: * input signal samples in the inSig array. See above.
267: *
268: * @param lowSig This is the array where the low-pass output
269: * signal is placed. It must be of the same type as inSig and it
270: * should be long enough to contain the output signal.
271: *
272: * @param lowOff This is the index in lowSig of the element where
273: * to put the first low-pass output sample.
274: *
275: * @param lowStep This is the step, or interleave factor, of the
276: * low-pass output samples in the lowSig array. See above.
277: *
278: * @param highSig This is the array where the high-pass output
279: * signal is placed. It must be of the same type as inSig and it
280: * should be long enough to contain the output signal.
281: *
282: * @param highOff This is the index in highSig of the element where
283: * to put the first high-pass output sample.
284: *
285: * @param highStep This is the step, or interleave factor, of the
286: * high-pass output samples in the highSig array. See above.
287: *
288: * @see WaveletFilter#getDataType
289: *
290: *
291: *
292: *
293: * */
294: public abstract void analyze_hpf(Object inSig, int inOff,
295: int inLen, int inStep, Object lowSig, int lowOff,
296: int lowStep, Object highSig, int highOff, int highStep);
297:
298: /**
299: * Returns the time-reversed low-pass synthesis waveform of the
300: * filter, which is the low-pass filter. This is the time-reversed
301: * impulse response of the low-pass synthesis filter. It is used
302: * to calculate the L2-norm of the synthesis basis functions for a
303: * particular subband (also called energy weight).
304: *
305: * <P>The returned array may not be modified (i.e. a reference to
306: * the internal array may be returned by the implementation of
307: * this method).
308: *
309: * @return The time-reversed low-pass synthesis waveform of the
310: * filter.
311: *
312: *
313: * */
314: public abstract float[] getLPSynthesisFilter();
315:
316: /**
317: * Returns the time-reversed high-pass synthesis waveform of the
318: * filter, which is the high-pass filter. This is the
319: * time-reversed impulse response of the high-pass synthesis
320: * filter. It is used to calculate the L2-norm of the synthesis
321: * basis functions for a particular subband (also called energy
322: * weight).
323: *
324: * <P>The returned array may not be modified (i.e. a reference to
325: * the internal array may be returned by the implementation of
326: * this method).
327: *
328: * @return The time-reversed high-pass synthesis waveform of the
329: * filter.
330: *
331: *
332: * */
333: public abstract float[] getHPSynthesisFilter();
334:
335: /**
336: * Returns the equivalent low-pass synthesis waveform of a cascade
337: * of filters, given the syhthesis waveform of the previous
338: * stage. This is the result of upsampling 'in' by 2, and
339: * concolving it with the low-pass synthesis waveform of the
340: * filter. The length of the returned signal is 2*in_l+lp_l-2,
341: * where in_l is the length of 'in' and 'lp_l' is the lengthg of
342: * the low-pass synthesis filter.
343: *
344: * <P>The length of the low-pass synthesis filter is
345: * getSynLowNegSupport()+getSynLowPosSupport().
346: *
347: * @param in The synthesis waveform of the previous stage.
348: *
349: * @param out If non-null this array is used to store the
350: * resulting signal. It must be long enough, or an
351: * IndexOutOfBoundsException is thrown.
352: *
353: * @see #getSynLowNegSupport
354: *
355: * @see #getSynLowPosSupport
356: *
357: *
358: * */
359: public float[] getLPSynWaveForm(float in[], float out[]) {
360: return upsampleAndConvolve(in, getLPSynthesisFilter(), out);
361: }
362:
363: /**
364: * Returns the equivalent high-pass synthesis waveform of a
365: * cascade of filters, given the syhthesis waveform of the
366: * previous stage. This is the result of upsampling 'in' by 2, and
367: * concolving it with the high-pass synthesis waveform of the
368: * filter. The length of the returned signal is 2*in_l+hp_l-2,
369: * where in_l is the length of 'in' and 'hp_l' is the lengthg of
370: * the high-pass synthesis filter.
371: *
372: * <P>The length of the high-pass synthesis filter is
373: * getSynHighNegSupport()+getSynHighPosSupport().
374: *
375: * @param in The synthesis waveform of the previous stage.
376: *
377: * @param out If non-null this array is used to store the
378: * resulting signal. It must be long enough, or an
379: * IndexOutOfBoundsException is thrown.
380: *
381: * @see #getSynHighNegSupport
382: *
383: * @see #getSynHighPosSupport
384: *
385: *
386: * */
387: public float[] getHPSynWaveForm(float in[], float out[]) {
388: return upsampleAndConvolve(in, getHPSynthesisFilter(), out);
389: }
390:
391: /**
392: * Returns the signal resulting of upsampling (by 2) the input
393: * signal 'in' and then convolving it with the time-reversed
394: * signal 'wf'. The returned signal is of length l_in*2+l_wf-2,
395: * where l_in is the length of 'in', and l_wf is the length of
396: * 'wf'.
397: *
398: * <P>The 'wf' signal has to be already time-reversed, therefore
399: * only a dot-product is performed (instead of a
400: * convolution). This is equivalent to convolving with the
401: * non-time-reversed 'wf' signal.
402: *
403: * @param in The signal to upsample and filter. If null it is
404: * considered to be a dirac.
405: *
406: * @param wf The time-reversed impulse response used for
407: * filtering.
408: *
409: * @param out If non-null this array is used to store the
410: * resulting signal, it must be of length in.length*2+wf.length-2
411: * at least. An IndexOutOfBoundsException is thrown if this is not
412: * the case.
413: *
414: * @return The resulting signal, of length in.length*2+wf.length-2
415: *
416: *
417: * */
418: private static float[] upsampleAndConvolve(float in[], float wf[],
419: float out[]) {
420: // NOTE: the effective length of the signal 'in' upsampled by
421: // 2 is 2*in.length-1 (not 2*in.length), so the resulting signal
422: // (after convolution) is of length 2*in.length-1+wf.length-1,
423: // which is 2*in.length+wf.length-2
424:
425: int i, k, j;
426: float tmp;
427: int maxi, maxk;
428:
429: // If in null, then simulate dirac
430: if (in == null) {
431: in = new float[1];
432: in[0] = 1.0f;
433: }
434:
435: // Get output buffer if necessary
436: if (out == null) {
437: out = new float[in.length * 2 + wf.length - 2];
438: }
439: // Convolve the signals
440: for (i = 0, maxi = in.length * 2 + wf.length - 2; i < maxi; i++) {
441: tmp = 0.0f;
442:
443: // Calculate limits of loop below
444: k = (i - wf.length + 2) / 2;
445: if (k < 0)
446: k = 0;
447: maxk = i / 2 + 1;
448: if (maxk > in.length)
449: maxk = in.length;
450:
451: // Calculate dot-product with upsampling of 'in' by 2.
452: for (j = 2 * k - i + wf.length - 1; k < maxk; k++, j += 2) {
453: tmp += in[k] * wf[j];
454: }
455: // Store result
456: out[i] = tmp;
457: }
458:
459: return out;
460: }
461:
462: /**
463: * Returns the type of filter used according to the FilterTypes
464: * interface.
465: *
466: * @see FilterTypes
467: *
468: * @return The filter type.
469: *
470: */
471: public abstract int getFilterType();
472:
473: /**
474: * Returns the parameters that are used in this class and
475: * implementing classes. It returns a 2D String array. Each of the
476: * 1D arrays is for a different option, and they have 3
477: * elements. The first element is the option name, the second one
478: * is the synopsis, the third one is a long description of what
479: * the parameter is and the fourth is its default value. The
480: * synopsis or description may be 'null', in which case it is
481: * assumed that there is no synopsis or description of the option,
482: * respectively. Null may be returned if no options are supported.
483: *
484: * @return the options name, their synopsis and their explanation,
485: * or null if no options are supported.
486: *
487: *
488: * */
489: public static String[][] getParameterInfo() {
490: return pinfo;
491: }
492:
493: }
|