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