src/3rdparty/libjpeg/wizard.doc
changeset 0 1918ee327afb
equal deleted inserted replaced
-1:000000000000 0:1918ee327afb
       
     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).