Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

pnmtojpeg(1) [xfree86 man page]

PNMTOJPEG(1)						      General Commands Manual						      PNMTOJPEG(1)

NAME
       pnmtojpeg - convert PNM image to a JFIF ("JPEG") image

SYNOPSIS
       pnmtojpeg [ options ] [ filename ]

DESCRIPTION
       pnmtojpeg converts the named PBM, PGM, or PPM image file, or the standard input if no file is named, to a JFIF file on the standard output.

       pnmtojpeg uses the Independent JPEG Group's JPEG library to create the output file.  See http://www.ijg.org for information on the library.

       "JFIF"  is  the correct name for the image format commonly known as "JPEG."  Strictly speaking, JPEG is a method of compression.  The image
       format using JPEG compression that is by far the most common is JFIF.  There is also a subformat of TIFF that uses JPEG compression.

       EXIF is an image format that is a subformat of JFIF (to wit, a JFIF file that contains an EXIF header as an APP1 marker).   pnmtojpeg  cre-
       ates an EXIF image when you specify the -exif option.

OPTIONS
       The basic options are:

       --exif=filespec
	      This  option  specifies  that  the output image is to be EXIF (a subformat of JFIF), i.e. it will have an EXIF header as a JFIF APP1
	      marker.  The contents of that marker are the contents of the specified file.  The special value - means to read the EXIF header con-
	      tents from standard input.  It is invalid to specify standard input for both the EXIF header and the input image.

	      The EXIF file starts with a two byte field which is the length of the file, including the length field, in pure binary, most signif-
	      icant byte first.  The special value of zero for the length field means there is to be no EXIF header, i.e. the  same  as  no  -exif
	      option.	This  is  useful  for when you convert a file from JFIF to PNM using jpegtopnm, then transform it, then convert it back to
	      JFIF with pnmtojpeg, and you don't know whether or not it includes an EXIF header.  jpegtopnm creates an EXIF file containing  noth-
	      ing  but	two bytes of zero when the input JFIF file has no EXIF header.	Thus, you can transfer any EXIF header from the input JFIF
	      to the output JFIF without worrying about whether an EXIF header actually exists.

	      The contents of the EXIF file after the length field are the exact byte for byte contents of  the  APP1  marker,	not  counting  the
	      length field, that constitutes the EXIF header.

       --quality=n
	      Scale quantization tables to adjust image quality.  n is 0 (worst) to 100 (best); default is 75.	(See below for more info.)

       --grayscale

       --greyscale
	      Create gray scale JFIF file.  With this option, pnmtojpeg converts color input to gray scale.  If you don't specify this option, The
	      output file is in color format if the input is PPM, and grayscale format if the input is PBM or PGM.

	      In the PPM input case, even if all the colors in the image are gray, the output is in color format.  Of course, the colors in it are
	      still gray.  The difference is that color format takes up a lot more space and takes longer to create and process.

       --optimize
	      Perform  optimization of entropy encoding parameters.  Without this, pnmtojpeg uses default encoding parameters.	--optimize usually
	      makes the JFIF file a little smaller, but pnmtojpeg runs somewhat slower and needs much more memory.  Image  quality  and  speed	of
	      decompression are unaffected by --optimize.

       --progressive
	      Create a progressive JPEG file (see below).

       --comment=text
	      Include  a comment marker in the JFIF output, with comment text text.  Without this option, there are no comment markers in the out-
	      put.

       The --quality option lets you trade off compressed file size against quality of the reconstructed image: the higher  the  quality  setting,
       the  larger the JFIF file, and the closer the output image will be to the original input.  Normally you want to use the lowest quality set-
       ting (smallest file) that decompresses into something visually indistinguishable from the original image.  For  this  purpose  the  quality
       setting should be between 50 and 95; the default of 75 is often about right.  If you see defects at --quality=75, then go up 5 or 10 counts
       at a time until you are happy with the output image.  (The optimal setting will vary from one image to another.)

       --quality=100 generates a quantization table of all 1's, minimizing loss in the quantization step (but there is still information  loss	in
       subsampling,  as well as roundoff error).  This setting is mainly of interest for experimental purposes.  Quality values above about 95 are
       not recommended for normal use; the compressed file size goes up dramatically for hardly any gain in output image quality.

       In the other direction, quality values below 50 will produce very small files of low image quality.  Settings around 5 to 10 might be  use-
       ful  in preparing an index of a large image library, for example.  Try --quality=2 (or so) for some amusing Cubist effects.  (Note: quality
       values below about 25 generate 2-byte quantization tables, which are considered optional in the JFIF standard.  pnmtojpeg emits	a  warning
       message when you give such a quality value, because some other JFIF programs may be unable to decode the resulting file.  Use --baseline if
       you need to ensure compatibility at low quality values.)

       The --progressive option creates a "progressive JPEG" file.  In this type of JFIF file, the data is stored in multiple scans of	increasing
       quality.   If  the  file  is being transmitted over a slow communications link, the decoder can use the first scan to display a low-quality
       image very quickly, and can then improve the display with each subsequent scan.	The final image is exactly equivalent to a  standard  JFIF
       file  of  the  same quality setting, and the total file size is about the same -- often a little smaller.  Caution: progressive JPEG is not
       yet widely implemented, so many decoders will be unable to view a progressive JPEG file at all.

       Options for advanced users:

       --dct=int
	      Use integer DCT method (default).

       --dct=fast
	      Use fast integer DCT (less accurate).

       --dct=float
	      Use floating-point DCT method.  The float method is very slightly more accurate than the int method, but is much slower unless  your
	      machine  has  very  fast	floating-point	hardware.   Also  note	that results of the floating-point method may vary slightly across
	      machines, while the integer methods should give the same results everywhere.  The fast integer method is much less accurate than the
	      other two.

       --restart=n
	      Emit  a  JPEG restart marker every n MCU rows, or every n MCU blocks if you append B to the number.  --restart 0 (the default) means
	      no restart markers.

       --smooth=n
	      Smooth the input image to eliminate dithering noise.  n, ranging from 1 to  100,	indicates  the	strength  of  smoothing.   0  (the
	      default) means no smoothing.

       --maxmemory=n
	      Set  a  limit  for  amount of memory to use in processing large images.  Value is in thousands of bytes, or millions of bytes if you
	      append M to the number.  For example, --max=4m selects 4,000,000 bytes.  If pnmtojpeg needs more space, it will use temporary files.

       --verbose
	      Print to the Standard Error file messages about the conversion process.  This can be helpful in debugging problems.

       The --restart option tells pnmtojpeg to insert extra markers that allow a JPEG decoder to resynchronize after a transmission error.   With-
       out  restart markers, any damage to a compressed file will usually ruin the image from the point of the error to the end of the image; with
       restart markers, the damage is usually confined to the portion of the image up to the next restart marker.  Of course, the restart  markers
       occupy extra space.  We recommend --restart=1 for images that will be transmitted across unreliable networks such as Usenet.

       The --smooth option filters the input to eliminate fine-scale noise.  This is often useful when converting dithered images to JFIF:  a mod-
       erate smoothing factor of 10 to 50 gets rid of dithering patterns in the input file, resulting in a smaller JFIF file and a  better-looking
       image.  Too large a smoothing factor will visibly blur the image, however.

       Options for wizards:

       --baseline
	      Force  baseline-compatible  quantization tables to be generated.	This clamps quantization values to 8 bits even at low quality set-
	      tings.  (This switch is poorly named, since it does not ensure that the output is actually baseline JPEG.  For example, you can  use
	      --baseline and --progressive together.)

       --qtables=filespec
	      Use the quantization tables given in the specified text file.

       --qslots=n[,...]
	      Select which quantization table to use for each color component.

       --sample=HxV[,...]
	      Set JPEG sampling factors for each color component.

       --scans=filespec
	      Use the scan script given in the specified text file.  See below for information on scan scripts.

       The "wizard" options are intended for experimentation with JPEG.  If you don't know what you are doing, don't use them.	These switches are
       documented further in the file wizard.doc that comes with the Independent JPEG Group's JPEG library.

