Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame^] | 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 | If the progression parameters Ss,Se,Ah,Al are omitted, the values 0,63,0,0 |
| 141 | are used, producing a sequential JPEG file. cjpeg automatically determines |
| 142 | whether the script represents a progressive or sequential file, by observing |
| 143 | whether Ss and Se values other than 0 and 63 appear. (The -progressive |
| 144 | switch is unnecessary and is ignored when -scans appears.) When specifying |
| 145 | progression parameters, the user must follow the JPEG restrictions on |
| 146 | progression parameters. (cjpeg checks that the spec's requirements are |
| 147 | obeyed.) |
| 148 | |
| 149 | Scan script files are free format, in that arbitrary whitespace can appear |
| 150 | between numbers and around punctuation. Also, comments can be included: a |
| 151 | comment starts with '#' and extends to the end of the line. For additional |
| 152 | legibility, commas or dashes can be placed between values. (Actually, any |
| 153 | single punctuation character other than ':' or ';' can be inserted.) For |
| 154 | example, the following two scan definitions are equivalent: |
| 155 | 0 1 2: 0 63 0 0; |
| 156 | 0,1,2 : 0-63, 0,0 ; |
| 157 | |
| 158 | Here is an example of a scan script that generates a partially interleaved |
| 159 | sequential JPEG file: |
| 160 | |
| 161 | 0; # Y only in first scan |
| 162 | 1 2; # Cb and Cr in second scan |
| 163 | |
| 164 | Here is an example of a progressive scan script using only spectral selection |
| 165 | (no successive approximation): |
| 166 | |
| 167 | # Interleaved DC scan for Y,Cb,Cr: |
| 168 | 0,1,2: 0-0, 0, 0 ; |
| 169 | # AC scans: |
| 170 | 0: 1-2, 0, 0 ; # First two Y AC coefficients |
| 171 | 0: 3-5, 0, 0 ; # Three more |
| 172 | 1: 1-63, 0, 0 ; # All AC coefficients for Cb |
| 173 | 2: 1-63, 0, 0 ; # All AC coefficients for Cr |
| 174 | 0: 6-9, 0, 0 ; # More Y coefficients |
| 175 | 0: 10-63, 0, 0 ; # Remaining Y coefficients |
| 176 | |
| 177 | Here is an example of a successive-approximation script. This is equivalent |
| 178 | to the default script used by "cjpeg -progressive" for YCbCr images: |
| 179 | |
| 180 | # Initial DC scan for Y,Cb,Cr (lowest bit not sent) |
| 181 | 0,1,2: 0-0, 0, 1 ; |
| 182 | # First AC scan: send first 5 Y AC coefficients, minus 2 lowest bits: |
| 183 | 0: 1-5, 0, 2 ; |
| 184 | # Send all Cr,Cb AC coefficients, minus lowest bit: |
| 185 | # (chroma data is usually too small to be worth subdividing further; |
| 186 | # but note we send Cr first since eye is least sensitive to Cb) |
| 187 | 2: 1-63, 0, 1 ; |
| 188 | 1: 1-63, 0, 1 ; |
| 189 | # Send remaining Y AC coefficients, minus 2 lowest bits: |
| 190 | 0: 6-63, 0, 2 ; |
| 191 | # Send next-to-lowest bit of all Y AC coefficients: |
| 192 | 0: 1-63, 2, 1 ; |
| 193 | # At this point we've sent all but the lowest bit of all coefficients. |
| 194 | # Send lowest bit of DC coefficients |
| 195 | 0,1,2: 0-0, 1, 0 ; |
| 196 | # Send lowest bit of AC coefficients |
| 197 | 2: 1-63, 1, 0 ; |
| 198 | 1: 1-63, 1, 0 ; |
| 199 | # Y AC lowest bit scan is last; it's usually the largest scan |
| 200 | 0: 1-63, 1, 0 ; |
| 201 | |
| 202 | It may be worth pointing out that this script is tuned for quality settings |
| 203 | of around 50 to 75. For lower quality settings, you'd probably want to use |
| 204 | a script with fewer stages of successive approximation (otherwise the |
| 205 | initial scans will be really bad). For higher quality settings, you might |
| 206 | want to use more stages of successive approximation (so that the initial |
| 207 | scans are not too large). |