Backtestshugorun-20260922-141813#12543
resources/images: Poor overlay quality when background image is an indexed (not true color) PNG
Our patch was judged better than the merged fix.
In this judgment, Patch B = our agent, Patch A = the merged fix.
Both patches contain the identical root-cause fix for issue 12543: they add the `images.ActionFilter` constant, tag filter operations with it, and gate the source-palette re-application in `doWithImageConfig` with `conf.Action != images.ActionFilter` so overlay/text output is no longer clamped back to an indexed PNG's palette. On correctness of the reported issue they are equivalent. The deciding factors are tests and scope. Patch B adds a targeted regression test, `TestImagesFiltersPalettedIsTrueColor`, that overlays true-color content (sunset.jpg) onto an indexed PNG and asserts the published output is NOT `*image.Paletted`. That test would fail before the fix (paletted, quality-limited) and pass after, directly exercising the exact scenario the issue describes. Patch A adds no such assertion for the actual issue — its only evidence for the overlay fix is opaque updated golden binaries, and its new test additions (color_test.go) exercise a *different* concern. Which leads to scope: Patch A bundles a substantial, unrelated change to resources/images/color.go (NRGBA normalization, ColorGoToHexString un-premultiplication, AddColorToPalette value comparison, hexStringToColorGo returning NRGBA) explicitly attributed to issue 12536, not 12543. That is scope creep against this issue, and its ripple is visible: it forces an extra golden change (padding-transparent-chained.png) beyond the overlay/text goldens both patches touch, signaling broader behavioral impact unrelated to the overlay bug. Under the ordered criteria — equal correctness on the reported issue, superior and directly-relevant test coverage in B, and tighter scope in B — Patch B is the better fix. Patch A's color work may be valid on its own merits, but it belongs to a separate issue and dilutes a focused fix.
The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.
Solve
28m 46s34 turns
Wall-clock time in the container
Full test suite
No new failures
3,748 passed · 99 skipped · 3,853 total
Contamination audit
Unknown
See the audit notes for this run
Patch size
52vs 58 merged
Changed lines, ours vs merged
The issue
View on GitHubReference: <https://discourse.gohugo.io/t/image-overlay-quality-is-poor/50034>
Before getting into the details, I have verified that this is not an upstream issue with disintegration/gift. I tested with this:
<details>
<summary>main.go</summary>
package main
import (
"image"
"image/png"
"log"
"os"
_ "image/png"
"github.com/disintegration/gift"
)
func main() {
// Get the background image (24 bit: indexed not true color)
f, err := os.Open("background.png")
if err != nil {
log.Fatal(err)
}
bgImage, _, err := image.Decode(f)
if err != nil {
log.Fatal(err)
}
// Get the foreground image (24 bit with 8 bit alpha channel)
f, err = os.Open("foreground.png")
if err != nil {
log.Fatal(err)
}
fgImage, _, err := image.Decode(f)
if err != nil {
log.Fatal(err)
}
// Create a new image with dimensions of the bgImage.
dstImage := image.NewRGBA(bgImage.Bounds())
// Copy the bgImage to the dstImage.
gift.New().Draw(dstImage, bgImage)
// Draw the fgImage over the dstImage at the (20, 20) position.
gift.New().DrawAt(dstImage, fgImage, image.Pt(20, 20), gift.OverOperator)
// Create the composite file.
f, err = os.Create("composite.png")
if err != nil {
log.Fatal(err)
}
defer f.Close()
// Encode the composite image.
err = png.Encode(f, dstImage)
if err != nil {
log.Fatal(err)
}
}
</details>
Details:
- Background image is a 24 bit indexed PNG file with 256 colors in its palette
- Foreground image is a 24 bit true color PNG with an 8 bit alpha channel
- The final (composite) image seems to be limited to the palette of the background image
Simple example:
git clone --single-branch -b hugo-github-issue-12543 https://github.com/jmooring/hugo-testing hugo-github-issue-12543
cd hugo-github-issue-12543
hugo server
Note that GIF images (also indexed) work fine.
The two patches
resources/image.goindex 467e23f26..fb776afa0 100644@@ -321,7 +321,7 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) { return nil, err } - confMain.Action = "filter"+ confMain.Action = images.ActionFilter confMain.Key = hashing.HashString(gfilters) return i.doWithImageConfig(confMain, func(src image.Image) (image.Image, error) {@@ -438,7 +438,11 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im converted = tmp } - if conf.TargetFormat == images.PNG {+ // Preserve the source palette for indexed PNGs on geometric transforms (resize/crop/fit/fill)+ // to keep the output small, but not for filter operations (e.g. overlay, text): those may+ // composite true color content, and clamping back to the source palette destroys quality.+ // See issue 12543.+ if conf.TargetFormat == images.PNG && conf.Action != images.ActionFilter { // Apply the colour palette from the source if paletted, ok := src.(*image.Paletted); ok { palette := paletted.Paletteresources/images/config.goindex 4cbd7e629..e8fd69c94 100644@@ -36,6 +36,7 @@ const ( ActionCrop = "crop" ActionFit = "fit" ActionFill = "fill"+ ActionFilter = "filter" ) var Actions = map[string]bool{resources/images/images_golden_integration_test.goindex 8367c43b2..a8840f270 100644@@ -14,10 +14,15 @@ package images_test import (+ "image" _ "image/jpeg"+ "os"+ "path/filepath" "strings" "testing" + qt "github.com/frankban/quicktest"+ "github.com/gohugoio/hugo/hugolib" "github.com/gohugoio/hugo/resources/images/imagetesting" ) @@ -371,6 +376,44 @@ Home. imagetesting.RunGolden(opts) } +// Overlaying true color content onto an indexed PNG must not clamp the result to the source palette. See issue 12543.+func TestImagesFiltersPalettedIsTrueColor(t *testing.T) {+ t.Parallel()++ files := `+-- hugo.toml --+-- assets/gohugoio8.png --+sourcefilename: ../testdata/gohugoio8.png+-- assets/sunset.jpg --+sourcefilename: ../testdata/sunset.jpg+-- layouts/home.html --+Home.+{{ $bg := (resources.Get "gohugoio8.png").Resize "500x" }}+{{ $sunset := (resources.Get "sunset.jpg").Resize "x160" }}+{{ $overlay := $bg.Filter (images.Overlay $sunset 230 70) }}+{{ with $overlay | resources.Copy "images/overlay.png" }}{{ .Publish }}{{ end }}+`++ c := hugolib.Test(t, files, hugolib.TestOptWithConfig(func(conf *hugolib.IntegrationTestConfig) {+ conf.NeedsOsFS = true+ }))++ codec := c.H.ResourceSpec.Imaging.Codec++ c.AssertFileContent("public/index.html", "Home.")++ outputDir := filepath.Join(c.H.Conf.WorkingDir(), "public", "images")+ f, err := os.Open(filepath.Join(outputDir, "overlay.png"))+ c.Assert(err, qt.IsNil)+ defer f.Close()++ img, err := codec.Decode(f)+ c.Assert(err, qt.IsNil)++ _, ok := img.(*image.Paletted)+ c.Assert(ok, qt.IsFalse, qt.Commentf("overlay of an indexed PNG must be true color, not palette-limited (issue 12543)"))+}+ func TestImagesGoldenProcessMisc(t *testing.T) { t.Parallel() resources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fd..631854dd8 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/overlay.png and b/resources/images/testdata/images_golden/filters/paletted/overlay.png differresources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d..65d1a60ce 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/text.png and b/resources/images/testdata/images_golden/filters/paletted/text.png differ
resources/image.goindex 467e23f26..a2ed5f3c9 100644@@ -321,7 +321,7 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) { return nil, err } - confMain.Action = "filter"+ confMain.Action = images.ActionFilter confMain.Key = hashing.HashString(gfilters) return i.doWithImageConfig(confMain, func(src image.Image) (image.Image, error) {@@ -438,7 +438,11 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im converted = tmp } - if conf.TargetFormat == images.PNG {+ // Preserve the source palette for the geometric actions so an indexed+ // PNG stays indexed. Filters (e.g. images.Overlay, images.Text) routinely+ // introduce colors outside the source palette, and clamping the result+ // back to that palette destroys the filtered output. See issue 12543.+ if conf.TargetFormat == images.PNG && conf.Action != images.ActionFilter { // Apply the colour palette from the source if paletted, ok := src.(*image.Paletted); ok { palette := paletted.Paletteresources/images/color.goindex fe233c7b7..72f3710e3 100644@@ -69,9 +69,12 @@ func (c Color) Key() string { } func (c *Color) init() error {- c.hex = ColorGoToHexString(c.color)- r, g, b, _ := c.color.RGBA()- c.luminance = 0.2126*c.toSRGB(uint8(r)) + 0.7152*c.toSRGB(uint8(g)) + 0.0722*c.toSRGB(uint8(b))+ // Normalize to the canonical non-premultiplied form so that equal colors+ // compare equal whether they came from a hex string or from image pixels.+ nrgba := color.NRGBAModel.Convert(c.color).(color.NRGBA)+ c.color = nrgba+ c.hex = ColorGoToHexString(nrgba)+ c.luminance = 0.2126*c.toSRGB(nrgba.R) + 0.7152*c.toSRGB(nrgba.G) + 0.0722*c.toSRGB(nrgba.B) return nil } @@ -88,10 +91,13 @@ func (c Color) toSRGB(i uint8) float64 { // Note that it does no additional checks, so callers must make sure // that the palette is valid for the relevant format. func AddColorToPalette(c color.Color, p color.Palette) color.Palette {- var found bool- if slices.Contains(p, c) {- found = true- }+ // Compare color values rather than interface values, so that e.g. a+ // color.NRGBA is found even if the palette holds it as a color.RGBA.+ cr, cg, cb, ca := c.RGBA()+ found := slices.ContainsFunc(p, func(v color.Color) bool {+ vr, vg, vb, va := v.RGBA()+ return cr == vr && cg == vg && cb == vb && ca == va+ }) if !found { p = append(color.Palette{c}, p...)@@ -108,12 +114,13 @@ func ReplaceColorInPalette(c color.Color, p color.Palette) { // ColorGoToHexString converts a color.Color to a hex string. func ColorGoToHexString(c color.Color) string {- r, g, b, a := c.RGBA()- rgba := color.RGBA{uint8(r), uint8(g), uint8(b), uint8(a)}- if rgba.A == 0xff {- return fmt.Sprintf("#%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B)+ // Hex notation is not alpha-premultiplied, so convert via NRGBA to+ // un-premultiply the color components of any transparent color.+ nrgba := color.NRGBAModel.Convert(c).(color.NRGBA)+ if nrgba.A == 0xff {+ return fmt.Sprintf("#%.2x%.2x%.2x", nrgba.R, nrgba.G, nrgba.B) }- return fmt.Sprintf("#%.2x%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B, rgba.A)+ return fmt.Sprintf("#%.2x%.2x%.2x%.2x", nrgba.R, nrgba.G, nrgba.B, nrgba.A) } // ColorGoToColor converts a color.Color to a Color.@@ -195,5 +202,8 @@ func hexStringToColorGo(s string) (color.Color, error) { return nil, err } - return color.RGBA{b[0], b[1], b[2], b[3]}, nil+ // Hex notation is not alpha-premultiplied, so this must be a color.NRGBA;+ // as a color.RGBA any transparent color would be invalid (component > alpha)+ // and corrupted when drawn onto an alpha-premultiplied image. See issue 12536.+ return color.NRGBA{b[0], b[1], b[2], b[3]}, nil }resources/images/color_test.goindex 540f3bea8..47bc5ae8b 100644@@ -39,8 +39,12 @@ func TestHexStringToColor(t *testing.T) { {"#ffffff", color.White}, {"ffffff", color.White}, {"#000", color.Black},- {"#4287f5", color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}},- {"777", color.RGBA{R: 0x77, G: 0x77, B: 0x77, A: 0xff}},+ {"#4287f5", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}},+ {"777", color.NRGBA{R: 0x77, G: 0x77, B: 0x77, A: 0xff}},+ // Hex notation is not alpha-premultiplied, so a transparent color+ // must parse to a color.NRGBA. See issue 12536.+ {"#00f7", color.NRGBA{R: 0x00, G: 0x00, B: 0xff, A: 0x77}},+ {"4287f580", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}}, } { c.Run(test.arg, func(c *qt.C) {@@ -71,10 +75,11 @@ func TestColorToHexString(t *testing.T) { {color.Black, "#000000"}, {color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}, "#4287f5"}, - // 50% opacity.+ // 50% opacity. Hex notation is not alpha-premultiplied, so the+ // components of a transparent color are the non-premultiplied ones. // Note that the .Colors (dominant colors) received from the Image resource // will always have an alpha value of 0xff.- {color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}, "#4287f580"},+ {color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}, "#4287f580"}, } { c.Run(test.expect, func(c *qt.C) {resources/images/config.goindex 4cbd7e629..e8fd69c94 100644@@ -36,6 +36,7 @@ const ( ActionCrop = "crop" ActionFit = "fit" ActionFill = "fill"+ ActionFilter = "filter" ) var Actions = map[string]bool{resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.pngindex 899e21f25..34392755c 100644Binary files a/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png and b/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png differresources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fd..631854dd8 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/overlay.png and b/resources/images/testdata/images_golden/filters/paletted/overlay.png differresources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d..65d1a60ce 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/text.png and b/resources/images/testdata/images_golden/filters/paletted/text.png differ
What the agent reported
The review confirms the fix is correct, minimal, and well-scoped. All work is complete.
Summary
What was wrong
When a background image was an indexed (palette-based, ≤256-color) PNG, compositing filters like images.Overlay and images.Text produced palette-limited output of poor quality. The root cause was in resources/image.go's doWithImageConfig: for any PNG-target operation whose decoded source was *image.Paletted, a block re-applied the source's palette via Floyd–Steinberg dithering, throwing away the true-color result that doFilter had correctly produced. This palette clamping is a legitimate size optimization for geometric transforms (resize/crop/fit/fill), but for .Filter operations it destroys the newly composited true-color content. GIFs were unaffected because they flow through a separate animated code path.
What I changed
resources/images/config.go: added constantActionFilter = "filter"(not added to the geometric-onlyActionsmap).resources/image.go: replaced the bare"filter"literal withimages.ActionFilter, and gated the palette re-application block withconf.Action != images.ActionFilterso it is skipped for filter operations while still preserving indexed output for resize/crop/fit/fill.resources/images/images_golden_integration_test.go: added regression testTestImagesFiltersPalettedIsTrueColorthat overlays a true-color sunset onto an indexed PNG and asserts the published PNG is not*image.Paletted.- Regenerated the two buggy pre-fix golden binaries
.../filters/paletted/overlay.pngandtext.png(colortype 3 → 2, true color). No other goldens changed.
Test evidence
- New regression test failed before the fix (
got: bool(true)— output was*image.Paletted) and passes after. TestImagesGoldenFiltersPalettedpasses against the corrected true-color goldens.- Full-package gates all green:
./resources/images/,./resources/(incl.TestImageResize8BitPNG, which confirms resize-of-indexed-PNG behavior is unchanged), and./tpl/images/. git diff --statconfirms only the two paletted filter goldens changed; resize/process goldens untouched.
Requirements checklist
- Fix poor overlay quality for indexed-PNG backgrounds → implemented; output is now true color (test + regenerated golden evidence).
images.Texton indexed PNG (the report's second filter case) → implemented by the same gate; regression-guarded via the correctedtext.pnggolden.- Preserve "GIFs work fine" and don't regress geometric resize of indexed PNGs → verified unchanged: resize goldens byte-identical,
TestImageResize8BitPNGstill passes, GIF/animated path untouched.
All changes are left uncommitted in the working tree.