randwallpaper

randwallpaper

I love clear, detailed, unsmoothed wallpapers/icons but finding ones that fit the random resolutions across my devices (phones, laptops, monitors) has always been a pain. And I love seeing cool patterns emerge from simple rules. This tool exists because I wanted to solve both of those things at once.

I came across Python's randimage and the EPWT papers, and built a batch tool to generate and publish images to a subreddit and a discord server. But the Python library was painfully slow. So I rebuilt the library from scratch in Go, writing as much as I could myself relying on dependencies that would do most of the work for me. The result ended up being roughly 50x faster over randimage.

I hope someone else will find this useful.

What it does

randwallpaper generates unique, procedural wallpapers using a three-step process:

1. Create a random mask (grayscale image)
2. Trace a path through its pixels
3. Map path position to colour via a procedurally generated colourmap

How the algorithm works

1. Mask generation

A mask is a grayscale image of the same dimensions as the final wallpaper. It determines the "terrain" the path will follow. There are three randomly chosen strategies used by randwallpaper:

2. Path finding

Given a mask, create a path that visits every pixel exactly once. There are two randomly chosen strategies for this, both starting from a random point and expanding outward in concentric square neighborhoods:

3. Colourmap

Each pixel in the path gets coloured according to its position, from 0 at the first pixel to 1 at the last. That position maps to a colour via a procedural colourmap. Colourmaps are generated dynamically by:

1. Picking 3-7 random anchor positions in [0, 1]
2. Assigning each anchor a random RGB colour
3. Interpolating between anchors using smooth (cubic Hermite) interpolation

Every call to Generate produces a unique colourmap.

Installation

Homebrew

brew tap michaelwiciak/tap
brew trust michaelwiciak/tap
brew install michaelwiciak/tap/randwallpaper

Go install

# Install the CLI tool
go install github.com/MichaelWiciak/randwallpaper/cmd/randwallpaper@latest

# Or add as a dependency in your Go project
go get github.com/MichaelWiciak/randwallpaper

go install places the binary in $GOPATH/bin (usually ~/go/bin on macOS/Linux). Make sure this directory is in your PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="$PATH:$HOME/go/bin"

CLI

randwallpaper -width 1920 -height 1080 -out wallpaper
randwallpaper -w 1920 -h 1080 -out batch -count 10
randwallpaper -w 800 -h 600 -out test -seed 42

There is a -h flag that specifies the usage of the binary.

Usage: randwallpaper [options]

  -count int
    	number of images to generate (default 1)
  -h int
    	image height (shorthand) (default 1080)
  -height int
    	image height (default 1080)
  -out string
    	output file name (without extension) (default "wallpaper")
  -seed int
    	random seed (0 = random)
  -version
    	print version and exit
  -w int
    	image width (shorthand) (default 1920)
  -width int
    	image width (default 1920)

API

import "github.com/MichaelWiciak/randwallpaper"

// Generate creates wallpapers and saves them as PNG files.
//
//   output="wallpaper" with count=1   -> saves as wallpaper.png
//   output="wallpaper" with count=5   -> creates folder wallpaper/
//                                        with wallpaper_1.png ... wallpaper_5.png
//
func Generate(width, height int, output string, opts ...Option) error

Options

// Number of images to generate (default 1)
func WithCount(n int) Option

// Seed for reproducible results (default: time.Now().UnixNano())
func WithSeed(seed int64) Option

Examples

// Single wallpaper, 1920x1080, saved as "wallpaper.png"
err := randwallpaper.Generate(1920, 1080, "wallpaper")

// Batch of 10 wallpapers, 3840x2160, saved to folder "batch/"
err := randwallpaper.Generate(3840, 2160, "batch", randwallpaper.WithCount(10))

// Reproducible wallpaper
err := randwallpaper.Generate(800, 600, "fixed", randwallpaper.WithSeed(42))

Development

Run the CLI directly from the repo without building the binary every time:

go run ./cmd/randwallpaper -out test -count 5
go run ./cmd/randwallpaper -version

Run checks:

gofmt -l .
go vet ./...
go test -race ./...
go run honnef.co/go/tools/cmd/staticcheck@v0.8.2 ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.9.0 ./...

Fuzz the path and colourmap invariants:

go test -run=^$ -fuzz=FuzzPathCoverage -fuzztime=30s .
go test -run=^$ -fuzz=FuzzColourmap -fuzztime=30s .

License

Released under the MIT License. Copyright (c) 2026 Michael Wiciak.

References

• randimage - Python library that inspired this project
• G. Plonka, "The Easy Path Wavelet Transform" - EPWT algorithm
• R. Budinich, "Region Based Easy Path Wavelet Transform" - RBEPWT variant