Skip to content

Commit

Permalink
Document JPEG 2000 support for writing YCbCr and reading subsampled c…
Browse files Browse the repository at this point in the history
…olor

Read support for subsampled RGB and YCbCr color channels was added in
4f4c3b3 and not documented at the time.  Write support for YCbCr
appears to date to 61fb89e, the original commit.

Retain the existing language about YCbCr input conversion to RGB, even
though it's not completely correct.  OpenJPEG through 2.5.0 doesn't set
color_space in opj_read_header(), so we end up in our
OPJ_CLRSPC_UNSPECIFIED fallback path, which guesses sRGB if there's no
component subsampling.  This means we currently can't round-trip YCbCr via
JPEG 2000.  The next OpenJPEG release will fix this, so leave the docs as
is.

Also fix typo: .j2p -> .jp2.
  • Loading branch information
bgilbert committed Dec 26, 2023
1 parent df83428 commit a72b596
Showing 1 changed file with 7 additions and 6 deletions.
13 changes: 7 additions & 6 deletions docs/handbook/image-file-formats.rst
Original file line number Diff line number Diff line change
Expand Up @@ -552,12 +552,13 @@ JPEG 2000

.. versionadded:: 2.4.0

Pillow 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. Pillow supports JPEG 2000 raw codestreams (``.j2k`` files),
as well as boxed JPEG 2000 files (``.j2p`` or ``.jpx`` files). Pillow does
*not* support files whose components have different sampling frequencies.
Pillow reads and writes JPEG 2000 files containing ``L``, ``LA``, ``RGB``,
``RGBA``, or ``YCbCr`` data. When reading, ``YCbCr`` data is converted to
``RGB`` or ``RGBA`` depending on whether or not there is an alpha channel.
Beginning with version 8.3.0, Pillow can read (but not write) ``RGB``,
``RGBA``, and ``YCbCr`` images with subsampled components. Pillow supports
JPEG 2000 raw codestreams (``.j2k`` files), as well as boxed JPEG 2000 files
(``.jp2`` or ``.jpx`` files).

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 Pillow to
Expand Down

0 comments on commit a72b596

Please sign in to comment.