Backtestshugorun-20261013-011256#12543

Issue #12543 Merged fix PR # Run 13 Oct 2026 · run-20261013-011256 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 the same way: they skip re-quantizing the output to the source palette when filters can add new colors. That is what clamps an Overlay onto an indexed PNG to the background's 256 colors. Both update the paletted overlay.png and text.png golden images to match.

Patch B is more precise. It still keeps the source palette when every filter is geometric (images.Process specs or orientation filters). It drops the palette only when a color-introducing filter such as Overlay, Text, Padding or Grayscale is present. Patch A drops palette preservation for every `Filter` call, so `$img.Filter (images.Process "resize 100x")` or AutoOrient on an indexed PNG now loses its palette. That is an unnecessary behavior regression relative to the plain Resize path.

Patch A also bundles a separate change for a different issue (12536). It switches hex color parsing from RGBA to NRGBA and rewrites ColorGoToHexString, Color.init and AddColorToPalette. This alters semantics beyond the issue and changes an unrelated golden image (padding-transparent-chained.png). That adds risk and obscures the fix.

On tests, Patch B adds a targeted integration test. It checks pixel by pixel that the overlay keeps the foreground's colors and that the text color and padding color are preserved. It checks that grayscale output is truly gray and that a purely geometric Process still yields a paletted image. This test would fail before the fix. Patch A's test changes are mostly about the unrelated hex/NRGBA work, and it relies on golden-image updates for the actual issue.

B is more correct, better tested and better scoped.

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

1h 23m

Wall-clock time in the container

Full test suite

No new failures

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

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

123vs 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+116 −7
resources/image.goindex 467e23f26..f8416eccd 100644@@ -309,10 +309,20 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) {  	var options []string +	// Filters such as Overlay, Text, Padding or Grayscale may introduce colors+	// that are not in the source's palette, so we only quantize the result back+	// to the source palette if all filters are geometric (resize, crop, rotate etc.).+	// See issue 12543.+	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:+		default:+			keepSourcePalette = false 		} 	} @@ -324,7 +334,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 +383,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 +396,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 +415,10 @@ 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 processes the image using f.+// If keepSourcePalette is set and the source is a paletted image and the target is PNG,+// the result is quantized to the source's palette.+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 conf.TargetFormat == images.PNG && keepSourcePalette { 			// Apply the colour palette from the source 			if paletted, ok := src.(*image.Paletted); ok { 				palette := paletted.Paletteresources/images/images_integration_test.goindex 172449d21..78af1bbb8 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" )@@ -182,3 +187,94 @@ Page. 		builder.Build() 	} }++// Issue 12543.+func TestFilterPalettedPNGDoesNotClampToSourcePalette(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" }}+{{ $fg := (resources.Get "sunset.jpg").Resize "x60 png" }}+{{ $textOpts := dict "color" "#ff0060" "size" 40 "x" 10 "y" 10 }}+{{ with $fg | resources.Copy "fg.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Overlay $fg 20 30) | resources.Copy "overlay.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Text "Hugo" $textOpts) | resources.Copy "text.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Padding 10 "#00ff7f") | resources.Copy "padding.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter images.Grayscale | resources.Copy "grayscale.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Process "resize 100x") | resources.Copy "resized.png" }}{{ .Publish }}{{ end }}+`++	b := hugolib.Test(t, files)++	decode := func(filename string) image.Image {+		t.Helper()+		img, err := png.Decode(strings.NewReader(b.FileContent(filename)))+		b.Assert(err, qt.IsNil)+		return img+	}++	eqRGBA := func(c1, c2 color.Color) bool {+		r1, g1, b1, a1 := c1.RGBA()+		r2, g2, b2, a2 := c2.RGBA()+		return r1 == r2 && g1 == g2 && b1 == b2 && a1 == a2+	}++	// Make sure the test source is a paletted image.+	_, isPaletted := decode("assets/gohugoio8.png").(*image.Paletted)+	b.Assert(isPaletted, qt.IsTrue)++	// The overlay must be drawn with its original colors.+	fg := decode("public/fg.png")+	overlay := decode("public/overlay.png")+	b.Assert(fg.Bounds().Dx() > 0, qt.IsTrue)+	var mismatches int+	for y := fg.Bounds().Min.Y; y < fg.Bounds().Max.Y; y++ {+		for x := fg.Bounds().Min.X; x < fg.Bounds().Max.X; x++ {+			if !eqRGBA(fg.At(x, y), overlay.At(x+20, y+30)) {+				mismatches+++			}+		}+	}+	b.Assert(mismatches, qt.Equals, 0)++	containsColor := func(img image.Image, c color.Color) bool {+		for y := img.Bounds().Min.Y; y < img.Bounds().Max.Y; y++ {+			for x := img.Bounds().Min.X; x < img.Bounds().Max.X; x++ {+				if eqRGBA(img.At(x, y), c) {+					return true+				}+			}+		}+		return false+	}++	// The text must be drawn with its original color.+	b.Assert(containsColor(decode("public/text.png"), color.NRGBA{R: 0xff, G: 0x00, B: 0x60, A: 0xff}), qt.IsTrue)++	// The padding must be filled with the given color.+	padding := decode("public/padding.png")+	b.Assert(eqRGBA(padding.At(0, 0), color.NRGBA{R: 0x00, G: 0xff, B: 0x7f, A: 0xff}), qt.IsTrue)++	// Grayscale must produce only gray pixels.+	grayscale := decode("public/grayscale.png")+	var nonGray int+	for y := grayscale.Bounds().Min.Y; y < grayscale.Bounds().Max.Y; y++ {+		for x := grayscale.Bounds().Min.X; x < grayscale.Bounds().Max.X; x++ {+			r, g, bb, _ := grayscale.At(x, y).RGBA()+			if r != g || g != bb {+				nonGray+++			}+		}+	}+	b.Assert(nonGray, qt.Equals, 0)++	// Pure geometric processing still keeps the source palette.+	_, isPaletted = decode("public/resized.png").(*image.Paletted)+	b.Assert(isPaletted, qt.IsTrue)+}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