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