Turn PBM Images into Terminal Art with pbmtoascii

You will convert a monochrome PBM image into ASCII graphics that can be read in a terminal or redirected to a text file. The examples use the pbmtoascii command from Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. Allow about ten minutes if the PBM file already exists.

You need a shell, a readable PBM image and the netpbm package. The conversion is normally an unprivileged operation. You do not need sudo unless your input or output directory has deliberately restricted permissions.

1. Confirm the installed command

Check which executable your shell will run, then inspect the package version. These commands only read local state:

$ command -v pbmtoascii
/usr/bin/pbmtoascii
$ pbmtoascii --version
pbmtoascii: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pbmtoascii: Built from source dated 2024-03-31 09:09:47
$ man pbmtoascii

The program's help output points to its manual page rather than printing a full option list. The installed manual documents one optional input filename and two mappings: -1x2, which is the default, and -2x4.

2. Convert a PBM file with the default mapping

Pass the input filename as the final argument. The result goes to standard output, so redirect it to a new text file:

$ pbmtoascii /path/to/input.pbm > preview.txt

In the default 1x2 mode, each output character represents one pixel across by two pixels down. That keeps individual pixels visible and is usually the better choice for a small image or a diagnostic preview.

For a real output path, use a name that does not already contain something valuable. Shell redirection with > truncates an existing destination before pbmtoascii starts. If the output should replace an existing file, use a temporary name first:

$ pbmtoascii /path/to/input.pbm > preview.txt.new
$ test -s preview.txt.new && mv -- preview.txt.new preview.txt

The second command replaces preview.txt only after a non-empty result exists. If conversion fails, inspect the error and leave the original in place. To recover from a failed attempt, remove the incomplete preview.txt.new after checking that it is the file you intended to discard. That removal is irreversible, so do not use a broad wildcard.

3. Read the output and verify the exit status

A successful conversion usually prints no diagnostic message. The visible output is the ASCII image itself. For example, an 8 by 4 test PBM produced this on the installed command:

o"o"o"o"
oo""""oo

The exact characters depend on the PBM pixels and terminal font. Do not compare a different image with this sample character for character. Check the command status when scripting:

$ pbmtoascii /path/to/input.pbm > preview.txt
$ printf 'conversion status: %s\\n' "$?"
conversion status: 0
$ test -s preview.txt && echo 'ASCII output is non-empty'
ASCII output is non-empty

Status 0 means the command completed successfully. It does not prove that the picture is recognisable. Open the text file in a terminal, and check that the output dimensions and contrast suit the display you are using.

4. Use 2x4 mode for a larger picture

Use -2x4 when the image is too large for the available terminal width or height:

$ pbmtoascii -2x4 /path/to/input.pbm > compact.txt
$ sed -n '1,12p' compact.txt

Here each character represents two pixels across by four pixels down. The output is more compact, but the mapping hides pixel-level detail. A small source can therefore become less informative rather than more readable.

The two documented forms are equivalent in intent:

$ pbmtoascii -1x2 /path/to/input.pbm > detailed.txt
$ pbmtoascii -2x4 /path/to/input.pbm > compact.txt

The first command spells out the default explicitly, which can make a script easier to review. Use one mapping consistently when comparing previews.

5. Feed the image through standard input

Omit the filename when another command is supplying PBM data on standard input. This is useful in a pipeline, and it avoids creating an intermediate PBM file:

$ cat /path/to/input.pbm | pbmtoascii -2x4 > compact.txt

A direct filename is clearer when there is no pipeline. For a filter chain, keep the producer separate so an error is easier to locate:

$ some-pbm-producing-command | pbmtoascii -1x2 > preview.txt
$ printf 'pbmtoascii status: %s\\n' "${PIPESTATUS[1]}"
pbmtoascii status: 0

PIPESTATUS is a Bash array. In another shell, use that shell's pipeline-status mechanism or test each stage separately. A pipeline can otherwise hide a failure in the producer or converter.

6. Diagnose the common failures

If the command reports a usage error, check the option spelling. The installed interface accepts -1x2 or -2x4, followed by an optional PBM filename. An unknown option returns status 1:

$ pbmtoascii -1x2x /path/to/input.pbm
pbmtoascii: usage:  pbmtoascii [-1x2|-2x4] [pbmfile]
$ printf 'status: %s\\n' "$?"
status: 1

If the input cannot be opened, verify the path and read permission without changing anything:

$ ls -l /path/to/input.pbm
$ test -r /path/to/input.pbm && echo readable

If the output looks like a solid block, try the other mapping and inspect the PBM with a separate image viewer or Netpbm tool. pbmtoascii is deliberately a crude renderer, not a faithful image viewer. For colour input, use a tool intended for colour images, such as the related ppmtoterm command documented by Netpbm.

The reverse direction is handled by asciitopgm, but it is not a lossless round trip. The ASCII representation has already collapsed groups of PBM pixels into terminal characters, so keep the original PBM when it matters.