Create Edge-to-Edge Image Gradients with pamwipeout

You will finish with a Netpbm image whose detail has been replaced by a smooth gradient between two opposite edges. pamwipeout can blend from left to right or from top to bottom. Allow about fifteen minutes for a first test. You need Netpbm, a Netpbm image, and enough disk space for a second copy of the image.

This guide uses Netpbm 11.5.2 from Debian package netpbm 2:11.05.02-1.1build1, installed as /usr/bin/pamwipeout. The installed manual requires exactly one direction option: -lr or -tb. No elevated privileges are needed for the examples.

1. Check the installed command

First confirm that the command and its package are the ones you expect. This is a read-only check:

$ command -v pamwipeout
/usr/bin/pamwipeout
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pamwipeout --version
pamwipeout: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version text includes build details after the line shown above. The command does not offer a useful option listing through --help; the local manual is the contract for this utility. If your version differs, read its pamwipeout(1) page before relying on output or memory behaviour.

2. Inspect the source before transforming it

Do not send an unknown file straight into an image pipeline. Ask Netpbm to identify it first:

$ pnmfile source.ppm
source.ppm: PPM raw, 2400 by 1600

The dimensions and exact wording vary. The useful result is that the file is a Netpbm image and that its size is plausible. pamwipeout reads its input from a filename or from standard input. If you have a different image format, convert it with an appropriate Netpbm tool first, then inspect the converted file.

Keep the original untouched while testing. The redirection in the next step creates a new output file, but a shell redirection will truncate an existing destination before the program starts. Choose a new name or make a backup first. If an output file is accidentally replaced, recovery depends on your backup or filesystem snapshots; pamwipeout has no undo operation.

3. Make a horizontal gradient

Use -lr when the gradient should run from the left edge to the right edge:

$ pamwipeout -lr source.ppm > horizontal.ppm
$ pnmfile horizontal.ppm
horizontal.ppm: PPM raw, 2400 by 1600

The output dimensions stay the same. The pixels at the two opposite horizontal edges provide the endpoints, and the pixels between them are replaced by interpolated colour values. The original detail between the edges is not retained. Because output is an image stream, do not run this command without redirection in a terminal.

The program may write a raw Netpbm representation even when the input used a plain-text representation. That is normal. Let Netpbm tools read the result, or convert it later if another program needs a particular format.

4. Make a vertical gradient

Use -tb when the gradient should run from the top edge to the bottom edge:

$ pamwipeout -tb source.ppm > vertical.ppm
$ pnmfile vertical.ppm
vertical.ppm: PPM raw, 2400 by 1600

This mode takes its endpoint pixels from the top and bottom edges. It reads the whole image into memory before processing, so the input dimensions and pixel depth matter. For a large image, check available memory and watch the command's resource use before running it on a production host. A failure caused by memory pressure can affect other processes even though the command itself does not change system configuration.

-lr is the streaming-friendly choice: it reads one row at a time, processes that row, and writes it. That makes it preferable for large images when a horizontal gradient is suitable. Do not swap the options merely to save memory, because they produce different gradients.

5. Use standard input in a pipeline

Omitting the filename makes pamwipeout read standard input. This lets you connect it to another Netpbm command:

$ pamflip -cw source.ppm | pamwipeout -lr | pamflip -ccw > rotated-result.ppm
$ pnmfile rotated-result.ppm
rotated-result.ppm: PPM raw, 2400 by 1600

This is the documented way to get the top-to-bottom effect without asking pamwipeout -tb to hold the whole original orientation in memory. The first flip turns the desired vertical direction into left-to-right, pamwipeout -lr processes rows, and the final flip restores the orientation. Test the geometry on a small image first: the two flips must be inverse operations for the chosen image orientation.

If any stage fails, do not treat the output as valid just because a file was created. Check the exit status and run pnmfile on the result. For a script, enable a pipeline failure policy such as set -o pipefail before the pipeline, because a plain shell pipeline can otherwise report only the final command's status.

6. Understand the option boundary

You must provide one of -lr or -tb, but not both. A missing direction is an error:

$ pamwipeout source.ppm > rejected.ppm
pamwipeout: one of -lr or -tb must be specified
$ printf 'exit status: %s\n' "$?"
exit status: 1

The diagnostic wording can vary by build, but a non-zero status is the important signal. An output file may already have been created or truncated by the shell before pamwipeout reports the error, so use a temporary destination when a failed run must not replace a previous result.

Minimum unique option abbreviations are accepted, and the manual also permits double hyphens. Prefer the complete short options in scripts because -lr and -tb make the intended orientation obvious and are less exposed to future option-name changes. The common libnetpbm option -quiet is available if you need to reduce diagnostics, but do not hide errors while you are testing a new pipeline.

7. Combine the result with an existing image

The utility is useful when removing unwanted detail from part of a larger image. A typical workflow is to use pamcut to isolate a region, create a wiped version, then use pamcomp or pnmpaste to place it back. Keep each intermediate file separate until you have checked its dimensions:

$ pamcut -left 0 -right 2400 -top 0 -bottom 1600 source.ppm > region.ppm
$ pamwipeout -lr region.ppm > region-wiped.ppm
$ pnmfile region.ppm region-wiped.ppm
region.ppm: PPM raw, 2400 by 1600
region-wiped.ppm: PPM raw, 2400 by 1600

The exact cut coordinates belong to your image, and the surrounding composition must have matching dimensions and format. Do not paste a result into the original until you have opened or otherwise inspected it. This workflow changes only files named by your redirections; it does not modify a service, configuration file or system image.