Doc/library/jpeg.rst

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