Skip to content

Speed up Image.point() and Image.point_transform() - #9743

Merged
radarhere merged 6 commits into
python-pillow:mainfrom
akx:faster-point
Nov 11, 2026
Merged

radarhere merged 6 commits into
python-pillow:mainfrom
akx:faster-point

Conversation

@akx

@akx akx commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Refs #9649, #9675, #9736, #9737, #9738, #9739, #9740 (same series, same techniques).

Cf. the aforementioned PRs, this also does a couple other cleanups for performance; on my machine, using ImagingNewDirty gave another +10% on top of the first commit. The last commit would technically allow a compiler to inline the point functions, but given their size, a compiler probably won't.

@akx akx changed the title Speed up Image.point() Speed up Image.point() and Image.point_transform() Jun 30, 2026
@codspeed

codspeed Bot commented Jun 30, 2026 •

Copy link
Copy Markdown

Merging this PR will improve performance by 35.45%

3 warnings

⚠️ 2 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 5 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

⚠️ 5 benchmarks with a significant change ran in a different software environment

Their base and head results were measured with a different OS or toolchain, such as compiler, runtime or library versions, so the changes might come from this difference rather than from the code. Open an affected benchmark to see what changed.

See affected benchmarks

⚡ 5 improved benchmarks
✅ 663 untouched benchmarks
⏩ 352 skipped benchmarks1

Performance Changes

Benchmark BASE HEAD Efficiency
⚡ test_point_transform[1237x811-I] 15.7 ms 8 ms +97.08%
⚡ test_point_lut[1237x811-L] 11.9 ms 7.5 ms +57.91%
⚡ test_point_transform[1237x811-F] 9.4 ms 8 ms +17.39%
⚡ test_point_lut[1237x811-RGBA] 31.6 ms 28.3 ms +11.81%
⚡ test_point_transform[1237x811-RGBA] 32.2 ms 28.8 ms +11.6%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


Comparing akx:faster-point (1d55cf8) with main (8dd45e0)2

Open in CodSpeed

Footnotes

  1. 352 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

  2. No successful run was found on main (e188fea) during the generation of this report, so 8dd45e0 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

@hugovk

hugovk commented Aug 9, 2026

Copy link
Copy Markdown
Member

Rebased following benchmark image update: #9831.

Comment thread src/libImaging/Point.c
out[0] = table[in[0]];
out[1] = table[in[1] + 256];
out[2] = table[in[2] + 512];
out[3] = 0;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't look performance-related. Did you want to explain why you added this?

@akx akx Aug 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is in fact performance-related. As noted at the top of the file,

// Note: all point handlers must fill the entirety of `imOut`,
//       as it is allocated dirty by `ImagingPoint`.

and without this, that contract isn't fulfilled.

The same thing happens above in im_point_2x8_2x8.

@akx
akx requested a review from radarhere August 31, 2026 06:33

@espressolee espressolee left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I built both sides and measured the change, and also checked the new initialization requirements. Everything I probed for correctness checked out; the main observation I have is about attribution.

Setup

Base c8c74c8, head 1000b1b, CPython 3.14.6 on macOS arm64. Base and head runs are interleaved and the order alternates each round, so both arms share whatever drift the machine has. The statistic is the median per-call time over 15 equal-duration batches, five rounds. Image.copy() is carried through every run as a negative control, since this PR does not touch it.

The PR contains two independent changes

ImagingNew → ImagingNewDirty is one. restrict plus the hoisted loop bounds is the other. Only the first creates an obligation — every handler must now fill every byte of imOut, including the padding lanes, currently enforced by hand in four places.

I measured them separately by building a third tree that is head with only the allocation call reverted. At 1024×1024:

case whole PR loop changes only allocation change only
L→I (8_32) 0.686x 0.742x 0.925x
L (8_8) 0.724x 0.747x 0.970x
LA (2x8) 0.835x 0.863x 0.965x
RGB (3x8) 0.887x 0.902x 0.980x
RGBA (4x8) 0.931x 0.940x 0.986x
control, Image.copy() 0.997x 1.010x 0.985x

