Turn an SBIG ST-4 Camera File into PGM with st4topgm

st4topgm turns an old SBIG ST-4 autoguider capture into a plain greyscale PGM you can actually open. It is the Netpbm tool built specifically for that format. Allow about ten minutes if the file is already on disk. Along the way you will keep the original camera file untouched and confirm the result is a real Netpbm image, not just a file with the right extension.

You need a shell, the netpbm package, and a readable file in the native SBIG ST-4 format. This converter is for the ST-4 format specifically: it is not the tool for most other SBIG cameras, which use sbigtopgm instead.

1. Check the installed converter

Confirm which executable will run and record the Netpbm version. Both commands are read-only and need no elevated privileges:

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

That version line mixes build details in with the Netpbm version you actually want. There is no separate --help screen; the program's own message just points you at the manual page. The documented interface is small on purpose: an optional input file name plus the standard libnetpbm options.

Checkpoint: if command -v prints nothing, stop and install or repair Netpbm through your normal package-management process. Do not copy a converter binary over from an unrelated machine just because the filename matches.

2. Convert to a new PGM file

Pick a fresh destination so a failed conversion cannot truncate an image you already have. Swap in the file you actually have for the placeholder path:

$ st4topgm /path/to/camera-image.st4 > camera-image.pgm

The image data goes to standard output, so that shell redirection is a normal part of the workflow, not an extra step. Diagnostic lines such as the camera comment and calibration values can appear on standard error instead; they have no business ending up in the PGM file.

There is no need for sudo here when the input is readable and the destination directory is writable. Elevated privileges do not improve the conversion, and they can leave the output owned by root instead of you.

Checkpoint: inspect the result without opening binary data in a text editor:

$ file camera-image.pgm
camera-image.pgm: Netpbm image data, size = 192 x 165, rawbits, greymap
$ head -c 2 camera-image.pgm
P5

The exact wording from file can vary. What matters is that the output is non-empty, file calls it a greymap image, and the first two bytes read P5, the binary PGM magic number. The dimensions above came from the installed Netpbm test input; check a camera file from another source rather than assuming it matches.

3. Use standard input when the file is already in a pipeline

The input argument is optional. With none given, st4topgm reads ST-4 bytes from standard input and you still redirect the PGM output to a new file:

$ cat /path/to/camera-image.st4 | st4topgm > camera-image-from-stdin.pgm

A direct file argument is easier to review and skips an unnecessary cat, but standard input earns its keep when another approved tool is already handing you the camera data. Keep the output redirection separate from the input pipeline, and never pipe diagnostic text into another image converter.

As a quick sanity check, both conversions above should produce PGM files with the same header and dimensions:

$ file camera-image.pgm camera-image-from-stdin.pgm
camera-image.pgm:            Netpbm image data, size = 192 x 165, rawbits, greymap
camera-image-from-stdin.pgm: Netpbm image data, size = 192 x 165, rawbits, greymap

4. Keep failed conversions recoverable

Shell redirection with > creates or truncates its destination before st4topgm even starts. When the output name already matters, write to a temporary name in the same directory first and replace the old file only after you have checked the new one:

$ st4topgm /path/to/camera-image.st4 > camera-image.pgm.new
$ file camera-image.pgm.new
camera-image.pgm.new: Netpbm image data, size = 192 x 165, rawbits, greymap
$ mv camera-image.pgm.new camera-image.pgm

Treat that final mv as the deliberate replacement point, since it is the moment the directory entry actually changes. If conversion or verification fails, leave the original output alone and remove only the incomplete .new file, after checking its path. Never delete the source ST-4 file as part of cleanup: it is your recovery copy if the dimensions or content turn out wrong.

5. Diagnose the common failures

Missing or unreadable input. Usually a path or permission problem; check it without changing anything.
Wrong file size reported. Not a valid ST-4 file for this converter, or it was truncated in transfer. Do not pad it with arbitrary bytes; get the original capture again and compare checksums if you have a trusted copy.
Empty output. Check the exit status immediately after the run.

$ ls -l /path/to/camera-image.st4
$ test -r /path/to/camera-image.st4 && echo readable

$ st4topgm /path/to/camera-image.st4 > camera-image.pgm
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 means the converter completed successfully, not that the image is visually useful. Check the PGM header and dimensions anyway, then look at it with a trusted image viewer or a later Netpbm conversion. A non-zero status means the output may be incomplete, so discard it rather than treating it as usable.

Done means

st4topgm is confirmed as the intended Netpbm executable, with its installed version recorded.
The input is a readable native SBIG ST-4 file and remains untouched.
The converter wrote a non-empty PGM file beginning with P5.
You checked the output dimensions instead of trusting the file name or a successful exit status.
An existing result was protected by converting to a new name before any deliberate replacement.