Turn Sparse Colour Marks into a Tileable Gradient with pampaintspill

You will finish with a repeatable way to turn a few crisp, coloured pixels into a smooth background, tune how the colour falls off, and optionally produce an image that tiles at its edges. The examples use pampaintspill from Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need Netpbm, an input image, and a directory where you can write a new output file. The command reads an image and writes the result to standard output. These examples are ordinary, unprivileged commands. Do not use sudo unless your chosen input or output directory is genuinely inaccessible to your account.

1. Check the installed command

Confirm which executable will run and record the local version before relying on an option in a script:

$ command -v pampaintspill
/usr/bin/pampaintspill
$ pampaintspill --version
pampaintspill: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pampaintspill: Built from source dated 2024-03-31 09:09:47

The local manual is dated November 2021, while this installation reports Netpbm 11.5.2. The documented --near option was added in Netpbm 10.97, and --randomseed in 10.94, so both are available in this installation.

Checkpoint: if command -v finds a different path, inspect that copy's version and manual before comparing results with this guide.

2. Prepare a small set of paint sources

pampaintspill treats non-background pixels as paint sources and fills the background around them. Results are generally clearest when the source image contains a few small, hard-edged marks. A soft brush or a large painted region creates many sources, which can make the command slower and the result less predictable.

For a first run, use an existing image with a plain background and one or more small coloured marks. If the background is not obvious from the corners, pass it explicitly. Colour names such as white and hexadecimal values such as #f5f1e8 are accepted by the Netpbm colour parser.

Do not overwrite the source. Shell redirection truncates its destination before the program starts, so choose a new output name:

$ INPUT='/path/to/marks.ppm'
$ OUTPUT='/path/to/marks-spilled.ppm'
$ test -r "$INPUT" && echo 'input is readable'
input is readable

3. Make the first gradient

Specify the background and redirect standard output to a new file. The explicit seed makes random sampling reproducible if you later add --downsample:

$ pampaintspill --bgcolor=white --randomseed=7 "$INPUT" > "$OUTPUT"
pampaintspill: Treating White as the background color
pampaintspill: Image contains 24 background + 1 non-background pixels
pampaintspill: 100.0% complete

The progress lines are written to the terminal, while the image goes to the redirected file. The counts depend on your input, so your numbers will differ. A zero exit status means the command completed; check the result rather than relying on status alone:

$ pamfile "$OUTPUT"
/path/to/marks-spilled.ppm:  PPM raw, 5 by 5  maxval 255

Your pamfile description will use your image dimensions. Check that the file exists, is non-empty, and has the dimensions and image type you expected. Open it in an image viewer or pass it to a separate Netpbm converter for a visual check.

4. Make the edges wrap

Add --wrap when the output will repeat as a texture. Colours spilling past the right edge reappear at the left, and the same applies to the top and bottom. Without this option, the image is not calculated as a seamless tile:

$ TILE='/path/to/marks-tile.ppm'
$ pampaintspill --bgcolor=white --wrap --randomseed=7 "$INPUT" > "$TILE"
$ pamfile "$TILE"
/path/to/marks-tile.ppm:  PPM raw, 5 by 5  maxval 255

Wrapping changes the gradient calculation, not the input file. Compare the four edges in a viewer, or place copies of the image side by side in your graphics tool. If you are making a single illustration rather than a repeating background, leave --wrap out.

5. Tune speed and colour behaviour

By default, every non-background pixel can contribute to each calculated pixel. On a large image with many coloured pixels, that can be slow. --downsample=NUMBER randomly chooses that many paint sources, trading detail for execution time. Use a fixed --randomseed when comparing two settings:

$ pampaintspill --bgcolor=white --downsample=5000 --randomseed=7 "$INPUT" > /path/to/marks-fast.ppm

--near=NUMBER limits each calculation to the nearest sources. A small value usually has more effect than considering every source, and --near=1 gives a result resembling a Voronoi diagram. It is a separate limit from --downsample: the first reduces the source pool, while the second reduces the sources considered for each pixel.

The default --power=-2.0 makes intensity fall with the square of distance. A value such as -1.0 gives a gentler falloff when there are only a few sources. Positive values push gradients away from their sources and are better treated as an effect to test, not a neutral default:

$ pampaintspill --bgcolor=white --near=8 --power=-1.0 --randomseed=7 "$INPUT" > /path/to/marks-soft.ppm

Normally, existing non-background pixels are preserved. Add --all only when you deliberately want every pixel recoloured according to its distance from the other sources. It can remove the original marks from the output, so keep the source image and write to a separate destination.

6. Recover from common mistakes

If the result has unexpected colours, the guessed background is a likely cause. The automatic guess is based on the image corners, so a coloured corner can be mistaken for the background. Supply the exact value with --bgcolor and rerun.

If the command is slow, first count the image size and consider --downsample or --near. Do not assume that a smaller output file means the calculation was faster: the cost is driven by the number of pixels and paint sources used during processing.

If a run fails or produces a bad image, the original remains unchanged when you used a distinct output path. Remove only the incomplete new file after checking its path:

$ test -f /path/to/marks-fast.ppm && echo 'review this file before removing it'
review this file before removing it

There is no persistent configuration to undo. Rerunning with different options is the recovery path. If you did overwrite an existing output by mistake, restore it from your backup or filesystem snapshot; pampaintspill cannot reconstruct the previous file.