Replace pgmedge with pamedge for Netpbm Edge Detection

Old scripts still call pgmedge for Netpbm edge detection, but the command to build new ones around is pamedge. On the current machine, Netpbm 11.5.2 still accepts the old name as a compatibility alias, and this guide walks through swapping it out, writing to a new file, and checking the result is a usable image.

Allow about ten minutes. You need the netpbm package, a readable PGM, PBM, PPM or other Netpbm image, and a writable working directory. The examples only read the source and create a separate output file; none of them need sudo or other elevated privileges.

1. Check the installed command

Start by checking which package and executable you actually have. This is entirely read-only:

$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ command -v pgmedge
/usr/bin/pgmedge
$ readlink -f /usr/bin/pgmedge
/usr/bin/pamedge

Package version and paths will vary by distribution. The line that matters is the last one: here pgmedge resolves straight to pamedge, and the installed library reports Netpbm 11.5.2.

The old manual page says pgmedge was replaced by pamedge back in Netpbm 10.14, specifically to handle colour images as well as the PGM and PBM the older program was stuck with. Use the new name in documentation, scripts and automation from here on.

2. Read the replacement command's contract

pamedge takes an optional image filename and writes the processed image to standard output. Its basic form is:

$ pamedge IMAGE_FILE > EDGE_FILE

There are no pamedge-specific options, just the common ones shared across Netpbm programs, so do not invent a flag for changing the edge algorithm. The documented method combines two perpendicular Sobel gradients. Output normally keeps the input's image type, except that PBM input becomes PGM, and the maximum sample value comes out at least 255.

Standard input works too, useful in a pipeline as long as the binary output still lands somewhere sensible:

$ pamedge < /path/to/source.pgm > /path/to/edges.pgm

$ file /path/to/source.pgm
/path/to/source.pgm: Netpbm image data, size 640 x 480, rawbits, greymap

3. Create a new edge image

Pick an output name that is not already holding a result you need. > truncates its destination the moment the shell opens it, before pamedge starts, so a careless filename can wipe an existing image before the command even runs.

$ pamedge /path/to/source.pgm > /path/to/source-edges.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status only means the command completed, not that the image looks right, so check that separately:

$ file /path/to/source-edges.pgm
/path/to/source-edges.pgm: Netpbm image data, size 640 x 480, rawbits, greymap
$ test -s /path/to/source-edges.pgm && echo 'edge image is non-empty'
edge image is non-empty

The exact wording from file varies by version. Check dimensions, the Netpbm type and that the file is non-empty, and keep the original input until you have viewed or converted the result.

4. Process a colour image

This is the actual reason to migrate. The old pgmedge interface only understood PGM and PBM, while pamedge reads PNM or PAM input, colour PPM included. Try a colour file without touching your original:

$ pamedge /path/to/colour.ppm > /path/to/colour-edges.ppm
$ file /path/to/colour-edges.ppm
/path/to/colour-edges.ppm: Netpbm image data, size 1920 x 1080, rawbits, pixmap

The output type normally matches the input's. Do not assume an edge result is greyscale just because it looks like outlines; check the type with file or whatever Netpbm tool comes next.

For a stronger result out of low sample values, the manual suggests raising the input's maximum value with pamdepth first. That is an extra conversion, not a required part of normal use:

$ pamdepth 255 /path/to/source.pgm > /tmp/source-depth.pgm
$ pamedge /tmp/source-depth.pgm > /path/to/source-edges.pgm

Use a temporary path you control and check its contents before deleting it. Nothing here touches an original file.

5. Update an old script safely

Swap the command name while leaving the redirection and arguments alone. Do not run a broad search-and-replace across a directory until you have actually looked at the matches:

$ rg -n --glob '*.sh' --glob 'Makefile' 'pgmedge' /path/to/project
$ sed -i.bak 's/\bpgmedge\b/pamedge/g' /path/to/project/edge-images.sh
$ diff -u /path/to/project/edge-images.sh.bak /path/to/project/edge-images.sh

The .bak file is your recovery copy. If the diff looks wrong, restore the script explicitly with cp --preserve=all from that backup and look again. Once the new script is tested and committed to your normal version control, remove the backup if you no longer need it. Do not run a migration as root.

6. Diagnose failures without guessing

If the input will not open, check its path and permissions:

$ test -r /path/to/source.pgm && echo readable
readable
$ pamedge /path/to/missing.pgm > /tmp/edges.pgm
pamedge: Unable to open file '/path/to/missing.pgm' for reading. ...
$ printf 'exit status: %s\n' "$?"
exit status: 1

The real diagnostic includes your local path and system error, so it will not match this shortened example word for word. A non-zero status means fix the input or permissions before trusting whatever the redirection created; do not treat a new file's mere existence as proof of a valid image.

Seeing pgmedge: Use 'man pgmedge' for help. from an old script is expected for this compatibility entry point. Read man pamedge and update the script to call pamedge instead. There is no service to restart and no persistent configuration to undo.