Add JPEG XL Open/Read support via libjxl #7848

olokelo · 2024-03-02T00:38:31Z

This PR enables opening and reading JPEG XL images and animations.
Supported image modes are: RGB, RGBA, RGBa, L, LA, La.
A relatively recent libjxl version is needed to compile Pillow with libjxl support.
The main changes are the addition of _jxl.c and JxlImagePlugin.py.
I'm also the author of jxlpy so this PR was influenced by the work of contributors there. This PR is also largely based on WebPImagePlugin.py which had similar implementation.

Why?
JPEG XL has recently seen increased adoption especially in Apple ecosystem. A lot of users are requesting Pillow support for JPEG XL as their products use Pillow and need to be able to handle jxl files.

I'm open to suggestions and comments. I understand such change would need a lot of testing and probably changes. After all Pillow would need to become somewhat dependent on libjxl. Creating documentation will not be a big problem however I decided to wait for feedback from Pillow core developers.

for more information, see https://pre-commit.ci

src/PIL/features.py

Tests/test_jxl_leaks.py

Tests/test_file_jxl_metadata.py

src/PIL/JxlImagePlugin.py

brunoais · 2024-03-02T14:36:33Z

May you please commit the images as LFS?

olokelo · 2024-03-02T18:43:02Z

May you please commit the images as LFS?

Do you mean those .jxl files under Tests/images I've committed? I'm not really sure how to do that.

brunoais · 2024-03-03T08:30:48Z

~~The explanation is outlined here: https://docs.github.com/en/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage~~
Nevermind. I just noticed they are not putting the test images as lfs:

They already setup lfs and they only use for other larger stuff. Let it stay as you did.

Removed jxl feature

for more information, see https://pre-commit.ci

olokelo · 2024-03-11T12:04:24Z

Mac OS builds were failing because clang complained about goto labels being declared before variables in scope.
I also merged @radarhere's commits that remove the jxl feature which was causing troubles before.
Now it should be fine. Almost all checks pass except codecov.

src/PIL/JxlImagePlugin.py

hugovk · 2024-03-19T08:53:37Z

src/PIL/__init__.py

@@ -47,6 +47,7 @@
    "IptcImagePlugin",
    "JpegImagePlugin",
    "Jpeg2KImagePlugin",
+    "JxlImagePlugin",


Naming things: like other plugins, shall we use the name of the format rather than the extension?

Suggested change

"JxlImagePlugin",

"JpegXlImagePlugin",

That's a good point. Not sure why I decided to go with "jxl" from the beginning.
Would you want me to change all the references to jxl (including tests, function/class names, feature.jxl) or only plugin and .c extension filename?

I think let's just use jxl for the filename extension (so the Tests/images/jxl/) dir is fine too) and of course the MIME type, and change the rest.

Tests/test_file_jxl_metadata.py

hugovk · 2024-03-19T08:55:57Z

Tests/test_jxl_leaks.py

+    # TODO: lower the limit, I'm not sure what is correct limit
+    # since I have libjxl debug system-wide
+    mem_limit = 16 * 1024  # kb


How can we find out the correct limit?

I tested it on release version of libjxl and I've set it to 6 megabytes which seem to work well, that's also similar to memory usage of djxl for decoding hopper.jxl.
I think libjxl memory usage could depend also on number of decoding threads used. By default we use all available cores.

Tests/test_jxl_leaks.py

src/_jxl.c

src/PIL/JxlImagePlugin.py

hugovk · 2024-03-19T09:13:03Z

src/PIL/JxlImagePlugin.py

+        # jpeg xl does some weird shenanigans when storing exif
+        # it omits first 6 bytes of tiff header but adds 4 byte offset instead
+        if len(exif) <= 4:
+            return None


Can we add a test case for this and _getexit?

hugovk · 2024-03-19T09:13:24Z

src/PIL/JxlImagePlugin.py

+
+    def seek(self, frame):
+        if not self._seek_check(frame):
+            return


And a test for this?

There's already test_file_jxl_animated.py test which also does seeking.

The return isn't covered: https://app.codecov.io/gh/python-pillow/Pillow/pull/7848/blob/src/PIL/JxlImagePlugin.py

hugovk · 2024-03-19T09:24:07Z

I've merged in main to include #7827 to fix a lot of the warnings I'm seeing on macOS 14.4 Sonoma with CommandLineTools installed.

