Program #8: The Future Pleads, 'Save Your ASCII Art!'

CSc 352 — Systems Programming and UNIX 

Fall 2012 (McCann) 

http://www.cs.arizona.edu/classes/cs352/fall12/ 

Program #8: The Future Pleads, ‘Save Your ASCII Art!’ 

Due Date: November 20 th , 2012, at the beginning of class 

Overview: Backinthegoodol’daysofcomputing, whenyourscreenhadonewindow(creatively, the‘screen’), 

it showed only ASCII (or EBCDIC) characters, and printers were large, loud, and consumed fan-fold paper by 

the box-full, users demonstrated their creativity by constructing and distributing “ASCII art”. Each picture 

used a subset of the printable ASCII characters to form an image by using one character for each pixel of the 

picture’s representation. Up close, the image often looked like a bunch of characters, but from a distance it 

looked like ...a bunch of characters that sort of resembled a picture. 

It’s a good thing you know all of this, because recently your phone rang and you received an oddly distorted 

call ...from the future! “Please, you must help. We’ve lost all of the ASCII art created in the past, and have 

only enough power in our temporal iPad 26 to call back to 2012. Convert all of the ASCII art you can find to 

the one true image format, PCX, and put it on a USB stick stuck with gum under the bar in Dirtbag’s for us. 

Our historians are counting on you!” 

The future is in luck; there are still a few archives of ASCII art on the ’net. Your task is to write a C program 

that accepts the filename of such an image’s text file and converts it to a (binary) PCX file. PCX was created 

by ZSoft for its PC Paintbrush program, which Microsoft distributed with its first Microsoft Mouse in the late 

1980s. Its simplicity earned it a long life and widespread support in image viewing programs, although you 

hardly ever find an image stored in that format today. Clearly, the format is due for a resurgence in the future! 

EventhoughthePCXformatissimplebycomparisontoJPGorPNGformats, it’snotexactlytrivial. Attached 

to this handout is a brief description of the PCX format. Expect to read that description several times before 

you have a good feel for what’s going on! Note that we will not be using the color palette section, just the 

header and the image data sections. 

Assignment: Write a complete, well-documented (take that, whm! :-)), well-structured C program named 

prog08.c that reads an ASCII image from a text file whose name is given on the command line (e.g., 

myimage.txt) and creates a PCX version of that image named with the same name but a .pcx extension 

(e.g., myimage.pcx). Following the text file’s name on the command line may be a second argument; see below 

for details. 

Data: While you’re keen to help the future, you have limited time. You will assume that the length of the first 

line of the supplied text file is the length of all of the file’s lines. If an image has some longer lines, truncate 

them. For shorter lines, pad them with spaces to reach the length of the first line. 

Each image will have at least one pixel (the future doesn’t want void art). If the image filename is not supplied, 

if it cannot be opened for reading for any reason, or if any out-of-range characters are encountered, display an 

error message and terminate. 

