1Advanced 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 Annex K (Clause K.1) of 47 # Recommendation ITU-T T.81 (1992) | ISO/IEC 10918-1:1994. 48 49 # This is table 0 (the luminance table): 50 16 11 10 16 24 40 51 61 51 12 12 14 19 26 58 60 55 52 14 13 16 24 40 57 69 56 53 14 17 22 29 51 87 80 62 54 18 22 37 56 68 109 103 77 55 24 35 55 64 81 104 113 92 56 49 64 78 87 103 121 120 101 57 72 92 95 98 112 100 103 99 58 59 # This is table 1 (the chrominance table): 60 17 18 24 47 99 99 99 99 61 18 21 26 66 99 99 99 99 62 24 26 56 99 99 99 99 99 63 47 66 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 99 99 99 99 99 99 99 99 68 69If the -qtables switch is used without -quality, then the specified tables 70are used exactly as-is. If both -qtables and -quality are used, then the 71tables taken from the file are scaled in the same fashion that the default 72tables would be scaled for that quality setting. If -baseline appears, then 73the quantization values are constrained to the range 1-255. 74 75By default, cjpeg will use quantization table 0 for luminance components and 76table 1 for chrominance components. To override this choice, use the -qslots 77switch: 78 79 -qslots N[,...] Select which quantization table to use for 80 each color component. 81 82The -qslots switch specifies a quantization table number for each color 83component, in the order in which the components appear in the JPEG SOF marker. 84For example, to create a separate table for each of Y,Cb,Cr, you could 85provide a -qtables file that defines three quantization tables and say 86"-qslots 0,1,2". If -qslots gives fewer table numbers than there are color 87components, then the last table number is repeated as necessary. 88 89 90Sampling Factor Adjustment 91-------------------------- 92 93By default, cjpeg uses 2:1 horizontal and vertical downsampling when 94compressing YCbCr data, and no downsampling for all other color spaces. 95You can override this default with the -sample switch: 96 97 -sample HxV[,...] Set JPEG sampling factors for each color 98 component. 99 100The -sample switch specifies the JPEG sampling factors for each color 101component, in the order in which they appear in the JPEG SOF marker. 102If you specify fewer HxV pairs than there are components, the remaining 103components are set to 1x1 sampling. For example, the default YCbCr setting 104is equivalent to "-sample 2x2,1x1,1x1", which can be abbreviated to 105"-sample 2x2". 106 107There are still some JPEG decoders in existence that support only 2x1 108sampling (also called 4:2:2 sampling). Compatibility with such decoders can 109be achieved by specifying "-sample 2x1". This is not recommended unless 110really necessary, since it increases file size and encoding/decoding time 111with very little quality gain. 112 113 114Multiple Scan / Progression Control 115----------------------------------- 116 117By default, cjpeg emits a single-scan sequential JPEG file. The 118-progressive switch generates a progressive JPEG file using a default series 119of progression parameters. You can create multiple-scan sequential JPEG 120files or progressive JPEG files with custom progression parameters by using 121the -scans switch: 122 123 -scans file Use the scan sequence given in the named file. 124 125The specified file should be a text file containing a "scan script". 126The script specifies the contents and ordering of the scans to be emitted. 127Each entry in the script defines one scan. A scan definition specifies 128the components to be included in the scan, and for progressive JPEG it also 129specifies the progression parameters Ss,Se,Ah,Al for the scan. Scan 130definitions are separated by semicolons (';'). A semicolon after the last 131scan definition is optional. 132 133Each scan definition contains one to four component indexes, optionally 134followed by a colon (':') and the four progressive-JPEG parameters. The 135component indexes denote which color component(s) are to be transmitted in 136the scan. Components are numbered in the order in which they appear in the 137JPEG SOF marker, with the first component being numbered 0. (Note that these 138indexes are not the "component ID" codes assigned to the components, just 139positional indexes.) 140 141The progression parameters for each scan are: 142 Ss Zigzag index of first coefficient included in scan 143 Se Zigzag index of last coefficient included in scan 144 Ah Zero for first scan of a coefficient, else Al of prior scan 145 Al Successive approximation low bit position for scan 146If the progression parameters are omitted, the values 0,63,0,0 are used, 147producing a sequential JPEG file. cjpeg automatically determines whether 148the script represents a progressive or sequential file, by observing whether 149Ss and Se values other than 0 and 63 appear. (The -progressive switch is 150not needed to specify this; in fact, it is ignored when -scans appears.) 151The scan script must meet the JPEG restrictions on progression sequences. 152(cjpeg checks that the spec's requirements are obeyed.) 153 154Scan script files are free format, in that arbitrary whitespace can appear 155between numbers and around punctuation. Also, comments can be included: a 156comment starts with '#' and extends to the end of the line. For additional 157legibility, commas or dashes can be placed between values. (Actually, any 158single punctuation character other than ':' or ';' can be inserted.) For 159example, the following two scan definitions are equivalent: 160 0 1 2: 0 63 0 0; 161 0,1,2 : 0-63, 0,0 ; 162 163Here is an example of a scan script that generates a partially interleaved 164sequential JPEG file: 165 166 0; # Y only in first scan 167 1 2; # Cb and Cr in second scan 168 169Here is an example of a progressive scan script using only spectral selection 170(no successive approximation): 171 172 # Interleaved DC scan for Y,Cb,Cr: 173 0,1,2: 0-0, 0, 0 ; 174 # AC scans: 175 0: 1-2, 0, 0 ; # First two Y AC coefficients 176 0: 3-5, 0, 0 ; # Three more 177 1: 1-63, 0, 0 ; # All AC coefficients for Cb 178 2: 1-63, 0, 0 ; # All AC coefficients for Cr 179 0: 6-9, 0, 0 ; # More Y coefficients 180 0: 10-63, 0, 0 ; # Remaining Y coefficients 181 182Here is an example of a successive-approximation script. This is equivalent 183to the default script used by "cjpeg -progressive" for YCbCr images: 184 185 # Initial DC scan for Y,Cb,Cr (lowest bit not sent) 186 0,1,2: 0-0, 0, 1 ; 187 # First AC scan: send first 5 Y AC coefficients, minus 2 lowest bits: 188 0: 1-5, 0, 2 ; 189 # Send all Cr,Cb AC coefficients, minus lowest bit: 190 # (chroma data is usually too small to be worth subdividing further; 191 # but note we send Cr first since eye is least sensitive to Cb) 192 2: 1-63, 0, 1 ; 193 1: 1-63, 0, 1 ; 194 # Send remaining Y AC coefficients, minus 2 lowest bits: 195 0: 6-63, 0, 2 ; 196 # Send next-to-lowest bit of all Y AC coefficients: 197 0: 1-63, 2, 1 ; 198 # At this point we've sent all but the lowest bit of all coefficients. 199 # Send lowest bit of DC coefficients 200 0,1,2: 0-0, 1, 0 ; 201 # Send lowest bit of AC coefficients 202 2: 1-63, 1, 0 ; 203 1: 1-63, 1, 0 ; 204 # Y AC lowest bit scan is last; it's usually the largest scan 205 0: 1-63, 1, 0 ; 206 207It may be worth pointing out that this script is tuned for quality settings 208of around 50 to 75. For lower quality settings, you'd probably want to use 209a script with fewer stages of successive approximation (otherwise the 210initial scans will be really bad). For higher quality settings, you might 211want to use more stages of successive approximation (so that the initial 212scans are not too large). 213