:orphan:

.. _JPEG2000-PIL:

JPEG2000-PIL JPEG 2000 (ISO 15444)
==================================

Extensions: ``.jp2``, ``.j2k``, ``.jpc``, ``.jpf``, ``.jpx``, ``.j2c``

*From the Pillow docs:*


.. versionadded:: Pillow  2.4.0

PIL reads and writes JPEG 2000 files containing ``L``, ``LA``, ``RGB`` or
``RGBA`` data.  It can also read files containing ``YCbCr`` data, which it
converts on read into ``RGB`` or ``RGBA`` depending on whether or not there is
an alpha channel.  PIL supports JPEG 2000 raw codestreams (``.j2k`` files), as
well as boxed JPEG 2000 files (``.j2p`` or ``.jpx`` files).  PIL does *not*
support files whose components have different sampling frequencies.

When loading, if you set the ``mode`` on the image prior to the
:py:meth:`~PIL.Image.Image.load` method being invoked, you can ask PIL to
convert the image to either ``RGB`` or ``RGBA`` rather than choosing for
itself.  It is also possible to set ``reduce`` to the number of resolutions to
discard (each one reduces the size of the resulting image by a factor of 2),
and ``layers`` to specify the number of quality layers to load.

The :py:meth:`~PIL.Image.Image.save` method supports the following options:

**offset**
    The image offset, as a tuple of integers, e.g. (16, 16)

**tile_offset**
    The tile offset, again as a 2-tuple of integers.

**tile_size**
    The tile size as a 2-tuple.  If not specified, or if set to None, the
    image will be saved without tiling.

**quality_mode**
    Either `"rates"` or `"dB"` depending on the units you want to use to
    specify image quality.

**quality_layers**
    A sequence of numbers, each of which represents either an approximate size
    reduction (if quality mode is `"rates"`) or a signal to noise ratio value
    in decibels.  If not specified, defaults to a single layer of full quality.

**num_resolutions**
    The number of different image resolutions to be stored (which corresponds
    to the number of Discrete Wavelet Transform decompositions plus one).

**codeblock_size**
    The code-block size as a 2-tuple.  Minimum size is 4 x 4, maximum is 1024 x
    1024, with the additional restriction that no code-block may have more
    than 4096 coefficients (i.e. the product of the two numbers must be no
    greater than 4096).

**precinct_size**
    The precinct size as a 2-tuple.  Must be a power of two along both axes,
    and must be greater than the code-block size.

**irreversible**
    If ``True``, use the lossy Irreversible Color Transformation
    followed by DWT 9-7.  Defaults to ``False``, which means to use the
    Reversible Color Transformation with DWT 5-3.

**progression**
    Controls the progression order; must be one of ``"LRCP"``, ``"RLCP"``,
    ``"RPCL"``, ``"PCRL"``, ``"CPRL"``.  The letters stand for Component,
    Position, Resolution and Layer respectively and control the order of
    encoding, the idea being that e.g. an image encoded using LRCP mode can
    have its quality layers decoded as they arrive at the decoder, while one
    encoded using RLCP mode will have increasing resolutions decoded as they
    arrive, and so on.

**cinema_mode**
    Set the encoder to produce output compliant with the digital cinema
    specifications.  The options here are ``"no"`` (the default),
    ``"cinema2k-24"`` for 24fps 2K, ``"cinema2k-48"`` for 48fps 2K, and
    ``"cinema4k-24"`` for 24fps 4K.  Note that for compliant 2K files,
    *at least one* of your image dimensions must match 2048 x 1080, while
    for compliant 4K files, *at least one* of the dimensions must match
    4096 x 2160.

.. note::

   To enable JPEG 2000 support, you need to build and install the OpenJPEG
   library, version 2.0.0 or higher, before building the Python Imaging
   Library.

   Windows users can install the OpenJPEG binaries available on the
   OpenJPEG website, but must add them to their PATH in order to use PIL (if
   you fail to do this, you will get errors about not being able to load the
   ``_imaging`` DLL).

Parameters for reading
----------------------

pilmode : str
    From the Pillow documentation:

    * 'L' (8-bit pixels, grayscale)
    * 'P' (8-bit pixels, mapped to any other mode using a color palette)
    * 'RGB' (3x8-bit pixels, true color)
    * 'RGBA' (4x8-bit pixels, true color with transparency mask)
    * 'CMYK' (4x8-bit pixels, color separation)
    * 'YCbCr' (3x8-bit pixels, color video format)
    * 'I' (32-bit signed integer pixels)
    * 'F' (32-bit floating point pixels)

    PIL also provides limited support for a few special modes, including
    'LA' ('L' with alpha), 'RGBX' (true color with padding) and 'RGBa'
    (true color with premultiplied alpha).

    When translating a color image to grayscale (mode 'L', 'I' or 'F'),
    the library uses the ITU-R 601-2 luma transform::

        L = R * 299/1000 + G * 587/1000 + B * 114/1000
as_gray : bool
    If True, the image is converted using mode 'F'. When `mode` is
    not None and `as_gray` is True, the image is first converted
    according to `mode`, and the result is then "flattened" using
    mode 'F'.

