Turn ASCII shading into a PGM image with asciitopgm

You will convert a fixed-size ASCII drawing into a greyscale PGM image, adjust its character brightness, and check the output without changing the source text. Allow about ten minutes. You need a shell, the netpbm package, and an ASCII input whose intended height and width are known.

1. Check the installed command

This guide follows Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. The local manual page is dated 20 January 2011, so examples describe the installed command's behaviour rather than promising identical details for every Netpbm release.

$ command -v asciitopgm
/usr/bin/asciitopgm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The command takes the output height first, then the output width, followed by an optional input file:

asciitopgm [-d divisor] height width [asciifile]

That order is an easy distraction trap. asciitopgm 3 4 means three rows high and four columns wide, not four rows high and three columns wide.

2. Make a small input with an explicit size

Use a new working directory so the input and generated image are easy to identify. This ordinary shell operation needs no elevated privileges:

$ mkdir -p ~/asciitopgm-example
$ cd ~/asciitopgm-example
$ printf 'M.  \n .# \n    \n' > drawing.txt
$ wc -l -L drawing.txt
3 4 drawing.txt

The file contains three lines, each four characters wide. The spaces at the ends are meaningful: a space represents white, and a missing character is also padded with white. Avoid editors or copy-and-paste tools that trim trailing spaces if those spaces form part of the drawing.

Checkpoint: inspect invisible line endings and trailing spaces before converting:

$ sed -n 'l' drawing.txt
M.  $
 .# $
    $

3. Convert the drawing to PGM

Redirect standard output to a new file. The command reads the input as ASCII character data and assigns a greyscale value based on an assumed printing font. Capitals such as M are normally dark, a full stop is lighter, and a space is white. This is an approximation, not a font renderer.

$ asciitopgm 3 4 drawing.txt > drawing.pgm
$ file drawing.pgm
drawing.pgm: Netpbm image data, size = 4 x 3, rawbits, greymap
$ head -n 3 drawing.pgm
P5
4 3
127

The PGM header shows width 4 and height 3. The maximum sample value is 127 for this command's output. The remaining bytes are binary pixel samples, so do not inspect the whole file with a text editor.

There is no need for sudo. If the command fails, read the input and write the output in a directory you own. Keep the original text file until the image has been checked.

4. Tune the character darkness

Use -d with an integer divisor when the result is not dark or light enough for your use. Its default is 1. The manual describes the value as dividing character blackness and also states that larger values produce darker output; use a small trial conversion and inspect the image rather than guessing from the option name.

$ asciitopgm -d 2 3 4 drawing.txt > drawing-dark.pgm
$ file drawing-dark.pgm
drawing-dark.pgm: Netpbm image data, size = 4 x 3, rawbits, greymap

Use a positive decimal integer such as 2 or 4. Keep the same height and width while comparing files. A change to either dimension changes how many output samples are written; it is not a brightness adjustment.

Checkpoint: compare the headers before opening the images:

$ head -n 3 drawing.pgm
P5
4 3
127
$ head -n 3 drawing-dark.pgm
P5
4 3
127

5. Use standard input or overstrike rows

Omit the input filename to read from standard input. This is useful in a pipeline, but keep the dimensions explicit:

$ printf 'AB\n' | asciitopgm 1 3 > piped.pgm
$ head -n 3 piped.pgm
P5
3 1
127

Input lines shorter than the requested width are padded with white, and longer lines are truncated. Extra input rows beyond the requested height are ignored. This makes a successful exit status insufficient proof that the dimensions were correct.

A line beginning with + is special. Instead of starting a new output row, asciitopgm combines the rest of that line with the previous row. This overstrike-style behaviour can represent a wider range of grey values. The plus sign is not part of the image row in that case; at the start of the input there is no previous row to combine with, so use this feature only after an ordinary row.

6. Handle input warnings and failed replacements

The program uses the lower seven bits of each input byte and warns when a byte has its most significant bit set. It is therefore intended for ASCII data, not arbitrary UTF-8 artwork. If you see that warning, check the file encoding rather than treating accented or non-Latin characters as reliable shades.

Shell redirection truncates an existing destination before the converter runs. Protect a useful image by writing to a temporary name, checking it, and then replacing the old file:

$ asciitopgm 3 4 drawing.txt > drawing.pgm.new
$ file drawing.pgm.new
drawing.pgm.new: Netpbm image data, size = 4 x 3, rawbits, greymap
$ mv drawing.pgm.new drawing.pgm

If conversion fails, leave drawing.pgm alone and remove the incomplete drawing.pgm.new after checking the error. The mv command changes the destination, so run it only after the replacement has the expected dimensions.