Here’s an example of a small ASCII image file’s contents (from http://www.asciiworld.com): 

xMhn. .nlMx 

XMMf" xXMX XMXx "lMMX 

"=x.. ......-MMMX "MMMMMmMMMMM" XMMM-....... ..x=" 

x ‘"!MMMMMMMMMMMMx’MM> "MMMMMMM"

tilde (ASCII 126). Any given ASCII image is unlikely to use them all, so your program will have to determine 

which characters the given image actually uses, and map them to grayscale colors to be used in the PCX 

version. See the Output section for details. 

As mentioned above, the command line is expected to contain at least the file name and extension, if any, 

of the source file. The same file name (w/o any extension) is to be used as the name of the PCX file, just 

with the extension “.pcx” appended. Thus, if the input file name is apple.txt, the output file name would 

be apple.pcx. You may assume that the last period of the command line argument and any subsequent 

characters comprise the extension. That is, .ascii is the extension of this.is.my.image.ascii. 

Optionally, a second string may be supplied on the command line that is the dark-to-light sequence of the 

ASCII characters that the user wishes to use for this image. For example, the string @#A8%(, indicates that @ 

is the darkest shade of gray and , the lightest, for that image. If the string has a larger selection of characters 

than does the image, no problem; some shades of gray won’t be used. If the opposite is true, display an error 

message and terminate the program. 

Output: In keeping with traditional UNIX utility practice, your program should output nothing to the screen 

if the conversion to PCX is successful, and it should create the .pcx file with a name constructed as discussed 

above. Display error messages to stderr as necessary. 

As you have probably inferred from the optional dark-to-light command-line string, we aren’t specifying a 

specific grayscale sequence for the 95 ASCII characters; you are to define your own default sequence of those 

ASCII characters, to use when the user doesn’t provide one. (When the user does supply one, your program 

is to create a mapping on the fly.) PCX allows 256 intensities for each of red, green, and blue in the RGB 

system. To create shades of gray, simply set R = G = B. With 256 intensities for each of R, G, and B, you 

can form a grayscale for the 95 characters with room to spare. 

To verify that your PCX file is correctly structured, use an image viewing program capable of displaying PCX 

files. If it can display it, and it looks like your source ASCII art image, your file’s format is probably OK. 

Some suggestions for image viewers are given below. 

Turn In: Use turnin to submit your prog08.c file to the submission directory cs352p08. Of course, make 

sure that it compiles and executes correctly on lectura before you do. 

General Requirements, Hints, and Miscellany: 

• If you feel the following PCX file format information is inadequate, you can find descriptions on the ’net. 

For example: http://www.fileformat.info/format/pcx/egff.htm and 

http://www.techheap.com/compression/graphics/pcxfmt.html 

• Creating a grayscale mapping of ASCII characters to intensities of gray is subjective. 

http://paulbourke.net/dataformats/asciiart/ offers an incomplete “character ramp” from dark to 

light that you might wish to use as a starting point (note that the space character is at the far end, but 

is of course not displayed): 

$@B%8&WM#*oahkbdpqwmZO0QLCJUYXzcvunxrjft/\|()1{}[]?-_+~i!lI;:,"^‘’. 

• NeedsomeASCIIimagesfortesting? http://www.asciiworld.com/andhttp://www.chris.com/ascii/ 

have a lot you can cut-n-paste. (Most images are G-rated, but these sites have ‘adult’ images, too. Shockingly, 

the pre-Internet era of computing was not terribly different from the modern Internet era. You’ve 

been warned!) 

Don’t bothering trying Google Images; it has examples, but formatted as .gif, .jpg, and/or .png files. 

• Suggestions for image viewers that can handle PCX files: 

– (Nearly) All OSes: Gimp (/usr/bin/gimp in the lab, or free from www.gimp.org) 

– Windows: Irfanview (free from www.irfanview.com) 

– Linux: Eye of Gnome (/usr/bin/eog in the lab) 

You’ll probably have to turn off pixel blending (which goes by various names in menus) in some programs, 

and use extreme zooming, to get a clear view of the individual pixels in images. 

2

Historical Background 

A Description of the PCX Image File Format 

(L. McCann) 

When Microsoft began selling its own mouse (creatively named “The Microsoft Mouse”), it promoted its use 

by shipping it with a program called PC Paintbrush, written by a company named ZSoft. Both ZSoft and PC 

Paintbrush are long gone, but the image file format ZSoft created for it, PCX, lives on, even though today it 

is more than a bit outdated. 

The PCX File Format 

A PCX file has two, and possibly three, sections: 

1. Header (exactly 128 bytes) 

2. Image Data (unlimited) 

3. Color Palette (exactly 768 bytes, used only for 256-color images) 

Here are the details on these three sections. 

1. Header: The header contains several fields, some of which are essentially constants while others changed 

based on the image. The following table briefly explains each field: 

Byte(s) Field Type Value Remarks 

0 Manufacturer unsigned char 10 10 = ZSoft 

1 Version unsigned char 5 Version 5 is the most recent 

2 Encoding unsigned char 1 1 means that the image is encoded in RLE 

3 Bits Per Pixel unsigned char 8 2 8 =256, num. of intensities per color 

4-5 Xmin 2-byte integer - (Xmin,Ymin) is upper left corner of image 

6-7 Ymin 2-byte integer - ” 

8-9 Xmax 2-byte integer - (Xmax,Ymax) is lower right corner 

10-11 Ymax 2-byte integer - ” 

12-13 Horizontal DPI 2-byte integer - often ignored, or = 300 by default 

14-15 Vertical DPI 2-byte integer - ” 

16-63 EGA Colormap 48 bytes 0’s unused for modern graphics modes 

64 – unused – unsigned char 0 Reserved; set to 0 

65 Color Planes unsigned char 3 One each for Red, Green, and Blue 

66-67 Bytes per Line 2-byte integer - Really bytes/line/color 

68-69 Palette Type 2-byte integer 1 1 means a color or grayscale palette 

70-71 Horiz. Screen Size 2-byte integer - Depends on size of window 

72-73 Vertical Screen Size 2-byte integer - ” 

74-127 Filler 54 bytes 0’s Room for future expansion 

2. Image Data: The image data (a.k.a. color planes) is usually compressed using a technique called RLE 

– Run-Length Encoding. Information on how PCX handles each is covered in this section. 

• PCX’s Implementation of RLE. 

In RLE, if you have a sequence of identical values (a ‘run’), you store one copy of that value and 

a repetition quantity instead of the sequence. For example, instead of storing “4 4 4 4 4 4”, RLE 

stores “6 4”. 

(continued ...) 

3

But how do you know that 6 is a count, and not a data value? PCX’s version of RLE solves the 

problem this way: 

– If a byte’s value is < 192, then it is the value of a single pixel. 

– If it is >= 192, then it is a count equal to itself minus 192. The next byte is repeated that 

many times within the image. 

Notes: 

∗ The maximum byte value is 255, making the longest possible run 63 (255 - 192). 

∗ How can we store a data value that is >= 192? We store it as a run of size 1. For example, 

200 is stored as the pair 193 200. 

∗ Instead of just reading to the end of the file, it is smarter to verify that, after decompression, 

the total number of pixels found is equal to (Xmax−Xmin+1)∗(Ymax−Ymin+1). 

∗ Runs are not allowed to extend beyond the end of a scan line (that is, beyond the end of a 

row of pixels). 

∗ (256 colors only!) Immediately following the compressed image data is a byte with the value 

12. 

As an example, let’s decompress the sequence 195 16 127 193 192 200 6. “195 16” decompresses 

to “16 16 16” (195 - 192 = 3 copies). 127 is less than 192, and so is just 127. “193 192” becomes 

the value 192. Finally, “200 6” decompresses to “6 6 6 6 6 6 6 6”. The result: 16 16 16 127 192 

6 6 6 6 6 6 6 6 

• Color Planes. 

If the image is capable of having more than 256 colors, PCX encodes the color data as part of the 

picture data, and the third section of a PCX file, the color palette, is not used. (If the color planes 

field of the header is set to 3, your file is capable of having more than 256 colors.) 

Each scan line is stored as three RLE–compressed color lines – R (red), G (green), and B (blue) – 

in that order. Here’s a representation of the color data order for first two scan lines of an image: 

/ RLE-compressed Red data 

Scan Line (Row) #0 RLE-compressed Green data 

\ RLE-compressed Blue data 

/ RLE-compressed Red data 

Scan Line (Row) #1 RLE-compressed Green data 

\ RLE-compressed Blue data 

For example, consider a 2-column by 3-row image of 24 bits per pixel (8 bits per color): 

( R , G , B ) ( R , G , B ) 

----------------------------- 

Row 0: | ( 32, 64,128) (255,255,255) | 

Row 1: | (255,255,255) (255, 0,128) | 

Row 2: | (255,255,255) (255,255,255) | 

----------------------------- 

In hexadecimal, here are the PCX RLE encodings of the three rows. Remember, we’re encoding 

each color of each row separately, and note that C016 = 19210: 

Colors: ----RED---- ---GREEN--- ----BLUE---- 

Row 0: Color Sequences: [ 32 255 ] [ 64 255 ] [ 128 255 ] 

Hex encoding: 20 C1 FF 40 C1 FF 80 C1 FF 


Hex encoding: C2 FF C1 FF 00 C1 FF 80 


Hex encoding: C2 FF C2 FF C2 FF 

(continued ...) 

4

3. Color Palette (for 256-color images only): 

For 256-color (VGA) images, the palette is 768 bytes in length. Each color is a RGB intensity triple; R, 

then G, then B, with one byte per color. As an example, here are the first three palette entries: 

R G B R G B R G B 

Byte 0 1 2 3 4 5 6 7 8 

Color #0 #1 #2 

The intensities are in the range 0–255. If the image’s data intensities do not match this range, they must 

be scaled accordingly. For example, in VGA’s Mode 13h, which was once very popular for MS-DOS 

games, intensities are in the range 0–63. To save a Mode 13h image in PCX, the intensities must be 

multiplied by 4. 

Because the palette is at the end of the file, it is easy to read the palette before reading the image data. 

This is desirable so that the image data can be decoded directly to the screen. C’s fseek() function 

makes this easy: fseek(fp, -768, SEEK END); 

Remember: For this assignment, we are not using the color palette section! 

On Converting from ASCII Characters to Colored Pixels 

The above example moves from RGB triples (colors of pixels) to an RLE encoding. You may be wondering 

how to move from ASCII characters to the RGB triples. This example may help. 

First, you need a translation table that matches characters to RGB triples. That is, you’d want to say, for 

example, that a space is white (red = green = blue = FF16, or (FF,FF,FF)), an ‘X’ is mostly red (C816,0,0), 

and an ‘O’ is lightly green (0,6416,0). Of course, you’ll have to do that for the other 92 characters, too. 

Second, you need to form the sequences of red, green, and blue components for each row before you can 

compress them (and remember that each color of each row is compressed separately). 

Let’s say that you want to use the above colors for space, ‘X’ and ‘O’ to convert this tic-tac-toe board into 

a 3x3 image. The diagram shows the conversion from characters to RGB triples, and the arranging of color 

components into sequences. From there, the individual sequences can be run-length encoded. 

3 3 

XOX (C8,00,00) (00,64,00) (C8,00,00) R:[C8 00 C8] G:[00 64 00] B:[00 00 00] 

OX ==> (00,64,00) (C8,00,00) (FF,FF,FF) ==> R:[00 C8 FF] G:[64 00 FF] B:[00 00 FF] 

X O (C8,00,00) (FF,FF,FF) (00,64,00) R:[C8 FF 00] G:[00 FF 64] B:[00 FF 00] 

ASCII RGB (R,G,B) Triples Unencoded Color Sequences 

5

Bonus Example 

Consider this grayscale representation of a 4x2x24bpp PCX file: 

The non–white pixel on the top row is black, and the pixel on the second row is a dirty green. (View the PDF 

of this handout to see the lovely green color.) Here is the hexadecimal dump of this PCX file: 

$ od -Ax -x -v twopixel.pcx 

000000 050a 0801 0000 0000 0003 0001 0060 0060 

000010 0000 0000 0000 0000 0000 0000 0000 0000 

000020 0000 0000 0000 0000 0000 0000 0000 0000 

000030 0000 0000 0000 0000 0000 0000 0000 0000 

000040 0300 0004 0001 0000 0000 0000 0000 0000 

000050 0000 0000 0000 0000 0000 0000 0000 0000 

000060 0000 0000 0000 0000 0000 0000 0000 0000 

000070 0000 0000 0000 0000 0000 0000 0000 0000 

000080 ffc1 c200 c1ff 00ff ffc2 ffc1 c200 80ff 

000090 ffc3 c380 40ff ffc3 

The image data section starts at 8016. The byte pairs are inconveniently displayed by od in reverse order, so 

ffc1 is really c1ff in memory. Put another way, c1 is at address 8016 and ff is at address 8116. Here is a list 

of the data in sequence: 

C1 FF 00 C2 FF C1 FF 00 C2 FF C1 FF 00 C2 FF 80 C3 FF 80 C3 FF 40 C3 FF 

Organized into scan lines (rows) and decoded, the data looks like this: 

---------RED-------- --------GREEN------- --------BLUE-------- 

Line 1: C1 FF 00 C2 FF C1 FF 00 C2 FF C1 FF 00 C2 FF 

[ 255 0 255 255] [ 255 0 255 255] [ 255 0 255 255] 

Line 2: 80 C3 FF 80 C3 FF 40 C3 FF 

[ 128 255 255 255 ] [128 255 255 255 ] [ 64 255 255 255 ] 

You can determine the amount of decoded data per color by the length of a line of the image (4 pixels, in this 

example). 

6

Program #8: The Future Pleads, 'Save Your ASCII Art!'

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?