Backtestshugorun-20261009-153657#12543

Issue #12543 Merged fix PR # Run 9 Oct 2026 · run-20261009-153657 gohugoio/hugo

resources/images: Poor overlay quality when background image is an indexed (not true color) PNG

Better

Our patch was judged better than the merged fix.

In this judgment, Patch B = our agent, Patch A = the merged fix.

Both patches fix the root cause of the issue: the paletted PNG source's palette was being forced onto the result of `Filter`, so overlay and text colors were clamped to the background's palette. Both regenerate the overlay and text golden images to match.

**Correctness.** Patch B is more precise. It quantizes to the source palette only when every filter in the chain cannot introduce new colors (`ImageProcessSpecProvider` such as resize, or orientation filters). Any other filter (overlay, text, grayscale and other color adjustments) disables quantization. So an indexed PNG passed through `images.Process "resize"` or an orientation filter stays indexed, matching normal Resize behavior. Patch A disables palette preservation for every `filter` action. That fixes the issue but changes output for Process/orientation filters on paletted PNGs, which now come out true-color.

**Scope.** Patch A also carries a sizable unrelated change. It switches hex color parsing from `color.RGBA` to `color.NRGBA`, rewrites `ColorGoToHexString`, normalizes `Color.init`, and changes `AddColorToPalette` equality. Its own comment cites a different issue. This churn changes behavior elsewhere: it alters an unrelated golden file (padding-transparent-chained.png) and modifies existing test expectations. That adds risk and obscures the actual fix.

**Tests.** Patch B adds a thorough integration test that would fail before the change and pass after it. It checks that:
- every opaque overlay pixel is reproduced exactly;
- the exact text color appears in the text result;
- the grayscale result contains only gray pixels;
- resize and Process outputs remain paletted.

Patch A's only coverage of the issue itself comes from the regenerated golden images. Its new unit tests cover the unrelated color change.

**Craft.** Patch B's explicit `keepSourcePalette` parameter is clear and well documented. Patch A's `ActionFilter` constant is tidy, but the fix is coarser.

Overall, Patch B is the better, more targeted fix with stronger tests.

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

32m 15s

Wall-clock time in the container

Full test suite

No new failures

1,012 passed · 71 skipped · 1,083 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

137vs 58 merged

Changed lines, ours vs merged

Reference: <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

