GIFs on the FLY

# fly: create GIF images on the fly

Author: Martin Gleeson, gleeson@unimelb.edu.au.

fly is a C program that creates GIF images on the fly from CGI and other programs. Using Thomas Boutell's gd graphics library for fast GIF creation, it provides a command-file interface for creating and modifying GIF images.

Current version: 1.4.2, 26th June 1997

Table of Contents

1. Obtaining the source.
2. Installing fly.
3. How to use fly.
4. Feedback.
5. Fly on the Web.
6. Mailing Lists.
7. The Future.
8. Bugs & FAQs.
9. Contributors.
10. Release notes.

## Obtaining fly

### via FTP

fly source code is available in the following formats:

unix tar:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.tar (410k)
unix tar, compressed:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.tar.Z (137k)
unix tar, GNU zipped:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.tar.gz (82k)
pkzip:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.zip (85k)

Source code is available for MMS (Module Management System) on VMS and OpenVMS:

In tar+GNU zipped format:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.vms-src.tar.gz (51k)

Precompiled binaries are available for some operating systems:

Windows NT & Windows 95 (x86):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.WinNT.zip (59k ZIP file)
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.exe (134k executable)
DEC OSF/1 v3 aka Digital UNIX (DEC Alpha):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.OSF1-alpha.tar.gz (40k)
OpenVMS for DEC Alpha:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.OpenVMS-alpha.tar.gz (51k)
IBM AIX 3.2.5 for RS/6000:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.AIX-rs6000.tar.gz (39k)
SGI IRIX 5.2:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.IRIX-5.2-sgi.tar.gz (36k)
SGI IRIX 5.3:
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.IRIX-5.3-sgi.tar.gz (37k)
Linux 1.3.82 (Intel x86):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.Linux-i586.tar.gz (33k)
SunOS 4.1.3 (SPARC):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.SunOS-4.1.3-sun4.tar.gz (38k)
Solaris 2.3 (SPARC):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.SunOS-5.3-sun4.tar.gz (35k)
Solaris 2.5 (SPARC):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.SunOS-5.5-sun4.tar.gz (35k)
FreeBSD 2.0.5 (Intel x86):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.FreeBSD-i486.tar.gz (34k)
Archimedes (RISC-OS):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.archimedes.spark (76k)
Risc PC StrongArm (RISC-OS):
  ftp://www.unimelb.edu.au/pub/www/tools/unix/fly/fly-1.4.2.RPC-SA.tar.gz (56k)

HP/UX binaries are available from the HP/UX Porting and Archive Centre at <URL:http://hpux.csc.liv.ac.uk/>. Search for "fly" and look under the X11/Graphics section.

### via E-Mail

Because some users have reported difficulties in retrieving fly by ftp, due to slow internet links, I have created an autoresponse system where the fly distribution can be mailed to you.

To obtain fly via email, send a message to `fly@www.unimelb.edu.au` with no subject, and the following line in the body of the message:
`send <filename>`
where `<filename>` is one of the filenames above (e.g. `fly.tar.gz`, `fly.exe`, `fly.SunOS-5.5-sun4.tar.gz` etc.)

## Installing fly

If you have obtained fly-n.tar.Z or fly-n.tar.gz, enter the following commands at the unix prompt:

`uncompress fly-n.tar.Z` or `gunzip fly-n.tar.gz`
  This will decompress the compressed archive.
`tar xfv fly-n.tar`
  This will un-tar the archive, placing its contents in a directory called fly
`cd fly-n; make`
  If all goes well, this will compile the program giving you an executable called fly

If you have obtained fly-n.WinNT.zip, enter the following command at the DOS prompt:

`pkunzip -d fly-n.zip`
  This will unzip the archive. Note: it is essential that you use the -d switch to force pkunzip to create the necessary directories.
  You will need a C compiler (and possibly some experience) to compile fly.

Windows users can also use WinZip to extract the files with all the compression formats used on this page including zip, tar, and gz.