The middle column was also measured directly against base rather than derived from the other two; the two ways of getting it agree to within 0.4%.

At 64×64 the loop-change results on this setup range from 0.965x to 1.002x, so I could not resolve a consistent gain at that size.

Reading

On this machine and build, the loop changes account for the larger share of the measured speedup. The allocation change shows a clear additional gain for L→I (about 7.5%); for the other four paths its measured gain is 1.4–3.5%, close enough to the 1–1.5% control variation that I would not draw a strong conclusion from those alone. That smaller or less certain gain comes with a permanent requirement that every present and future handler fill every output byte.

Whether that tradeoff is worthwhile is a maintainer decision; I mainly wanted to make the two contributions visible. I am not necessarily suggesting this be split into separate PRs — I measured them separately because they have different performance and maintenance tradeoffs.

These proportions are from one machine, one compiler and one OS, and I would not assume they carry to GCC, x86-64 or a different allocator.

Correctness

I also checked the obvious points: restrict appears safe because the handlers are static and imOut is allocated within ImagingPoint; the current handlers fill all output bytes, including the newly explicit padding writes in im_point_3x8_3x8 and im_point_2x8_2x8; and the L→I and I→L paths write complete words. I did not establish whether the tests or valgrind exercise reads of the padding lanes, which is what would matter for detecting a future missed fill.

I can share the harness and exact build commands, or rerun particular cases if useful.

@akx

akx commented Sep 2, 2026

Copy link
Copy Markdown
Contributor Author

@espressolee Thanks for the comment...

The PR contains two independent changes

