From a72b5963d73c90017bd3ab457df52256d8812eff Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Mon, 11 Dec 2023 04:14:18 -0600 Subject: [PATCH] Document JPEG 2000 support for writing YCbCr and reading subsampled color Read support for subsampled RGB and YCbCr color channels was added in 4f4c3b34f8 and not documented at the time. Write support for YCbCr appears to date to 61fb89ec54, 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. --- docs/handbook/image-file-formats.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index 9cd65fd48cb..53565dbbdb3 100644 --- a/docs/handbook/image-file-formats.rst +++ b/docs/handbook/image-file-formats.rst @@ -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