Convert a PGM Image to SBIG ST-4 with pgmtost4

pgmtost4 turns a PGM image into an uncompressed SBIG ST-4 file, but only if it is exactly 192 by 165 pixels. Allow about fifteen minutes for the conversion, plus a check that the result has the expected size and reads back cleanly.

The examples use Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1.

• You need: a readable PGM image, the Netpbm converter package, and a directory where you can write the output.
• It will not touch: the input image or any system configuration. This workflow does not need root privileges.

1. Check the installed converter

Confirm which executable the shell will run, then ask it for its version information. These are ordinary, read-only commands:

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

The extra diagnostic lines can vary with the package build. The useful checkpoint is the Netpbm version and the fact that the command exists. The installed manual says pgmtost4 has no options specific to itself. It accepts the common libnetpbm options, but the conversion normally needs only an optional input file name.

2. Check the PGM dimensions before converting

For the installed program, use a PGM that is 192 pixels wide by 165 pixels high. A PGM header normally makes this easy to inspect:

$ head -4 /path/to/image.pgm
P5
192 165
255

P2 means an ASCII PGM and P5 means a binary PGM. Both are PGM forms, but the header is not the whole file: a binary PGM has pixel bytes after the third line, while an ASCII PGM has decimal samples separated by whitespace. Comments beginning with # may appear in a PGM header, so use a format-aware tool if the dimensions are not in the first four lines.

$ pamfile /path/to/image.pgm
/path/to/image.pgm: PGM raw, 192 by 165

The wording may differ slightly between Netpbm builds. The important values are 192 and 165. Do not guess that the input can be resized by pgmtost4; it has no resizing option.

3. Convert to a new output path

Run the converter with the input file as its only ordinary argument. ST-4 data is binary, so redirect standard output to a file:

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

A successful command prints the converted data to standard output and normally prints no progress message. The output is an SBIG ST-4 camera CCD image, not a text report, and the format is uncompressed. The converter writes header values that identify the image as coming from an ST-6 camera, which is a property of this format conversion rather than a claim about the original camera.

The output name is just a local convention: the file contents, not the suffix, determine whether another program recognises it. Keep the original PGM until the ST-4 file has passed the checks below.

4. Verify the binary result

For a 192 x 165 input, the installed converter produced a 31,872-byte file in the local test. Check the file without dumping binary data into your terminal:

$ wc -c /path/to/image.st4
31872 /path/to/image.st4
$ test -s /path/to/image.st4 && echo 'non-empty output'
non-empty output

The exact byte count is a useful format check for this image size, though not a general substitute for checking the image itself. If the file is empty or much smaller than expected, inspect the command's exit status and error output, then fix the input rather than passing the result to a camera tool.

5. Round-trip the file when you need stronger evidence

If st4topgm is installed, use it to decode a copy of the ST-4 file back to PGM. This reads the ST-4 file and creates a separate output; it does not alter the source:

$ command -v st4topgm
/usr/bin/st4topgm
$ st4topgm /path/to/image.st4 > /tmp/image-roundtrip.pgm
$ pamfile /tmp/image-roundtrip.pgm
/tmp/image-roundtrip.pgm: PGM raw, 192 by 165

The reverse converter may print metadata such as exposure time or calibration values on standard error. That is not a failure if its exit status is zero and the PGM has the expected dimensions. Compare the round-trip image with the source using an image viewer or comparison tool appropriate to your workflow. This checks the data path, but it does not prove that every downstream ST-4 reader accepts the file.

6. Diagnose rejected input

If the installed converter reports that the image has the wrong height, check the dimensions again. A small test PGM with the wrong geometry was rejected with an error stating that the height must be 165; the corresponding width requirement is 192 for the ST-4 file this Netpbm build produces. These fixed dimensions are the most likely surprise, because the short manual does not list them as command-line options.

$ pgmtost4 /path/to/wrong-size.pgm > /tmp/failed.st4
pgmtost4: Image is wrong height for ST-4 SBIG: 2 pixels.  Must be 165
$ printf 'exit status: %s\n' "$?"
exit status: 1

If the input cannot be opened, check its path and read permission as the current user:

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

Use sudo only if your normal access policy genuinely requires it, and never to hide a bad path or a bad PGM header. Conversion in a user-owned working directory should be unprivileged.

7. Keep the format boundary clear

The ST-4 format is distinct from the SBIG format used by many other SBIG cameras. If your target workflow expects the latter, pgmtost4 is the wrong converter; the manual points to pgmtosbig for that separate format. Check the receiving software's documented format before transferring or archiving the file.

There is no persistent setting to undo from this guide. To discard a test result, delete only the output file you created after confirming its path. To recover an overwritten file, restore it from your normal backup. The safer replacement pattern is to write to a new name, verify it, and then perform any deliberate rename as a separate step.