From fc233a3ecbd0313030270ef2b3126455f5557259 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..55f16296d31 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 ``RGB``, ``RGBA``, and +``YCbCr`` images whose components have different sampling frequencies. +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