Replace pgmedge with pamedge for Netpbm Edge Detection

You will replace an old pgmedge invocation with pamedge, write the edge image to a new file, and verify that the result is a usable Netpbm image. On the current machine, Netpbm 11.5.2 still accepts the old name, but it is a compatibility alias rather than the command to build new scripts around.

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. They do not need sudo or other elevated privileges.

1. Check the installed command

Start by checking which package and executable are present. This is 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

The package version and paths can differ on another distribution. The useful checkpoint is the final line: here, pgmedge resolves directly to pamedge. The installed library reports Netpbm 11.5.2.

The old manual page describes pgmedge as replaced by pamedge in Netpbm 10.14. The replacement was made to handle colour images as well as the PGM and PBM images supported by the older program. Use the new name in documentation, scripts and automation.

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 command-line options. It accepts the common options used by Netpbm programs, but do not invent an option for changing the edge algorithm. The documented algorithm combines two perpendicular Sobel gradients. The output normally keeps the input image type, except that PBM input becomes PGM, and its maximum sample value is at least 255.

You can also use standard input. This is useful in a pipeline, but remember that the command's binary image output must go somewhere suitable:

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

Checkpoint: confirm that the source is actually a Netpbm image before processing it:

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

3. Create a new edge image

Choose an output name that does not already contain a useful result. Shell redirection with > truncates its destination before pamedge starts, so an accidental filename can destroy an existing image.

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

A zero status means that the command completed. It does not tell you whether the image looks correct, so inspect the output 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 wording from file varies. Check the dimensions, the Netpbm type and that the file is non-empty. Keep the original input until you have viewed or converted the result.

4. Process a colour image

This is the practical reason to migrate. The old pgmedge interface was limited to PGM and PBM, while pamedge reads PNM or PAM input, including colour PPM images. Try a colour file without replacing it:

$ 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 is normally the same as the input. Do not assume that an edge result is greyscale merely because it shows outlines; verify the type with file or with the Netpbm tool you use next.

For a stronger result with low sample values, the manual suggests increasing the input maximum value with pamdepth first. That is an additional conversion, not a required part of ordinary 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 that you control and check its contents before deleting it. This example changes no original file.

5. Update an old script safely

Replace the command name while preserving the redirection and arguments. Do not use a broad search-and-replace across a directory until you have inspected 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 a recovery copy. If the diff is wrong, restore the script explicitly with cp --preserve=all from that backup, then inspect it again. Once the new script has been tested and committed to your normal version control, remove the backup only if you no longer need it. Do not run a migration as root.

6. Diagnose failures without guessing

If the input cannot be opened, 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 exact diagnostic includes the local path and system error, so it will not match this shortened example. A non-zero status means you should fix the input or permissions before trusting the destination. If you redirected into a new file and the command failed, inspect that file before using it; do not treat its existence as proof of a valid image.

If an old script says pgmedge: Use 'man pgmedge' for help., that is expected for this compatibility entry point. Read man pamedge and change the script to call pamedge. There is no service to restart and no persistent configuration to undo.