Convert PGM Images to SBIG Format with pgmtosbig

pgmtosbig turns a Portable Graymap into an uncompressed SBIG Type 3 image, the format the old SBIG astronomy camera software expects. Allow about ten minutes for the conversion plus a quick header check to confirm it reads back cleanly.

The examples use the Netpbm 11.5.2 build installed by Debian package netpbm 2:11.05.02-1.1build1.

• You need: a shell, Netpbm, and a PGM image.
• It will not touch: the source image, and none of it needs root. It writes a new output file, so check the destination before running a command that could overwrite an existing one.

1. Check the installed command

Confirm which executable will run and record the local Netpbm version. This is a read-only checkpoint:

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

The option spelling is worth checking on your host: this build accepts --version and prints diagnostics before reading input. The command has no pgmtosbig-specific switches. It accepts the common libnetpbm options, but the core interface is deliberately small, an optional PGM filename, with the SBIG bytes written to standard output.

2. Inspect the PGM before converting it

A PGM image has a magic number, width, height, maximum grey value, and raster data. Netpbm's raw PGM form starts with P5; its plain-text form starts with P2. A maximum value below 256 uses one byte per pixel, while larger values use two bytes in most-significant-byte-first order.

Ask Netpbm to describe a candidate file without changing it:

$ file INPUT.pgm
INPUT.pgm: Netpbm image data, size 640 x 480, rawbits, gray, 8-bit
$ pamfile INPUT.pgm
INPUT.pgm: PGM file, 640 by 480 by 255

Replace INPUT.pgm with a real path. If file or pamfile reports a different format, stop and convert or repair the input first; a file extension is not proof that the contents are PGM.

Do not confuse a PGM's image sequence with a list of unrelated files. The PGM specification permits one or more images in one stream, but a conversion tool may produce one output image per input image, or reject an unexpected sequence. For a predictable result, use one image and verify its dimensions first.

3. Convert a file to SBIG

Redirect standard output to a new destination. The source remains unchanged:

$ pgmtosbig INPUT.pgm > OUTPUT.sbig
$ printf 'converter exit status: %s\n' "$?"
converter exit status: 0
$ ls -lh OUTPUT.sbig
-rw-r--r-- 1 you you 301K Sep 26 09:15 OUTPUT.sbig

A zero status means the process completed successfully. The file size depends on the image and the fixed SBIG header.

$ cp -- OUTPUT.sbig OUTPUT.sbig.before-pgmtosbig
$ pgmtosbig INPUT.pgm > OUTPUT.sbig

4. Use standard input when the image is a stream

Omit the optional filename to make pgmtosbig read the PGM from standard input, which is useful when another Netpbm command produces the image:

$ pgm_source_command | pgmtosbig > OUTPUT.sbig
$ test -s OUTPUT.sbig
$ printf 'non-empty SBIG output: %s\n' "$?"
non-empty SBIG output: 0

Replace pgm_source_command with a command that really emits PGM. Keep diagnostics in mind: a producer that writes status text to standard output can corrupt the image stream. Well-behaved Unix filters write messages to standard error, but inspect unfamiliar tools before composing a pipeline.

For a small, known-good smoke test, this plain-text PGM contains two pixels:

$ printf 'P2\n2 1\n15\n0 15\n' | pgmtosbig > /tmp/two-pixel.sbig
$ test "$(wc -c < /tmp/two-pixel.sbig)" -gt 20
$ printf 'SBIG stream created\n'
SBIG stream created

The temporary file is safe to discard after testing. Do not use a tiny synthetic image as evidence that an astronomical exposure has the correct calibration, orientation or dynamic range.

5. Verify the SBIG header

The generated file begins with a Type 3 style header. On the installed build, the first lines identify the image as an ST-6 image and record its dimensions and saturation level:

$ od -An -tc -N 48 OUTPUT.sbig
   S   T   -   6       I   m   a   g   e  \n  \r   H   e   i   g   h
   t   =   4  \n  \r   W   i   d   t   h   =   2  \n  \r   S   a   t   _   l

For a less visual check, search the printable header without assuming that every later byte is text:

$ strings -a -n 4 OUTPUT.sbig | sed -n '1,6p'
ST-6 Image
Height=480
Width=640
Sat_level=255
End

Expect the height and width to match the PGM, with the saturation level reflecting its maximum grey value. The exact byte layout and line endings are format details, not a promise that every SBIG reader accepts every possible PGM input.

6. Round-trip through sbigtopgm

Use the companion reader for a practical compatibility check. It writes a PGM to standard output, so send that output to a separate file:

$ sbigtopgm OUTPUT.sbig > ROUNDTRIP.pgm
$ pamfile ROUNDTRIP.pgm
ROUNDTRIP.pgm: PGM file, 640 by 480 by 255

This checks that Netpbm can parse the file it just produced and recover the expected dimensions and range. It does not prove that a camera control program, archive system or third-party SBIG reader will accept it. Compare pixel data as well when scientific or evidential accuracy matters.

7. Keep the format boundary clear

pgmtosbig produces an uncompressed Santa Barbara Instrument Group SBIG Type 3 image. The manpage explicitly distinguishes this from the SBIG ST-4 format. The generated header says ST-6, which is part of this tool's output convention and does not turn the file into an ST-6 camera capture.

The command has no option for compression, camera model selection, metadata editing or format conversion beyond this PGM-to-SBIG path. If you need those properties, use a tool that documents them and verify its output separately; do not infer support from an option accepted by a different Netpbm command.