add dithering option and integrate pushd-dither tool

Author: jtomson

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "plugins/pushd-dither"]
+	path = plugins/pushd-dither
+	url = git@github.com:pushd/pushd-dither.git

docker/Dockerfile

@@ -31,6 +31,27 @@ RUN apt-get update \
   && ln -s /usr/lib/$(uname -m)-linux-gnu/libtcmalloc_minimal.so.4 /usr/local/lib/libtcmalloc_minimal.so \
   && rm -rf /var/lib/apt/lists/*
 
+# ====== PUSHD DITHER ========
+# This is a temporary solution to install pushd-dither
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+      python3 \
+      python3-pip \
+      python3-dev \
+      gfortran \
+      libopencv-dev \
+      curl
+
+RUN pip3 install scikit-image opencv-python numpy Pillow --break-system-packages
+
+COPY plugins/pushd-dither /opt/pushd-dither/
+
+RUN cd /opt/pushd-dither \
+    && python3 -m pip install -e . --break-system-packages --target=/usr/local/lib/python3.11/
+
+# ====== END PUSHD DITHER ========
+
+
 COPY docker/entrypoint.sh /usr/local/bin/
 COPY --from=build /usr/local/bin/imgproxy /usr/local/bin/
 COPY --from=build /usr/local/lib /usr/local/lib

options/processing_options.go

@@ -52,11 +52,18 @@ type TrimOptions struct {
 	EqualVer  bool
 }
 
-type backgroundOptions struct {
+type BackgroundOptions struct {
 	Color  vips.Color
 	Effect string
 }
 
+type DitherType string
+
+const (
+	DitherNone DitherType = "none"
+	DitherBNFS DitherType = "bnfs" // Blue noise, Floyd-Steinberg
+)
+
 type WatermarkOptions struct {
 	Enabled   bool
 	Opacity   float64
@@ -87,10 +94,11 @@ type ProcessingOptions struct {
 	FormatQuality     map[imagetype.Type]int
 	MaxBytes          int
 	Flatten           bool
-	Background        backgroundOptions
+	Background        BackgroundOptions
 	Blur              float32
 	Sharpen           float32
 	Pixelate          int
+	Dither            DitherType
 	StripMetadata     bool
 	KeepCopyright     bool
 	StripColorProfile bool
@@ -139,10 +147,11 @@ func NewProcessingOptions() *ProcessingOptions {
 		Quality:           0,
 		MaxBytes:          0,
 		Format:            imagetype.Unknown,
-		Background:        backgroundOptions{Color: vips.Color{R: 255, G: 255, B: 255}},
+		Background:        BackgroundOptions{Color: vips.Color{R: 255, G: 255, B: 255}},
 		Blur:              0,
 		Sharpen:           0,
 		Dpr:               1,
+		Dither:            DitherNone,
 		Watermark:         WatermarkOptions{Opacity: 1, Replicate: false, Gravity: GravityOptions{Type: GravityCenter}},
 		StripMetadata:     config.StripMetadata,
 		KeepCopyright:     config.KeepCopyright,
@@ -700,6 +709,22 @@ func applyPixelateOption(po *ProcessingOptions, args []string) error {
 	return nil
 }
 
+func applyDitherOption(po *ProcessingOptions, args []string) error {
+	if len(args) > 1 {
+		return fmt.Errorf("Invalid dither arguments: %v", args)
+	}
+
+	switch args[0] {
+	case "bnfs":
+		po.Dither = DitherBNFS
+	case "none":
+		po.Dither = DitherNone
+	default:
+		return fmt.Errorf("Invalid dither: %s", args[0])
+	}
+	return nil
+}
+
 func applyPresetOption(po *ProcessingOptions, args []string) error {
 	for _, preset := range args {
 		if p, ok := presets[preset]; ok {
@@ -1033,6 +1058,8 @@ func applyURLOption(po *ProcessingOptions, name string, args []string) error {
 		return applySharpenOption(po, args)
 	case "pixelate", "pix":
 		return applyPixelateOption(po, args)
+	case "dither", "dit":
+		return applyDitherOption(po, args)
 	case "watermark", "wm":
 		return applyWatermarkOption(po, args)
 	case "strip_metadata", "sm":

plugins/pushd-dither

@@ -0,0 +1,92 @@
+package processing
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+
+	"github.com/imgproxy/imgproxy/v3/imagedata"
+	"github.com/imgproxy/imgproxy/v3/imagetype"
+	"github.com/imgproxy/imgproxy/v3/options"
+	"github.com/imgproxy/imgproxy/v3/security"
+	"github.com/imgproxy/imgproxy/v3/vips"
+	log "github.com/sirupsen/logrus"
+)
+
+func dither(pctx *pipelineContext, img *vips.Image, po *options.ProcessingOptions, imgdata *imagedata.ImageData) error {
+	if po.Dither != options.DitherBNFS {
+		return nil
+	}
+
+	// Get a snapshot of current image
+	if err := img.CopyMemory(); err != nil {
+		return err
+	}
+
+	// write to temp file
+	f, err := os.CreateTemp("", "dither*.png")
+	if err != nil {
+		return err
+	}
+
+	// clean up temp file with error logging
+	defer func(name string) {
+		if err := os.Remove(name); err != nil {
+			log.Errorf("failed to remove temp file: %s", err)
+		}
+	}(f.Name())
+
+	pngData, err := img.Save(imagetype.PNG, 0)
+	if err != nil {
+		return err
+	}
+	defer pngData.Close()
+
+	if err := os.WriteFile(f.Name(), pngData.Data, 0644); err != nil {
+		return err
+	}
+
+	// the dirty business - will clobber the file
+	if err := shellOutDither(f.Name()); err != nil {
+		return err
+	}
+
+	// read from dithered file
+	ditheredData, err := imagedata.FromFile(f.Name(), "dithered image", security.DefaultOptions())
+	if err != nil {
+		return err
+	}
+
+	ditheredImg := new(vips.Image)
+	if err := ditheredImg.Load(ditheredData, 1, 1.0, 1); err != nil {
+		return err
+	}
+
+	defer ditheredImg.Clear()
+	defer ditheredData.Close()
+
+	// always use png for output
+	po.Format = imagetype.PNG
+
+	// replace original image
+	// FIXME: use copy? embed image is a bit of a hack on a hack to not have to manage the png data lifecycle
+	return img.EmbedImage(0, 0, ditheredImg)
+}
+
+func shellOutDither(inFile string) error {
+	// installed via Dockerfile in /opt/pushd-dither
+	outFile := fmt.Sprintf("%s-dithered-tmp.png", inFile)
+	cmd := exec.Command("python3",
+		"test.py",
+		"--pal-meter-13",
+		"--image-in", inFile,
+		"--image-out", outFile)
+	cmd.Dir = "/opt/pushd-dither"
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("dither failed: %s: %s", err, output)
+	}
+
+	// clobber the original file
+	return os.Rename(outFile, inFile)
+}

processing/dither.go

@@ -35,6 +35,7 @@ var mainPipeline = pipeline{
 	fixSize,
 	flatten,
 	watermark,
+	dither,
 	exportColorProfile,
 	stripMetadata,
 }