Convert a PBM Image to BitGraph Data with pbmtobbnbg

You will finish with a BitGraph Display Pixel Data (DPD) file made from a PBM image, ready for a program or terminal path that understands BBN BitGraph graphics. The examples use Netpbm 11.5.2 from Debian package version 2:11.05.02-1.1build1, which is the version 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 does not need root, and it does not edit the input. The 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. These are ordinary read-only commands:

$ 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

Checkpoint: if command -v prints nothing, stop and install Netpbm through your normal package-management process. Do not substitute a similarly named converter. The manpage's synopsis contains a shortened spelling in one place, but the installed executable and command name are pbmtobbnbg.

2. Confirm the PBM input shape

pbmtobbnbg always reads the PBM image from standard input. It does not take an input filename as a positional argument. For a file, inspect it without changing it:

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

The wording from file can vary. You are looking for a PBM image and the dimensions you expect. If the file is not readable, fix the path or permissions first. Do not run the converter as root just 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, the program uses raster operation 3, described by the manual as replace. The output goes to standard output, so shell redirection is what creates the file. There is normally no progress message on the terminal because the converted data is the command's output.

Checkpoint: inspect the output as bytes, not with a text editor. For a small 4 by 2 PBM on this installed build, the stream starts with a BitGraph header containing the dimensions:

$ 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. Use the consumer that needs BitGraph data to perform the real end-to-end check.

4. Choose a raster operation and position

You may give a raster operation, an x y position, or both. If 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. They are not PBM dimensions and they do not resize the image. If you omit the coordinates, the command emits the image without that explicit position. If you omit the raster operation, the default is still 3.

Do not guess a raster operation from a modern graphics API. The accepted value belongs to the BitGraph protocol and the target terminal or consumer must agree with it. Start with the documented default unless you have a specific reason to request another operation.

5. Protect an existing output file

Shell redirection with > truncates an existing destination before pbmtobbnbg starts. That is destructive if the old DPD file is useful. Write a temporary file in the same directory, 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 command changes the destination name and can replace an existing file. Check the input path and temporary name 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. If you need a recoverable rollback, copy the old output to a clearly named backup before the move:

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

Deleting that backup is irreversible, so keep it until the BitGraph consumer has accepted the replacement.

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. This creates a tiny test image in the pipeline without writing a PBM file:

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

The byte count above is the result from the installed Netpbm 11.5.2 build for this exact 2 by 2 input. Do not use a fixed byte count as 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 correct that cause.

There is no reverse bbnbgtopbm tool in the installed Netpbm documentation. Keep the original PBM if you may need to inspect, regenerate or convert the image again. pbmtobbnbg itself makes no persistent configuration change and needs no service restart.