If you have obtained the NT/Win95 zip file, fly-win.zip, enter the following command at the DOS prompt:

`pkunzip -d fly-n.zip`

This will unzip the archive.

If you have obtained the NT/Win95 binary, fly-n.exe, no installation is necessary.

If you obtained one of the precompiled binaries, enter the following commands:

  `gunzip fly-n.OS.tar.gz`
  `tar xfv fly-n.OS.tar`

#### Troubleshooting

If you are attempting to compile from source and don't have gcc, you will get an error message along the lines of `'gcc: command not found'` and make will exit. Just change the lines in the Makefile and the Makefile in the gd1.2 directory that read:
`CC = gcc`
to:
`CC = cc`
and it should work. If it still doesn't compile, try one of the pre-compiled binaries, or contact me.

Hans Schrader <hans.schrader@geol.uib.no> has written an excellent Guide to getting fly and Matt Wright's Counter script working on Win95 with Perl32.

## Using fly

### Invoking fly

Note that the command line arguments for v1.1 and later are different from v1.0 and earlier.

The standard manner used to invoke fly is:
`fly -i <input file> -o <output file>`

You can omit the input file, and fly takes its directives from stdin, and if you omit the output file, the output goes to stdout.

- Using the `-q` switch sets fly to quiet mode - no on-screen reporting.
- A quick reference to directives may be seen by using the `-h` switch.

### The command file

The command file uses a number of directives. It must start with one of the following lines:

`existing /path/to/file.gif`
  if modifying an existing image, OR
`new
size x,y`
  for creating a new image of width x pixels, height y pixels.

After the initial command, any of the commands below may be used.

To create more than one image from a command file, use the directive `end`, followed by either

`existing /path/to/file.gif
name <filename.gif>`
  if modifying an existing image, OR
`new
size x,y
name <filename.gif>`
  for creating a new image.

Note:

- All x,y values are in pixels measured from the top left of the image. For a 256x256 image, top left is 0,0 and bottom right is 255,255. All x1,y1,x2,y2 pairs must specify the top left and bottom right of the shape, where appropriate.
- All RGB colour values are in integer format, not hexadecimal.
- Arc sweeps are clockwise.

#### Directives & explanations

`line x1,y1,x2,y2,R,G,B`
  Creates a line from coordinates x1,y1 to coordinates x2,y2 of colour R,G,B.
`dline x1,y1,x2,y2,R,G,B`
  Creates a dashed line from coordinates x1,y1 to coordinates x2,y2 of colour R,G,B.
`rect x1,y1,x2,y2,R,G,B`
  Creates a rectangle from coordinates x1,y1 to coordinates x2,y2 with edging of colour R,G,B.
`frect x1,y1,x2,y2,R,G,B`
  Creates a filled rectangle from coordinates x1,y1 to coordinates x2,y2 filled with colour R,G,B.
`square x1,y1,s,R,G,B`
  Creates a square qith the top left corner at coordinates x1,y1, with side s in length, with edge of colour R,G,B.
`fsquare x1,y1,s,R,G,B`
  Creates a square qith the top left corner at coordinates x1,y1, with side s in length, filled with colour R,G,B.
  Creates a filled rectangle from coordinates x1,y1 to coordinates x2,y2 filled with colour R,G,B.
`poly R,G,B,x1,y1...,xn,yn`
  Creates a polygon (has to be closed) through the points x1,y1 to x2,y2 to ... to xn,yn, of colour R,G,B.
  Note that the colour values appear before the coordinates in this directive.
`fpoly R,G,B,x1,y1...,xn,yn`
  Creates a polygon (has to be closed) through the points x1,y1 to x2,y2 to ... to xn,yn, filled with colour R,G,B.
  Note that the colour values appear before the coordinates in this directive.
`arc x1,y1,w,h,start,finish,R,G,B`
  Creates an arc of colour R,G,B centered at coordinates x1,y1, of width w and height h, starting at start degrees and finishing at finish degrees.