And this is failing to build for me with:

      src/_jxl.c:174:12: error: incompatible integer to pointer conversion returning 'int' from a function with result type 'void *' [-Wint-conversion]
          return true;
                 ^~~~
      /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/15.0.0/include/stdbool.h:21:14: note: expanded from macro 'true'
      #define true 1
                   ^

Full log: log2.txt

olokelo · 2024-03-19T12:26:29Z

I've merged in main to include #7827 to fix a lot of the warnings I'm seeing on macOS 14.4 Sonoma with CommandLineTools installed.

And this is failing to build for me with:
      src/_jxl.c:174:12: error: incompatible integer to pointer conversion returning 'int' from a function with result type 'void *' [-Wint-conversion]
          return true;
                 ^~~~
      /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/15.0.0/include/stdbool.h:21:14: note: expanded from macro 'true'
      #define true 1
                   ^
Full log: log2.txt

Thanks for reporting. The _jxl_decoder_count_frames function was declared to return void * instead of bool. That was an obvious mistake and I'm even not sure why it worked under gcc.

src/PIL/JxlImagePlugin.py

hugovk · 2024-03-19T13:45:25Z

src/PIL/JxlImagePlugin.py

+    if is_jxl and not SUPPORTED:
+        return "image file could not be identified because JXL support not installed"


Exception instead of return string?

Should we raise SyntaxError like here in Jpeg2K plugin?
I based my work on WebP plugin which just returns string.

for more information, see https://pre-commit.ci

radarhere · 2025-05-10T09:24:53Z

src/_jpegxl.c

