Convert PFM Images to PAM Safely with pfmtopam

pfmtopam turns a Portable Float Map (PFM) image into a PAM file that ordinary Netpbm tools can read. You will check the result's dimensions, depth and tuple type as you go, using the Netpbm 11.5.2 package installed on this machine. Allow about five minutes if the input already exists; no root access is needed.

The route

Jump straight to the step you need, or tick off Done means at the end.

Before you start
1. Convert one PFM file
2. Verify the PAM header
3. Read from standard input
4. Get diagnostics with -verbose
5. Know the -maxval limit on this install
Common failure traps and recovery

Before you start

You need a readable PFM file and the pfmtopam command. Check both before changing anything. Replace the example path with your own file, but keep the quotes if the path contains spaces.

command -v pfmtopam
pfmtopam --version
test -r "./input.pfm"

On the packaged version used here, the version command prints diagnostics beginning with Netpbm Version: Netpbm 11.5.2. The installed manual describes PFM as the input and PAM as the output. A failed test produces no image, and normally means the path or permissions need correcting.

1. Convert one PFM file

The simplest form writes PAM bytes to standard output. Redirect them to a new filename. Shell redirection can overwrite an existing file without asking, so the guarded example below stops first if the destination already exists.

input='./input.pfm'
output='./converted.pam'

test -r "$input" || { echo "Cannot read $input" >&2; exit 1; }
test ! -e "$output" || { echo "Refusing to overwrite $output" >&2; exit 1; }
pfmtopam "$input" > "$output"
file "$output"

A successful conversion produces a file recognised as a Netpbm PAM image. The converter selects the tuple type from the input; it does not turn a greyscale image into colour merely because the output format is PAM.

Colour PFM: the header normally contains DEPTH 3 and TUPLTYPE RGB.
Greyscale PFM: the header is represented with TUPLTYPE GRAYSCALE.

2. Verify the PAM header

Inspect only the text header, not the binary raster that follows it. PAM headers end at ENDHDR. The following command is a quick, read-only check:

sed -n '1,/^ENDHDR$/p' ./converted.pam

For the small colour test image used while preparing this guide, the result was:

P7
WIDTH 2
HEIGHT 1
DEPTH 3
MAXVAL 255
TUPLTYPE RGB
ENDHDR

Your width, height and tuple type should match the PFM you supplied. MAXVAL 255 is the documented default.

Checkpoint

If the header is absent or the dimensions are implausible, stop there and keep the original PFM. The most useful next check is whether the input is actually PFM data rather than a file with the wrong extension.

3. Read from standard input

Leaving out the image filename makes pfmtopam read from standard input. This is handy when another program or a decompressor supplies the PFM. Keep the final redirect pointed at a new file and apply the same overwrite warning as above.

test ! -e ./piped.pam || { echo 'Refusing to overwrite ./piped.pam' >&2; exit 1; }
cat ./input.pfm | pfmtopam > ./piped.pam
sed -n '1,/^ENDHDR$/p' ./piped.pam

For a plain file this pipeline adds no conversion capability, and the direct form is easier to diagnose. Avoid a pipeline if you need the producer's failure status to be obvious in a script, unless you also enable the shell's pipeline failure handling.

4. Get diagnostics with -verbose

Add -verbose when you need to see what the reader found. The messages go to standard error, while PAM data still goes to standard output, so this stays safe when output is redirected.

pfmtopam -verbose ./input.pfm > ./diagnostic.pam

The installed command reports values such as width, height, whether the image is colour, byte order and scale factor. These messages are diagnostics, not image data. If the command exits non-zero, treat the output as unusable and inspect the error before retrying.

5. Know the -maxval limit on this install

The manual documents -maxval=n and says its default is 255. It also says options may use two hyphens and that the value may be separated by whitespace. Netpbm 11.5.2 as installed here rejects tested values including 100, 255 and 65535 anyway, with the message Maximum allowed -maxval is 65535. You specified ....

Warning

Do not build a workflow around this option without testing the exact package on the target host.

The reliable path on this host is to accept the default and verify the resulting header. If your distribution ships a different Netpbm release and you need another maximum value, read that host's manual and test into a disposable output file first. This is a compatibility check, not a reason to edit the input or install a second package.

Common failure traps and recovery

Empty or missing output: check the exit status with if pfmtopam ...; then ...; fi and read standard error. Do not pass a failed conversion to the next image tool.
Unexpected colours: confirm the PFM header and remember that PFM can be colour or greyscale. Compare the PAM DEPTH and TUPLTYPE values rather than judging from a thumbnail.
Overwriting the source: never redirect to the input path. If a destination was overwritten, recovery depends on backups or filesystem snapshots; pfmtopam has no undo operation.
Permission errors: prefer a writable directory in your own account. Do not use sudo merely to convert an image; elevated access is unnecessary.

Done means

Clean exit: pfmtopam completed with exit status zero.
File recognised: file converted.pam identifies a PAM image.
Header matches: it contains the expected width, height, depth, maximum value and tuple type.
Source protected: the original PFM remains untouched and any existing destination was protected from accidental overwrite.