EXAMPLES
       This example compresses the PPM file foo.ppm with a quality factor of 60 and saves the output as foo.jpg:

	      pnmtojpeg --quality=60 foo.ppm > foo.jpg

	      cat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg

HINTS
       JFIF is not ideal for cartoons, line drawings, and other images that have only a few distinct colors.  For those, try instead  pnmtopng	or
       ppmtobmp.   If  you need to convert such an image to JFIF, though, you should experiment with pnmtojpeg's --quality and --smooth options to
       get a satisfactory conversion.  --smooth 10 or so is often helpful.

       JPEG compression is notable for being a "lossy."  This means that, unlike with most graphics conversions, you lose information, which means
       image  quality,	when you convert to JFIF.  If you convert from PPM to JFIF and back repeatedly, image quality loss will accumulate.  After
       ten or so cycles the image may be noticeably worse than it was after one cycle.

       Because of this, you should do all the manipulation you have to do on the image in some other format and convert to JFIF as the last  step.
       And if you can keep a copy in the original format, so much the better.  PNG is a good choice for a format that is lossless, yet fairly com-
       pact.  GIF is another way to go, but chances are you can't create a GIF image without owing a lot of money to Unisys and  IBM,  holders	of
       patents on the LZW compression used in the GIF format.

       The --optimize option to pnmtojpeg is worth using when you are making a "final" version for posting or archiving.  It's also a win when you
       are using low quality settings to make very small JFIF files; the percentage improvement is often a lot more than it is	on  larger  files.
       (At present, --optimize mode is automatically in effect when you generate a progressive JPEG file).

       Another	program,  cjpeg, is similar.  cjpeg is maintained by the Independent JPEG Group and packaged with the JPEG library which pnmtojpeg
       uses for all its JPEG work.  Because of that, you may expect it to exploit more current JPEG features.  Also, since you have  to  have  the
       library to run pnmtojpeg, but not vice versa, cjpeg may be more commonly available.

       On  the other hand, cjpeg does not use the NetPBM libraries to process its input, as all the NetPBM tools such as pnmtojpeg do.	This means
       it is less likely to be consistent with all the other programs that deal with the NetPBM formats.  Also, the command syntax of pnmtojpeg is
       consistent with that of the other Netpbm tools, unlike cjpeg.

