gither

gither is a Go dithering toolkit with two equally important surfaces:

• a CLI for batch image conversion
• a Go library for embedding dithering directly into your own code

The goal is to make gither a serious option when you want broad dithering coverage from a single binary, while the library stays clean enough to use as the Go-native core underneath.

license: The Unlicense

Why gither

• broad algorithm coverage across ordered, diffusion, halftone, Yliluoma, variable diffusion, and DBS families
• usable as both a CLI and a library
• auto-palette and explicit-palette workflows
• dedicated DBS surface, including clustered, multilevel, and palette-index color DBS

Install

CLI:

go install github.com/pixelkarma/gither/cmd/gither@latest

macOS note for downloaded release binaries:

xattr -d com.apple.quarantine gither
chmod +x gither

Library:

go get github.com/pixelkarma/gither

Build from source:

git clone https://github.com/pixelkarma/gither.git
cd gither
mkdir -p dist
go build -o ./dist/gither ./cmd/gither

CLI Quick Start

Basic diffusion:

gither \
  -in ./images/test.png \
  -out ./examples-out/gither-floyd.png \
  -algorithm floyd-steinberg \
  -quantizer rgb-levels \
  -levels 4

Auto-palette ordered dither:

gither \
  -in ./images/test.png \
  -out ./examples-out/gither-cluster-dot.png \
  -algorithm cluster-dot-8x8 \
  -quantizer palette \
  -palette auto \
  -palette-colors 6

DBS preview:

gither \
  -in ./images/test.png \
  -out ./examples-out/gither-dbs-preview.png \
  -algorithm dbs \
  -quantizer gray-levels \
  -levels 2 \
  -dbs-schedule preview \
  -verbose

Generate the full example matrix:

./scripts/render_examples.sh

Generate only DBS outputs:

./scripts/render_dbs_examples.sh

Both scripts:

• scan every image file in images by default
• create examples-out if needed
• clear old image outputs before rendering
• name outputs as gither-[image]-[detail].png

You can also point either script at a single image file or a different directory:

./scripts/render_examples.sh ./images/test.png
./scripts/render_examples.sh ./images ./examples-out

Library Quick Start

package main

import (
	"github.com/pixelkarma/gither"
	"github.com/pixelkarma/gither/adapters/stdimage"
)

func main() {
	img, err := stdimage.LoadPath("images/test.png")
	if err != nil {
		panic(err)
	}

	if err := gither.FloydSteinberg(img, gither.Options{
		Quantizer: gither.RGBLevels(4),
	}); err != nil {
		panic(err)
	}

	if err := stdimage.SavePath("out.png", stdimage.ToImage(img), 95); err != nil {
		panic(err)
	}
}

More library notes live in:

• docs/library.md
• docs/algorithms.md
• docs/releases.md

Stable vs Experimental

This project is alpha. The CLI and library are usable now, but names and APIs can still move before v1.

Current intent:

• stable alpha:
  • Bayer
  • cluster-dot
  • Yliluoma
  • classic diffusion kernels
  • threshold/random
  • Riemersma
  • DBS family
• experimental alpha:
  • adaptive ordered
  • polyomino
  • space-filling variants
  • void-and-cluster
  • blue-noise variants
  • dot-diffusion
  • AM/FM hybrids
  • variable diffusion family

gither -h reflects the same split.

Benchmarks

Run the full suite locally:

go test -run '^$' -bench . -benchmem ./...

For focused DBS benchmarking:

./scripts/benchmark_dbs.sh

Releases

Tagged releases are built automatically with GoReleaser and published to GitHub Releases.

• release automation: .goreleaser.yaml
• CI: .github/workflows/ci.yml
• tagged releases: .github/workflows/release.yml

Samples

Sample source images are kept in images so the scripts and benchmarks have fixture inputs. Generated outputs remain out of git.