blob: 54170b227df0b22d3c011ec16b72826464200a5f [file] [log] [blame]
Dees_Troy51a0e822012-09-05 15:24:24 -04001Advanced usage instructions for the Independent JPEG Group's JPEG software
2==========================================================================
3
4This file describes cjpeg's "switches for wizards".
5
6The "wizard" switches are intended for experimentation with JPEG by persons
7who are reasonably knowledgeable about the JPEG standard. If you don't know
8what you are doing, DON'T USE THESE SWITCHES. You'll likely produce files
9with worse image quality and/or poorer compression than you'd get from the
10default settings. Furthermore, these switches must be used with caution
11when making files intended for general use, because not all JPEG decoders
12will support unusual JPEG parameter settings.
13
14
15Quantization Table Adjustment
16-----------------------------
17
18Ordinarily, cjpeg starts with a default set of tables (the same ones given
19as examples in the JPEG standard) and scales them up or down according to
20the -quality setting. The details of the scaling algorithm can be found in
21jcparam.c. At very low quality settings, some quantization table entries
22can get scaled up to values exceeding 255. Although 2-byte quantization
23values are supported by the IJG software, this feature is not in baseline
24JPEG and is not supported by all implementations. If you need to ensure
25wide compatibility of low-quality files, you can constrain the scaled
26quantization values to no more than 255 by giving the -baseline switch.
27Note that use of -baseline will result in poorer quality for the same file
28size, since more bits than necessary are expended on higher AC coefficients.
29
30You can substitute a different set of quantization values by using the
31-qtables switch:
32
33 -qtables file Use the quantization tables given in the named file.
34
35The specified file should be a text file containing decimal quantization
36values. The file should contain one to four tables, each of 64 elements.
37The tables are implicitly numbered 0,1,etc. in order of appearance. Table
38entries appear in normal array order (NOT in the zigzag order in which they
39will be stored in the JPEG file).
40
41Quantization table files are free format, in that arbitrary whitespace can
42appear between numbers. Also, comments can be included: a comment starts
43with '#' and extends to the end of the line. Here is an example file that
44duplicates the default quantization tables:
45
46 # Quantization tables given in JPEG spec, section K.1
47
48 # This is table 0 (the luminance table):
49 16 11 10 16 24 40 51 61
50 12 12 14 19 26 58 60 55
51 14 13 16 24 40 57 69 56
52 14 17 22 29 51 87 80 62
53 18 22 37 56 68 109 103 77
54 24 35 55 64 81 104 113 92
55 49 64 78 87 103 121 120 101
56 72 92 95 98 112 100 103 99
57
58 # This is table 1 (the chrominance table):
59 17 18 24 47 99 99 99 99
60 18 21 26 66 99 99 99 99
61 24 26 56 99 99 99 99 99
62 47 66 99 99 99 99 99 99
63 99 99 99 99 99 99 99 99
64 99 99 99 99 99 99 99 99
65 99 99 99 99 99 99 99 99
66 99 99 99 99 99 99 99 99
67
68If the -qtables switch is used without -quality, then the specified tables
69are used exactly as-is. If both -qtables and -quality are used, then the
70tables taken from the file are scaled in the same fashion that the default
71tables would be scaled for that quality setting. If -baseline appears, then
72the quantization values are constrained to the range 1-255.
73
74By default, cjpeg will use quantization table 0 for luminance components and
75table 1 for chrominance components. To override this choice, use the -qslots
76switch:
77
78 -qslots N[,...] Select which quantization table to use for
79 each color component.
80
81The -qslots switch specifies a quantization table number for each color
82component, in the order in which the components appear in the JPEG SOF marker.
83For example, to create a separate table for each of Y,Cb,Cr, you could
84provide a -qtables file that defines three quantization tables and say
85"-qslots 0,1,2". If -qslots gives fewer table numbers than there are color
86components, then the last table number is repeated as necessary.
87
88
89Sampling Factor Adjustment
90--------------------------
91
92By default, cjpeg uses 2:1 horizontal and vertical downsampling when
93compressing YCbCr data, and no downsampling for all other color spaces.
94You can override this default with the -sample switch:
95
96 -sample HxV[,...] Set JPEG sampling factors for each color
97 component.
98
99The -sample switch specifies the JPEG sampling factors for each color
100component, in the order in which they appear in the JPEG SOF marker.
101If you specify fewer HxV pairs than there are components, the remaining
102components are set to 1x1 sampling. For example, the default YCbCr setting
103is equivalent to "-sample 2x2,1x1,1x1", which can be abbreviated to
104"-sample 2x2".
105
106There are still some JPEG decoders in existence that support only 2x1
107sampling (also called 4:2:2 sampling). Compatibility with such decoders can
108be achieved by specifying "-sample 2x1". This is not recommended unless
109really necessary, since it increases file size and encoding/decoding time
110with very little quality gain.
111
112
113Multiple Scan / Progression Control
114-----------------------------------
115
116By default, cjpeg emits a single-scan sequential JPEG file. The
117-progressive switch generates a progressive JPEG file using a default series
118of progression parameters. You can create multiple-scan sequential JPEG
119files or progressive JPEG files with custom progression parameters by using
120the -scans switch:
121
122 -scans file Use the scan sequence given in the named file.
123
124The specified file should be a text file containing a "scan script".
125The script specifies the contents and ordering of the scans to be emitted.
126Each entry in the script defines one scan. A scan definition specifies
127the components to be included in the scan, and for progressive JPEG it also
128specifies the progression parameters Ss,Se,Ah,Al for the scan. Scan
129definitions are separated by semicolons (';'). A semicolon after the last
130scan definition is optional.
131
132Each scan definition contains one to four component indexes, optionally
133followed by a colon (':') and the four progressive-JPEG parameters. The
134component indexes denote which color component(s) are to be transmitted in
135the scan. Components are numbered in the order in which they appear in the
136JPEG SOF marker, with the first component being numbered 0. (Note that these
137indexes are not the "component ID" codes assigned to the components, just
138positional indexes.)
139
140The progression parameters for each scan are:
141 Ss Zigzag index of first coefficient included in scan
142 Se Zigzag index of last coefficient included in scan
143 Ah Zero for first scan of a coefficient, else Al of prior scan
144 Al Successive approximation low bit position for scan
145If the progression parameters are omitted, the values 0,63,0,0 are used,
146producing a sequential JPEG file. cjpeg automatically determines whether
147the script represents a progressive or sequential file, by observing whether
148Ss and Se values other than 0 and 63 appear. (The -progressive switch is
149not needed to specify this; in fact, it is ignored when -scans appears.)
150The scan script must meet the JPEG restrictions on progression sequences.
151(cjpeg checks that the spec's requirements are obeyed.)
152
153Scan script files are free format, in that arbitrary whitespace can appear
154between numbers and around punctuation. Also, comments can be included: a
155comment starts with '#' and extends to the end of the line. For additional
156legibility, commas or dashes can be placed between values. (Actually, any
157single punctuation character other than ':' or ';' can be inserted.) For
158example, the following two scan definitions are equivalent:
159 0 1 2: 0 63 0 0;
160 0,1,2 : 0-63, 0,0 ;
161
162Here is an example of a scan script that generates a partially interleaved
163sequential JPEG file:
164
165 0; # Y only in first scan
166 1 2; # Cb and Cr in second scan
167
168Here is an example of a progressive scan script using only spectral selection
169(no successive approximation):
170
171 # Interleaved DC scan for Y,Cb,Cr:
172 0,1,2: 0-0, 0, 0 ;
173 # AC scans:
174 0: 1-2, 0, 0 ; # First two Y AC coefficients
175 0: 3-5, 0, 0 ; # Three more
176 1: 1-63, 0, 0 ; # All AC coefficients for Cb
177 2: 1-63, 0, 0 ; # All AC coefficients for Cr
178 0: 6-9, 0, 0 ; # More Y coefficients
179 0: 10-63, 0, 0 ; # Remaining Y coefficients
180
181Here is an example of a successive-approximation script. This is equivalent
182to the default script used by "cjpeg -progressive" for YCbCr images:
183
184 # Initial DC scan for Y,Cb,Cr (lowest bit not sent)
185 0,1,2: 0-0, 0, 1 ;
186 # First AC scan: send first 5 Y AC coefficients, minus 2 lowest bits:
187 0: 1-5, 0, 2 ;
188 # Send all Cr,Cb AC coefficients, minus lowest bit:
189 # (chroma data is usually too small to be worth subdividing further;
190 # but note we send Cr first since eye is least sensitive to Cb)
191 2: 1-63, 0, 1 ;
192 1: 1-63, 0, 1 ;
193 # Send remaining Y AC coefficients, minus 2 lowest bits:
194 0: 6-63, 0, 2 ;
195 # Send next-to-lowest bit of all Y AC coefficients:
196 0: 1-63, 2, 1 ;
197 # At this point we've sent all but the lowest bit of all coefficients.
198 # Send lowest bit of DC coefficients
199 0,1,2: 0-0, 1, 0 ;
200 # Send lowest bit of AC coefficients
201 2: 1-63, 1, 0 ;
202 1: 1-63, 1, 0 ;
203 # Y AC lowest bit scan is last; it's usually the largest scan
204 0: 1-63, 1, 0 ;
205
206It may be worth pointing out that this script is tuned for quality settings
207of around 50 to 75. For lower quality settings, you'd probably want to use
208a script with fewer stages of successive approximation (otherwise the
209initial scans will be really bad). For higher quality settings, you might
210want to use more stages of successive approximation (so that the initial
211scans are not too large).