Convert Netpbm Images to Portable Float Maps with pamtopfm

You will convert a PNM or PAM image into a PFM image, set its scale and byte order when needed, and check the result without changing the source. Allow about ten minutes if Netpbm is already installed. The examples use pamtopfm from Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

PFM, or Portable Float Map, is similar to PPM but stores four-byte IEEE floating-point samples without a maxval. That makes it suitable for generic light intensity and high dynamic range data rather than only ordinary display values. The command writes the converted image to standard output, so redirect it to a new file.

1. Check the installed command

Confirm that the executable is available and record the version before putting it into a script:

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

The exact build details can differ on another machine. The installed manual describes the interface used here: an optional input filename, -scale=float, and -endian={big|little}. It also says that options may be abbreviated to their shortest unique prefix, but full names are clearer in scripts.

Checkpoint: if command -v prints nothing, stop and install the Netpbm package through your normal package-management process. Neither conversion nor verification needs elevated privileges when the input and output directories are yours.

2. Convert a colour PPM image

Choose a destination that does not already contain useful data, then redirect standard output:

$ pamtopfm /path/to/input.ppm > output.pfm
$ printf 'exit status: %s\n' "$?"
exit status: 0

An RGB input becomes a colour PFM. The installed command test below produced the PF magic number and a two-pixel, one-row image:

$ head -n 3 output.pfm
PF
2 1
-1.000000

The PFM raster contains binary floating-point values, so head only shows its text header. Do not treat a successful exit status as proof that the image is visually correct. Check its dimensions and inspect it with a tool that understands PFM, or convert it with an appropriate Netpbm program if one is installed.

3. Keep the original and avoid truncating output

Shell redirection with > truncates an existing destination before pamtopfm starts. For a cautious replacement, write to a temporary name and move it only after the command succeeds:

$ pamtopfm /path/to/input.ppm > output.pfm.new
$ status=$?
$ if [ "$status" -eq 0 ] && [ -s output.pfm.new ]; then
>     mv output.pfm.new output.pfm
> else
>     printf 'conversion failed with status %s\n' "$status" >&2
>     exit "$status"
> fi

This changes only the output path. If conversion fails, the old output.pfm remains in place and the incomplete output.pfm.new can be removed after you have checked the error. Removing a file is irreversible, so do not add an automatic cleanup step to a batch until its failure handling is tested.

PFM output can be much larger than a compressed display format. Keep the original PNM or PAM until the PFM has been checked; pamtopfm reads it and does not modify it.

4. Set the PFM scale

The scale factor is part of the PFM format. Its default is 1.0. Supply a different floating-point value when the consumer of the PFM file expects one:

$ pamtopfm -scale=0.5 /path/to/input.ppm > output-half-scale.pfm
$ head -n 3 output-half-scale.pfm
PF
2 1
-0.500000

The header is a useful quick check that the requested value reached the output. It does not replace a check by the program that will consume the PFM, because scale has meaning to that consumer.

Do not confuse scale with resizing. pamtopfm converts sample data; it does not offer a width or height option. The output dimensions come from the input image.

5. Choose byte order when interoperability requires it

The raster stores each sample as a four-byte IEEE floating-point number. The default byte order is the native endianness of the machine running pamtopfm, chosen for faster execution. If another program or file specification requires a particular order, set it explicitly:

$ pamtopfm -endian=little /path/to/input.ppm > output-little.pfm
$ head -n 3 output-little.pfm
PF
2 1
-1.000000

Use -endian=big for big-endian output. The choice is not a display preference: it affects how readers decode the binary raster. A file can have a correct-looking header and still be unusable to a reader that assumes the other order, so agree the setting with the receiving tool rather than guessing.

You can combine the options:

$ pamtopfm -scale=0.5 -endian=little /path/to/input.ppm > output-little-half.pfm

6. Convert from standard input and diagnose failures

The input filename is optional, so a pipeline can provide a Netpbm image on standard input:

$ cat /path/to/input.ppm | pamtopfm > output.pfm

For a simple one-off conversion, naming the input file is easier to review. In either form, check the status immediately. If the command cannot read the input, verify the path and permission without changing anything:

$ ls -l /path/to/input.ppm
$ test -r /path/to/input.ppm && echo 'input is readable'

If the output is reported as a non-colour PFM when you expected colour, check the input type. pamtopfm creates colour output for RGB PPM input and non-colour output otherwise. A PFM header beginning with PF is colour; use a suitable PFM-aware checker for the complete file rather than relying on a text editor.

The option syntax accepts either -scale=0.5 or -scale 0.5, and the manual permits two hyphens as well. Prefer one consistent, explicit form in automation. An invalid option or unreadable image should stop the pipeline; do not publish a partial redirected file as if it were valid.