tgd

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 http://www.ironic.com/tgd/index.html .
RCS:$Id: index.html,v 1.2 2002/06/15 17:08:33 bks Exp $

Preface

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 bks@ironic.com

Preface
Credits
Table of Contents
Changes in version 1.2
Where do I get it?
How to I build it?
Basics
Commands
Fonts
Examples
Bugs

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 (waider@cork.cig.mot.com).

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 http://www.pottsoft.com/home/pds/pds.html

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

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

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.

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


stockimage foo 2
filledrectangle foo 0 0 20 20 yellow
filledrectangle foo 0 0 15 15 green
fill foo 10 10 blue
gif foo fill.gif

filltoborder -- filltoborder handle x y border_color fill_color

filledpolygon -- filledpolygon handle x1 y1 x2 y2 ... xN yN N color


stockimage polygif 2
polygon polygif 0 0 34 0 34 24  0 24 4 black
polygon polygif 1 1 33 1 33 23  1 23 4 red
polygon polygif 2 2 32 2 32 22  2 22 4 black
filledpolygon  polygif 11 4 20 4 30 12 23 20 11 20 4 12 6 green
polygon polygif 17 10 7 15 27 20 3 blue
gif polygif poly.gif

filledrectangle -- filledrectangle handle x1 y1 x2 y2 color
gd -- gd handle filename (if filename is stdout, tgd writes to standard output)
getinterlaced -- getinterlaced handle
Print "1" if interlaced, "0" otherwise.
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 (if filename is stdout, tgd writes to standard output)
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 handle x1 y1 x2 y2 color
polygon -- polygon handle x1 y1 x2 y2 ... xN yN N color
rectangle -- rectangle handle 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 im grey
  - interlace im 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-insensitive in tgd: gdFontTiny, gdFontSmall, gdFontMediumBold, gdFontLarge, gdFontGiant, gdFont5x8, gdFont6x10, gdFont6x12, gdFont6x13, gdFont6x13bold, gdFont6x9, gdFont7x13, gdFont7x13bold, gdFont7x14, gdFont8x13, gdFont8x13bold, gdFont8x16, gdFont9x15, gdFont9x15bold, gdFont10x20, gdFont12x24.

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.

Bugs and Porting

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

tgd