Nsgd-a module for interfacing AOLserver with gd

The Big Picture

Nsgd is a module for AOLserver that allows a programmer access to Thomas Boutell's gd package for programmatically creating images. This module was derived from Spencer Thomas's Gdtclft. Gdtclft was modified by John Ellson before I got my hands on it. Possible uses of nsgd include plotting data, fancy page counters, drawing game boards, or any other application where there is a need for dynamically creating images.

Using nsgd

The module adds a single command, gd, to those you have available when writing Tcl files for AOLserver. The general steps for creating an image are as follows:
  1. Create the image using create or one of the createFromXXX commands.
  2. Set up your colors using color.
  3. Manipulate the image using the various drawing commands.
  4. Save your image using writeXXX or send it out to an HTTP connection using returnXXX.
  5. Get rid of the image data structure using destroy.

Following is an example Tcl script that makes use of the gd command. You can see the script in action. Mini-logo is another example using nsgd. 

    # /www/trial.tcl
    #
    # Build an image based upon whether user is logged in.
    #
    # mburke@arsdigita.com, Wed Sep 13 20:38:19 2000
    #
    # $Id: nsgd.html,v 1.1.1.1 2000/10/27 14:05:57 matthewburke Exp $



    # Create a 400x120 pixel image.
    set im [gd create 400 120]


    # Define the palette.
    set black [gd color new $im 0 0 0]
    set white [gd color new $im 255 255 255]
    set red   [gd color new $im 255 0 0]
    set green [gd color new $im 0 255 0]
    set blue  [gd color new $im 0 0 255]


    set user_id [ad_verify_and_get_user_id]

    set user_name [db_string dbs1 \
	"select first_names || ' ' || last_name 
         from users where user_id = :user_id" -default "Stranger" ]


    if { $user_id != 0 } {
        set first_color $red
	set second_color $green
    } else {
        set first_color $green
	set second_color $blue
    }


    # Draw some shapes.
    gd fillpolygon $im $blue 360 20 380 20 380 40 370 50 360 40
    gd arc $im $red 240 80 100 100 0 360


    # Draw some text using a TrueType font.
    gd textTT $im $first_color [ns_info pageroot]/fonts/arialn.ttf 14 0 10 20 \
	"Hello $user_name!"

    if {$user_id != 0} {
       gd textTT $im $second_color [ns_info pageroot]/fonts/arialn.ttf 24 3.14 380 80 \
	    "Welcome to BlueDino Net"
    } else {
       gd textTT $im $second_color [ns_info pageroot]/fonts/arialn.ttf 24 3.14 380 80 \
	    "Why don't you register?"
    }


    # Send the image out to the HTTP connection.
    # Add a HTTP header to insure image is reloaded properly on page reload.
    ns_set put [ns_conn outputheaders] Expires [ns_httptime [ns_time]]
    gd returnPNG $im


    # Get rid of data structure.
    gd destroy $im

gd Commands

Installing nsgd

If you have a binary release, installing is simple. First, copy nsgd.so into AOLserver's /bin directory. Then modify your server's .ini file to load the module by including the line: 
    nsgd=nsgd.so
in the modules section. Modify these directions as appropriate if you are using a .tcl startup file rather than an .ini file. Finally, restart your server and you are ready to go. Of course you must have all the appropriate libraries such as gd, libpng, zlib, etc.

Building nsgd

 I'm not a real hacker, merely an academic who has sold out, so my understanding of linking is at the armchair level. What I describe below may not work for you or may not be the best way to do things. If you have any tips/suggestions, let me know.

There are several support libraries you need to build nsgd including gd, libpng and zlib. If you want to use .ttf fonts, you will need the FreeType library. gd supports reading and writing JPEG files if you have libjpeg (although I could not get it to work). Similarly, XBMs are supported, but I haven't tried using them.

Here's what I did to get this to build:

  1. Get, build and install zlib (http://www.freesoftware.com/pub/infozip/zlib/zlib.html).
  2. Get, build and install libpng (http://www.freesoftware.com/pub/png).
  3. Get, build and install gd. I used a distribution (http:///www.graphviz.org/pub/gd-1.8.3p1.tar.gz) by John Ellson which builds gd as a shared library,
    rather than as a static library.
  4. Optional: Get, build and install FreeType (http://www.freetype.org). Acquire some .ttf fonts.
  5. Get the source distribution of AOLserver (http://aolserver.com). Move the nsgd distribution into the aolserver directory. Change to the nsgd directory and run make.

Future Work

mburke@arsdigita.com