Send a PBM Image to a GraphOn Terminal with pbmtogo

You will convert a PBM bitmap into the compressed GraphOn graphics stream produced by pbmtogo, save that stream safely, and understand what must be configured before sending it to a GraphOn terminal. The installed command is Netpbm 11.5.2 from package version 2:11.05.02-1.1build1.

Allow about fifteen minutes. You need a shell, the netpbm package, a readable PBM file, and either a GraphOn terminal or a way to transfer its output stream. The examples write files in the current directory and do not require elevated privileges. They do not change the source bitmap.

1. Check the installed command

Confirm that the executable is present and record its version. These are ordinary read-only checks:

$ command -v pbmtogo
/usr/bin/pbmtogo
$ pbmtogo -version
pbmtogo: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pbmtogo: Built from source dated 2024-03-31 09:09:47
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The rest of this guide describes that installed build. -version is a common Netpbm option, not a pbmtogo-specific image option. The manual defines no command-line options specific to this program.

2. Inspect the PBM input

pbmtogo reads a PBM image. Check the file without opening it in a terminal, because the output is an image stream rather than human-readable text:

$ INPUT='/path/to/image.pbm'
$ test -r "$INPUT" && echo 'input is readable'
input is readable
$ file "$INPUT"
/path/to/image.pbm: Netpbm image data, size = 320 x 200, bitmap, ASCII text

Your file description may say rawbits instead of ASCII text. The useful checks are that the file is readable and that it is identified as a PBM bitmap. A PGM or PPM image is a different Netpbm format and is not a valid substitute just because its filename ends in .pbm.

If you need a small test image and pbmmake is installed, create one in a temporary location rather than replacing a real bitmap:

$ pbmmake -gray 64 48 > /tmp/pbmtogo-test.pbm
$ file /tmp/pbmtogo-test.pbm
/tmp/pbmtogo-test.pbm: Netpbm image data, size = 64 x 48, bitmap, ASCII text

The test image is disposable. Remove it later with rm -- /tmp/pbmtogo-test.pbm only when you no longer need it.

3. Convert to a saved GraphOn stream

Pass the PBM filename as the optional positional argument and redirect standard output to a new file:

$ pbmtogo "$INPUT" > image.graphon.new
$ status=$?
$ printf 'pbmtogo exit status: %s\n' "$status"
pbmtogo exit status: 0
$ test "$status" -eq 0 && test -s image.graphon.new && echo 'non-empty GraphOn stream written'
non-empty GraphOn stream written

The output is compressed GraphOn graphics, including terminal control bytes. It is normal for file to call the result simply data, and it is not useful to inspect the whole file with cat. A zero exit status and a non-empty destination show that the conversion completed; they do not prove that a GraphOn terminal is configured correctly.

Redirection with > truncates its destination before the converter starts. That is why the example uses image.graphon.new. After checking the new file, make it the chosen output:

$ wc -c image.graphon.new
58 image.graphon.new
$ mv -- image.graphon.new image.graphon
$ test -s image.graphon && echo 'final stream is non-empty'
final stream is non-empty

The byte count depends on the bitmap. If conversion fails, leave the old destination alone and remove the incomplete .new file with rm -- image.graphon.new. If you need to undo the successful rename, use a deliberate replacement such as mv -- image.graphon image.graphon.previous; do not delete a file you have not backed up.

4. Use standard input when a pipeline is clearer

With no filename, the command reads the PBM image from standard input. This produces the same kind of stream:

$ pbmtogo < "$INPUT" > image-from-stdin.graphon.new
$ test -s image-from-stdin.graphon.new && echo 'stdin conversion produced output'
stdin conversion produced output
$ mv -- image-from-stdin.graphon.new image-from-stdin.graphon

Use this form when another trusted Netpbm tool already emits PBM. Keep the input and output directions visible. Accidentally typing pbmtogo without an input file at an interactive prompt can make it wait for data from the keyboard, while accidentally writing the binary result to your terminal can leave the terminal displaying control characters.

Do not pass several input filenames. The synopsis accepts at most one PBM filename, and the program produces one output stream. Build a loop around separate invocations if you have several images, giving every output a distinct temporary name.

5. Prepare a GraphOn terminal before transmission

The manual requires these GraphOn communication settings: 8 bits, no parity, XON/XOFF disabled, and NUL characters accepted. It also says to turn off tty post-processing. Configure those settings in the GraphOn communication menu before sending the stream. These are terminal settings, not pbmtogo flags.

Test with the saved file first. Sending binary control sequences directly to the wrong terminal can alter its state or make the shell display unreadable characters. A normal file check is safer:

$ od -An -tx1 -N 12 image.graphon
 1b 31 1b 0c 1b 72 1b 5b 3d 31 31 6c

On this Netpbm build, a small sample begins with those escape bytes. The exact length and later bytes depend on the bitmap. Do not edit the stream as text and do not add a newline to it.

When the terminal is correctly configured, transfer the file using the terminal connection method appropriate to your system. Keep the original PBM and the saved stream until the display has been checked. No root access is needed unless your separate transfer mechanism or device permissions specifically require it.

6. Diagnose failures without guessing

A missing or unreadable input is a path or permission problem. Check it without changing permissions:

$ ls -l -- "$INPUT"
$ test -r "$INPUT" && echo readable || echo 'not readable'
not readable

Correct the path or ask the file owner to grant appropriate read access. Avoid using sudo merely to hide a typo. If the input is not actually PBM, convert it with a separate Netpbm tool first, then inspect the converted file.

If a command reports an invalid Netpbm magic number, the input may be empty, corrupt, or another image format. If output is empty or the exit status is non-zero, do not rename the temporary file over a useful result. Keep the source and rerun after fixing the input.

If the file converts successfully but the GraphOn display is wrong, check the four communication settings and tty post-processing first. The manual states that there is no gotopbm tool, so pbmtogo is a one-way conversion for this workflow. It does not provide a command-line option to reverse the saved stream back into PBM.