It contains three, honestly (see the commits, they're atomic and separate on purpose).
The end goal of this PR is "faster point and point_transform", and that it does, with a couple steps.

That smaller or less certain gain comes with a permanent requirement that every present and future handler fill every output byte.

The gain from using Dirty (which has been a theme; see 31dba2d) grows larger with larger images -- there is no point for the non-dirty handler to clear the image if the handlers will fill it anyway. Also, autovectorization tends to work much better when a compiler can look at a loop and see it will end up filling the entire surface, as it were.

As for the maintenance tradeoff, this file has not seen large changes in a while. It's unlikely we'll see new point handlers very soon - but if we do, the new contract is now clearly documented. In fact, by the looks of it,

(main) $ git log --follow --format="%h %cr: %s" src/libImaging/Point.c
140d06dc1 7 weeks ago: Rename IMAGING_TYPE_SPECIAL to IMAGING_TYPE_I16
84aa4372f 1 year, 1 month ago: linter changes
9527ce7f8 1 year, 1 month ago: change mode structs to enums Structs have better type safety, but they make allocation more difficult, especially when we have multiple Python modules trying to share the same code.
7e48697f8 1 year, 1 month ago: use mode structs in Point.c
070e1eba6 1 year, 3 months ago: [pre-commit.ci] pre-commit autoupdate (#8993)
2973b041c 2 years, 2 months ago: [pre-commit.ci] auto fixes from pre-commit.com hooks
617e7295a 2 years, 4 months ago: [pre-commit.ci] auto fixes from pre-commit.com hooks
46b7e86ba 6 years ago: Format with ClangFormat
3a75e843f 6 years ago: Added braces
c1d9931ad 6 years ago: Added braces
ae43af61d 6 years ago: Replaced tabs with spaces
7a4af2b76 7 years ago: fix unaligned accesses by using memcpy()
0bb3f4fee 9 years ago: source layout reorg
bda6d1e58 9 years ago: rename ImagingCopyPaletteInfo to ImagingCopyPalette
f6a05fd22 9 years ago: Rename ImagingCopyInfo to ImagingCopyPaletteInfo
e3954aa4e 9 years ago: remove unnecessary ImagingCopyInfos
bb1b3a532 13 years ago: Cleanup WS, courtesy of @Arfrever
4ebf8e71e 17 years ago: Load Imaging-1.1.7 into pil.
56124d728 21 years ago: Load Imaging-1.1.5 into pil.
893c52a89 21 years ago: Load Imaging-1.1.4 into pil.
8ba491eac 21 years ago: Load Imaging-1.1.3 into pil.
178095672 21 years ago: pil 1.1.1 baseline

it's been 7 years since the last substantial change, 7a4af2b, and before that, all we have is an SVN checkin from effbot, 4ebf8e71e, from 2009. Everything else is just "chore" stuff or refactoring side-effects (something refactored elsewhere, touching Point.c).

These proportions are from one machine, one compiler and one OS, and I would not assume they carry to GCC, x86-64 or a different allocator.

You can refer to the CodSpeed results above for another take. If you want, you can also run the same benchmarks (instead of your own harness) on your machine:

# (on main)
uv pip install -e . pytest-benchmark && uv run pytest --benchmark-autosave Tests/benchmarks.py -kpoint
# (on this branch)
uv pip install -e . pytest-benchmark && uv run pytest --benchmark-autosave Tests/benchmarks.py -kpoint

and then use e.g. uv run pytest-benchmark compare --between=min 0001 0002 (--between mode new in pytest-benchmark 5.3.0, courtesy of yours truly) to get a comparison.

@espressolee espressolee left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right: three implementation changes plus the test commit, and Point.c's history weakens my maintenance concern.

Ran Tests/benchmarks.py -kpoint as suggested, base c8c74c8 (merge-base) vs head 1000b1b, CPython 3.14.6 on macOS arm64; two separately run base/head pairs in opposite order gave deltas within about one percentage point:

benchmark (1237x811) ΔMedian
point_transform I −57%
point_lut L −30%
point_transform F −14%
point_lut LA, point_transform LA −9%
point_lut RGBA, point_transform RGBA −9%
point_lut RGB −4.5%

Same direction throughout; magnitudes differ by mode — notably smaller here for LA and RGB than on my harness. The correctness points from my earlier review still hold at this head. Approving.

@akx
akx force-pushed the faster-point branch 2 times, most recently from 04492ca to 4507f6c Compare September 20, 2026 12:50
@akx

akx commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

Rebased post #10026.

@akx
akx force-pushed the faster-point branch 2 times, most recently from f940b0a to 2adc800 Compare October 27, 2026 06:00
@radarhere
radarhere enabled auto-merge (squash) November 11, 2026 03:02
@radarhere
radarhere merged commit 9f8a597 into python-pillow:main Nov 11, 2026
62 checks passed
@akx

akx commented Nov 11, 2026

Copy link
Copy Markdown
Contributor Author

@radarhere Why does it look like the "Rearrange code" commit you added removes the hoists for ysize, as well as explanatory comments?

@radarhere

Copy link
Copy Markdown
Member

I removed the hoists for ysize because they were single use.
I removed the comments because I felt they were sort of obvious? At least in the context of Pillow's broader behaviour.

@akx

akx commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor Author

I removed the hoists for ysize because they were single use.

Ah... no, that's not quite it 😅

The point is that that once you do int ysize = im->ysize; (and we as programmers know that the image's size won't change during the loop), in for(int y = 0; y < ysize; y++) the end point of the loop is more a constant and not something that would need to be loaded from the pointer on every iteration. That allows the compiler to emit more efficient autovectorizing code. With im->ysize, it would need to do deeper control flow analysis to see if any of the operations within that loop might have a side effect to change im->ysize.

For the comments... especially the restrict-safe comments I think are valuable, as they explain why exactly it is safe to use restrict in that context (for instance, ImagingColorLUT3D_linear gained a doc comment noting that imIn and imOut MAY alias each other, which is why we don't restrict there.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants