PNGs on the fly
Description: How to use fly.

# fly: Documentation: Using fly |

## Table of Contents

1. Invoking fly.
2. The command file.
3. Directives and explanations.
4. Comments.

### 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.png`
  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.png
name <filename.png>`
  if modifying an existing image, OR
`new
size x,y
name <filename.png>`
  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.

`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.

`ellipse x1,y1,w,h,R,G,B`

  Creates an ellipse of colour R,G,B centered at coordinates x1,y1, of width w and height h.

`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 (5x8), small (6x12), medium (7x13, bold), large (8x16) or giant (9x15, bold).

`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,[source-filename.png|`command`]`

  Copies region x1,y1 - x2,y2 of source-filename.png or the PNG output of command 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,[source-filename.png|`command`]`

  Copies region x1,y1 - x2,y2 of source-filename.png or the PNG output of command 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.

`colourchange R1,G1,B1,R2,G2,B2`

  Changes all pixels of colour R1,G1,B1 to R2,G2,B2.

`setbrush filename.png`

  Sets the current "brush" to filename.png. 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.png`

  Sets the current "tile" to filename.png. Subsequent directives of `fill`, 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.

`rotate deg`

  Rotates the PNG image `deg` degrees clockwise, where `deg` is 90, 180 or 270.

`interlace`

  Makes the image output by fly an interlaced PNG.

#### 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.

    Created:       21 June 1995
    Last modified: 10 June 1999
    Access:        Unrestricted.
    Copyright © 1994-1998 The University of Melbourne.
    <URL:http://www.unimelb.edu.au/fly/>