Our patch+130 −7
resources/image.goindex 467e23f26..84d2f98f6 100644@@ -309,10 +309,19 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) {  	var options []string +	// Filters that may introduce colors not present in the source (e.g. overlay, text, color adjustments)+	// must not have their result quantized to the source palette.+	keepSourcePalette := true+ 	for _, f := range gfilters { 		f = images.UnwrapFilter(f)-		if specProvider, ok := f.(images.ImageProcessSpecProvider); ok {-			options = append(options, strings.Fields(specProvider.ImageProcessSpec())...)+		switch ff := f.(type) {+		case images.ImageProcessSpecProvider:+			options = append(options, strings.Fields(ff.ImageProcessSpec())...)+		case images.ImageFilterFromOrientationProvider:+			// Rotate/flip only, no new colors.+		default:+			keepSourcePalette = false 		} 	} @@ -324,7 +333,7 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) { 	confMain.Action = "filter" 	confMain.Key = hashing.HashString(gfilters) -	return i.doWithImageConfig(confMain, func(src image.Image) (image.Image, error) {+	return i.doWithImageConfig(confMain, keepSourcePalette, func(src image.Image) (image.Image, error) { 		var filters []gift.Filter 		for _, f := range gfilters { 			f = images.UnwrapFilter(f)@@ -373,7 +382,7 @@ func (i *imageResource) processOptions(options []string) (images.ImageResource, 		return nil, err 	} -	img, err := i.doWithImageConfig(conf, func(src image.Image) (image.Image, error) {+	img, err := i.doWithImageConfig(conf, true, func(src image.Image) (image.Image, error) { 		return i.Proc.ApplyFiltersFromConfig(src, conf) 	}) 	if err != nil {@@ -386,7 +395,7 @@ func (i *imageResource) processOptions(options []string) (images.ImageResource, 			// Smartcrop fails silently in some rare cases. 			// Fall back to a center fill. 			conf = conf.Reanchor(gift.CenterAnchor)-			return i.doWithImageConfig(conf, func(src image.Image) (image.Image, error) {+			return i.doWithImageConfig(conf, true, func(src image.Image) (image.Image, error) { 				return i.Proc.ApplyFiltersFromConfig(src, conf) 			}) 		}@@ -405,7 +414,11 @@ func init() { 	imageProcSem = make(chan bool, imageProcWorkers) } -func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src image.Image) (image.Image, error)) (images.ImageResource, error) {+// doWithImageConfig applies f to the decoded source image.+// If keepSourcePalette is set and the source is a paletted PNG, the result is quantized to the source palette.+// This should only be set when f does not introduce colors outside of the source's palette (other than+// those introduced by resampling), see issue 12543.+func (i *imageResource) doWithImageConfig(conf images.ImageConfig, keepSourcePalette bool, f func(src image.Image) (image.Image, error)) (images.ImageResource, error) { 	img, err := i.getSpec().ImageCache.getOrCreate(i, conf, func() (*imageResource, image.Image, error) { 		imageProcSem <- true 		defer func() {@@ -438,7 +451,7 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im 			converted = tmp 		} -		if conf.TargetFormat == images.PNG {+		if keepSourcePalette && conf.TargetFormat == images.PNG { 			// Apply the colour palette from the source 			if paletted, ok := src.(*image.Paletted); ok { 				palette := paletted.Paletteresources/images/images_integration_test.goindex 172449d21..9b89f9b20 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" )@@ -129,6 +134,111 @@ Home. 	) } +// Filters that introduce new colors must not have their result clamped to the+// palette of an indexed (paletted) PNG source.+// See issue 12543.+func TestFilterPalettedPNGIssue12543(t *testing.T) {+	t.Parallel()++	files := `+-- hugo.toml --+disableKinds = ['page','rss','section','sitemap','taxonomy','term']+-- assets/bg.png --+sourcefilename: ../testdata/gohugoio8.png+-- assets/fg.png --+sourcefilename: ../testdata/gohugoio24.png+-- layouts/home.html --+{{ $bg := resources.Get "bg.png" }}+{{ $fg := (resources.Get "fg.png").Resize "100x" }}+{{ $textOpts := dict "color" "#ff0060" "size" 40 "x" 10 "y" 10 }}+{{ with $bg | resources.Copy "images/bg.png" }}{{ .Publish }}{{ end }}+{{ with $fg | resources.Copy "images/fg.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Overlay $fg 20 30) | resources.Copy "images/overlay.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Text "Hugo Rocks!" $textOpts) | resources.Copy "images/text.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter images.Grayscale | resources.Copy "images/grayscale.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Resize "200x" | resources.Copy "images/resize.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Process "resize 200x") | resources.Copy "images/process.png" }}{{ .Publish }}{{ end }}+`++	b := hugolib.Test(t, files)++	decode := func(name string) image.Image {+		t.Helper()+		img, err := png.Decode(strings.NewReader(b.FileContent("public/images/" + name)))+		b.Assert(err, qt.IsNil, qt.Commentf(name))+		return img+	}++	toNRGBA := func(c color.Color) color.NRGBA {+		return color.NRGBAModel.Convert(c).(color.NRGBA)+	}++	bg := decode("bg.png")+	_, bgIsPaletted := bg.(*image.Paletted)+	b.Assert(bgIsPaletted, qt.IsTrue)++	// Overlay: every fully opaque pixel of the overlay must be reproduced exactly.+	fg := decode("fg.png")+	overlay := decode("overlay.png")+	_, isPaletted := overlay.(*image.Paletted)+	b.Assert(isPaletted, qt.IsFalse)+	var opaque, mismatches int+	fgb := fg.Bounds()+	for y := fgb.Min.Y; y < fgb.Max.Y; y++ {+		for x := fgb.Min.X; x < fgb.Max.X; x++ {+			fc := toNRGBA(fg.At(x, y))+			if fc.A != 0xff {+				continue+			}+			opaque+++			if toNRGBA(overlay.At(x-fgb.Min.X+20, y-fgb.Min.Y+30)) != fc {+				mismatches+++			}+		}+	}+	b.Assert(opaque > 0, qt.IsTrue)+	b.Assert(mismatches, qt.Equals, 0)++	// Text: the exact text color must be present in the result.+	text := decode("text.png")+	_, isPaletted = text.(*image.Paletted)+	b.Assert(isPaletted, qt.IsFalse)+	want := color.NRGBA{R: 0xff, G: 0x00, B: 0x60, A: 0xff}+	var found bool+	tb := text.Bounds()+	for y := tb.Min.Y; y < tb.Max.Y && !found; y++ {+		for x := tb.Min.X; x < tb.Max.X; x++ {+			if toNRGBA(text.At(x, y)) == want {+				found = true+				break+			}+		}+	}+	b.Assert(found, qt.IsTrue)++	// Color adjustments: a grayscale result must only contain gray pixels.+	gray := decode("grayscale.png")+	gb := gray.Bounds()+	var nonGray int+	for y := gb.Min.Y; y < gb.Max.Y; y++ {+		for x := gb.Min.X; x < gb.Max.X; x++ {+			c := toNRGBA(gray.At(x, y))+			if c.A != 0 && (c.R != c.G || c.G != c.B) {+				nonGray+++			}+		}+	}+	b.Assert(nonGray, qt.Equals, 0)++	// Resizing does not introduce new colors, so the source palette is kept.+	for _, name := range []string{"resize.png", "process.png"} {+		img := decode(name)+		p, ok := img.(*image.Paletted)+		b.Assert(ok, qt.IsTrue, qt.Commentf(name))+		b.Assert(p.Bounds().Dx(), qt.Equals, 200, qt.Commentf(name))+	}+}+ func BenchmarkImageResize(b *testing.B) { 	files := ` -- content/p1/sunrise.jpg --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 
Merged fix · PR #+39 −19
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