Backtestshugorun-20260930-140149#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 make the same core fix in `resources/image.go`: they skip re-applying the source image's palette when the action is a filter. This addresses the root cause, since `images.Overlay` and `images.Text` output was being clamped back to the indexed PNG's palette. Both also update the paletted overlay and text golden images. Patch A adds an `ActionFilter` constant, which is slightly cleaner than B's string literal "filter". However, Patch A also bundles a separate change for a different issue (12536). It switches hex parsing from `color.RGBA` to `color.NRGBA`, normalizes `Color.init` to NRGBA (which changes stored colors and luminance input), and rewrites `ColorGoToHexString` and `AddColorToPalette` equality semantics. It also regenerates an unrelated golden file (`padding-transparent-chained.png`) and edits existing color test expectations. That is unrelated behavior change in a widely used color path, so it adds regression risk and obscures the actual fix. On tests, Patch B adds a targeted integration test. It overlays a JPEG onto an indexed PNG, then asserts the output is not paletted and has more distinct colors than the source palette. This test would fail before the fix and pass after it. Patch A's coverage for this issue is only the regenerated golden images; its new unit tests concern the unrelated hex/NRGBA change. With equal correctness on the reported issue, B wins on a real regression test and a tighter, lower-risk scope.
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
39m 35s22 turns
Wall-clock time in the container
Full test suite
No new failures
3,752 passed · 99 skipped · 3,853 total
Contamination audit
Clean
No sign the agent saw the real fix
Patch size
51vs 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..cf5134fcf 100644@@ -438,7 +438,9 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im converted = tmp } - if conf.TargetFormat == images.PNG {+ // Filters may introduce colors not in the source palette (e.g. overlays, text),+ // so only re-apply the source palette for resize/fit/fill/crop.+ if conf.TargetFormat == images.PNG && conf.Action != "filter" { // Apply the colour palette from the source if paletted, ok := src.(*image.Paletted); ok { palette := paletted.Paletteresources/images/images_integration_test.goindex 172449d21..6c5213a38 100644@@ -14,9 +14,14 @@ package images_test import (+ "image"+ "image/color"+ "image/png"+ "strings" "testing" "github.com/bep/logg"+ qt "github.com/frankban/quicktest" "github.com/gohugoio/hugo/htesting" "github.com/gohugoio/hugo/hugolib" )@@ -105,6 +110,48 @@ CropSmart: {{ .Width }}x{{ .Height }}| b.AssertFileContent("public/index.html", "Original: 900x562|CropTopLeft: 900x561|CropSmart: 900x561|") } +// Filtering an indexed PNG must not clamp the result to the source palette.+// See issue 12543.+func TestFilterPalettedPNGNotClampedToSourcePalette(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 --+{{ $bg := resources.Get "gohugoio8.png" }}+{{ $sunset := (resources.Get "sunset.jpg").Resize "x160" }}+{{ with $bg.Filter (images.Overlay $sunset 0 0) | resources.Copy "images/overlay.png" }}{{ .Publish }}{{ end }}+`++ b := hugolib.Test(t, files)++ decode := func(filename string) image.Image {+ img, err := png.Decode(strings.NewReader(b.FileContent(filename)))+ b.Assert(err, qt.IsNil)+ return img+ }++ src, ok := decode("assets/gohugoio8.png").(*image.Paletted)+ b.Assert(ok, qt.IsTrue)++ overlay := decode("public/images/overlay.png")+ _, ok = overlay.(*image.Paletted)+ b.Assert(ok, qt.IsFalse)++ colors := make(map[color.Color]bool)+ bounds := overlay.Bounds()+ for y := bounds.Min.Y; y < bounds.Max.Y; y++ {+ for x := bounds.Min.X; x < bounds.Max.X; x++ {+ colors[color.NRGBAModel.Convert(overlay.At(x, y))] = true+ }+ }+ b.Assert(len(colors) > len(src.Palette), qt.IsTrue, qt.Commentf("got %d colors, source palette has %d", len(colors), len(src.Palette)))+}+ func TestImagingGlobalsDeprecated(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
I fixed the bug: an overlay or text filter on an indexed PNG now keeps the new colors instead of being squeezed back into the background's palette. I couldn't verify it through ./bt-test, though. Its test run can't download Go modules because there's no network, so the package failed to build and no tests ran. All the results below come from running go test directly against the module cache already on disk (GOMODCACHE=/bt/cache/go-mod GOPROXY=off).
What was wrong: After any image operation, doWithImageConfig in resources/image.go checked whether the source was an indexed PNG. If it was, it redrew the result using only the source's palette (at most 256 colors). That's fine for resize, fit, fill and crop, which don't add colors. But overlays and text do add colors, so the composite was reduced to the background's palette. GIFs weren't affected because this step only runs for PNG output.
What I changed:
- The fix (
resources/image.go:441): that palette step is now skipped when the operation is a filter (conf.Action != "filter"). Resize, fit, fill and crop still keep the palette. - Golden images: I regenerated
resources/images/testdata/images_golden/filters/paletted/overlay.pngandtext.png. The most recent commit added them with the note that they were made before any fix. So they captured the bad output, and the oldoverlay.pngis itself an indexed 256-color image. I didn't change the test code inTestImagesGoldenFiltersPaletted, and no other golden files changed. - New test:
TestFilterPalettedPNGNotClampedToSourcePaletteinresources/images/images_integration_test.go. It overlayssunset.jpgon the indexedgohugoio8.pngwithimages.Overlay. It then checks that the published PNG is not indexed and has more distinct colors than the source palette.
Test results:
- Before the fix:
TestImagesGoldenFiltersPalettedpassed against the bad golden files. - Fix applied, old golden files: it failed on
overlay.png. After regenerating, it passes. - New test with the fix temporarily removed: it failed (the output was still indexed). With the fix, it passes.
- Wider runs:
./resources/images/,./resources/and./tpl/images/all pass. Across./resources/..., only two tests failed:TestGetRemoteHeadandTestGetRemoteResponseHeaders. Both fetchhttps://gohugo.io/img/hugo.pngand got "Forbidden" because there's no network, so they're unrelated to this change.
Side effects:
- Any filter on an indexed PNG, including grayscale or brightness, now writes a full-color PNG, so those files can be larger. This makes sense because any filter can add colors, but it may be worth a release note.
- Filtered images already cached in
resources/_genwill keep the old output until that cache is cleared. Bumping the PNG format version would force a refresh, but it would also invalidate every cached PNG, so I didn't do it.
What the report asked for:
- Better overlay quality on an indexed PNG background: done, with the new test and the updated golden
overlay.png. - Output no longer limited to the background's palette: done. The new test checks the output isn't indexed and has more colors than the palette.
- Confirm it isn't an upstream
giftproblem: it isn't. The palette step was in Hugo'sresources/image.go, not ingift. - GIFs work fine: unchanged. The palette step only applies to PNG output, and the GIF tests still pass.
Everything is left as uncommitted changes. AGENTS.md and CLAUDE.md were already showing as deleted before I started, and I didn't touch them.