`fcircle x1,y1,d,R,G,B`
  Creates a circle centered at coordinates x1,y1, of diameter d, filled with colour R,G,B.
`circle x1,y1,d,R,G,B`
  Creates a circle of colour R,G,B centered at coordinates x1,y1, of diameter d.
`fill x,y,R,G,B`
  Flood fills with the colour R,G,B from the coordinates x,y to the edge of the area of the original color of x,y.
`filltoborder x,y,R1,G1,B1,R2,B2,G2`
  Flood fills with colour R2,G2,B2 from x,y to the border of colour R1,G1,B1.
`string R,G,B,x,y,<size>,<string>`
  Writes a string starting at x,y (in the colour R,G,B), of font size <size>, where size can be one of tiny, small, medium, large or giant.
`stringup R,G,B,x,y,<size>,<string>`
  Writes a string vertically starting at x,y (in the colour R,G,B), of font size <size>, where size can be one of tiny, small, medium, large or giant. The string will go up from the coordinates supplied.
`copy x,y,x1,y1,x2,y2,filename.gif`
  Copies region x1,y1 - x2,y2 of filename.gif to the coordinates x,y of the image being created/modified.
  If x1,y1,x2,y2 are all -1, copy the entire image.
`copyresized x1,y1,x2,y2,dx1,dy1,dx2,dy2,filename.gif`
  Copies region x1,y1 - x2,y2 of filename.gif to the area dx1,dy1 - dx2,dy2 of the image being created/modified, resizing the image to fit.
  If x1,y1,x2,y2 are all -1, copy the entire image.
`getpixel x,y`
  Gets the colour index of the point at x,y.
`setpixel x,y,R,G,B`
  Sets the point at x,y to the colour R,G,B.
`setbrush filename.gif`
  Sets the current "brush" to filename.gif. Subsequent directives of `line`, `dline`, `rect`, `poly` and `arc` will use the selected "brush" to draw their lines, until a call of `killbrush.`
`killbrush`
  Turns off the brush selection. Calls to `line`, `dline`, `rect`, `poly` and `arc` will then use the standard single-pixel width brush.
`settile filename.gif`
  Sets the current "tile" to filename.gif. Subsequent directives of `fill`, `filltoborder`, and `fpoly` will use the selected "tile" as a fill pattern, until a call of `killtile.`
`killtile`
  Turns off the tile selection. Calls to `fill`, `filltoborder` and `fpoly` will then use the specified colour for fills.
`setstyle R1,G1,B1, R2, G2, B2, ..., Rn,Gn,Bn`
  Various line calls can use a style, specified by one or more colour settings for each pixel, that is repeated for the length of the "line". All subsequent directives of `line`, `dline`, `rect`, `poly` and `arc` will use the selected "style" to draw their lines, until a call of `killstyle.`
`killstyle`
  Turns off the style selection. Calls to `line`, `dline`, `rect`, `poly` and `arc` will then use the standard single-pixel width brush.
`transparent R,G,B`
  Makes the colour R,G,B the transparent colour.
`sizex`
  Returns the width of the image in pixels.
`sizey`
  Returns the height of the image in pixels.
`interlace`
  Makes the image output by fly an interlaced GIF.

#### Comments in the command file

At any point in the command file, you can insert a comment line starting with "#".

Example:

    new
    size 256,256
    #
    # start with a background fill
    fill 1,1,255,255,255
    #
    # then a circle in the middle
    circle 128,128,180,0,0,0
    #
    etc.

#### Examples

If you are using fly from within a CGI program, here are some examples:

Perl

      #!/usr/local/bin/perl

      $flyprog = "/usr/local/bin/fly";
      $outfile = "temp.gif";

      open(FLY,"| $flyprog -o $outfile ");
      print FLY "new\n";
      print FLY "size 256,256\n";
      print FLY "fill 1,1,255,255,255\n";
      print FLY "circle 128,128,180,0,0,0\n";
      print FLY "fill 128,128,255,255,0\n";
      print FLY "arc 128,128,120,120,0,180,0,0,0\n";
      print FLY "circle 96,96,10,0,0,0\n";
      print FLY "circle 160,96,10,0,0,0\n";
      print FLY "fill 96,96,0,0,0\n";
      print FLY "fill 160,96,0,0,0\n";
      close(FLY);