SCAN SCRIPTS
       Use the -scan option to specify a scan script.  Or use the -progressive option to specify a particular built-in scan script.

       Just what a scan script is, and the basic format of the scan script file, is covered in the wizard.doc file that comes with the Independent
       JPEG Group's JPEG library.  Scan scripts are same for pnmtojpeg as the are for cjpeg.

       This section contains additional information that isn't, but probably should be, in that document.

       First, there are many restrictions on what is a valid scan script.  The JPEG library, and thus pnmtojpeg, checks thoroughly for any lack of
       compliance  with  these	restrictions, but does little to tell you how the script fails to comply.  The messages are very general and some-
       times untrue.

       To start with, the entries for the DC coefficient must come before any entries for the AC coefficients.	The DC coefficient is  Coefficient
       0; all the other coefficients are AC coefficients.  So in an entry for the DC coefficient, the two numbers after the colon must be 0 and 0.
       In an entry for AC coefficients, the first number after the colon must not be 0.

       In a DC entry, the color components must be in increasing order.  E.g. "0,2,1" before the colon is wrong.  So is "0,0,0".

       In an entry for an AC coeffient, you must specify only one color component.  I.e. there can be only one number before the colon.

       In the first entry for a particular coefficient for a particular color component, the "Ah" value must be zero, but the Al value can be  any
       valid  bit number.  In subsequent entries, Ah must be the Al value from the previous entry (for that coefficient for that color component),
       and the Al value must be one less than the Ah value.

       The script must ultimately specify at least some of the DC coefficent for every color component.  Otherwise,  you  get  the  error  message
       "Script does not transmit all the data."  You need not specify all of the bits of the DC coefficient, or any of the AC coefficients.

       There  is  a  standard  option in building the JPEG library to omit scan script capability.  If for some reason your library was built with
       this option, you get the message "Requested feature was omitted at compile time."

ENVIRONMENT
       JPEGMEM
	      If this environment variable is set, its value is the default memory limit.  The value is specified as described for the --maxmemory
	      option.  An explicit --maxmemory option overrides any JPEGMEM.

SEE ALSO
       cjpeg(1), djpeg(1), jpegtran(1), rdjpgcom(1), wrjpgcom(1)
       ppm(5), pgm(5), jpegtopnm(1)
       Wallace, Gregory K.  "The JPEG Still Picture Compression Standard", Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

LIMITATIONS
       Arithmetic coding is not supported for legal reasons.

       The program could be much faster.

AUTHOR
       pnmtojpeg  and  this man page were derived in large part from cjpeg, by the Independent JPEG Group.  The program is otherwise by Bryan Hen-
       derson on March 07, 2000.

								   07 March 2000						      PNMTOJPEG(1)
Man Page