tgd

A text based tool for creating and manipulating GIF images

Provides shell level access to the gd 1.1.1 graphics library

Preface

tgd reads text files and writes GIF files. It was born out of my desire to learn the gd 1.1.1 graphics library and Perl simultaneously, 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. The latest version of the documentation should be available at http://s27w007.pswfs.gov/tgd/tgd.html .

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.1.1 library at gd.html#notice or in the tgd distribution. Thanks to Sam Cartinhour for additional fonts.

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 drop me a line to let me know you're using it, and send bug reports and comments to bks@s27w007.pswfs.gov .

Preface
Credits
Table of Contents
Where do I get it?
How to I build it?
Basics
Commands
Fonts
Examples

Where do I get tgd

Anonymous ftp to s27w007.pswfs.gov/pub/tgd as tar'ed compress'ed file tgd0.tar.Z (400K) or tar'ed gzip'ed tgd0.tar.gz .

How do I build tgd?

tgd is written in the same crufty C as gd1.1.1. It should be possible under *ix to:

  % uncompress tgd0.tar.Z
  % tar xvf tgd0.tar
  % cd tgd0
  % make

But this is tested only on a Sun. You may need to fiddle with the Makefiles either in tgd0, or in tgd0/gd1.1.1.

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

Characters are ASCII.
Blanklines are ignored.
Lines beginning with '#' are ignored.
Input lines may be no more than 5000 characters.
no more than 64 simultaneous images
image handles no more 100 characters
colornames no more than 100 characters

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

Commands are case-insensitive. With the exceptions of:

checksyntax,
debug,
stringcenter,
stockimage,

the gd 1.1.1 function underlying tgd function foo is named gdImageFoo Thus the documentation for gd 1.1.1 function gdImageFillToBorder applies to tgd command filltoborder .

arc -- arc handle x y width height start_degree end_degree color
```
stockimage im 2
arc im 17 12 20 20 0 270 red
gif im im.gif
```
blue -- blue handle color
Prints blue value of color
boundssafe -- boundssafe handle x y
Print "1" if x,y is within the image, "0" otherwise. or 0

char -- char handle font x y character color


stockimage im 2
char   im gdFontLarge     5 10 E red
charup im gdFont7x13bold 10  5 E blue
gif im char.gif

charup -- char handle font x y character color
checksyntax -- checksyntax
checksyntax stops command processing but continues checking the syntax of the lines in the rest of the file.
colorallocate -- colorallocate handle color red_val green_val blue_val
n.b. the first color allocated is the background color
colorclosest -- colorclosest handle red_val green_val blue_val (ouputs color)
colordeallocate -- colordeallocate handle color
colorexact -- colorexact handle red_val green_val blue_val (ouputs color or string "-1" )
colorstotal -- colorstotal handle
colortransparent -- colortransparent color
copy -- copy handle_to handle_from x_to y_to x_from y_from width height
copyresized -- copyresized handle_to handle_from x_to y_to x_from y_from width_to height_to width_from height_from
create -- create handle width height
createfromgd -- createfromgd handle filename
createfromgif -- createfromgif handle filename
createfromxbm -- createfromxbm handle filename
dashedline -- dashedline handle x1 y1 x2 y2
debug -- debug debug_level
For debugging output try debug 2001.
destroy -- destroy handle

fill -- fill handle x y color

getpixel -- getpixel handle x y

prints color of pixel x,y.
gettransparent -- gettransparent handle

Prints name of transparent color for this image, "-1" if none.
gif -- gif handle filename
green -- green handle color

Prints green value for color.
interlace -- interlace handle N

 if N = 1, interlace the image, if N = 0, do not.
line -- line x1 y1 x2 y2 color
polygon -- polygon x1 y1  x2 y2 ... xN yN N color
rectangle -- rectangle x1 y1 x2 y2 color
red -- red handle color

Prints red value for color.
setbrush -- setbrush handle brush
setpixel -- setpixel handle x y color
setstyle -- setstyle handle XXX
settile -- settile handle tile
stockimage -- stockimage handle N
	
Available stockimages:
	
	stockimage im 0 is equivalent to:
	
	create im 350 250
	
colorallocate im grey    192 192 192
	
colorallocate im white   255 255 255
	
colorallocate im black     0   0   0
	
colortransparent im grey
	
interlace im 1
	
	
stockimage im 1 is equivalent to:
	
	create im 350 250
	
colorallocate im grey    192 192 192
	
colorallocate im white   255 255 255
	
colorallocate im black     0   0   0
	
colorallocate im red     255   0   0
	
colorallocate im orange  255 127   0
	
colorallocate im yellow  255 255   0
	
colorallocate im green     0 255   0
	
colorallocate im blue      0   0 255
	
colorallocate im indigo  127   0 255
	
colorallocate im violet  255   0 255
	
colortransparent im grey
	
interlace im 1
	
	
stockimage im 2 is equivalent to:
	
	create im 35 25
	
colorallocate im grey    192 192 192
	
colorallocate im white   255 255 255
	
colorallocate im black     0   0   0
	
colorallocate im red     255   0   0
	
colorallocate im orange  255 127   0
	
colorallocate im yellow  255 255   0
	
colorallocate im green     0 255   0
	
colorallocate im blue      0   0 255
	
colorallocate im indigo  127   0 255
	
colorallocate im violet  255   0 255
	
colortransparent bar grey
	
interlace bar 1
	

string -- string handle font x y s color
stringup -- stringup handle font x y s color
stringcenter -- stringcenter handle f x y s c

Write string s using font f in color c centered
at the pixel x,y.
sx -- sx handle

Prints width of image in pixels.
sy -- sy handle

Prints height of image in pixels.

Fonts

Font names are case-sensitive.

gdFont5x8
gdFont6x10
gdFont6x12
gdFont6x13
gdFont6x13bold
gdFont6x9
gdFont7x13
gdFont7x13bold
gdFont7x14
gdFont8x13
gdFont8x13bold
gdFont8x16
gdFont9x15
gdFont9x15bold
gdFont10x20
gdFont12x24
gdFontLarge
gdFontSmall

Examples

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 rainbow.pl which when invoked like this

rainbow.pl | tgd

creates:

Here's a Perl script called gifcap.pl And we can add a caption to rainbow.gif using the script in this manner:

gifcap.pl rainbow.gif cap.gif 14 "Rainbow Gif by bks" 255:0:0 0:0:255

which produces:

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

A GIF filethat resembles a key pad
A configuration filethat can be used by imagemap to invoke the URL's when a user clicks on a keypad button.
An html file that includes the gif and the path to the configuration file.

tgd