Convert Netpbm Images to FITS after pnmtofits was Renamed

You will finish with a reproducible way to turn a PNM or PAM image into a FITS file, using the pnmtofits name that older scripts may still call. On this machine, Netpbm 11.05.02-1.1build1 provides pnmtofits as a symbolic link to pamtofits. Allow about fifteen minutes. You need a shell and a readable PBM, PGM, PPM or PAM image; no elevated privileges are normally required.

The name matters because pnmtofits is the old interface. Netpbm 10.30 extended the converter to accept PAM and renamed it pamtofits. The old command is retained as a compatibility name, so new scripts should use pamtofits while existing scripts can keep working with pnmtofits.

1. Check which converter you are using

Confirm the package version and the two command paths before putting the converter into a script. This is read-only:

$ dpkg-query -W netpbm
netpbm 2:11.05.02-1.1build1
$ ls -l "$(command -v pnmtofits)" "$(command -v pamtofits)"
/usr/bin/pamtofits
/usr/bin/pnmtofits -> pamtofits

Package versions and paths vary. The useful check is that both names resolve, and that the legacy name points at the current converter. Read the installed manual if your package is from another release:

$ man pamtofits

Checkpoint: the command accepts one optional input file. With no file argument it reads the image from standard input, and it writes FITS data to standard output.

2. Convert an image without changing the source

Use shell redirection to send the result to a new file. The converter does not modify the input:

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

The compatibility spelling is equivalent:

$ pnmtofits /path/to/input.pgm > output-from-legacy-name.fits

For a pipeline, omit the input path:

$ some-netpbm-command /path/to/input.pgm | pamtofits > output.fits

There is usually no progress display. Check the exit status and make sure the destination is non-empty:

$ printf 'conversion status: %s\n' "$?"
conversion status: 0
$ test -s output.fits && echo 'FITS file is non-empty'
FITS file is non-empty

Do not use sudo for an ordinary conversion. If the input directory is not readable or the output directory is not writable, fix the path or permissions deliberately rather than running an image converter as root.

3. Verify the FITS header

FITS begins with fixed-width header cards. The first card should identify a simple FITS file, and the header is padded to a 2880-byte boundary. Inspect the first few bytes without attempting to edit the binary file:

$ od -An -c -N 80 output.fits
   S   I   M   P   L   E           =
                                                       T

Exact spacing in od output can differ. Look for SIMPLE = T. A small test image converted by the installed command is 5760 bytes, which is two 2880-byte FITS blocks: one header block and one data block. Real images can be larger.

PBM and PGM inputs produce a single-plane image with FITS NAXIS = 2. PPM input produces a three-plane image with NAXIS = 3 and NAXIS3 = 3. Confirm those cards when the number of planes matters. A successful exit status alone only proves that the converter accepted the input and wrote output.

4. Understand the bit depth and sample values

The output resolution is 8 or 16 bits per pixel, based on the input image's maxval. It is not selected by the output filename. Keep the original image while you check the result, especially when a later FITS reader expects a particular bit depth.

By default, Netpbm maps sample zero to physical value 0 and the input maxval to its own physical value. Use -min and -max when the samples represent another physical range:

$ pamtofits -min -1.5 -max 3.5 /path/to/input.pgm > calibrated.fits

These options set the FITS BSCALE and BZERO cards. They describe the physical meaning of the stored samples; they do not resize the image or change its width and height. Inspect the header after conversion:

$ od -An -c -N 320 calibrated.fits | less

The program also writes DATAMIN and DATAMAX as conservative limits based on the possible input range. They do not necessarily describe the smallest and largest samples that actually occur in your image.

5. Check orientation before sharing the file

Netpbm writes pixels in row-major order from top to bottom, then left to right. FITS itself does not define which pixel is at which end of the data, and some ImageMagick and Gimp versions have used bottom-to-top order. If a viewer displays the result upside down, do not assume the conversion corrupted the image.

Use pamflip -topbottom on the Netpbm image before conversion when the receiving tool requires the opposite orientation:

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

That creates a different image stream. Keep the original and compare both outputs in the target FITS viewer before replacing a published or scientific product. The conversion commands above are ordinary user commands; there is no service restart or persistent configuration to undo.

6. Avoid the overwrite and input traps

Shell redirection truncates its destination before pamtofits starts. Do not convert directly over a FITS file you may need:

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

The mv is the state-changing step. If conversion fails, remove only the incomplete output.fits.new after checking its exact path; the old output remains. If conversion succeeds but the FITS reader rejects the file, restore the previous output from your normal backup rather than deleting it blindly.

A message such as bad magic number means the input was not recognised as PBM, PGM, PPM or PAM. Check the source command and its output before adding options:

$ file /path/to/input.pgm
$ head -c 2 /path/to/input.pgm
P5

For binary PNM files, head only checks the magic number. It does not validate every pixel or prove that a later FITS application will interpret the image as intended.