+
+    // count all JXL_DEC_NEED_IMAGE_OUT_BUFFER events
+    while (decp->status != JXL_DEC_SUCCESS) {
+        decp->status = JxlDecoderProcessInput(decp->decoder);


I actually think it would probably be preferable to not call JxlDecoderProcessInput on open at all, to improve performance, and only set n_frames when the user asks for it.

#7311 (comment)

For me this is one of the key concepts in Pillow: you can safely open the image file without decoding the whole image (which is much more expensive operation) and get any info from the file.

That could be as simple as

Pillow/src/PIL/GifImagePlugin.py

Lines 125 to 135 in 3c71559

@property

def n_frames(self) -> int:

if self._n_frames is None:

current = self.tell()

try:

while True:

self._seek(self.tell() + 1, False)

except EOFError:

self._n_frames = self.tell() + 1

self.seek(current)

return self._n_frames

Tests/test_jxl_leaks.py

radarhere · 2025-05-16T12:53:19Z

src/PIL/JpegXlImagePlugin.py

+            self.n_frames = None
+            if n_frames > 0:
+                self.n_frames = n_frames
+                self._tps_dur_secs = tps_num / tps_denom


I'm guessing that n_frames is zero when there is an animated file but one of the frames can't be loaded? As in, a well-formed image shouldn't cause this, but it is a file where we will never know the number of frames even when seeking forward, because it will fail.

j99ca · 2025-06-25T12:39:05Z

@radarhere couple of questions:

Will this decoding allow us to decode float32 JXL images? This is important for us as JXL files are great for scientific data (depth, thermal, etc)
Is there any chance that PIL will be able to extract the metadata that might be included in the JXL image, like XMP?

radarhere · 2025-06-25T13:49:09Z

The first commit here left a comment in the C file that 'PIL doesn't support high bit depth images'. I don't know what the thinking was there - in general, Pillow does support single channel 32-bit float images. Perhaps that specific depth just wasn't added.
EXIF and XMP data can be extracted with this PR, yes.

olokelo and others added 2 commits March 2, 2024 00:56

add tests

8e0c5db

[pre-commit.ci] auto fixes from pre-commit.com hooks

a57ebea

for more information, see https://pre-commit.ci

radarhere reviewed Mar 2, 2024

View reviewed changes

src/PIL/features.py Outdated Show resolved Hide resolved

radarhere reviewed Mar 2, 2024

View reviewed changes

Tests/test_jxl_leaks.py Outdated Show resolved Hide resolved

radarhere reviewed Mar 2, 2024

View reviewed changes

Tests/test_file_jxl_metadata.py Outdated Show resolved Hide resolved

radarhere reviewed Mar 2, 2024

View reviewed changes

src/PIL/JxlImagePlugin.py Outdated Show resolved Hide resolved

minor fixes, linting corrections

23fb57d

olokelo mentioned this pull request Mar 2, 2024

JPEG XL support #4247

Open

radarhere added 2 commits March 6, 2024 20:54

Added type hints

2eb5987

Removed feature

37b58f3

radarhere mentioned this pull request Mar 6, 2024

Removed jxl feature olokelo/Pillow#1

Merged

olokelo and others added 3 commits March 11, 2024 10:48

Merge pull request #1 from radarhere/jxl-support2

eeaecb4

Removed jxl feature

fix goto labels for clang

24b63ad

[pre-commit.ci] auto fixes from pre-commit.com hooks

0b50410

for more information, see https://pre-commit.ci

radarhere added the JPEG label Mar 11, 2024

radarhere reviewed Mar 19, 2024

View reviewed changes

src/PIL/JxlImagePlugin.py Outdated Show resolved Hide resolved

hugovk reviewed Mar 19, 2024

View reviewed changes

Merge branch 'main' into jxl-support2

f403672

olokelo added 2 commits March 19, 2024 13:00

modify leak test

f6086d4

fix _jxl_decoder_count_frames

5320450

hugovk reviewed Mar 19, 2024

View reviewed changes

olokelo added 3 commits March 19, 2024 19:22

minor plugin code tweaks

1b049ab

add type hints

6048520

rename jxl -> jpegxl

8fa280f

radarhere and others added 3 commits May 7, 2025 14:59

Replace slice and comparison with startswith

ade1db0

[pre-commit.ci] auto fixes from pre-commit.com hooks

ceec3f9

for more information, see https://pre-commit.ci

Removed getxmp()

5e0457a

radarhere force-pushed the jxl-support2 branch from 76069d2 to ae6edb1 Compare May 7, 2025 08:36

radarhere added 4 commits May 7, 2025 20:33

Do not set info["exif"] to None

9266318

Do not add _getexif to new plugin

29e4b55

Added type hint

3cd3848

Removed self.rawmode

aa6510f

radarhere force-pushed the jxl-support2 branch from ae6edb1 to 6943276 Compare May 7, 2025 10:34

tile is already empty list

36640de

radarhere force-pushed the jxl-support2 branch from 4de4d3a to 36640de Compare May 7, 2025 10:37

radarhere added 2 commits May 7, 2025 23:29

Fixed type hints

7125fe4

Use monkeypatch

05aee33

radarhere force-pushed the jxl-support2 branch from 41f2921 to 05aee33 Compare May 7, 2025 14:02

radarhere added 5 commits May 9, 2025 19:16

Use member names to initialize module

6c3f0b5

Use member names to initialize PyTypeObject

80e9963

Removed C method unused by Python

29c1e4c

Simplified code

c8409e0

is_animated should be a bool

61ce5c2

radarhere reviewed May 10, 2025

View reviewed changes

radarhere reviewed May 11, 2025

View reviewed changes

Tests/test_jxl_leaks.py Outdated Show resolved Hide resolved

radarhere added 2 commits May 12, 2025 18:46

Test on Linux

bf0cdb2

Added argument that was removed in 0.9.0

79f941d

radarhere reviewed May 16, 2025

View reviewed changes

radarhere and others added 3 commits June 15, 2025 22:25

Removed specific leak check

b5d64e8

Use multi-phase initialization

ccca015

Merge branch 'main' into jxl-support2

ece4065

Merge branch 'main' into jxl-support2

e99989f

		if is_jxl and not SUPPORTED:
		return "image file could not be identified because JXL support not installed"

	@property
	def n_frames(self) -> int:
	if self._n_frames is None:
	current = self.tell()
	try:
	while True:
	self._seek(self.tell() + 1, False)
	except EOFError:
	self._n_frames = self.tell() + 1
	self.seek(current)
	return self._n_frames

Uh oh!

Add JPEG XL Open/Read support via libjxl #7848

Are you sure you want to change the base?

Add JPEG XL Open/Read support via libjxl #7848

Uh oh!

Conversation

olokelo commented Mar 2, 2024 • edited by radarhere Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brunoais commented Mar 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

olokelo commented Mar 2, 2024

Uh oh!

brunoais commented Mar 3, 2024

Uh oh!

olokelo commented Mar 11, 2024

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugovk commented Mar 19, 2024

Uh oh!

olokelo commented Mar 19, 2024

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

olokelo Mar 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

j99ca commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

radarhere commented Jun 25, 2025

Uh oh!

Uh oh!

olokelo commented Mar 2, 2024 •

edited by radarhere

Loading

brunoais commented Mar 2, 2024 •

edited

Loading

olokelo Mar 19, 2024 •

edited

Loading

j99ca commented Jun 25, 2025 •

edited

Loading