Convert FITS Images to PNM Safely with fitstopnm

You will finish with a verified PGM or PPM file made from a FITS image, while keeping the input unchanged. The examples use fitstopnm from Netpbm 11.5.2, installed here as Debian package netpbm 2:11.05.02-1.1build1. Allow about fifteen minutes if you already have a FITS file and the Netpbm tools installed.

You need a readable FITS file, a shell, and enough free space for the output. This guide does not edit FITS headers or delete source data. Conversion is normally an ordinary, unprivileged operation. Do not use sudo unless your chosen input or output directory genuinely requires access that your user does not have.

1. Confirm the installed command

Check the executable and package version before relying on examples. These commands only read local metadata:

$ command -v fitstopnm
/usr/bin/fitstopnm
$ fitstopnm --version
fitstopnm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

The version text includes build details that can vary between distributions. The relevant point is the Netpbm version. The installed manual documents the options used below, and says that the shortest unique option abbreviation is accepted. Use full option names in scripts so that a later option addition cannot change what an abbreviation means.

2. Check the FITS input without changing it

Set a shell variable to the actual path. Quoting it protects spaces and shell metacharacters in the filename:

$ FITS_FILE='/path/to/observation.fits'
$ test -r "$FITS_FILE" && echo 'input is readable'
input is readable
$ file "$FITS_FILE"
/path/to/observation.fits: FITS image data

The wording from file depends on its version and on the FITS contents. A readable file is not necessarily a valid image with the dimensions you expect. Keep the original in place until the PNM has been checked.

Do not redirect output to the input path. Shell redirection opens the destination before fitstopnm starts, so a command such as fitstopnm "$FITS_FILE" > "$FITS_FILE" can destroy the source before conversion begins. Choose a separate destination.

3. Inspect the sample range first

Use -printmax when you want the minimum and maximum sample values but not an image yet:

$ fitstopnm -printmax "$FITS_FILE"
-12.5 843.75

The two values are an example of the command's output shape, not a prediction about your data. The option prints the range and quits without doing the normal conversion. This is useful before choosing explicit scaling limits or an output maximum value.

By default, fitstopnm uses DATAMIN and DATAMAX from the FITS header when they are available. Use -scanmax to force a scan of the image data, which is sensible when header metadata may be stale:

$ fitstopnm -scanmax -printmax "$FITS_FILE"
-12.5 843.75

Use -min and -max when you deliberately want bounds different from the header or scan. The values are floating-point numbers:

$ fitstopnm -min 0 -max 500 -printmax "$FITS_FILE"
0 500

That last command reports the selected limits; it still does not write an image. Treat clipping as a visualisation choice. If your scientific interpretation depends on the full measured range, record the limits and keep the original FITS file rather than assuming the PNM is a lossless representation.

4. Convert a two-dimensional FITS image

For a FITS image with two axes, run the converter and redirect its standard output to a new PNM file:

$ fitstopnm "$FITS_FILE" > observation.pgm
$ test -s observation.pgm && echo 'PNM output is non-empty'
PNM output is non-empty
$ file observation.pgm
observation.pgm: Netpbm image data, size 2048 x 2048, graymap

The exact dimensions and file description will follow your input. The program tells you what kind of PNM it is writing. A two-axis image normally produces PGM. For floating-point FITS samples, the documented default output maximum is 255 because the input precision is effectively unlimited. For other input, the default maximum is chosen to retain the available integer precision, based on the sample range.

Use a temporary destination when replacing an existing derived image. This avoids leaving a truncated old file if conversion fails:

$ fitstopnm "$FITS_FILE" > observation.pgm.new
$ test -s observation.pgm.new
$ mv observation.pgm.new observation.pgm

The mv is the state-changing step. If the conversion or verification fails, remove only observation.pgm.new and the previous observation.pgm remains available. Do not remove the original FITS as part of cleanup.

5. Select one plane from a three-axis file

A FITS file with three image planes can produce a pseudo-PPM by default. That is often not a colour image: the third axis commonly represents time or another measurement, not red, green and blue channels.

Select one plane explicitly with -image. Replace 1 with the plane number you need:

$ fitstopnm -image 1 "$FITS_FILE" > observation-plane-1.pgm
$ file observation-plane-1.pgm
observation-plane-1.pgm: Netpbm image data, size 2048 x 2048, graymap

The manpage recommends using -image for three-axis FITS data when you do not want an unwanted pseudo-PPM. Do not assume that plane 1 is the earliest observation or that the third axis is colour; check the FITS metadata and the instrument documentation before assigning scientific meaning to a plane.

If you really need all three planes as the program's PNM output, omit -image and verify the result as a PPM:

$ fitstopnm "$FITS_FILE" > observation-planes.ppm
$ file observation-planes.ppm
observation-planes.ppm: Netpbm image data, size 2048 x 2048, pixmap

The output type and dimensions in these examples are representative. Trust the command's report and your local inspection rather than copying these values blindly.

6. Set output precision deliberately

Use -omaxval when a downstream tool or comparison requires a particular PNM maximum value:

$ fitstopnm -omaxval 255 "$FITS_FILE" > observation-8bit.pgm
$ head -n 3 observation-8bit.pgm
P5
2048 2048
255

For raw PNM output, the header is text followed by binary sample data, so head is only a quick header check. Do not open the whole file in a text editor. The chosen maximum changes the numeric representation available to the PNM consumer. It does not restore information that was clipped by your -min and -max choices.

7. Check orientation and diagnose failures

The Netpbm manual warns that FITS pixel order may require a top-to-bottom flip. If the image is vertically inverted, make the flip a separate, reviewable step:

$ pamflip -topbottom observation.pgm > observation-topdown.pgm
$ file observation-topdown.pgm
observation-topdown.pgm: Netpbm image data, size 2048 x 2048, graymap

This guide assumes pamflip is installed and leaves the original converted PGM untouched. If you do not need a flip, keep the first output. Compare the result with a trusted FITS viewer before interpreting features.

A non-zero exit status means conversion did not complete successfully. For a missing input, the installed command reports that it cannot open the file and returns status 1. Check the path and read permission first:

$ ls -l -- "$FITS_FILE"
$ test -r "$FITS_FILE" && echo readable
readable

If the file is readable but the output is unexpected, rerun with -printmax, then decide whether stale header limits, explicit -min/-max, -scanmax, or an explicit -image selection is appropriate. Keep each command and its chosen limits in your processing notes.