Convert a PGM Image to FaceSaver Format with pgmtofs

You will finish with a repeatable command that reads a PGM greyscale image and writes Usenix FaceSaver format to a separate output file. The examples use Netpbm 11.5.2, packaged here as netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, the Netpbm package, a PGM image, and enough disk space for a second copy of the converted data. This guide does not overwrite the source image or install anything. The output is an image file rather than terminal text, so do not print it directly to your screen.

1. Check the installed command

Confirm that the executable and package are the ones you expect. These are ordinary, read-only commands and do not need elevated privileges:

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

The command's version output includes build details as well as the Netpbm version. Exact package versions and the build date will vary on another host.

2. Check that the input is really PGM

pgmtofs accepts one optional input filename. With no filename it reads standard input. The PGM specification supports raw files beginning with P5 and plain files beginning with P2; both describe a greyscale raster with a width, height, maximum value and pixel data.

Inspect the file before converting it:

$ file INPUT.pgm
$ head -n 5 INPUT.pgm

For a plain PGM, the header is readable. A raw PGM contains binary raster data, so head may show unreadable characters after the header. Use a format-aware Netpbm tool when you need a stronger check:

$ pamfile INPUT.pgm
INPUT.pgm: PGM raw, 640 by 480 maxval 255

The dimensions and maximum value in the output are examples, not defaults. Check that they match the image you intend to convert. A PGM value of zero represents black and its maximum value represents white.

3. Convert to a new FaceSaver file

Choose an output path that does not already contain data, then run the conversion:

$ pgmtofs INPUT.pgm > OUTPUT.face

The filename suffix is only a convention. pgmtofs writes FaceSaver data to standard output, so the shell redirection is what creates OUTPUT.face. The program has no command-line options specific to it. It does recognise options common to Netpbm programs, but add one only when you have checked the installed common-options documentation.

$ if test -e OUTPUT.face; then
>     printf '%s\n' 'Refusing to overwrite OUTPUT.face' >&2
>     exit 1
> fi
$ pgmtofs INPUT.pgm > OUTPUT.face
$ printf 'exit status: %s\n' "$?"
exit status: 0

If you accidentally replace a file, stop using that path and recover it from your normal backup or snapshot. There is no undo operation in pgmtofs.

4. Verify the result without treating it as text

Check that the command created a non-empty output and that it is not merely a copied PGM header:

$ wc -c OUTPUT.face
$ xxd -g1 -l 96 OUTPUT.face

On the installed build, a small test conversion begins with FaceSaver metadata such as FirstName:, LastName: and E-mail:. The exact byte count depends on the input dimensions and the generated metadata. Do not compare the complete output byte-for-byte with another host unless the inputs and tool builds are identical.

A successful exit status confirms that the program completed its read and write operation. It does not prove that a receiving application accepts every image dimension or display convention. If the destination system has its own importer, use that importer as the final compatibility check.

5. Use standard input in a pipeline

Because the input filename is optional, another program can provide the PGM stream:

$ generate-pgm-image | pgmtofs > OUTPUT.face

Keep the output redirection separate from the input pipeline. This makes it clear which command produces PGM data and which command produces FaceSaver data. For a saved PGM, the equivalent form is:

$ cat INPUT.pgm | pgmtofs > OUTPUT.face

The pipeline form is useful for testing, but it does not make a bad upstream image valid. Check the producer's exit status if the pipeline is part of a script. In a POSIX shell, enable pipeline failure reporting where supported:

$ set -o pipefail
$ image-producer | pgmtofs > OUTPUT.face
$ printf 'pipeline status: %s\n' "$?"

If your shell does not support pipefail, capture and check the producer's status using that shell's documented pipeline facilities.

6. Recover from the common failures

A missing input file normally produces a non-zero status and an error on standard error. Check spelling, path and permissions before adding sudo; elevated privileges are not normally required to read an image in a directory you can access.

If the input is not a valid PGM, convert or regenerate it with an image tool that can write PGM, then inspect it again with pamfile. Do not rename a PNG or JPEG to .pgm, because the suffix does not change its contents.

If writing fails, check the destination directory, free space and ownership. Avoid running the whole conversion as root merely to hide a permissions problem. If the output is going to a shared or removable location, write to a local temporary path first, verify it, then copy it using the permissions and process required by that destination.

To inspect a FaceSaver file later, the related fstopgm command converts it back to PGM. That is a separate conversion, not an undo operation that restores the original file byte-for-byte:

$ fstopgm OUTPUT.face > ROUNDTRIP.pgm
$ pamfile ROUNDTRIP.pgm