001: /*
002: * $RCSfile: EntropyCoder.java,v $
003: * $Revision: 1.1 $
004: * $Date: 2005/02/11 05:02:08 $
005: * $State: Exp $
006: *
007: * Class: EntropyCoder
008: *
009: * Description: The abstract class for entropy encoders
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.entropy.encoder;
045:
046: import jj2000.j2k.quantization.quantizer.*;
047: import jj2000.j2k.codestream.writer.*;
048: import jj2000.j2k.wavelet.analysis.*;
049: import jj2000.j2k.wavelet.*;
050: import jj2000.j2k.entropy.*;
051: import jj2000.j2k.image.*;
052: import jj2000.j2k.util.*;
053: import jj2000.j2k.roi.*;
054: import jj2000.j2k.*;
055:
056: import java.util.*;
057: import java.io.*;
058:
059: import com.sun.media.imageioimpl.plugins.jpeg2000.J2KImageWriteParamJava;
060:
061: /**
062: * This abstract class provides the general interface for block-based entropy
063: * encoders. The input to the entropy coder is the quantized wavelet
064: * coefficients, or codewords, represented in sign magnitude. The output is a
065: * compressed code-block with rate-distortion information.
066: *
067: * <P>The source of data for objects of this class are 'CBlkQuantDataSrcEnc'
068: * objects.
069: *
070: * <P>For more details on the sign magnitude representation used see the
071: * Quantizer class.
072: *
073: * <P>This class provides default implemenations for most of the methods
074: * (wherever it makes sense), under the assumption that the image and
075: * component dimensions, and the tiles, are not modifed by the entropy
076: * coder. If that is not the case for a particular implementation then the
077: * methods should be overriden.
078: *
079: * @see Quantizer
080: * @see CBlkQuantDataSrcEnc
081: * */
082: public abstract class EntropyCoder extends ImgDataAdapter implements
083: CodedCBlkDataSrcEnc, StdEntropyCoderOptions {
084:
085: /** The prefix for entropy coder options: 'C' */
086: public final static char OPT_PREFIX = 'C';
087:
088: /** The list of parameters that is accepted for entropy coding. Options
089: * for entropy coding start with 'C'. */
090: private final static String[][] pinfo = {
091: {
092: "Cblksiz",
093: "[<tile-component idx>] <width> <height> "
094: + "[[<tile-component idx>] <width> <height>]",
095: "Specifies the maximum code-block size to use for tile-component. "
096: + "The maximum width and height is 1024, however the surface area "
097: + "(i.e. width x height) must not exceed 4096. The minimum width and "
098: + "height is 4.", "64 64" },
099: {
100: "Cbypass",
101: "[<tile-component idx>] true|false"
102: + "[ [<tile-component idx>] true|false ...]",
103: "Uses the lazy coding mode with the entropy coder. This will bypass "
104: + "the MQ coder for some of the coding passes, where the distribution "
105: + "is often close to uniform. Since the MQ codeword will be "
106: + "terminated "
107: + "at least once per lazy pass, it is important to use an efficient "
108: + "termination algorithm, see the 'Cterm' option."
109: + "'true' enables, 'false' disables it.",
110: "false" },
111: {
112: "CresetMQ",
113: "[<tile-component idx>] true|false"
114: + "[ [<tile-component idx>] true|false ...]",
115: "If this is enabled the probability estimates of the MQ coder are "
116: + "reset after each arithmetically coded (i.e. non-lazy) coding pass. "
117: + "'true' enables, 'false' disables it.",
118: "false" },
119: {
120: "Creg_term",
121: "[<tile-component idx>] true|false"
122: + "[ [<tile-component idx>] true|false ...]",
123: "If this is enabled the codeword (raw or MQ) is terminated on a "
124: + "byte boundary after each coding pass. In this case it is important "
125: + "to use an efficient termination algorithm, see the 'Cterm' option. "
126: + "'true' enables, 'false' disables it.",
127: "false" },
128: {
129: "Ccausal",
130: "[<tile-component idx>] true|false"
131: + "[ [<tile-component idx>] true|false ...]",
132: "Uses vertically stripe causal context formation. If this is "
133: + "enabled "
134: + "the context formation process in one stripe is independant of the "
135: + "next stripe (i.e. the one below it). 'true' "
136: + "enables, 'false' disables it.", "false" },
137: {
138: "Cseg_symbol",
139: "[<tile-component idx>] true|false"
140: + "[ [<tile-component idx>] true|false ...]",
141: "Inserts an error resilience segmentation symbol in the MQ "
142: + "codeword at the end of "
143: + "each bit-plane (cleanup pass). Decoders can use this "
144: + "information to detect and "
145: + "conceal errors.'true' enables, 'false' disables "
146: + "it.", "false" },
147: {
148: "Cterm",
149: "[<tile-component idx>] near_opt|easy|predict|full"
150: + "[ [<tile-component idx>] near_opt|easy|predict|full ...]",
151: "Specifies the algorithm used to terminate the MQ codeword. "
152: + "The most efficient one is 'near_opt', which delivers a codeword "
153: + "which in almost all cases is the shortest possible. The 'easy' is "
154: + "a simpler algorithm that delivers a codeword length that is close "
155: + "to the previous one (in average 1 bit longer). The 'predict' is"
156: + " almost "
157: + "the same as the 'easy' but it leaves error resilient information "
158: + "on "
159: + "the spare least significant bits (in average 3.5 bits), which can "
160: + "be used by a decoder to detect errors. The 'full' algorithm "
161: + "performs a full flush of the MQ coder and is highly inefficient.\n"
162: + "It is important to use a good termination policy since the MQ "
163: + "codeword can be terminated quite often, specially if the 'Cbypass'"
164: + " or "
165: + "'Creg_term' options are enabled (in the normal case it would be "
166: + "terminated once per code-block, while if 'Creg_term' is specified "
167: + "it will be done almost 3 times per bit-plane in each code-block).",
168: "near_opt" },
169: {
170: "Clen_calc",
171: "[<tile-component idx>] near_opt|lazy_good|lazy"
172: + "[ [<tile-component idx>] ...]",
173: "Specifies the algorithm to use in calculating the necessary MQ "
174: + "length for each decoding pass. The best one is 'near_opt', which "
175: + "performs a rather sophisticated calculation and provides the best "
176: + "results. The 'lazy_good' and 'lazy' are very simple algorithms "
177: + "that "
178: + "provide rather conservative results, 'lazy_good' one being "
179: + "slightly "
180: + "better. Do not change this option unless you want to experiment "
181: + "the effect of different length calculation algorithms.",
182: "near_opt" },
183: {
184: "Cpp",
185: "[<tile-component idx>] <dim> <dim> [<dim> <dim>] "
186: + "[ [<tile-component idx>] ...]",
187: "Specifies precinct partition dimensions for tile-component. The "
188: + "first "
189: + "two values apply to the highest resolution and the following ones "
190: + "(if "
191: + "any) apply to the remaining resolutions in decreasing order. If "
192: + "less "
193: + "values than the number of decomposition levels are specified, "
194: + "then the "
195: + "last two values are used for the remaining resolutions.",
196: null }, };
197:
198: /** The source of quantized wavelet coefficients */
199: protected CBlkQuantDataSrcEnc src;
200:
201: /**
202: * Initializes the source of quantized wavelet coefficients.
203: *
204: * @param src The source of quantized wavelet coefficients.
205: * */
206: public EntropyCoder(CBlkQuantDataSrcEnc src) {
207: super (src);
208: this .src = src;
209: }
210:
211: /**
212: * Returns the code-block width for the specified tile and component.
213: *
214: * @param t The tile index
215: *
216: * @param c the component index
217: *
218: * @return The code-block width for the specified tile and component
219: * */
220: public abstract int getCBlkWidth(int t, int c);
221:
222: /**
223: * Returns the code-block height for the specified tile and component.
224: *
225: * @param t The tile index
226: *
227: * @param c the component index
228: *
229: * @return The code-block height for the specified tile and component
230: * */
231: public abstract int getCBlkHeight(int t, int c);
232:
233: /**
234: * Returns the reversibility of the tile-component data that is provided
235: * by the object. Data is reversible when it is suitable for lossless and
236: * lossy-to-lossless compression.
237: *
238: * <P>Since entropy coders themselves are always reversible, it returns
239: * the reversibility of the data that comes from the 'CBlkQuantDataSrcEnc'
240: * source object (i.e. ROIScaler).
241: *
242: * @param t Tile index
243: *
244: * @param c Component index
245: *
246: * @return true is the data is reversible, false if not.
247: *
248: * @see jj2000.j2k.roi.encoder.ROIScaler
249: * */
250: public boolean isReversible(int t, int c) {
251: return src.isReversible(t, c);
252: }
253:
254: /**
255: * Returns a reference to the root of subband tree structure representing
256: * the subband decomposition for the specified tile-component.
257: *
258: * @param t The index of the tile.
259: *
260: * @param c The index of the component.
261: *
262: * @return The root of the subband tree structure, see Subband.
263: *
264: * @see SubbandAn
265: *
266: * @see Subband
267: * */
268: public SubbandAn getAnSubbandTree(int t, int c) {
269: return src.getAnSubbandTree(t, c);
270: }
271:
272: /**
273: * Returns the horizontal offset of the code-block partition. Allowable
274: * values are 0 and 1, nothing else.
275: * */
276: public int getCbULX() {
277: return src.getCbULX();
278: }
279:
280: /**
281: * Returns the vertical offset of the code-block partition. Allowable
282: * values are 0 and 1, nothing else.
283: * */
284: public int getCbULY() {
285: return src.getCbULY();
286: }
287:
288: /**
289: * Returns the parameters that are used in this class and
290: * implementing classes. It returns a 2D String array. Each of the
291: * 1D arrays is for a different option, and they have 3
292: * elements. The first element is the option name, the second one
293: * is the synopsis, the third one is a long description of what
294: * the parameter is and the fourth is its default value. The
295: * synopsis or description may be 'null', in which case it is
296: * assumed that there is no synopsis or description of the option,
297: * respectively. Null may be returned if no options are supported.
298: *
299: * @return the options name, their synopsis and their explanation,
300: * or null if no options are supported.
301: * */
302: public static String[][] getParameterInfo() {
303: return pinfo;
304: }
305:
306: /**
307: * Creates a EntropyCoder object for the appropriate entropy coding
308: * parameters in the parameter list 'pl', and having 'src' as the source
309: * of quantized data.
310: *
311: * @param src The source of data to be entropy coded
312: *
313: * @param wp The parameter list (or options).
314: *
315: * @param cbks Code-block size specifications
316: *
317: * @param pss Precinct partition specifications
318: *
319: * @param bms By-pass mode specifications
320: *
321: * @param mqrs MQ-reset specifications
322: *
323: * @param rts Regular termination specifications
324: *
325: * @param css Causal stripes specifications
326: *
327: * @param sss Error resolution segment symbol use specifications
328: *
329: * @param lcs Length computation specifications
330: *
331: * @param tts Termination type specifications
332: *
333: * @exception IllegalArgumentException If an error occurs while parsing
334: * the options in 'pl'
335: * */
336: public static EntropyCoder createInstance(CBlkQuantDataSrcEnc src,
337: J2KImageWriteParamJava wp, CBlkSizeSpec cblks,
338: PrecinctSizeSpec pss, StringSpec bms, StringSpec mqrs,
339: StringSpec rts, StringSpec css, StringSpec sss,
340: StringSpec lcs, StringSpec tts) {
341: // Check parameters
342: //pl.checkList(OPT_PREFIX,pl.toNameArray(pinfo));
343: return new StdEntropyCoder(src, cblks, pss, bms, mqrs, rts,
344: css, sss, lcs, tts);
345: }
346: }
|