NAME
     GIF320 - GIF image viewer, manipulator and output  optimiser  for
     VT-320 terminals

SYNOPSIS
     gif320 giffile ...

     gif320 -p < giffile

DESCRIPTION
     GIF320 is a GIF file viewer for use on DEC VT-320 terminals.   It
     has  three  degrees of shading for each point: black, white and a
     false "gray" formed by dithering  black  and  white  pixels.  The
     threshold  values  control  how  bright  a  point  must  be to be
     displayed in grey or white, for half and full value respectively.
     A simple colour balance mechanism is also included (although out-
     put is monochrome).  However, GIFView's best feature is its image
     packer/optimiser,  which  cuts  the  number  of cells used to its
     minimum without losing picture quality. This allows images to  be
     larger  than  the  usual 16*6 96-cell display, depending on their
     complexity.

     It has two modes: interactive and reading from a pipe. Pipe  mode
     (when  GIF320  is  invoked  with a -p on the command line) simply
     reads the GIF file from stdin and prints the optimised  image  on
     stdout,  whereas  interactive mode requires the input GIF file to
     be specified on the command line. Most of the following  will  be
     only occur in interactive mode.

     When GIF320 warms up, you will see a box  with  diamonds  in  it,
     with  headers  containing useful information on either side and a
     quick summary of the commands beneath it; A progress meter marked
     "Reading"  will fill up as GIF320 resolves the GIF into a bitmap,
     then the image will be  developed  (see  "DEVELOPMENT"  for  more
     information)  and  displayed  in  the diamond-filled box. Next, a
     prompt will appear at the bottom of the screen, waiting  for  you
     to enter commands. Firstly, here's what the headers mean:

THE HEADERS
     Filename: filename
          The name of the input file.

     Image: x-dim x y-dim x colors
          The area of the overall image and the number of colors used.

     Zoom: ( left, top ) / ( right, bottom )
          The area of the overall image displayed.

     Balance (R/G/B): red / green / blue
          The percentages of each RGB input used to compose the  mono-
          chrome  displayed  image,  eg.  a  reading of "40 / 50 / 10"
          means that 40% of the red input, 50% of the green and 10% of
          the blue is used to determine the intensity of each pixel.

     Thresholds (F/H): full / half
          The threshold points at which a pixel is to  be  plotted  at
          full  (ie. on) or half (ie. dithering) intensity. The values
          vary from 0 to 100, and the lower they are, the brighter the
          image is likely to be.

     Output X:Y ratio: ratio
          A real number representing the X:Y ratio of the sides of the
          optimised  image;  a  ratio  of 2.0 means that the optimised
          image will be twice as wide as it is high.


     Approx optimise: x-cells x y-cells
          The estimated size to which  the  image  will  optimise,  in
          cells, based on the number of cells used and the ratio.

     Cells used: number / 96 ( pc %)
          The cells used by the display; the lower this is, the larger
          the  image  will  optimise  to.  There are only 96 definable
          cells (on a VT-320, at least).

COMMANDS
     Commands are represented here as full words, but  are  identified
     by the case-insensitive first character on the command line only,
     and parsed word-by-word.

     Thresholds full half
          Set the threshold values. The two  integer  values  must  be
          between 0 and 100, with 0 being bright and 100 being dark.

     Balance red green blue
          These range from 0 to 100, must total 100, and  control  how
          much  of  each  colour  is  used  to  determine the output's
          brightness. A value of 0 means that the  colour  is  ignored
          for the purposes of determining the output's brightness, and
          100 means that  the  colour  is  the  only  one  taken  into
          account.

     Ratio ratio
          A real number representing the X:Y ratio of the sides of the
          optimised  image;  a  ratio  of 2.0 means that the optimised
          image will be approximately twice as wide as it is high.

     Zoom-in / Xoom-out [ precision ]
          "Zoom in" on, or "Xoom  out"  from,  the  image.   precision
          defaults   to  10,  and  is  the  percentage  of  the  image
          width/height by which you zoom.

     Full-unzoom
          Unzoom fully from the image.

     H / J / K / L [ precision ]
          Pan left, down, up, or right on  the  image.   precision  is
          measured as when zooming.

     Optimise [ cells-x cells-y ]
          Applies the optimiser to the image at the current  settings.
          The  optimiser will try to make the displayed image as large
          as possible without losing any image quality, and  will  try
          to  make the image's sides conform to approximately the out-
          put X:Y ratio set  by  the  user.   If  the  two  arguments,
          cells-x  and  cells-y  are  provided,  GIF320 will try these
          values as the maximum possible size for the image and optim-
          ise  from there; otherwise, GIF320 will use the maximum size
          of image that will fit on-screen and conforms to the  output
          X:Y  ratio.  See  "OPTIMISATION" for more information on how
          GIF320 optimises.

     Save filename
          Output the last developed image (including optimised output)
          to  filename cat or type or whatever the appropriate display
          utility is, and will display the  image  shown.   This  will
          accept  tilde-globbing  if  you're on a UNIX system (ie. the
          use of '~' to represent your home  directory).   Note  that,
          since  SIXEL  uses  only 7 bits to carry its image data, the
          pictures can be transferred as 7-bit data,  FTP'd  as  text,
          etc.

     Double filename
          The same as Save, except the output will be twice the  size,
          using double-width and double-height escape sequences.  This
          looks quite impressive.

     ?
          Some program information - just the version, the patchlevel,
          the author and a "bugs-to" address.

     (return)
          Redevelop the sketch. If nothing has been  changed,  nothing
          will happen.

     Quit
          Exits GIF320 without any further ado.

DEVELOPMENT
     As the image is developed, two progress  meters,  "Progress"  and
     "Cells",  will race.  If the top one wins, so do you. If the bot-
     tom one wins, you've lost.  On a more technical level, "Progress"
     represents  the amount of image developed, and "Cells" represents
     the amount of character cells defined so far.  If  "Cells"  fills
     up,  all  of the cells have been defined, and if "Progress" fills
     up, the image is fully developed.  You want "Progress" to fill up
     before "Cells" does; it's as simple as that. ;-)

OPTIMISATION
     The optimiser applies a binary search to find the  optimum  value
     for  image  size,  where  the image is at its largest while still
     fitting its cell definitions into the  96-cell  limit.   It  does
     this  by repeatedly developing the image at different sizes, from
     the 96-cell size which, by definition, works, to as large as pos-
     sible, which is almost completely unlikely to work.  Every itera-
     tion, it tries halfway between the smallest and the largest.   If
     this works, halfway becomes the new smallest, as the optimum must
     be larger or equal to this. If it doesn't,  halfway  becomes  the
     new  largest, as the optimum must be smaller than this. This goes
     on until the difference between smallest and largest is impercep-
     tible.

BUGS
     This is a beta test edition. Send  any  bug  reports,  fixes,  or
     suggestions to me (doctorgonzo <sboyle@maths.tcd.ie>).

AVAILABILITY
     GIFView is free; anyone may redistribute copies of it  to  anyone
     under the terms stated in the Copyright notice.

AUTHORS
     The original GIFtoPS Converter was written in  May  16,  1988  by
     Scott  Hemphill.   GIFView  1.0  (6 December 1989) was written by
     Gregory Reid <gar@catt.ncsu.edu>, and was a modified  version  of
     the  above which used the VT-320 SIXEL graphics to display rather
     than PostScript.  GIFView 2.0 (23 January 1991)  was  written  by
     doctorgonzo  <sboyle@maths.tcd.ie>, and was basically GIFView 1.0
     with the optimiser, RGB & threshold setting, and a basic interac-
     tive interface. Then came 2.1 (5 December 1991), from doctorgonzo
     as well, which was the same but nicer and with less  bugs  and  a
     pipe  ability.  GIF320 3.0 (23 June 1992) is the latest revision;
     it's got progress meters, is more screen-oriented,  and  features
     zoom and pan capability.  Oh yeah, and it has a new name, to make
     life easier for anon-ftp and archie users.

     Thanks to  Marc-Michael  Brandis  <brandis@inf.ethz.ch>  for  the
     msqrt()  routine. It's compact and I don't need it to be particu-
     larly fast, so it fits my criteria perfectly.