csh

      #!/bin/csh
      # test out fly!

      cat > /tmp/fly.$$ <<EOD
      new
      size 256,256
      fill 1,1,255,255,255
      circle 128,128,180,0,0,0
      fill 128,128,255,255,0
      arc 128,128,120,120,0,180,0,0,0
      circle 96,96,10,0,0,0
      circle 160,96,10,0,0,0
      fill 96,96,0,0,0
      fill 160,96,0,0,0
      EOD

      fly -i /tmp/fly.$$ -o test.gif

C
  If you're using C, then you might as well use gd!!

Can you guess what the above examples produce? Here's the answer!

## Feedback

- Let me know if you're using fly - send email to gleeson@unimelb.edu.au.
- If you experience any problems compiling or using fly, let me know, and please include a copy of the errors that appear on the screen.
- If you'd like to see a particular feature included in fly that's not already there, just drop me a note with the details.

## Fly on the Web

A selection of web sites using fly:

- Web-A-Sketch
- Matt's Counter
- w3perl
- Incident Tracking System
- Syracuse OnLine Weather Station
- NewsReport
- PingToP
- Inner Sphere Cartography Society
- Fairmodel
- Australian Nature Conservation Reserves Place Finder
- COUNTERSTATS.COM
- The Pelecinus Project.
- FramePlot
- DymoJet Strips (look for "DymoJet").
- Modelling Crop Response to Potassium

## Fly Mailing Lists

I've set up two mailing list for users of fly: `fly-users` is a general discussion list for users of fly, and `fly-announce` is for important announcements, including updates and new versions of fly.

To subscribe, send a message to `majordomo@pixel.its.unimelb.edu.au` with no subject, and one (or both) of the following lines in the body of the message:

`subscribe fly-users`
`subscribe fly-announce`

## The Future (otherwise known as a to-do list).

I'm currently porting fly to the Macintosh. It will be an XCMD that can be used from Hypercard, MacPerl, Frontier (I think), and anything else that can use XCMDs or XFCNs.

## Bugs & Frequently Asked Questions

There is a bug in the polygon code in the gd library that causes blank 'streaks' on some occasions when drawing filled polygons. I am currently waiting on a bug fix for this from the author of gd.

If you're using fly with perl on Windows NT or Windows 95, this may be of interest to you: From: http://www.endcontsw.com/people/evangelo/Perl_for_Win32_FAQ.html

    7.3. How do I return a graphics file from a CGI script?

    One of the big differences between UNIX and Win32 platforms is
    that on Win32 there's a difference between text or ASCII files
    and binary file. To return a graphics file, you need to specify
    that the file is a binary file, and that the standard output
    stream should accept binary data. Try something like this:

        $MY_FILE_NAME = 'Penelope.jpg';
        $CHUNK_SIZE = 4096;

        open( MY_FILE, "<$MY_FILE_NAME" )
             or die( "Can't open $MY_FILE_NAME: $!\n" );

        print "Content-type: image/jpeg\r\n";
        print "\r\n";

        binmode( MY_FILE ); # These are crucial!
        binmode( STDOUT );

        while ( $cb = read( MY_FILE, $data, $CHUNK_SIZE ) )
        {
            print $data;
        }

        close( MY_FILE );

## Contributors

Claus Hofmann <claush@ipfr.bau-verm.uni-karlsruhe.de> - see release notes for v0.95b.

John Bowe <bowe@osf.org> - better Makefile, argument parsing, quiet mode, comment lines, and other suggestions.

Jean-Louis Damez <F1NZC@amsat.org> - Compilation of the Windows NT/95 version.

## Release notes

Version: 1.4.2 26th June 1997
  Bug fix: error when using copyresized with -1,-1,-1,-1 coordinates.
