Convert an SBIG CCDOPS File to PGM with sbigtopgm

sbigtopgm turns an SBIG astronomy camera's native file into a PGM image that Netpbm, GIMP or almost anything else can open. The original file is left untouched; the conversion only writes a new one. Allow about ten minutes if the camera file is already on the machine.

• A Linux shell and the netpbm package installed.
• A readable SBIG file to convert.

The examples below use Netpbm 11.5.2 from Debian package 2:11.05.02-1.1build1. The installed manual is dated 18 January 2015, so this guide describes the behaviour confirmed on that installation.

1. Check the installed converter

Confirm which executable runs and record its Netpbm version. Both commands are read-only and need no elevated privileges:

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

The version output includes build details alongside the library version. There is no separate option for picking an output format, dimensions or colour mode: sbigtopgm's whole job is reading the SBIG native format and producing PGM, nothing else.

2. Check that the input is readable

Use a real path in place of /path/to/image.sbig. The filename extension is not the test: sbigtopgm reads the file contents, and SBIG files turn up under all sorts of naming conventions.

$ test -r /path/to/image.sbig && echo 'input is readable'
input is readable
$ ls -lh /path/to/image.sbig
-rw-r--r-- 1 you you 2.4M Sep 26 10:15 /path/to/image.sbig

If the first command prints nothing, the file is either missing or your account cannot read it. Fix the path or the access through your normal data-management process. Do not reach for sudo as a first response: running the conversion as root can leave an output file your normal account cannot replace or inspect.

3. Convert a named file without overwriting anything

The synopsis takes one optional sbigfile argument. Supply it and the converter reads that file and writes the PGM image to standard output, which you redirect to a new destination:

$ sbigtopgm /path/to/image.sbig > image.pgm

A successful run normally leaves the terminal quiet, because the image data is the standard output rather than a status message. sbigtopgm only reads the input file; shell redirection is what creates image.pgm.

$ printf 'converter status: %s\n' "$?"
converter status: 0
$ test -s image.pgm && echo 'PGM output exists and is non-empty'
PGM output exists and is non-empty
$ file image.pgm
image.pgm: Netpbm image data, ...

The exact wording from file depends on its version, but it should identify a Netpbm image and report dimensions. A zero-byte or missing output is not a successful conversion, even if a wrapper script carried on regardless.

4. Use standard input when that suits the pipeline

The input argument is optional, so you can feed the SBIG data in on standard input instead. That is useful when another command has already selected or unpacked the file:

$ cat /path/to/image.sbig | sbigtopgm > image.pgm

• For a single local file, naming it directly is easier to review than piping through cat.
• Only the converted PGM should ever land on standard output; keep diagnostics on standard error if you wrap the command in a script.
• Do not test with an empty pipe. On the installed command, empty standard input fails with error reading SBIG file header and produces no image, which is a different failure from a valid file holding a very dark or blank frame.

5. Protect an existing PGM

> image.pgm truncates an existing file before sbigtopgm even starts. That is destructive if the destination already holds a useful image. Choose a fresh name, or convert to a temporary file and promote it only after checking the result:

$ tmp_pgm="image.pgm.tmp.$$"
$ sbigtopgm /path/to/image.sbig > "$tmp_pgm" && test -s "$tmp_pgm"
$ mv -- "$tmp_pgm" image.pgm

The mv runs only after the conversion and the non-empty check both succeed, and it replaces image.pgm if that file already exists. Inspect the temporary output with file or an image viewer before running that final command whenever the old image matters.

$ rm -- "$tmp_pgm"

That removal is irreversible, but it only ever targets the temporary output, never the original SBIG file. Keep the source until the PGM has been opened or processed successfully.

6. Diagnose a failed conversion

Capture errors separately when you need to investigate without mixing text into the PGM stream:

$ sbigtopgm /path/to/image.sbig > image.pgm 2> sbigtopgm.err
$ status=$?
$ printf 'converter status: %s\n' "$status"
converter status: 0
$ test "$status" -eq 0 && test -s image.pgm
$ sed -n '1,20p' sbigtopgm.err

For a successful run, the error file should be empty. If the header cannot be read, check you supplied the actual SBIG file rather than a text export, a partial download or an unrelated image. sbigtopgm recognises variations of the documented SBIG Type 3 format, including any capitalisation in the header and whitespace other than newlines, but that tolerance does not make an arbitrary file valid SBIG input.

• There are no sbigtopgm-specific switches listed in its manual. Do not add guessed width, height, crop or exposure options.
• Need further processing? Verify the PGM first, then pass it to a separate Netpbm tool built for that job.