Convert a PBM Image to BitGraph Data with pbmtobbnbg

pbmtobbnbg turns a PBM image into BitGraph Display Pixel Data, the stream format a BBN BitGraph terminal or its emulator expects. These examples use Netpbm 11.5.2 from Debian package version 2:11.05.02-1.1build1, installed on this machine.

Allow about ten minutes. You need pbmtobbnbg, a readable PBM file or PBM data on standard input, and a writable output directory. The converter needs no root, doesn't touch the input, and its output is a binary terminal data stream, not a PNG, SVG or text image.

1. Check the installed command

Confirm which executable will run and record its Netpbm build information. Both are ordinary, read-only checks:

$ command -v pbmtobbnbg
/usr/bin/pbmtobbnbg
$ pbmtobbnbg -version 2>&1 | sed -n '1,3p'
pbmtobbnbg: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pbmtobbnbg: Built from source dated 2024-03-31 09:09:47
pbmtobbnbg: Built by Debian

2. Confirm the PBM input shape

pbmtobbnbg always reads the PBM image from standard input: it never takes an input filename as a positional argument. Check a file without changing it:

$ file /path/to/input.pbm
/path/to/input.pbm: Netpbm PBM image data, 4 x 2

The exact wording from file varies by distribution. You're looking for a PBM image and the dimensions you expect. If the file isn't readable, fix the path or permissions first rather than running the converter as root to bypass an uncertain path.

3. Convert PBM input using the default operation

Pipe the PBM file into the converter and redirect its binary output to a new destination:

$ pbmtobbnbg < /path/to/input.pbm > /path/to/output.dpd
$ test -s /path/to/output.dpd && echo 'BitGraph data written'
BitGraph data written

With no raster operation or position given, the program uses raster operation 3, which the manual calls replace. The output goes to standard output, so it's the shell redirection that actually creates the file. There's normally no progress message, because the converted data is the command's entire output.

$ od -An -tx1 -N9 /path/to/output.dpd
 1b 50 3a 33 3b 34 3b 32 73

That byte sequence is an observation for this input and build, not a portable way to parse every DPD stream. The real end-to-end check is the consumer that actually needs BitGraph data.

4. Choose a raster operation and position

You can give a raster operation, an x y position, or both. When all three values are present, the raster operation comes first:

$ pbmtobbnbg 3 10 20 < /path/to/input.pbm > /path/to/output-at-10-20.dpd
$ test -s /path/to/output-at-10-20.dpd && echo 'positioned BitGraph data written'
positioned BitGraph data written

• The coordinates are x and y positions in the BitGraph output space, not PBM dimensions. They don't resize the image.
• Omit the coordinates and the command just emits the image with no explicit position.
• Omit the raster operation and the default is still 3.

Don't guess a raster operation from a modern graphics API: the accepted value belongs to the BitGraph protocol, and whatever terminal or consumer receives it has to agree. Start with the documented default unless you've a specific reason to ask for another.

5. Protect an existing output file

Shell redirection with > truncates an existing destination before pbmtobbnbg even starts, which is destructive if the old DPD file is worth keeping. Write a temporary file, check it, then replace the destination deliberately:

$ tmp='/path/to/output.dpd.new'
$ pbmtobbnbg < /path/to/input.pbm > "$tmp"
$ test -s "$tmp"
$ mv -- "$tmp" /path/to/output.dpd
$ test -s /path/to/output.dpd && echo 'replacement is non-empty'
replacement is non-empty

The mv is the step that can replace an existing file, so check both paths before running it. If conversion fails, leave the old output alone and remove only the incomplete temporary file with rm -- /path/to/output.dpd.new, after checking that exact path. For a recoverable rollback, copy the old output to a clearly named backup first:

$ cp --preserve=all /path/to/output.dpd /path/to/output.dpd.bak

6. Diagnose the common failures

A missing or malformed PBM normally produces an error and a non-zero exit status. Check the source independently, then retry with a known-good PBM built inline, no file required:

$ printf 'P1\n2 2\n0 1\n1 0\n' | pbmtobbnbg > /tmp/test.dpd
$ printf 'exit status: %s, bytes: ' "$?"
exit status: 0, bytes: 19

That byte count is specific to Netpbm 11.5.2 and this exact 2 by 2 input, not a general validity test. A non-zero status points to input parsing, an invalid invocation or an output problem: capture the diagnostic from standard error and fix that cause.

There's no reverse bbnbgtopbm tool in the installed documentation, so keep the original PBM if you might need to inspect, regenerate or reconvert later. pbmtobbnbg itself makes no persistent configuration change and needs no service restart.