Advanced usage instructions for the Independent JPEG Group's JPEG software========================================================================== This file describes cjpeg's "switches for wizards". The "wizard" switches are intended for experimentation with JPEG by personswho are reasonably knowledgeable about the JPEG standard.  If you don't knowwhat you are doing, DON'T USE THESE SWITCHES.  You'll likely produce fileswith worse image quality and/or poorer compression than you'd get from thedefault settings.  Furthermore, these switches must be used with cautionwhen making files intended for general use, because not all JPEG decoderswill support unusual JPEG parameter settings.  Quantization Table Adjustment----------------------------- Ordinarily, cjpeg starts with a default set of tables (the same ones givenas examples in the JPEG standard) and scales them up or down according tothe -quality setting.  The details of the scaling algorithm can be found injcparam.c.  At very low quality settings, some quantization table entriescan get scaled up to values exceeding 255.  Although 2-byte quantizationvalues are supported by the IJG software, this feature is not in baselineJPEG and is not supported by all implementations.  If you need to ensurewide compatibility of low-quality files, you can constrain the scaledquantization values to no more than 255 by giving the -baseline switch.Note that use of -baseline will result in poorer quality for the same filesize, since more bits than necessary are expended on higher AC coefficients. You can substitute a different set of quantization values by using the-qtables switch: 	-qtables file	Use the quantization tables given in the named file. The specified file should be a text file containing decimal quantizationvalues.  The file should contain one to four tables, each of 64 elements.The tables are implicitly numbered 0,1,etc. in order of appearance.  Tableentries appear in normal array order (NOT in the zigzag order in which theywill be stored in the JPEG file). Quantization table files are free format, in that arbitrary whitespace canappear between numbers.  Also, comments can be included: a comment startswith '#' and extends to the end of the line.  Here is an example file thatduplicates the default quantization tables: 	# Quantization tables given in JPEG spec, section K.1 	# This is table 0 (the luminance table):	  16  11  10  16  24  40  51  61	  12  12  14  19  26  58  60  55	  14  13  16  24  40  57  69  56	  14  17  22  29  51  87  80  62	  18  22  37  56  68 109 103  77	  24  35  55  64  81 104 113  92	  49  64  78  87 103 121 120 101	  72  92  95  98 112 100 103  99 	# This is table 1 (the chrominance table):	  17  18  24  47  99  99  99  99	  18  21  26  66  99  99  99  99	  24  26  56  99  99  99  99  99	  47  66  99  99  99  99  99  99	  99  99  99  99  99  99  99  99	  99  99  99  99  99  99  99  99	  99  99  99  99  99  99  99  99	  99  99  99  99  99  99  99  99 If the -qtables switch is used without -quality, then the specified tablesare used exactly as-is.  If both -qtables and -quality are used, then thetables taken from the file are scaled in the same fashion that the defaulttables would be scaled for that quality setting.  If -baseline appears, thenthe quantization values are constrained to the range 1-255. By default, cjpeg will use quantization table 0 for luminance components andtable 1 for chrominance components.  To override this choice, use the -qslotsswitch: 	-qslots N[,...]		Select which quantization table to use for				each color component. The -qslots switch specifies a quantization table number for each colorcomponent, in the order in which the components appear in the JPEG SOF marker.For example, to create a separate table for each of Y,Cb,Cr, you couldprovide a -qtables file that defines three quantization tables and say"-qslots 0,1,2".  If -qslots gives fewer table numbers than there are colorcomponents, then the last table number is repeated as necessary.  Sampling Factor Adjustment-------------------------- By default, cjpeg uses 2:1 horizontal and vertical downsampling whencompressing YCbCr data, and no downsampling for all other color spaces.You can override this default with the -sample switch: 	-sample HxV[,...]	Set JPEG sampling factors for each color				component. The -sample switch specifies the JPEG sampling factors for each colorcomponent, in the order in which they appear in the JPEG SOF marker.If you specify fewer HxV pairs than there are components, the remainingcomponents are set to 1x1 sampling.  For example, the default YCbCr settingis equivalent to "-sample 2x2,1x1,1x1", which can be abbreviated to"-sample 2x2". There are still some JPEG decoders in existence that support only 2x1sampling (also called 4:2:2 sampling).  Compatibility with such decoders canbe achieved by specifying "-sample 2x1".  This is not recommended unlessreally necessary, since it increases file size and encoding/decoding timewith very little quality gain.  Multiple Scan / Progression Control----------------------------------- By default, cjpeg emits a single-scan sequential JPEG file.  The-progressive switch generates a progressive JPEG file using a default seriesof progression parameters.  You can create multiple-scan sequential JPEGfiles or progressive JPEG files with custom progression parameters by usingthe -scans switch: 	-scans file	Use the scan sequence given in the named file. The specified file should be a text file containing a "scan script".The script specifies the contents and ordering of the scans to be emitted.Each entry in the script defines one scan.  A scan definition specifiesthe components to be included in the scan, and for progressive JPEG it alsospecifies the progression parameters Ss,Se,Ah,Al for the scan.  Scandefinitions are separated by semicolons (';').  A semicolon after the lastscan definition is optional. Each scan definition contains one to four component indexes, optionallyfollowed by a colon (':') and the four progressive-JPEG parameters.  Thecomponent indexes denote which color component(s) are to be transmitted inthe scan.  Components are numbered in the order in which they appear in theJPEG SOF marker, with the first component being numbered 0.  (Note that theseindexes are not the "component ID" codes assigned to the components, justpositional indexes.) The progression parameters for each scan are:	Ss	Zigzag index of first coefficient included in scan	Se	Zigzag index of last coefficient included in scan	Ah	Zero for first scan of a coefficient, else Al of prior scan	Al	Successive approximation low bit position for scanIf the progression parameters are omitted, the values 0,63,0,0 are used,producing a sequential JPEG file.  cjpeg automatically determines whetherthe script represents a progressive or sequential file, by observing whetherSs and Se values other than 0 and 63 appear.  (The -progressive switch isnot needed to specify this; in fact, it is ignored when -scans appears.)The scan script must meet the JPEG restrictions on progression sequences.(cjpeg checks that the spec's requirements are obeyed.) Scan script files are free format, in that arbitrary whitespace can appearbetween numbers and around punctuation.  Also, comments can be included: acomment starts with '#' and extends to the end of the line.  For additionallegibility, commas or dashes can be placed between values.  (Actually, anysingle punctuation character other than ':' or ';' can be inserted.)  Forexample, the following two scan definitions are equivalent:	0 1 2: 0 63 0 0;	0,1,2 : 0-63, 0,0 ; Here is an example of a scan script that generates a partially interleavedsequential JPEG file: 	0;			# Y only in first scan	1 2;			# Cb and Cr in second scan Here is an example of a progressive scan script using only spectral selection(no successive approximation): 	# Interleaved DC scan for Y,Cb,Cr:	0,1,2: 0-0,   0, 0 ;	# AC scans:	0:     1-2,   0, 0 ;	# First two Y AC coefficients	0:     3-5,   0, 0 ;	# Three more	1:     1-63,  0, 0 ;	# All AC coefficients for Cb	2:     1-63,  0, 0 ;	# All AC coefficients for Cr	0:     6-9,   0, 0 ;	# More Y coefficients	0:     10-63, 0, 0 ;	# Remaining Y coefficients Here is an example of a successive-approximation script.  This is equivalentto the default script used by "cjpeg -progressive" for YCbCr images: 	# Initial DC scan for Y,Cb,Cr (lowest bit not sent)	0,1,2: 0-0,   0, 1 ;	# First AC scan: send first 5 Y AC coefficients, minus 2 lowest bits:	0:     1-5,   0, 2 ;	# Send all Cr,Cb AC coefficients, minus lowest bit:	# (chroma data is usually too small to be worth subdividing further;	#  but note we send Cr first since eye is least sensitive to Cb)	2:     1-63,  0, 1 ;	1:     1-63,  0, 1 ;	# Send remaining Y AC coefficients, minus 2 lowest bits:	0:     6-63,  0, 2 ;	# Send next-to-lowest bit of all Y AC coefficients:	0:     1-63,  2, 1 ;	# At this point we've sent all but the lowest bit of all coefficients.	# Send lowest bit of DC coefficients	0,1,2: 0-0,   1, 0 ;	# Send lowest bit of AC coefficients	2:     1-63,  1, 0 ;	1:     1-63,  1, 0 ;	# Y AC lowest bit scan is last; it's usually the largest scan	0:     1-63,  1, 0 ; It may be worth pointing out that this script is tuned for quality settingsof around 50 to 75.  For lower quality settings, you'd probably want to usea script with fewer stages of successive approximation (otherwise theinitial scans will be really bad).  For higher quality settings, you mightwant to use more stages of successive approximation (so that the initialscans are not too large).