OVERVIEW

GIFSAMPL is a handy utility to produce sample collections of GIF files.  It
may be used to produce preview images for downloading, or just to showcase
a large collection.

Sample collections are GIF files that contain a number of other images on a
single screen.  Each sampled image is shrunk to a consistent size,
converted to a common color format, labeled, and stored with the others.

GIF is a graphics format created by CompuServe for storing bitmapped
images, but you probably already knew that.  GIF and "Graphics Interchange
Format" are trademarks (TM) of CompuServe Incorporated, an H&R Block
Company.

GIFSAMPL was created in August 1991 by Mark S. Ransom.  Version 2.3 was
created on February 23, 1994.


ACKNOWLEDGMENTS

No achievement stands alone;  it rests on the achievements of others.  In
this case, the relationship is a bit more direct.  This program was made
possible by the direct incorporation of code and algorithms by other
people.  I would like to acknowledge the following contributions, and thank
the authors:

CLIPGIF by Steve Becquer.  GIFSAMPL actually started as modifications made
to CLIPGIF.  Very little of the original remains;  however, I would have
had no idea how to deal with a GIF file without it.

DECODER.C by Steven A. Bennett, based on work by Steve Wilhite.  This
provides the GIF decompression function.

PICLAB by Lee Daniel Crocker and the Stone Soup Group.  The GIF compression
function from this package was used.

"Digital Halftoning" by Robert Ulichney.  This book contains a description
of the Floyd-Steinberg dithering algorithm, used in producing the color
images.


COMMAND LINE

The GIFSAMPL command line takes the following form:

     GIFSAMPL [drive:][path]outfile[.ext][ /option=value]

The first item is simply the name of the output file to create.  If the
drive and path are not included, the current directory is used.  If an
extension is not provided, .GIF will be used.

If the output file name ends with a number, GIFSAMPL can make more than one
output file.  The number at the end of the filename will get incremented
each time the old file fills up.  For example, if the filename is



SAMPLE01.GIF, the next file would be SAMPLE02.GIF, and so on up to
SAMPLE99.GIF.

Options:  (default values are in parenthesis)

     /WIDTH=screen width  (640)

Sets the width of the output file.

     /HEIGHT=screen height  (480)

Sets the height of the output file.

     /ROWS=rows of samples per screen  (3)

Selects the number of samples to be included in each output file.  The
screen will be divided into this many sections in both directions;  for the
default value of 3, there will be 9 images in a single screen.

     /GREY=bits per pixel  (0)

This option selects grey-scale output, instead of color.  The number of
bits per pixel determine how many shades of grey are created:  4 bits=16
shades, 5 bits=32 shades, 6 bits=64 shades.  A value of 4 produces samples
which can be viewed on all VGA displays;  6 is the maximum that can be
displayed on most super-VGAs.  The value may be between 1 and 8.

     /SHARPEN

This option turns on a standard edge enhancement algorithm.  As an image is
shrunk, much of the detail is lost.  The edge enhancement produces a
sharper looking image, counteracting some of the loss.  The main drawback
is a slight increase in processing time.

     /LUT=lut file name  (gifsampl.lut)

Specifies a Look-Up-Table (LUT) file for color conversion.  Two files are
included in the distribution kit.  The default, gifsampl.lut, tries to
treat all colors equally.  The second, skins.lut, is optimized for skin
tones at the expense of the other colors.  The selection of a LUT will
determine how grainy the samples look.  GIFSAMPL tries to look for this
file in the current directory first, and then in the directory that
GIFSAMPL was loaded from.


INPUT FILES

GIFSAMPL reads a list of file names to get the files to sample.  The file
names must be typed in, one at a time.  This can obviously be very time-
consuming.

The input redirection features of DOS can be used to feed the filenames to
GIFSAMPL.  If you have a list of files in a file called GIFLIST.TXT, for
example, you would use the following command:

     gifsampl sample01.gif <giflist.txt




If you want to sample all the files in the C:\GIFS directory, sorted by
name, you could use:

     dir /w /on /b c:\gifs\*.gif | gifsampl sample01.gif