Version: 1.4.1 29th January 1997
  Bug fix: fixed fatal error on Solaris when sending output to stdout.
Version: 1.4 23rd January 1997
  - Multiple GIFs from the one command file - use the new end command
  - New commands: getpixel returns the colour index of a pixel; square and fsquare draw a square or filled square; fcircle draws a filled circle;
  - Some extra examples in the file examples/test.fly
Version: 1.3.1 13th February 1996
  - verbose output now goes to stderr rather than stdout only when gif output goes to stdout.
  Bug fix: `fly -h` wouldn't work due to uninitialised filehandle.
Version: 1.3 23rd January 1996
  Addition of comment lines and some bug fixes, both thanks to John Bowe <bowe@osf.org>:
  - verbose output now goes to stderr rather than stdout.
  - bad first line caused core dump.
Version: 1.2 22nd January 1996
  Addition of `circle` directive, and more examples (incl. CGI).
Version: 1.1.3 4th January 1996
  Bug fix: first `string` directive interpreted as `stringup` directive on some platforms.
Version: 1.1.2 2nd January 1996
  Various bug fixes for platform-specific peculiarities (BSDI, SunOS, HP/UX).
Version: 1.1.1 21st December 1995
  Bugfix for quiet mode: `copy` and `copyresized` were talking when they shouldn't.
Version: 1.1 19th December 1995
  - New command line options:
    `fly [-h] [-q] [-i inputfile] [-o outputfile]`
    if inputfile and/or outputfile omitted, directives and output go to stdin and/or stdout.
  - New directives: `stringup`, `setstyle`, `settile`, `fpoly`.
  - Better argument parsing and quiet mode, thanks to John Bowe.
Version: 1.0 24th November 1995
  Release version, including support for 5 font sizes in `string`.
Version: 0.99b 20th November 1995
  Better Makefile (thanks to John Bowe), takes into account if you already have gd installed.
Version: 0.98b 8th November 1995
  Changed a calloc to a malloc due to BSDI problem.
Version: 0.97b 5th November 1995
  Miscellaneous bug fixes.
Version: 0.96b 1st November 1995
  Fixed major bug in polygon code.
Version: 0.95b 18th October 1995
  Additions contributed by Claus Hofmann <claush@ipfr.bau-verm.uni-karlsruhe.de>
  - addition of `transparent` directive.
  - addtion of code to check if colour already allocated before allocating
  - addition of feature to copy whole image if all coords are -1
Version: 0.94b 11th October 1995
  1. Added support for gdImageSX, gdImageSY. 2. Added support for gdSetBrush.
Version: 0.93b 10th October 1995
  Added support for gdCopyResized, for copying and scaling.
Version: 0.92b 6th October 1995
  1. Added support for gdImageString, to enable writing of strings, in small or large fonts, onto GIFs created by fly.
  2. Changed write out command to support OS/2
  Thanks to Andreas Rudolf <rudolf@vnet.ibm.com>
Version: 0.91b 16th August 1995
  Fixed problem reading from stdin (the problem was that it didn't! :-)
  Thanks to Nick Kennedy <nbk@ariel.its.unimelb.edu.au>
Version: 0.9b 12 August 1995
  First Release.

### Credits and license terms

fly 1.4.2 is copyright 1995-1997, The University of Melbourne. Permission is granted to copy and distribute this work provided that this notice remains intact. Credit for using this program must be given to both The University of Melbourne and the Quest Protein Database Center, Cold Spring Harbor Labs, in all derived works. This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for The University of Melbourne and Quest, not to interfere with your use of fly or gd.

("Derived works" includes all programs that utilize fly or the gd library. Credit must be given in user-visible documentation.)

If you want to mirror this page, ask for my permission first.

    Created:       21st June 1995
    Last modified: 24th July 1997
    Access:        Unrestricted.
    Copyright © 1995-1997 The University of Melbourne.
    <URL:http://www.unimelb.edu.au/fly/fly.html>