corrade-vassal – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 vero 1 /*
2 * CVS identifier:
3 *
4 * $Id: AnWTFilter.java,v 1.15 2001/05/08 16:14:52 grosbois Exp $
5 *
6 * Class: AnWTFilter
7 *
8 * Description: The abstract class for all analysis wavelet filters
9 *
10 *
11 *
12 * COPYRIGHT:
13 *
14 * This software module was originally developed by Raphaël Grosbois and
15 * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
16 * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
17 * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
18 * Centre France S.A) in the course of development of the JPEG2000
19 * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
20 * software module is an implementation of a part of the JPEG 2000
21 * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
22 * Systems AB and Canon Research Centre France S.A (collectively JJ2000
23 * Partners) agree not to assert against ISO/IEC and users of the JPEG
24 * 2000 Standard (Users) any of their rights under the copyright, not
25 * including other intellectual property rights, for this software module
26 * with respect to the usage by ISO/IEC and Users of this software module
27 * or modifications thereof for use in hardware or software products
28 * claiming conformance to the JPEG 2000 Standard. Those intending to use
29 * this software module in hardware or software products are advised that
30 * their use may infringe existing patents. The original developers of
31 * this software module, JJ2000 Partners and ISO/IEC assume no liability
32 * for use of this software module or modifications thereof. No license
33 * or right to this software module is granted for non JPEG 2000 Standard
34 * conforming products. JJ2000 Partners have full right to use this
35 * software module for his/her own purpose, assign or donate this
36 * software module to any third party and to inhibit third parties from
37 * using this software module for non JPEG 2000 Standard conforming
38 * products. This copyright notice must be included in all copies or
39 * derivative works of this software module.
40 *
41 * Copyright (c) 1999/2000 JJ2000 Partners.
42 * */
43 using System;
44 using CSJ2K.j2k.codestream.writer;
45 using CSJ2K.j2k.wavelet;
46 using CSJ2K.j2k.image;
47 using CSJ2K.j2k.util;
48 namespace CSJ2K.j2k.wavelet.analysis
49 {
50  
51 /// <summary> <p>This abstract class defines the methods of all analysis wavelet
52 /// filters. Specialized abstract classes that work on particular data types
53 /// (int, float) provide more specific method calls while retaining the
54 /// generality of this one. See the AnWTFilterInt and AnWTFilterFloat
55 /// classes. Implementations of analysis filters should inherit from one of
56 /// those classes.</p>
57 ///
58 /// All analysis wavelet filters should follow the following conventions:
59 ///
60 /// <ul>
61 /// <li>The first sample to filter is the low-pass one. As a consequence, if
62 /// the input signal is of odd-length then the low-pass output signal is one
63 /// sample longer than the high-pass output one. Therefore, if the length of
64 /// input signal is N, the low-pass output signal is of length N/2 if N is even
65 /// and N/2+1/2 if N is odd, while the high-pass output signal is of length N/2
66 /// if N is even and N/2-1/2 if N is odd.</li>
67 ///
68 /// <li>The normalization is 1 for the DC gain and 2 for the Nyquist gain (Type
69 /// I normalization), for both reversible and non-reversible filters.</li>
70 ///
71 /// <li>If the length of input signal is N, the low-pass output signal is of
72 /// length N/2 if N is even and N/2+1/2 if N is odd, while the high-pass output
73 /// sample is of length N/2 if N is even and N/2-1/2 if N is odd.</li>
74 ///
75 /// <li>The analyze method may seem very complicated, but is designed to
76 /// minimize the amount of data copying and redundant calculations when used
77 /// for block-based or line-based wavelet transform implementations, while
78 /// being applicable to full-frame transforms as well.</li>
79 ///
80 /// <li>All filters should implement the equals() method of the Object
81 /// class. The call x.equals(y) should test if the 'x' and 'y' filters are the
82 /// same or not, in what concerns the bit stream header syntax (two filters are
83 /// the same if the same filter code should be output to the bit stream).</li>
84 /// </ul>
85 ///
86 /// </summary>
87 /// <seealso cref="AnWTFilterInt">
88 /// </seealso>
89 /// <seealso cref="AnWTFilterFloat">
90 ///
91 /// </seealso>
92 public abstract class AnWTFilter : WaveletFilter
93 {
94 /// <summary> Returns the type of filter used according to the FilterTypes interface.
95 ///
96 /// </summary>
97 /// <seealso cref="FilterTypes">
98 ///
99 /// </seealso>
100 /// <returns> The filter type.
101 ///
102 /// </returns>
103 public abstract int FilterType{get;}
104 /// <summary> Returns the parameters that are used in this class and implementing
105 /// classes. It returns a 2D String array. Each of the 1D arrays is for a
106 /// different option, and they have 3 elements. The first element is the
107 /// option name, the second one is the synopsis, the third one is a long
108 /// description of what the parameter is and the fourth is its default
109 /// value. The synopsis or description may be 'null', in which case it is
110 /// assumed that there is no synopsis or description of the option,
111 /// respectively. Null may be returned if no options are supported.
112 ///
113 /// </summary>
114 /// <returns> the options name, their synopsis and their explanation, or null
115 /// if no options are supported.
116 ///
117 /// </returns>
118 public static System.String[][] ParameterInfo
119 {
120 get
121 {
122 return pinfo;
123 }
124  
125 }
126 public abstract int AnHighPosSupport{get;}
127 public abstract int AnLowNegSupport{get;}
128 public abstract int AnLowPosSupport{get;}
129 public abstract bool Reversible{get;}
130 public abstract int ImplType{get;}
131 public abstract int SynHighNegSupport{get;}
132 public abstract int SynHighPosSupport{get;}
133 public abstract int AnHighNegSupport{get;}
134 public abstract int DataType{get;}
135 public abstract int SynLowNegSupport{get;}
136 public abstract int SynLowPosSupport{get;}
137  
138 /// <summary>The prefix for wavelet filter options: 'F' </summary>
139 public const char OPT_PREFIX = 'F';
140  
141 /// <summary>The list of parameters that is accepted for wavelet filters. Options
142 /// for wavelet filters start with a 'F'.
143 /// </summary>
144 //UPGRADE_NOTE: Final was removed from the declaration of 'pinfo'. "ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?index='!DefaultContextWindowIndex'&keyword='jlca1003'"
145 private static readonly System.String[][] pinfo = new System.String[][]{new System.String[]{"Ffilters", "[<tile-component idx>] <id> " + "[ [<tile-component idx>] <id> ...]", "Specifies which filters to use for specified tile-component. " + "If this option is not used, the encoder choses the filters " + " of the tile-components according to their quantization type." + " If this option is used, a component transformation is applied " + "to the three first components.\n" + "<tile-component idx>: see general note\n" + "<id>: ',' separates horizontal and vertical filters, ':' separates" + " decomposition levels filters. JPEG 2000 part 1 only supports w5x3" + " and w9x7 filters.", null}};
146  
147 /// <summary> Filters the input signal by this analysis filter, decomposing it in a
148 /// low-pass and a high-pass signal. This method performs the filtering and
149 /// the subsampling with the low pass first filtering convention.
150 ///
151 /// <p>The input signal resides in the inSig array. The index of the first
152 /// sample to filter (i.e. that will generate the first low-pass output
153 /// sample) is given by inOff. The number of samples to filter is given by
154 /// inLen. This array must be of the same type as the one for which the
155 /// particular implementation works with (which is returned by the
156 /// getDataType() method).</p>
157 ///
158 /// <p>The input signal can be interleaved with other signals in the same
159 /// inSig array, and this is determined by the inStep argument. This means
160 /// that the first sample of the input signal is inSig[inOff], the second
161 /// is inSig[inOff+inStep], the third is inSig[inOff+2*inStep], and so
162 /// on. Therefore if inStep is 1 there is no interleaving. This feature
163 /// allows to filter columns of a 2-D signal, when it is stored in a line
164 /// by line order in inSig, without having to copy the data, in this case
165 /// the inStep argument should be the line width.</p>
166 ///
167 /// <p>This method also allows to apply the analysis wavelet filter by
168 /// parts in the input signal using an overlap and thus producing the same
169 /// coefficients at the output. The tailOvrlp argument specifies how many
170 /// samples in the input signal, before the first one to be filtered, can
171 /// be used for overlap. Then, the filter instead of extending the input
172 /// signal will use those samples to calculate the first output
173 /// samples. The argument tailOvrlp can be 0 for no overlap, or some value
174 /// that provides partial or full overlap. There should be enough samples
175 /// in the input signal, before the first sample to be filtered, to support
176 /// the overlap. The headOvrlp provides the same functionality but at the
177 /// end of the input signal. The inStep argument also applies to samples
178 /// used for overlap. This overlap feature can be used for line-based
179 /// wavelet transforms (in which case it will only be used when filtering
180 /// the columns) or for overlapping block-based wavelet transforms (in
181 /// which case it will be used when filtering lines and columns).</p>
182 ///
183 /// <p>The low-pass output signal is placed in the lowSig array. The lowOff
184 /// and lowStep arguments are analogous to the inOff and inStep ones, but
185 /// they apply to the lowSig array. The lowSig array must be long enough to
186 /// hold the low-pass output signal.</p>
187 ///
188 /// <p>The high-pass output signal is placed in the highSig array. The
189 /// highOff and highStep arguments are analogous to the inOff and inStep
190 /// ones, but they apply to the highSig array. The highSig array must be
191 /// long enough to hold the high-pass output signal.</p>
192 ///
193 /// </summary>
194 /// <param name="inSig">This is the array that contains the input signal. It must
195 /// be of the correct type (e.g., it must be int[] if getDataType() returns
196 /// TYPE_INT).
197 ///
198 /// </param>
199 /// <param name="inOff">This is the index in inSig of the first sample to filter.
200 ///
201 /// </param>
202 /// <param name="inLen">This is the number of samples in the input signal to
203 /// filter.
204 ///
205 /// </param>
206 /// <param name="inStep">This is the step, or interleave factor, of the input
207 /// signal samples in the inSig array. See above.
208 ///
209 /// </param>
210 /// <param name="tailOvrlp">This is the number of samples in the input signal
211 /// before the first sample to filter that can be used for overlap. See
212 /// above.
213 ///
214 /// </param>
215 /// <param name="headOvrlp">This is the number of samples in the input signal
216 /// after the last sample to filter that can be used for overlap. See
217 /// above.
218 ///
219 /// </param>
220 /// <param name="lowSig">This is the array where the low-pass output signal is
221 /// placed. It must be of the same type as inSig and it should be long
222 /// enough to contain the output signal.
223 ///
224 /// </param>
225 /// <param name="lowOff">This is the index in lowSig of the element where to put
226 /// the first low-pass output sample.
227 ///
228 /// </param>
229 /// <param name="lowStep">This is the step, or interleave factor, of the low-pass
230 /// output samples in the lowSig array. See above.
231 ///
232 /// </param>
233 /// <param name="highSig">This is the array where the high-pass output signal is
234 /// placed. It must be of the same type as inSig and it should be long
235 /// enough to contain the output signal.
236 ///
237 /// </param>
238 /// <param name="highOff">This is the index in highSig of the element where to put
239 /// the first high-pass output sample.
240 ///
241 /// </param>
242 /// <param name="highStep">This is the step, or interleave factor, of the
243 /// high-pass output samples in the highSig array. See above.
244 ///
245 /// </param>
246 /// <seealso cref="WaveletFilter.getDataType">
247 ///
248 /// </seealso>
249 public abstract void analyze_lpf(System.Object inSig, int inOff, int inLen, int inStep, System.Object lowSig, int lowOff, int lowStep, System.Object highSig, int highOff, int highStep);
250  
251 /// <summary> Filters the input signal by this analysis filter, decomposing it in a
252 /// low-pass and a high-pass signal. This method performs the filtering and
253 /// the subsampling with the high pass first filtering convention.
254 ///
255 /// <p>The input signal resides in the inSig array. The index of the first
256 /// sample to filter (i.e. that will generate the first high-pass output
257 /// sample) is given by inOff. The number of samples to filter is given by
258 /// inLen. This array must be of the same type as the one for which the
259 /// particular implementation works with (which is returned by the
260 /// getDataType() method).</p>
261 ///
262 /// <p>The input signal can be interleaved with other signals in the same
263 /// inSig array, and this is determined by the inStep argument. This means
264 /// that the first sample of the input signal is inSig[inOff], the second
265 /// is inSig[inOff+inStep], the third is inSig[inOff+2*inStep], and so
266 /// on. Therefore if inStep is 1 there is no interleaving. This feature
267 /// allows to filter columns of a 2-D signal, when it is stored in a line
268 /// by line order in inSig, without having to copy the data, in this case
269 /// the inStep argument should be the line width.</p>
270 ///
271 /// <p>The low-pass output signal is placed in the lowSig array. The lowOff
272 /// and lowStep arguments are analogous to the inOff and inStep ones, but
273 /// they apply to the lowSig array. The lowSig array must be long enough to
274 /// hold the low-pass output signal.</p>
275 ///
276 /// <p>The high-pass output signal is placed in the highSig array. The
277 /// highOff and highStep arguments are analogous to the inOff and inStep
278 /// ones, but they apply to the highSig array. The highSig array must be
279 /// long enough to hold the high-pass output signal.</p>
280 ///
281 /// </summary>
282 /// <param name="inSig">This is the array that contains the input signal. It must
283 /// be of the correct type (e.g., it must be int[] if getDataType() returns
284 /// TYPE_INT).
285 ///
286 /// </param>
287 /// <param name="inOff">This is the index in inSig of the first sample to filter.
288 ///
289 /// </param>
290 /// <param name="inLen">This is the number of samples in the input signal to
291 /// filter.
292 ///
293 /// </param>
294 /// <param name="inStep">This is the step, or interleave factor, of the input
295 /// signal samples in the inSig array. See above.
296 ///
297 /// </param>
298 /// <param name="lowSig">This is the array where the low-pass output signal is
299 /// placed. It must be of the same type as inSig and it should be long
300 /// enough to contain the output signal.
301 ///
302 /// </param>
303 /// <param name="lowOff">This is the index in lowSig of the element where to put
304 /// the first low-pass output sample.
305 ///
306 /// </param>
307 /// <param name="lowStep">This is the step, or interleave factor, of the low-pass
308 /// output samples in the lowSig array. See above.
309 ///
310 /// </param>
311 /// <param name="highSig">This is the array where the high-pass output signal is
312 /// placed. It must be of the same type as inSig and it should be long
313 /// enough to contain the output signal.
314 ///
315 /// </param>
316 /// <param name="highOff">This is the index in highSig of the element where to put
317 /// the first high-pass output sample.
318 ///
319 /// </param>
320 /// <param name="highStep">This is the step, or interleave factor, of the
321 /// high-pass output samples in the highSig array. See above.
322 ///
323 /// </param>
324 /// <seealso cref="WaveletFilter.getDataType">
325 ///
326 /// </seealso>
327 public abstract void analyze_hpf(System.Object inSig, int inOff, int inLen, int inStep, System.Object lowSig, int lowOff, int lowStep, System.Object highSig, int highOff, int highStep);
328  
329 /// <summary> Returns the time-reversed low-pass synthesis waveform of the filter,
330 /// which is the low-pass filter. This is the time-reversed impulse
331 /// response of the low-pass synthesis filter. It is used to calculate the
332 /// L2-norm of the synthesis basis functions for a particular subband (also
333 /// called energy weight).
334 ///
335 /// <p>The returned array may not be modified (i.e. a reference to the
336 /// internal array may be returned by the implementation of this
337 /// method).</p>
338 ///
339 /// </summary>
340 /// <returns> The time-reversed low-pass synthesis waveform of the filter.
341 ///
342 /// </returns>
343 public abstract float[] getLPSynthesisFilter();
344  
345 /// <summary> Returns the time-reversed high-pass synthesis waveform of the filter,
346 /// which is the high-pass filter. This is the time-reversed impulse
347 /// response of the high-pass synthesis filter. It is used to calculate the
348 /// L2-norm of the synthesis basis functions for a particular subband (also
349 /// called energy weight).
350 ///
351 /// <p>The returned array may not be modified (i.e. a reference to the
352 /// internal array may be returned by the implementation of this
353 /// method).</p>
354 ///
355 /// </summary>
356 /// <returns> The time-reversed high-pass synthesis waveform of the filter.
357 ///
358 /// </returns>
359 public abstract float[] getHPSynthesisFilter();
360  
361 /// <summary> Returns the equivalent low-pass synthesis waveform of a cascade of
362 /// filters, given the syhthesis waveform of the previous stage. This is
363 /// the result of upsampling 'in' by 2, and concolving it with the low-pass
364 /// synthesis waveform of the filter. The length of the returned signal is
365 /// 2*in_l+lp_l-2, where in_l is the length of 'in' and 'lp_l' is the
366 /// lengthg of the low-pass synthesis filter.
367 ///
368 /// <p>The length of the low-pass synthesis filter is
369 /// getSynLowNegSupport()+getSynLowPosSupport().</p>
370 ///
371 /// </summary>
372 /// <param name="in">The synthesis waveform of the previous stage.
373 ///
374 /// </param>
375 /// <param name="out">If non-null this array is used to store the resulting
376 /// signal. It must be long enough, or an IndexOutOfBoundsException is
377 /// thrown.
378 ///
379 /// </param>
380 /// <seealso cref="getSynLowNegSupport">
381 /// </seealso>
382 /// <seealso cref="getSynLowPosSupport">
383 ///
384 /// </seealso>
385 public virtual float[] getLPSynWaveForm(float[] in_Renamed, float[] out_Renamed)
386 {
387 return upsampleAndConvolve(in_Renamed, getLPSynthesisFilter(), out_Renamed);
388 }
389  
390 /// <summary> Returns the equivalent high-pass synthesis waveform of a cascade of
391 /// filters, given the syhthesis waveform of the previous stage. This is
392 /// the result of upsampling 'in' by 2, and concolving it with the
393 /// high-pass synthesis waveform of the filter. The length of the returned
394 /// signal is 2*in_l+hp_l-2, where in_l is the length of 'in' and 'hp_l' is
395 /// the lengthg of the high-pass synthesis filter.
396 ///
397 /// <p>The length of the high-pass synthesis filter is
398 /// getSynHighNegSupport()+getSynHighPosSupport().</p>
399 ///
400 /// </summary>
401 /// <param name="in">The synthesis waveform of the previous stage.
402 ///
403 /// </param>
404 /// <param name="out">If non-null this array is used to store the resulting
405 /// signal. It must be long enough, or an IndexOutOfBoundsException is
406 /// thrown.
407 ///
408 /// </param>
409 /// <seealso cref="getSynHighNegSupport">
410 /// </seealso>
411 /// <seealso cref="getSynHighPosSupport">
412 ///
413 /// </seealso>
414 public virtual float[] getHPSynWaveForm(float[] in_Renamed, float[] out_Renamed)
415 {
416 return upsampleAndConvolve(in_Renamed, getHPSynthesisFilter(), out_Renamed);
417 }
418  
419 /// <summary> Returns the signal resulting of upsampling (by 2) the input signal 'in'
420 /// and then convolving it with the time-reversed signal 'wf'. The returned
421 /// signal is of length l_in*2+l_wf-2, where l_in is the length of 'in',
422 /// and l_wf is the length of 'wf'.
423 ///
424 /// <p>The 'wf' signal has to be already time-reversed, therefore only a
425 /// dot-product is performed (instead of a convolution). This is equivalent
426 /// to convolving with the non-time-reversed 'wf' signal.</p>
427 ///
428 /// </summary>
429 /// <param name="in">The signal to upsample and filter. If null it is considered
430 /// to be a dirac.
431 ///
432 /// </param>
433 /// <param name="wf">The time-reversed impulse response used for filtering.
434 ///
435 /// </param>
436 /// <param name="out">If non-null this array is used to store the resulting
437 /// signal, it must be of length in.length*2+wf.length-2 at least. An
438 /// IndexOutOfBoundsException is thrown if this is not the case.
439 ///
440 /// </param>
441 /// <returns> The resulting signal, of length in.length*2+wf.length-2
442 ///
443 /// </returns>
444 private static float[] upsampleAndConvolve(float[] in_Renamed, float[] wf, float[] out_Renamed)
445 {
446 // NOTE: the effective length of the signal 'in' upsampled by
447 // 2 is 2*in.length-1 (not 2*in.length), so the resulting signal
448 // (after convolution) is of length 2*in.length-1+wf.length-1,
449 // which is 2*in.length+wf.length-2
450  
451 int i, k, j;
452 float tmp;
453 int maxi, maxk;
454  
455 // If in null, then simulate dirac
456 if (in_Renamed == null)
457 {
458 in_Renamed = new float[1];
459 in_Renamed[0] = 1.0f;
460 }
461  
462 // Get output buffer if necessary
463 if (out_Renamed == null)
464 {
465 out_Renamed = new float[in_Renamed.Length * 2 + wf.Length - 2];
466 }
467 // Convolve the signals
468 for (i = 0, maxi = in_Renamed.Length * 2 + wf.Length - 2; i < maxi; i++)
469 {
470 tmp = 0.0f;
471  
472 // Calculate limits of loop below
473 k = (i - wf.Length + 2) / 2;
474 if (k < 0)
475 k = 0;
476 maxk = i / 2 + 1;
477 if (maxk > in_Renamed.Length)
478 maxk = in_Renamed.Length;
479  
480 // Calculate dot-product with upsampling of 'in' by 2.
481 for (j = 2 * k - i + wf.Length - 1; k < maxk; k++, j += 2)
482 {
483 tmp += in_Renamed[k] * wf[j];
484 }
485 // Store result
486 out_Renamed[i] = tmp;
487 }
488  
489 return out_Renamed;
490 }
491 public abstract bool isSameAsFullWT(int param1, int param2, int param3);
492 }
493 }