Convert Netpbm Images to FITS with pamtofits

You will convert a PBM, PGM or PPM image into a FITS file, check the result, and understand which input values become FITS image planes and physical values. Allow about ten minutes for a single conversion. The examples use Netpbm 11.5.2, the version installed on this machine.

1. Check the installed command

Start with read-only checks. You need the netpbm package and a readable PNM or PAM image. Conversion normally needs no elevated privileges: read the source and write the result in a directory you own.

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

The installed program also prints build details with --version. The documented command shape is pamtofits [-max f] [-min f] [pamfile]. With no file argument it reads the image from standard input.

Checkpoint: confirm that command -v pamtofits finds the executable you intend to use, and that the input is a PNM or PAM file rather than a JPEG, PNG or an existing FITS file.

2. Convert an image to a new FITS file

Pass the input filename and redirect standard output to a new destination. This example keeps the source untouched:

$ pamtofits /path/to/input.ppm > /path/to/output.fits

There is normally no progress text because the FITS bytes are written to standard output. Shell redirection with > truncates an existing destination before pamtofits starts. To protect a useful file, choose a new name first:

$ pamtofits /path/to/input.ppm > /path/to/output.fits.new
$ test -s /path/to/output.fits.new && mv /path/to/output.fits.new /path/to/output.fits

The mv command in this example replaces the destination only after the converter has returned successfully and the new file is non-empty. If conversion fails, inspect or remove the .new file and the previous FITS file remains in place. Do not remove the old file until you have checked the replacement.

Checkpoint: a successful command returns to the shell without an error. The source image should still exist, and the destination should have a non-zero size.

3. Verify the FITS header and dimensions

Use a file-type check before handing the result to an astronomy tool:

$ file /path/to/output.fits
/path/to/output.fits: FITS image data, 8-bit, character or unsigned binary integer

The wording can vary between file versions. It should identify FITS image data. For a closer check, inspect the start of the file without editing it:

$ od -An -tc -N 320 /path/to/output.fits
   S   I   M   P   L   E           =
   ...
   B   I   T   P   I   X           =
   ...
   N   A   X   I   S               =

FITS header cards are fixed-width records, so the output from od is spread across whitespace. Look for cards such as BITPIX and NAXIS, not for a human-readable image preview. A successful exit status alone proves that the program completed; it does not prove that the input had the dimensions or orientation you expected.

4. Know how the input becomes FITS axes

A PBM or PGM input produces a single-plane image. Its FITS header has NAXIS = 2. A PPM input produces three planes, one for each colour component, with NAXIS = 3 and NAXIS3 = 3. The input's maxval also controls the output resolution: the installed documentation specifies 8 bits per pixel or 16 bits per pixel according to that value.

This is not a resize or colour-management operation. A PPM stays a three-plane image, and a greyscale PGM stays one plane. If you need a different number of planes, transform the image with an appropriate Netpbm tool before calling pamtofits, then verify the transformed input as well.

Netpbm writes pixels in row-major order: top to bottom, then left to right within each row. The FITS specification does not select a universal pixel orientation, and some viewers use bottom-to-top order. If a viewer displays the result upside down, make a deliberate flipped copy of the Netpbm input and convert that copy:

$ pamflip -topbottom /path/to/input.pgm > /path/to/input-topbottom.pgm
$ pamtofits /path/to/input-topbottom.pgm > /path/to/output.fits

Keep the original image while comparing viewers. The flip changes the pixels supplied to the converter, so it is a data transformation, not a display preference.

5. Map sample values to physical values

By default, Netpbm sample value zero maps to physical value 0, and the input maxval maps to that same maxval. In other words, omitting both options preserves the sample values as the FITS physical values.

Use -min and -max when the sample range represents a different physical range. The values tell pamtofits what zero and maxval mean, and the program records the mapping in FITS BSCALE and BZERO cards:

$ pamtofits -min=-1.5 -max=2.5 /path/to/input.pgm > /path/to/scaled.fits
$ file /path/to/scaled.fits
/path/to/scaled.fits: FITS image data, 8-bit, character or unsigned binary integer

Use the equal sign to keep a negative value attached to its option. Do not add these options merely because a file is called scientific data: choose the physical range from the data's specification. The command also writes DATAMIN and DATAMAX as a conservative indication based on the possible input endpoints. Those cards describe the available range, not necessarily the minimum and maximum sample values that actually occur in the image.

Checkpoint: write down the input maxval and the intended physical endpoints before using scaling. If another program consumes the FITS file, confirm that it honours BSCALE and BZERO rather than treating stored integers as already calibrated values.

6. Use standard input in a pipeline

The filename is optional, so a verified PNM-producing command can feed pamtofits directly:

$ some-pnm-command > /tmp/input.pgm
$ pamtofits /tmp/input.pgm > /path/to/output.fits

Keeping the intermediate file during the first run makes its header and dimensions inspectable. Once the pipeline is understood, standard input can remove that temporary file:

$ some-pnm-command | pamtofits > /path/to/output.fits

Replace some-pnm-command with a real command that emits PNM or PAM; it is a placeholder, not a pamtofits option. A pipeline can hide which stage failed unless you check exit statuses explicitly. For scripts, enable the shell's pipeline-failure handling where appropriate and write output to a temporary name before installing it over a useful file.

7. Diagnose failures without changing system state

If the program cannot open the input, check the path and readability:

$ ls -l /path/to/input.pgm
$ test -r /path/to/input.pgm && echo readable

If the input is not PNM or PAM, convert it to one of those formats with a suitable image tool first. If file reports an unexpected FITS type or the axes are wrong, inspect the input's format, width, height and maxval before changing scaling options. A FITS viewer showing an upside-down image is an orientation issue; it is not evidence that -min or -max is wrong.

Do not run the converter as root to solve an ordinary path or format error. Use elevated privileges only when the chosen input or output directory is genuinely restricted, and prefer copying the data to a working directory with the correct ownership. The command does not need a service restart and does not alter package, boot or persistent configuration.