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