001: /*
002: * $RCSfile: Quantizer.java,v $
003: * $Revision: 1.1 $
004: * $Date: 2005/02/11 05:02:20 $
005: * $State: Exp $
006: *
007: * Class: Quantizer
008: *
009: * Description: An abstract class for quantizers
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: package jj2000.j2k.quantization.quantizer;
045:
046: import jj2000.j2k.codestream.writer.*;
047: import jj2000.j2k.wavelet.analysis.*;
048: import jj2000.j2k.quantization.*;
049: import jj2000.j2k.wavelet.*; //import jj2000.j2k.encoder.*;
050: import jj2000.j2k.image.*;
051: import jj2000.j2k.util.*;
052:
053: import com.sun.media.imageioimpl.plugins.jpeg2000.J2KImageWriteParamJava;
054:
055: /**
056: * This abstract class provides the general interface for quantizers. The
057: * input of a quantizer is the output of a wavelet transform. The output of
058: * the quantizer is the set of quantized wavelet coefficients represented in
059: * sign-magnitude notation (see below).
060: *
061: * <p>This class provides default implementation for most of the methods
062: * (wherever it makes sense), under the assumption that the image, component
063: * dimensions, and the tiles, are not modifed by the quantizer. If it is not
064: * the case for a particular implementation, then the methods should be
065: * overriden.</p>
066: *
067: * <p>Sign magnitude representation is used (instead of two's complement) for
068: * the output data. The most significant bit is used for the sign (0 if
069: * positive, 1 if negative). Then the magnitude of the quantized coefficient
070: * is stored in the next M most significat bits. The rest of the bits (least
071: * significant bits) can contain a fractional value of the quantized
072: * coefficient. This fractional value is not to be coded by the entropy
073: * coder. However, it can be used to compute rate-distortion measures with
074: * greater precision.</p>
075: *
076: * <p>The value of M is determined for each subband as the sum of the number
077: * of guard bits G and the nominal range of quantized wavelet coefficients in
078: * the corresponding subband (Rq), minus 1:</p>
079: *
080: * <p>M = G + Rq -1</p>
081: *
082: * <p>The value of G should be the same for all subbands. The value of Rq
083: * depends on the quantization step size, the nominal range of the component
084: * before the wavelet transform and the analysis gain of the subband (see
085: * Subband).</p>
086: *
087: * <p>The blocks of data that are requested should not cross subband
088: * boundaries.</p>
089: *
090: * <p>NOTE: At the moment only quantizers that implement the
091: * 'CBlkQuantDataSrcEnc' interface are supported.</p>
092: *
093: * @see Subband
094: * */
095: public abstract class Quantizer extends ImgDataAdapter implements
096: CBlkQuantDataSrcEnc {
097:
098: /** The prefix for quantizer options: 'Q' */
099: public final static char OPT_PREFIX = 'Q';
100:
101: /** The list of parameters that is accepted for quantization. Options
102: * for quantization start with 'Q'. */
103: private final static String[][] pinfo = {
104: {
105: "Qtype",
106: "[<tile-component idx>] <id> "
107: + "[ [<tile-component idx>] <id> ...]",
108: "Specifies which quantization type to use for specified "
109: + "tile-component. The default type is either 'reversible' or "
110: + "'expounded' depending on whether or not the '-lossless' option "
111: + " is specified.\n"
112: + "<tile-component idx> : see general note.\n"
113: + "<id>: Supported quantization types specification are : "
114: + "'reversible' "
115: + "(no quantization), 'derived' (derived quantization step size) and "
116: + "'expounded'.\n"
117: + "Example: -Qtype reversible or -Qtype t2,4-8 c2 reversible t9 "
118: + "derived.", null },
119: {
120: "Qstep",
121: "[<tile-component idx>] <bnss> "
122: + "[ [<tile-component idx>] <bnss> ...]",
123: "This option specifies the base normalized quantization step "
124: + "size (bnss) for tile-components. It is normalized to a "
125: + "dynamic range of 1 in the image domain. This parameter is "
126: + "ignored in reversible coding. The default value is '1/128'"
127: + " (i.e. 0.0078125).", "0.0078125" },
128: {
129: "Qguard_bits",
130: "[<tile-component idx>] <gb> "
131: + "[ [<tile-component idx>] <gb> ...]",
132: "The number of bits used for each tile-component in the quantizer"
133: + " to avoid overflow (gb).", "2" }, };
134:
135: /** The source of wavelet transform coefficients */
136: protected CBlkWTDataSrc src;
137:
138: /**
139: * Initializes the source of wavelet transform coefficients.
140: *
141: * @param src The source of wavelet transform coefficients.
142: * */
143: public Quantizer(CBlkWTDataSrc src) {
144: super (src);
145: this .src = src;
146: }
147:
148: /**
149: * Returns the number of guard bits used by this quantizer in the
150: * given tile-component.
151: *
152: * @param t Tile index
153: *
154: * @param c Component index
155: *
156: * @return The number of guard bits
157: * */
158: public abstract int getNumGuardBits(int t, int c);
159:
160: /**
161: * Returns true if the quantizer of given tile-component uses derived
162: * quantization step sizes.
163: *
164: * @param t Tile index
165: *
166: * @param c Component index
167: *
168: * @return True if derived quantization is used.
169: * */
170: public abstract boolean isDerived(int t, int c);
171:
172: /**
173: * Calculates the parameters of the SubbandAn objects that depend on the
174: * Quantizer. The 'stepWMSE' field is calculated for each subband which is
175: * a leaf in the tree rooted at 'sb', for the specified component. The
176: * subband tree 'sb' must be the one for the component 'n'.
177: *
178: * @param sb The root of the subband tree.
179: *
180: * @param n The component index.
181: *
182: * @see SubbandAn#stepWMSE
183: * */
184: protected abstract void calcSbParams(SubbandAn sb, int n);
185:
186: /**
187: * Returns a reference to the subband tree structure representing the
188: * subband decomposition for the specified tile-component.
189: *
190: * <P>This method gets the subband tree from the source and then
191: * calculates the magnitude bits for each leaf using the method
192: * calcSbParams().
193: *
194: * @param t The index of the tile.
195: *
196: * @param c The index of the component.
197: *
198: * @return The subband tree structure, see SubbandAn.
199: *
200: * @see SubbandAn
201: *
202: * @see Subband
203: *
204: * @see #calcSbParams
205: * */
206: public SubbandAn getAnSubbandTree(int t, int c) {
207: SubbandAn sbba;
208:
209: // Ask for the wavelet tree of the source
210: sbba = src.getAnSubbandTree(t, c);
211: // Calculate the stepWMSE
212: calcSbParams(sbba, c);
213: return sbba;
214: }
215:
216: /**
217: * Returns the horizontal offset of the code-block partition. Allowable
218: * values are 0 and 1, nothing else.
219: * */
220: public int getCbULX() {
221: return src.getCbULX();
222: }
223:
224: /**
225: * Returns the vertical offset of the code-block partition. Allowable
226: * values are 0 and 1, nothing else.
227: * */
228: public int getCbULY() {
229: return src.getCbULY();
230: }
231:
232: /**
233: * Returns the parameters that are used in this class and implementing
234: * classes. It returns a 2D String array. Each of the 1D arrays is for a
235: * different option, and they have 3 elements. The first element is the
236: * option name, the second one is the synopsis, the third one is a long
237: * description of what the parameter is and the fourth is its default
238: * value. The synopsis or description may be 'null', in which case it is
239: * assumed that there is no synopsis or description of the option,
240: * respectively. Null may be returned if no options are supported.
241: *
242: * @return the options name, their synopsis and their explanation,
243: * or null if no options are supported.
244: * */
245: public static String[][] getParameterInfo() {
246: return pinfo;
247: }
248:
249: /**
250: * Creates a Quantizer object for the appropriate type of quantization
251: * specified in the options in the parameter list 'pl', and having 'src'
252: * as the source of data to be quantized. The 'rev' flag indicates if the
253: * quantization should be reversible.
254: *
255: * NOTE: At the moment only sources of wavelet data that implement the
256: * 'CBlkWTDataSrc' interface are supported.
257: *
258: * @param src The source of data to be quantized
259: *
260: * @param encSpec Encoder specifications
261: *
262: * @exception IllegalArgumentException If an error occurs while parsing
263: * the options in 'pl'
264: * */
265: public static Quantizer createInstance(CBlkWTDataSrc src,
266: J2KImageWriteParamJava wp) {
267: // Instantiate quantizer
268: return new StdQuantizer(src, wp);
269: }
270:
271: /**
272: * Returns the maximum number of magnitude bits in any subband in the
273: * current tile.
274: *
275: * @param c the component number
276: *
277: * @return The maximum number of magnitude bits in all subbands of the
278: * current tile.
279: * */
280: public abstract int getMaxMagBits(int c);
281:
282: }
|