wizard.txt

   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 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
  69 If the -qtables switch is used without -quality, then the specified tables
  70 are used exactly as-is.  If both -qtables and -quality are used, then the
  71 tables taken from the file are scaled in the same fashion that the default
  72 tables would be scaled for that quality setting.  If -baseline appears, then
  73 the quantization values are constrained to the range 1-255.
  74
  75 By default, cjpeg will use quantization table 0 for luminance components and
  76 table 1 for chrominance components.  To override this choice, use the -qslots
  77 switch:
  78
  79         -qslots N[,...]         Select which quantization table to use for
  80                                 each color component.
  81
  82 The -qslots switch specifies a quantization table number for each color
  83 component, in the order in which the components appear in the JPEG SOF marker.
  84 For example, to create a separate table for each of Y,Cb,Cr, you could
  85 provide 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
  87 components, then the last table number is repeated as necessary.
  88
  89
  90 Sampling Factor Adjustment
  91 --------------------------
  92
  93 By default, cjpeg uses 2:1 horizontal and vertical downsampling when
  94 compressing YCbCr data, and no downsampling for all other color spaces.
  95 You can override this default with the -sample switch:
  96
  97         -sample HxV[,...]       Set JPEG sampling factors for each color
  98                                 component.
  99
 100 The -sample switch specifies the JPEG sampling factors for each color
 101 component, in the order in which they appear in the JPEG SOF marker.
 102 If you specify fewer HxV pairs than there are components, the remaining
 103 components are set to 1x1 sampling.  For example, the default YCbCr setting
 104 is equivalent to "-sample 2x2,1x1,1x1", which can be abbreviated to
 105 "-sample 2x2".
 106
 107 There are still some JPEG decoders in existence that support only 2x1
 108 sampling (also called 4:2:2 sampling).  Compatibility with such decoders can
 109 be achieved by specifying "-sample 2x1".  This is not recommended unless
 110 really necessary, since it increases file size and encoding/decoding time
 111 with very little quality gain.
 112
 113
 114 Multiple Scan / Progression Control
 115 -----------------------------------
 116
 117 By default, cjpeg emits a single-scan sequential JPEG file.  The
 118 -progressive switch generates a progressive JPEG file using a default series
 119 of progression parameters.  You can create multiple-scan sequential JPEG
 120 files or progressive JPEG files with custom progression parameters by using
 121 the -scans switch:
 122
 123         -scans file     Use the scan sequence given in the named file.
 124
 125 The specified file should be a text file containing a "scan script".
 126 The script specifies the contents and ordering of the scans to be emitted.
 127 Each entry in the script defines one scan.  A scan definition specifies
 128 the components to be included in the scan, and for progressive JPEG it also
 129 specifies the progression parameters Ss,Se,Ah,Al for the scan.  Scan
 130 definitions are separated by semicolons (';').  A semicolon after the last
 131 scan definition is optional.
 132
 133 Each scan definition contains one to four component indexes, optionally
 134 followed by a colon (':') and the four progressive-JPEG parameters.  The
 135 component indexes denote which color component(s) are to be transmitted in
 136 the scan.  Components are numbered in the order in which they appear in the
 137 JPEG SOF marker, with the first component being numbered 0.  (Note that these
 138 indexes are not the "component ID" codes assigned to the components, just
 139 positional indexes.)
 140
 141 The 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
 146 If the progression parameters are omitted, the values 0,63,0,0 are used,
 147 producing a sequential JPEG file.  cjpeg automatically determines whether
 148 the script represents a progressive or sequential file, by observing whether
 149 Ss and Se values other than 0 and 63 appear.  (The -progressive switch is
 150 not needed to specify this; in fact, it is ignored when -scans appears.)
 151 The scan script must meet the JPEG restrictions on progression sequences.
 152 (cjpeg checks that the spec's requirements are obeyed.)
 153
 154 Scan script files are free format, in that arbitrary whitespace can appear
 155 between numbers and around punctuation.  Also, comments can be included: a
 156 comment starts with '#' and extends to the end of the line.  For additional
 157 legibility, commas or dashes can be placed between values.  (Actually, any
 158 single punctuation character other than ':' or ';' can be inserted.)  For
 159 example, the following two scan definitions are equivalent:
 160         0 1 2: 0 63 0 0;
 161         0,1,2 : 0-63, 0,0 ;
 162
 163 Here is an example of a scan script that generates a partially interleaved
 164 sequential JPEG file:
 165
 166         0;                      # Y only in first scan
 167         1 2;                    # Cb and Cr in second scan
 168
 169 Here 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
 182 Here is an example of a successive-approximation script.  This is equivalent
 183 to 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
 207 It may be worth pointing out that this script is tuned for quality settings
 208 of around 50 to 75.  For lower quality settings, you'd probably want to use
 209 a script with fewer stages of successive approximation (otherwise the
 210 initial scans will be really bad).  For higher quality settings, you might
 211 want to use more stages of successive approximation (so that the initial
 212 scans are not too large).