The options on the preceding DIR command only work under DOS 5.0 or better.


GREY-SCALE

Why would anyone want to use grey scale?  Good question.

4-bit grey-scale images can be displayed on ANY VGA adapter at 640x480
resolution, even the original IBM and the cheapies.

Grey-scale files are smaller.  A 4-bit grey-scale file is about half the
size of a color file.

The images can be sharper and free from dithering artifacts.  A 6-bit grey-
scale image has a smoothness that enhances its realism.

GIFSAMPL needs less memory to produce grey-scale images.


TEMP FILES

Normally, GIFSAMPL does not need to use any temporary files.  If you try to
make sample images that are too large to fit in memory, GIFSAMPL will open
a temporary file to store the excess.  If you have an environment variable
called TEMP (most people do), the file will be opened there.  If not, it
will be opened in the current directory.  The file will be deleted when
GIFSAMPL is done.


ASPECT RATIOS

This section is included for those not using Windows file viewers.  If you
use Windows, your screen resolution and aspect ratio are fixed by your
video drivers, and changing the file sizes created by GIFSAMPL won't
matter.  All that will change is whether the result will fit on the screen
or not.

What is an aspect ratio?  Technically speaking, the aspect ratio is the
ratio of the picture width to the picture height.

An aspect ratio is a tricky thing.  If it is wrong, an image will look too
squashed or too thin.  Why bring it up here?  Because GIFSAMPL may make
files that are a different size than the ones you started with.  Some
viewers will change your screen resolution to match the file you are
viewing, and that could cause trouble.

The 640x480, 800x600, and 1024x768 resolutions produce nice square pixels
on a properly adjusted standard monitor.  That's because the monitor screen
is 4" wide for every 3" of height.  Some other resolutions are not so
lucky.  The 640x350 EGA standard will look very squished if you don't use a
proper video mode when displaying it.  If you use GIFSAMPL's default screen



size of 640x480, you won't get the proper mode.  Since these images are
rare and/or ugly, my advice is to ignore them altogether.  If you must, use
a screen size of 640x350.

A bigger problem is the 320x200 resolution.  These files are a little more
common.  Luckily, they only look slightly squished.  You can ignore the
problem, or try a 640x400 screen.  It probably won't work, because your
viewer won't adjust to it, your VGA board won't support it, or your monitor
will squish itself to compensate.  If you're really lucky, the 320x200
files were created with the wrong aspect ratio in the first place, and will
be restored to their proper form when sampled.  Sometimes two wrongs DO
make a right!


PROBLEM SOLVING

  My GIF viewer only displays one image per screen.

The GIF standard allows multiple separate images per file.  However, it
never clearly states what you should do if you find more than one.  Since
GIFSAMPL turns each sample into a separate image, it is dependent on the
good nature of whoever created your viewer to create the proper effect.  I
only have experience with two viewers;  one works fine, and the other one
doesn't.  The one that works is VPIC by Bob Montgomery.

  I keep running out of memory.

GIFSAMPL stores the sample image in memory as it reads the input GIF file.
If the image won't fit, it will try to store some of it in a temporary
file.  Some memory is always needed, though.  There are three things you
can do to use less memory:

     Make the screen size smaller.  (Change the /WIDTH and /HEIGHT
     options).

     Put more samples on a screen.  (Change the /ROWS option).

     Use grey-scale instead of color.  (Use the /GREY option).


KNOWN BUGS

Only the GIF87a format is understood.  I have not checked any newer formats
to see if there are any incompatibilities.


FUTURE ENHANCEMENTS

The following enhancements are planned for future versions:

A user interface.  The current means of selecting files and options is from
the Dark Ages.  If you grew up in the Dark Ages like I did, don't worry;
the command line will be retained.

15-bit and 24-bit output options, for better color output.




Output files that are a single combined image, instead of a lot of little
images on a single screen.  This should make them compatible with all GIF
viewers.

Options for sorting the file list, and disabling portions of the image
label.

A background image option to fill out any unused space on the screen.  This
may be used as advertising space.