Feature: CSS Gradient Low Quality Image Placeholders - #2550
Conversation
github-actions
Bot
added
the
[Plugin] Image Placeholders
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## trunk #2550 +/- ##
==========================================
- Coverage 70.35% 69.79% -0.57%
==========================================
Files 91 92 +1
Lines 7867 8121 +254
==========================================
+ Hits 5535 5668 +133
- Misses 2332 2453 +121
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
bf90a65 to
893feee
Compare
|
@westonruter i've addressed your comments now. Two comments remain unresolved - minified css and the inline style for hovering to reveal the lqip css gradient. I responded to those, happy to handle them however you want. |
|
hover css removed now |
|
oh weird, the min.css file i created got skipped by the repo-level gitignore Lines 29 to 38 in 8d70987 Should I just remove the code that loads it? Evidently they arent used anywhere. That's probably something to address in another issue and PR |
westonruter
added
the
[Type] Enhancement
|
No, it's good that the minified file wasn't committed. We need to add CSS minification to the build process the same way we have for JS. |
|
With 6636887 the CSS file should get automatically re-minified whenever the plugin is built (via |
| * @return string|WP_Error Dominant hex color string, or an error on failure. | ||
| * @return array{r: int, g: int, b: int}|WP_Error RGB values (0-255), or WP_Error on failure. | ||
| */ | ||
| public function get_dominant_color() { |
There was a problem hiding this comment.
Feedback from Claude Opus 4.8:
Performance: full-resolution pixel scan when no medium subsize exists
Dominant_Color_Image_Editor_GD::get_dominant_color() now iterates every pixel of the source image in pure PHP (imagecolorat + sRGB→linear LUT + float accumulation), replacing the old resize-to-1×1 approach whose cost was independent of image dimensions. At the same time, dominant_color_get_attachment_file_path() no longer returns false when the requested medium size is missing — the if ( ! isset( $imagedata['sizes'][ $size ] ) ) { return false; } guard was dropped, so it now falls back to the full-resolution original.
In the normal upload flow this is fine: the medium subsize (~300px) is persisted before metadata generation runs, so the loop is ~67k iterations. But when medium is unavailable — e.g. medium_size_w/medium_size_h set to 0, or an original smaller than the medium threshold — a large original (a multi-megapixel -scaled image or bigger) gets scanned pixel-by-pixel in PHP during wp_generate_attachment_metadata. On a several-megapixel image that's multiple seconds of CPU and can exceed max_execution_time, blocking the upload/regeneration. The get_lqip_grid_values() path adds a further redundant has_transparency() pass.
Suggested fix: resize a working copy down to a small fixed size (as the original did) before the per-pixel averaging loop, so cost stays bounded regardless of source resolution.
Severity: conditional (only bites when medium is absent) — worth addressing but not CI-blocking. Not covered by the test suite, since fixtures are small.
The pixel-scan concern is GD-specific. Imagick is not affected.
The difference is in how each engine averages:
- GD (
get_dominant_color) does the averaging itself, in a pure-PHP nestedforloop over every pixel (imagecoloratper pixel). Cost scales withwidth × heightin the PHP layer → the timeout risk. - Imagick (
get_dominant_color) offloads the averaging to ImageMagick's C core: it clones, thenresizeImage( 1, 1, FILTER_LANCZOS, 1 )and reads that single pixel. The averaging happens during the resize, so cost is essentially bounded regardless of source resolution — the same O(1)-from-PHP's-view approach the old GD code used before this PR.
The shared part of the change — dominant_color_get_attachment_file_path() falling back to the full-resolution original when medium is absent — applies to both engines, but it only turns into a problem for GD, because only GD then walks that full-resolution image pixel-by-pixel in PHP. For Imagick, feeding a larger image into a C-level resize-to-1×1 stays cheap (Imagick already holds the decoded image in memory regardless).
get_lqip_grid_values() is bounded for both (GD imagecopyresampled → 3×2, Imagick resizeImage → 3×2), so it doesn't add to the concern.
So the finding applies specifically to the GD editor; sites using Imagick won't hit it.
There was a problem hiding this comment.
I wonder whether we should even be doing this looping over pixels at all... It was added to address #2535 because GD didnt seem to have such a mechanism as Imagick did.
It seems to me that:
- GD is uncommon
- As noted in the OP, the dominant color used generally doesnt have much effect on the final css gradient that's generated, which is why the 1x1 approach remained in use rather than something like ColorThief.
- This feature is so... minor... (just a flash of a gradient while the image downloads for the first time). If the gradient is slightly off from a non-perfect initial dominant color, people wont notice or even care.
- Sticking with 1x1 method wouldnt break any dominant color values that have already been extracted and stored in anyone's db.
Perhaps I should just revert the GD editor to 1x1 to avoid the complexity and overhead?
There was a problem hiding this comment.
Ugh, now the fixes have broken tests because the generated color is different. All the more reason to just go back to basics.
…sed for initial image processing and dominant colours
…never do anything in any test
…ominant_color_get_dominant_color_data. So not redundant to call it afterwards
…e GD tests tun, though not for imagick)
…t stuff coming in other PR. Also, cleaner to just convert in one place for all editors
ea86570 to
02c937c
Compare
|
fixing the unit test failure now |
2295153 to
f8e98c7
Compare
- Wrap wp_image_editors filter registration in load.php with a callback that ensures the core WP_Image_Editor_* classes are loaded before delegating to dominant_color_set_image_editors(), avoiding a potential fatal error if the filter runs early (e.g. during wp_image_editor_supports()). - Cast ImagickPixel::getColor() channel values to int in the Imagick editor to keep the int return contract stable under strict_types when ImageMagick returns floats. - Use the n.e.x.t @SInCE placeholder for the newly added dominant_color_get_attachment_metadata() helper. - Fix typo/grammar in inline comments in the GD and Imagick editor tests.
f8e98c7 to
eb05659
Compare
…back compat and wasn't even necessary in the end
eb05659 to
669d7ac
Compare
|
This is broken while we resolve how to handle |
669d7ac to
290972f
Compare
…k compat while allowing for css lqip to get the rgb values for the dominant color rather than hex string
Register a webpack config for the dominant-color-images plugin that generates assets/lqip.min.css via the shared cssMinifyTransformer, and add the plugin to pluginsWithBuild so the distribution build depends on it. This produces the lqip.min.css that hooks.php enqueues when SCRIPT_DEBUG is off. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review via westonruter
asked Claude Opus 5 to take a look:
> Both tools are wrong, and about the same thing: the two‑argument `round(down, A)` form where the rounding interval `B` is omitted.
>
> ## What the spec says
>
> css-values-4 §10.3:
>
> > The `round(<rounding-strategy>?, A, B?)` function … If the type of A matches `<number>`, then B may be omitted, and defaults to 1. … In all other cases, omitting B is invalid.
>
> `--lqip` is registered as `syntax: "<number>"` (`lqip.css:12-16`), so `A` is a `<number>` and omitting `B` is legal. The code is correct.
>
> ## Why the error points at `mod()` instead of `round()`
>
> Neither tool can establish a type for the `round()` result, so it falls through to `mod()`'s "both arguments must be the same type" check against the literal `4`/`8`. That's also why `lqip.css:27` — `mod(calc(var(--lqip) + 524288), 8)`, no `round()` — is clean in both tools while lines 19‑26 are not.
>
> ## The two tools fail for different reasons
>
> I probed both with variants:
>
> | Expression | PhpStorm | W3C |
> | --------------------------------------- | --------- | --------- |
> | `round(down, 5)` | ok | **error** |
> | `round(down, var(--lqip))` | ok | — |
> | `round(down, calc(var(--lqip) + 1))` | **error** | **error** |
> | `round(down, …, 1)` (explicit interval) | ok | ok |
>
> - **PhpStorm** does implement the number default — it even reads your `@property` to type a bare `var(--lqip)`. It just loses the type when the argument is a `calc()` containing a `var()`. Dropping the redundant `calc()` wrapper (`round(down, (var(--lqip) + 524288) / 262144)`) doesn't help.
> - **W3C/Jigsaw** doesn't implement the omitted-`B` rule at all — even `round(down, 5)` reports "The types are incompatible."
>
> ## Browsers disagree with both
>
> In Chrome 152, with `--lqip: 192900`, the omitted-interval and explicit-interval forms both compute `--lqip-ca: 2`, and `CSS.supports('opacity', 'round(down, 0.5)')` is `true`.
>
> ## If you want the warnings gone
>
> Adding the explicit `, 1` to the eight `round()` calls is a semantic no-op that satisfies both tools. Verified on a copy: W3C goes from 9 errors to 1, PhpStorm to 0.
>
> ```css
> --lqip-ca: mod(round(down, calc((var(--lqip) + 524288) / 262144), 1), 4);
> ```
>
> The remaining W3C error is `Unrecognized at-rule "@Property"` at `lqip.css:12` — a separate Jigsaw gap (it predates css-properties-values-api), and nothing you can or should work around.
290972f to
6db1b1b
Compare
2 participants
Summary
Fixes #2519 and #2535
Note:
This is stacked on/includes #2524, which isn't totally necessary but I think made improvements to the test functions. I can rebase this without any of that if desired.
Relevant technical choices
Implemented the CSS Gradient-based LQIP mechanism described in #2519. Extensive testing was done with various ways to generate the dominant color (the original used ColorThief, which has a php equivalent). On rare occasions, the fancier methods produced somewhat better gradients, but at great processing cost. Ultimately I found that the 1x1 pixel was sufficiently-good - especially given that it is already implemented.
I also changed the GD and Imagick editors to extract the color in linear rgb, as per #2535. Updated some tests to reflect the different results. They all pass for me.
Here's a video that shows the gradients using the previous colorspace (left) and the new colorspace (right), generated by imagick. Generally no difference, but its somewhat better in a few cases.
Kooha-2026-06-25-15-22-14.mp4
Nothing was done to accomodate any sort of transition. To use this, all images would need to be reprocessed. Both the dominant color hex and lqip values are generated and stored in postmeta.
Use of AI Tools
I used Deepseek V4 Flash via Github Copilot to assist with this. I reviewed and iterated on everything.