Convert a PBM Bitmap to an Andrew Toolkit Raster with pbmtoatk

pbmtoatk turns a monochrome PBM image into the raster object format that Andrew Toolkit programs expect. It writes to standard output, so the only real risk is a careless redirect overwriting a file you meant to keep. Budget five minutes if the PBM is already sitting there.

The route

Jump straight to the step you need, or tick off Done means at the end.

What you need
1. Check the PBM input
2. Convert to an Andrew Toolkit raster file
3. Use standard input in a pipeline
Common failure modes

What you need

Netpbm installed. Checked against Debian package netpbm 2:11.05.02-1.1build1, providing Netpbm 11.5.2.
A readable PBM file. PBM is a strictly two-colour bitmap format: black and white, no greyscale or colour.
Write permission where the output lands. Nothing here needs root.

Checkpoint

Confirm the program you're about to run is the one you expect.

command -v pbmtoatk
pbmtoatk -version

The first line should print /usr/bin/pbmtoatk. The second prints Netpbm build information, including Netpbm Version: Netpbm 11.5.2, and exits cleanly without converting anything.

1. Check the PBM input

Inspect the file type and dimensions before converting. Swap in your own path: the extension is just a convention, the contents have to be PBM.

INPUT='/path/to/input.pbm'
file "$INPUT"
pnmfile "$INPUT"

A valid file is identified as Netpbm image data, and pnmfile reports a PBM image with a width and height.
No pnmfile available? file alone is still a useful first check.
Do not use a file you don't trust. Conversion reads it, but reading is not the same as making an unsafe source safe.

PBM comes in raw and plain forms: raw starts with P4, plain starts with P1. Both are valid. It's strictly monochrome, so anything with grey or colour needs converting to PBM first with another Netpbm tool.

2. Convert to an Andrew Toolkit raster file

Run pbmtoatk with the PBM path and redirect standard output to a new file. There are no options specific to this conversion.

INPUT='/path/to/input.pbm'
OUTPUT='/path/to/output.rast'
pbmtoatk "$INPUT" > "$OUTPUT"

The output filename needs no particular suffix. .rast is just a clear local convention: the data is Andrew Toolkit's raster object format, not PBM. Success is silent, with exit status zero. Use a directory you own instead of reaching for sudo; there is no elevated-privilege step here.

Checkpoint

Verify the file exists and starts like an Andrew Toolkit raster object.

test -s "$OUTPUT" && sed -n '1,6p' "$OUTPUT"
printf 'exit status: %s\n' "$?"

A small successful result starts with lines like these:

\begindata{raster,1}
2 0 65536 65536 0 0 8 4
bits 1 8 4

The dimensions in that header should match the PBM's. The lines after that encode the bitmap rows for the Andrew Toolkit reader: don't hand-edit them unless you're deliberately working with the raster format itself.

3. Use standard input in a pipeline

The optional pbmfile argument means input can come from standard input too, handy when another Netpbm command already produces PBM and an intermediate file would just be clutter.

pnmfile "$INPUT"
cat "$INPUT" | pbmtoatk > "$OUTPUT"

The explicit cat is there so you can swap in a real producer without changing the shape of the pipeline:

some-pbm-producing-command | pbmtoatk > "$OUTPUT"

Keep diagnostic text out of that stream. Standard output is the converted object, and a redirection like > saves it byte for byte. If you want diagnostics kept separately, redirect standard error on its own:

pbmtoatk "$INPUT" > "$OUTPUT" 2>pbmtoatk.err

Common failure modes

Wrong path or permissions

A missing input file produces an error naming the path and a non-zero exit status. Check the path and read permission, then rerun. If a failed redirection already created the output file, inspect it before reusing that name. The safe retry writes a new temporary output and swaps it in only after success:

tmp_output=$(mktemp "\${OUTPUT}.XXXXXX")
if pbmtoatk "$INPUT" > "$tmp_output"; then
    mv "$tmp_output" "$OUTPUT"
else
    status=$?
    rm -f "$tmp_output"
    exit "$status"
fi

State only changes at the final mv. If conversion fails, the previous $OUTPUT stays untouched, and the rm removes nothing but the temporary file this script just created.

Input is not PBM

If Netpbm can't parse the input, stop and work out its real format. Don't just rename a PNG, JPEG or PGM to make it look like PBM: convert it properly with a format-appropriate tool, then run pnmfile again. A passing file-type check still doesn't replace actually looking at the dimensions and appearance.

Output looks empty or corrupt

Check the exit status and the first lines of the output before you open it anywhere else. Also check the source dimensions make sense and that nothing overwrote the output afterwards. Because the result is a textual Andrew Toolkit object with encoded bitmap data, a text editor will show readable headers, it just isn't an image viewer.

Done means

Version confirmed. pbmtoatk -version identifies the installed Netpbm build.
Source checked. The input is a readable PBM image with the dimensions you expect.
Conversion clean. pbmtoatk "$INPUT" > "$OUTPUT" exits zero.
Output verified. It's non-empty and begins with an Andrew Toolkit raster header.
Source kept. The original PBM is still there and the conversion is reproducible.