A text based tool for creating and manipulating GIF images

Provides shell level access to the gd 1.2 graphics library

Author: Bradley K. Sherman

The latest release of tgd is version 1.2c (7 Oct 1996). The latest version of the documentation should be available at .
RCS:$Id: index.html,v 1.2 2002/06/15 17:08:33 bks Exp $


tgd reads text files and writes GIF files. Typically, in a Unix environment, it would be at the end of a pipe: my_program | tgd. It can also be invoked on a file: tgd my_text_file. By using the special file handle stdout, it can be used in WWW applications to push images to a browser. It was born out of a desire to learn the gd graphics library and Perl simultaneously (but it can be used with any scripting language). I hope that it will allow me to make new tools available on the World-Wide Web to help molecular biologists cope with ever increasing quantities of data. .

Credits & Rights

This program would not exist if Doug Bigwood had not shown Thomas Boutell's gd 1.1.1 graphics library to me. To appreciate tgd you must read Boutell's documentation . You can find the Credits and License terms of the gd 1.2 library at gd.html#notice or in the tgd distribution.

We place no further restrictions on distribution of the source code other than those attached to the software from which it is derived except to request that novel software derived from tgd include credit to the Dendrome project, Institute of Forest Genetics, USDA Forest Service.

The Dendrome project is funded by the USDA ARS Plant Genome Research Program and by the USDA Forest Service .

tgd was written by Bradley K. Sherman . Please send bug reports and comments to

Table of Contents

Change in version 1.2

Font names are now case insensitive. There are three new fonts: gdFontTiny, gdFontMediumBold and gdFontGiant. There is a complete list of fonts below.

Changes in version1.2b

Font source files are broken up into separate file to allow compilation on machine where object modules must be kept smaller. Commands gif and gd will now accept special filename stdout to mean write the image files to the standard output rather than to a disk file.

Changes in version1.2c

Fixed polygon and filledpolygon bugs reported and diagnosed by Ronan Waide (

Where do I get tgd

Compressed with compress (tgd1.2c.tar.Z)
Gzipped with gzip (tgd1.2c.tar.gz)

For VMS users try Phil Ottewell's port at

How do I build tgd?

tgd is written in K&R style C. But it builds with gcc. It should be possible under *ix to:
  % uncompress tgd1.2c.tar.Z
  % tar xvf tgd1.2c.tar
  % cd tgd1.2c
  % make
But this is tested only on a Sun running SunOS 4.1.x. You may need to fiddle with the Makefiles either in tgd1.2c, or in tgd1.2c/gd1.2

tgd basics

The general idea is that tgd consumes files consisting of lines. Each non-blank non-comment line begins with a tgd command. tgd can be invoked with a list of files as argumemts
 % tgd file_a file_b file_c ...
or it can be used as the tail end of a pipe
 % perl -e myPerlscript | tgd
Limits on the tgd input file
Color Note:
When an image file is read from disk colornames are assigned to each color in the file. The names are are made from a template "#XXXXXX", so tgd assigns #000000 to a color with r,g,b values 0,0,0 and #FF00FF to a color with r,g,b values 255,0,255.

tgd Commands

The comands: checksyntax, debug, stringcenter, and stockimage are unique to tgd . All other commands are analogues of similar functions in the gd 1.2 library. The arguments to a tgd command are in the same order and of the same number as the arguments to the underlying gd 1.2 function . Thus, for example, the documentation for gd 1.2 function gdImageFillToBorder applies to tgd command filltoborder .
Commands are case-insensitive.


Font names are case-insensitive in tgd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant, gdFont5x8, gdFont6x10, gdFont6x12, gdFont6x13, gdFont6x13bold, gdFont6x9, gdFont7x13, gdFont7x13bold, gdFont7x14, gdFont8x13, gdFont8x13bold, gdFont8x16, gdFont9x15, gdFont9x15bold, gdFont10x20, gdFont12x24.


Here's a simple text file called helloworld.txt:
    create myimage 200 100
    colorallocate myimage white 255 255 255
    colorallocate myimage black 0 0 0
    string myimage gdFontLarge 40 40 "hello, world!" black
    gif myimage helloworld.gif
tgd can be used to turn this into a gif. E.g. using a Unix shell:
% tgd helloworld.txt
creates this image:

Here's the output of a short Perl script called which when invoked like this | tgd

Here's a Perl script called And we can add a caption to rainbow.gif using the script in this manner: rainbow.gif cap.gif 14 "Rainbow Gif by bks" 255:0:0 0:0:255

which produces:

Here's a simple demonstration script called which reads a set of 12 labels and corresponding URL's from an input file and creates:

Bugs and Porting

MSDOS ports may have problems
For VMS see port by Phil Ottewell.