man > pnmtojpeg(1)

Pnmtojpeg User Manual(1)               General Commands Manual              Pnmtojpeg User Manual(1)

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


SYNOPSIS
       pnmtojpeg  [-exif=filespec]  [-quality=n]  [{-grayscale|-greyscale}] [-density=nxn[dpi,dpcm]]
       [-optimize|-optimise] [-rgb] [-progressive] [-comment=text] [-dct={int|fast|float}]  [-arith‐
       metic]  [-restart=n]  [-smooth=n]  [-maxmemory=n]  [-verbose] [-baseline] [-qtables=filespec]
       [-qslots=n[,...]]  [-sample=HxV[,...]]  [-scans=filespec] [-tracelevel=N]

       filename

       Minimum unique abbreviation of option is acceptable.  You may use double hyphens  instead  of
       single hyphen to denote options.  You may use white space in place of the equals sign to sep‐
       arate an option name from its value.



DESCRIPTION
       This program is part of Netpbm(1).

       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
       ]8;;http://www.ijg.org\http://www.ijg.org]8;;\   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 creates an EXIF image when you specify the -exif
       option.


OPTIONS
       In addition to the options common to all programs based on libnetpbm  (most  notably  -quiet,
       see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pnmtojpeg recognizes the following command line options:


   Basic Options
       -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
              contents  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 significant 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 jpeg‐
              topnm,  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  con‐
              taining  nothing  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 con‐
              tents 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); de‐
              fault is 75.  Below about 25 can produce images some interpreters won't be able to in‐
              terpret.  See below for more info.


       -grayscale

       -greyscale

       -rgb   These options determine the color space used  in  the  JFIF  output.   -grayscale  (or
              -greyscale) means to create a gray scale JFIF, converting from color PPM input if nec‐
              essary.   -rgb  means to create an RGB JFIF, and the program fails if the input is not
              PPM.

              If you specify neither, The output file is in YCbCr format if the input  is  PPM,  and
              grayscale format if the input is PBM or PGM.

              YCbCr format (a color is represented by an intensity value and two chrominance values)
              usually compresses much better than RGB (a color is represented by one red, one green,
              and  one  blue  value).  RGB is rare.  But you may be able to convert between JFIF and
              PPM faster with RGB, since it's the same color space PPM uses.

              The testimg.ppm file that comes with Netpbm is 2.3 times larger with the  -rgb  option
              than with the YCbCr default, and in one experiment pnmtojpeg took 16% more CPU time to
              convert  it.   The  extra CPU time probably indicates that processing of all the extra
              compressed data consumed all the CPU time saved by not having to convert the  RGB  in‐
              puts to YCbCr.

              Grayscale  format  takes up a lot less space and takes less time to create and process
              than the color formats, even if the image contains nothing but black, white, and gray.

              The -rgb option was added in Netpbm 10.11 in October 2002.


       -density=density
              This option determines the density (aka resolution) information recorded in  the  JFIF
              output  image.   It does not affect the raster in any way; it just tells whoever reads
              the JFIF how to interpret the raster.

              The density value takes the form xxy followed by an optional unit specifier of dpi  or
              dpcm.   Examples: 1x1, 3x2, 300x300dpi, 100x200dpcm.  The first number is the horizon‐
              tal density; the 2nd number is the vertical density.  Each may be any integer  from  1
              to  65535.   The unit specifier is dpi for dots per inch or dpcm for dots per centime‐
              ter.  If you don't specify the units, the density information goes into the  JFIF  ex‐
              plicitly stating "density unspecified" (also interpreted as "unknown").  This may seem
              pointless,  but  note that even without specifying the units, the density numbers tell
              the aspect ratio of the pixels.  E.g. 1x1 tells you the pixels are square.  3x2  tells
              you the pixels are vertical rectangles.

              Note  that  if  you specify different horizontal and vertical densities, the resulting
              JFIF image is not a true representation of the input PNM image, because pnmtojpeg con‐
              verts the raster pixel-for-pixel and the pixels of a  PNM  image  are  defined  to  be
              square.   Thus, if you start with a square PNM image and specify -density=3x2, the re‐
              sulting JFIF image is a horizontally squashed version of the original.  However, it is
              common to use an input image which is a slight variation on PNM rather than  true  PNM
              such  that  the  pixels are not square.  In that case, the appropriate -density option
              yields a faithful reproduction of the input pseudo-PNM image.

              The default is 1x1 in unspecified units.

              Before Netpbm 10.15 (April 2003), this option did not exist and the  pnmtojpeg  always
              created a JFIF with a density of 1x1 in unspecified units.


       -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 output.



       The -quality option lets you trade off compressed file size against  quality  of  the  recon‐
       structed  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 for reason‐
       able  results;  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  of interest mainly 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 useful in preparing an index of a large image  li‐
       brary,  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, be‐
       cause  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  to‐
       tal 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.

       If you're trying to control the quality/file size tradeoff, you might consider  the  JPEG2000
       format instead.  See pamtojpeg2k(1).


   Advanced options
       -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.


       -arithmetic
              Use  arithmetic  coding.  Default is Huffman encoding.  Arithmetic coding tends to get
              you a smaller result.

              You may need patent licenses to use this option.  According  to  ]8;;http://www.faqs.org/faqs/jpeg-faq\the JPEG FAQ]8;;\  ,  This
              method is covered by patents owned by IBM, AT&T, and Mitsubishi.

              The  author  of the FAQ recommends against using arithmetic coding (and therefore this
              option) because the space savings is not great enough to justify the legal hassles.

              Most JPEG libraries, including any distributed by the  Independent  JPEG  Group  since
              about 1998 are not capable of arithmetic encoding.  pnmtojpeg uses a JPEG library (ei‐
              ther bound to it when the pnmtojpeg executable was built or accessed on your system at
              run  time) to do the JPEG encoding.  If pnmtojpeg terminates with the message, "Sorry,
              there are legal restrictions on arithmetic coding" or "Sorry,  arithmetic  coding  not
              supported," this is the problem.


       -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,  indi‐
              cates 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 thou‐
              sands  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 re‐
       synchronize  after a transmission error.  Without 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 moderate 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.


   Wizard Options
       -baseline
              Force baseline-compatible quantization tables to be generated.  This clamps  quantiza‐
              tion  values  to  8  bits even at low quality settings.  (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.


       -tracelevel=N
              This sets the level of debug tracing the program outputs as it runs.   0  means  none,
              and  is  the  default.  This level primarily controls tracing of the JPEG library, and
              you can get some pretty interesting information about the compression process.



       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


       Here's a more typical example.  It converts from BMP to JFIF:

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



JPEG LOSS
       When  you  compress  with JPEG, you lose information -- i.e. the resulting image has somewhat
       lower quality than the original.  This is a characteristic of JPEG itself, not any particular
       program.  So if you do the usual Netpbm thing and convert from JFIF to PNM, manipulate,  then
       convert  back  to JFIF, you will lose quality.  The more you do it, the more you lose.  Draw‐
       ings (charts, cartoons, line drawings, and such with few colors and sharp edges)  suffer  the
       most.

       To  avoid  this, you can use a compressed image format other than JPEG.  PNG and JPEG2000 are
       good choices, and Netpbm contains converters for those.

       If you need to use JFIF on a drawing, you should experiment  with  pnmtojpeg's  -quality  and
       -smooth options to get a satisfactory conversion.  -smooth 10 or so is often helpful.

       Because  of  the loss, 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  origi‐
       nal format, so much the better.

       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).

       You  can do flipping and rotating transformations losslessly with the program jpegtran, which
       is packaged with the Independent Jpeg Group's JPEG library.  jpegtran exercises its  intimate
       knowledge  of the way JPEG works to do the transformation without ever actually decompressing
       the image.


OTHER PROGRAMS
       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 doc‐
       ument.

       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
       sometimes untrue.

       To start with, the entries for the DC coefficient must come before any entries for the AC co‐
       efficients.  The DC coefficient is Coefficient 0; all the other coefficients are  AC  coeffi‐
       cients.  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 coefficient, 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 coefficient for every color compo‐
       nent.  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  fea‐
       ture 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
       jpegtopnm(1), pnm(1), cjpeg man page, djpeg man page, jpegtran man page, rdjpgcom  man  page,
       wrjpgcom man page

       Wallace,  Gregory  K.   "The  JPEG Still Picture Compression Standard", Communications of the
       ACM, April 1991 (vol. 34, no. 4), pp. 30-44.



AUTHOR
       pnmtojpeg and this manual were derived in large part from  cjpeg,  by  the  Independent  JPEG
       Group.  The program is otherwise by Bryan Henderson on March 07, 2000.

DOCUMENT SOURCE
       This  manual  page  was  generated by the Netpbm tool 'makeman' from HTML source.  The master
       documentation is at

              http://netpbm.sourceforge.net/doc/pnmtojpeg.html

netpbm documentation                        23 April 2007                   Pnmtojpeg User Manual(1)