Doc/lib/libjpeg.tex

   1 \section{\module{jpeg} ---
   2          Read and write JPEG files}
   3
   4 \declaremodule{builtin}{jpeg}
   5   \platform{IRIX}
   6 \modulesynopsis{Read and write image files in compressed JPEG format.}
   7
   8
   9 The module \module{jpeg} provides access to the jpeg compressor and
  10 decompressor written by the Independent JPEG Group
  11 \index{Independent JPEG Group}(IJG). JPEG is a standard for
  12 compressing pictures; it is defined in ISO 10918.  For details on JPEG
  13 or the Independent JPEG Group software refer to the JPEG standard or
  14 the documentation provided with the software.
  15
  16 A portable interface to JPEG image files is available with the Python
  17 Imaging Library (PIL) by Fredrik Lundh.  Information on PIL is
  18 available at \url{http://www.pythonware.com/products/pil/}.
  19 \index{Python Imaging Library}
  20 \index{PIL (the Python Imaging Library)}
  21 \index{Lundh, Fredrik}
  22
  23 The \module{jpeg} module defines an exception and some functions.
  24
  25 \begin{excdesc}{error}
  26 Exception raised by \function{compress()} and \function{decompress()}
  27 in case of errors.
  28 \end{excdesc}
  29
  30 \begin{funcdesc}{compress}{data, w, h, b}
  31 Treat data as a pixmap of width \var{w} and height \var{h}, with
  32 \var{b} bytes per pixel.  The data is in SGI GL order, so the first
  33 pixel is in the lower-left corner. This means that \function{gl.lrectread()}
  34 return data can immediately be passed to \function{compress()}.
  35 Currently only 1 byte and 4 byte pixels are allowed, the former being
  36 treated as greyscale and the latter as RGB color.
  37 \function{compress()} returns a string that contains the compressed
  38 picture, in JFIF\index{JFIF} format.
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{decompress}{data}
  42 Data is a string containing a picture in JFIF\index{JFIF} format. It
  43 returns a tuple \code{(\var{data}, \var{width}, \var{height},
  44 \var{bytesperpixel})}.  Again, the data is suitable to pass to
  45 \function{gl.lrectwrite()}.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{setoption}{name, value}
  49 Set various options.  Subsequent \function{compress()} and
  50 \function{decompress()} calls will use these options.  The following
  51 options are available:
  52
  53 \begin{tableii}{l|p{3in}}{code}{Option}{Effect}
  54   \lineii{'forcegray'}{%
  55     Force output to be grayscale, even if input is RGB.}
  56   \lineii{'quality'}{%
  57     Set the quality of the compressed image to a value between
  58     \code{0} and \code{100} (default is \code{75}).  This only affects
  59     compression.}
  60   \lineii{'optimize'}{%
  61     Perform Huffman table optimization.  Takes longer, but results in
  62     smaller compressed image.  This only affects compression.}
  63   \lineii{'smooth'}{%
  64     Perform inter-block smoothing on uncompressed image.  Only useful
  65     for low-quality images.  This only affects decompression.}
  66 \end{tableii}
  67 \end{funcdesc}
  68
  69
  70 \begin{seealso}
  71   \seetext{\emph{JPEG Still Image Data Compression Standard}, by
  72     Pennebaker and Mitchell, is the canonical reference for the JPEG
  73     image format.}
  74
  75   \seetext{The ISO standard for JPEG is also published as ITU T.81.
  76     This is available in PDF form at
  77     \url{http://www.w3.org/Graphics/JPEG/itu-t81.pdf}.}
  78 \end{seealso}