GIF2WPG V3.6a GIF -to- Word Perfect Graphics File Translator
Copyright 1988-90 by William J. Hinkle CIS [71121,3211]
27 May 1990


GIF and 'Graphics Interchange Format' are trademarks of
CompuServe, Incorporated.
an H&R Block Company

=== User's Guide ===

The GIF2WPG program was created to allow graphics files created as GIF
(Graphics Interchange Format) files to be used in Word Perfect documents. To
do this, the program translates the GIF file into a WPG bit-mapped raster
graphics file. In the process, GIF2WPG converts the GIF image's colors into
shades of gray, which it tries to reproduce in the WPG image.

There are zillions of GIF files available on CompuServe in the QPICS, GALLERY,
COMART, and CORNER forums, as well in other forums, and from other sources.
Generally they are in color, which GIF2WPG changes into grayscale and then
dithers (default) or halftones.

The translator is a single file: GIF2WPG.EXE. A quick and dirty example:

GIF2WPG yergif

will convert YERGIF.GIF to YERGIF.WPG in black and white.

=========
THE CATCH
=========

Note that this program is being released by the author, and is NOT supported
by Word Perfect Corporation, or by CompuServe Inc.

It is NOT public domain!

This utility program GIF2WPG.EXE was written by

William J. Hinkle

who retains the copyright. Copy and use the program freely. Distribute
it to whomever you want. But:

=== Do NOT distribute modified versions.
=== Do NOT remove the copyright notice.
=== ALWAYS distribute with the documentation.

If you feel that this program has been of some utility, please register
by sending $10.00 to:

William J. Hinkle
420 E.Boston Mills Rd.
Hudson, OH 44236-1111



=========
OPERATION
=========

First get a GIF image you want to integrate into your document. These are
usually "paint" or "screen capture" images. GO PICS on CompuServe will lead
you to a forum with all sorts of information on GIF images; GO QPICS,
GO COMART, GO CORNER and GO GALLERY on CompuServe will lead you to collections
of GIF images that you can download. Many on-line BBS's have GIF iamges
available. You must have the GIF image in a file on disk; the file should
have the standard .GIF file extension (i.e., fname.GIF).

To create a .WPG file, type in:

GIF2WPG fname
or
GIF2WPG fname.GIF
or
GIF2WPG fname.GIF fname.WPG

from the DOS command prompt. The .GIF extension is assumed if you do not
specify one. The .WPG extension is assumed whether you specify one or not.
The .WPG file name is made the same as the .GIF if not otherwise specified.
Full DOS pathnames can be specified. You can specify just a directory
(ending in \) or a drive (ending in 🙂 instead of the second filename; the
WPG file will use the name of the GIF file, with a WPG extension, and be
placed on that path.

The .GIF file will be translated to a .WPG file.
The .GIF file will not be erased. You can also specify scaling factors, but
the defaults often work the best (see below).

==================
WILDCARD FILENAMES
==================
GIF2WPG doesn't handle wildcard filenames, like *.GIF. But you can accomplish
the same thing by using the DOS "FOR" command. See your DOS manual's section
on Batch Commands for further info. To convert all of the GIFs in the current
directory to WPG:

FOR %f in (*.GIF) do GIF2WPG %f

===============
INTERLACED GIFS
===============
Some GIF files are "interlaced" -- they are specially constructed for on-line
viewing. GIF2WPG will process this type of GIF file without complaint, but
it has to temporarily create a special file while doing so. If you receive
error messages about interlace processing, check that you have plenty of free
space on your default disk.



==============
COMPLEAT USAGE
==============

If you invoke GIF2WPG from DOS without any other parameters, it will
display the following help message. This illustrates some of the
other options:

-----
GIF-to-WPG Translator: V3.6a ... Copyright 1988-90 by W.J.Hinkle

Usage: GIF2WPG fname1 [fname2] [option] [option] ...
where: fname1.GIF ... GIF format input file
fname2.WPG ... Word Perfect WPG file (default is fname1.WPG)

Command Line Options:
/v ... reverse video
/iN ... select sub-image N (default is 1)

/cN ... change contrast by N%
/bN ... change brightness by +/-N% (BEFORE contrast %)
/wN ... index of color to change into "white"
/p ... print pixel histogram data (colors used)

/g ... equal color weighting for grayscale GIF
/l ... linearize colors (ignore color maps)
/eN ... error diffused dither, expanding xN (default is 2)
/dN ... make dither pattern block NxN
/hN ... make halftone pattern block NxN
/xN ... x density = N pixels-per-inch horizontally
/yN ... y density = N pixels-per-inch vertically

GIF2WPG is a translator from CompuServe GIF files to Word Perfect WPG
graphics files - Black and White only! - for use in printed documents.

The GIF colors are converted to grayscale intensity using the weighting:
Red 30%, Green 59%, Blue 11%. You can specify that the GIF uses only gray
tones with the /g flag; equal color weighting will then be used.

The grayscale is dithered error diffused, by default. A pattern block
size can be used instead: select with /dN, N=1,2,4 or 8 for pattern dither
or with /hN, N=1,2,3 or 4 for pattern halftone.

The X density defaults to 100 pixels-per-inch times the halftone block
size (if any). The Y density is set for 4/3 aspect ratio, unless set by
use of the /xN and /yN options.

The /p option will print on-screen a histogram of the colors used in the GIF,
their RGB color components, and their brightness. You can adjust the overall
brightness with the /bN option (-100 <= N <= +100, in percentage brightness)
and the contrast with the /cN option (N is a percentage multiplier).

Eliminate a pesky background color by specifying /wN, where N is the index
number of that color. All the pixels in that color are turned pure white.

<< trademark info >>
<< followed by my shareware info >>

-----



==========
SUB-IMAGES
==========

If your GIF file contains multiple sub-images, you can specify which one
to extract and translate by specifying the /iN option, where N is the sub-
image number 1,2,3... etc. Normally, you can ignore this option; the 1st
(or only!) image will be translated. If there are additional sub-images
beyond the one selected, a warning is issued and they are ignored.

=============================
ASPECT RATIO AND PICTURE SIZE
=============================

Normally GIF2WPG decides that the image's X density (for width) is
100 pixels (or lines) per inch, times the halftone block size (see below).
The Y density (for height) is set by by computing the density required to
create a 4/3 aspect ratio in order to simulate a CRT screen. This is done
because most GIF images are a single full screen image. This allows
computation of a "natural" size for the graphics image.

You can specify a different density by specifying the /xN option switch (e.g.
/x300 is 300 pixels per inch horizontally). The corresponding Y density is
computed as above. You can also alter the aspect ratio by specifying both
the /x and /y option switches, with different density values. The overrides
are NOT further adjusted for halftoning or error-diffused multiplication!

====================
COLORS AND GRAYSCALE
====================

Most GIF files are in color. GIF2WPG transforms the color mapping into
intensity of grayscale using the above mentioned weights. If you know for
a fact that the GIF uses gray tones only, you can specify the /g option to
use equal color weights.

Once in grayscale, the image can be either dithered (the default) or
halftoned. Normally, you don't have to even think about this, but if you want
to tweak things, and possibly improve your results, read on...

Dithering tries to average the image brightness over a small area of the
image. The default is to use double the size of the image in both axes,
and use error-diffused dithering. You can vary the multiplication factor
by specifying the /eN option with N = 1 or larger than 2 (the default value).
In other words, the default dithering is equivalent to /e2. This type of
dithering tends to ease problems image artifacts (those weird "plaid"
patterns) if you later have to scale the image.

If you specify the /dN option (/d1, /d2, /d4, or /d8), the image size is not
multiplied and a patterned dither is used with an NxN dither block. This can
give smaller WPG files, but not very good visual results.

Better than pattern dither is (simulated) halftoning, which replaces each GIF
pixel with a block of on/off pixels that have a corresponding optical density.
Halftoning will be done instead of dithering if you specify the /hN option
(which will halftone with an NxN block). For example: /h1, /h2, /h3, or /h4.



=============
REVERSE VIDEO
=============

Normally GIF2WPG flips the photometric interpretation of the GIF file colors:
the brightest colors have the fewest pixels in the WPG file. This is because
GIF files are generally optimized for screen viewing, but Word Perfect will
(eventually) put the image on paper. However, if you WANT a reverse video
effect, use the /v option switch.

==========================
KILLING THE COLOR MAPPING
==========================

You can override the GIF file's color map by specifying the /l option (that's
an "el", not a "one"). This "linearizes" the color mapping: color indices
will be transformed directly into grayscale without worrying about how
bright the colors really ought to be. This sometimes gives a more detailed,
though probably less accurate, image. It may be most useful for charts
and such.

=======================
BRIGHTNESS AND CONTRAST
=======================

The /bN option can be specified to adjust the brightness the image. The
effect is to add N percent of maximum brightness to the image. The factor N
can range from -100 to +100 percent. If not specified, no change in the
brightness is made. For example: /b-25 lowers the brightness by 25%.

The /cN option can be specified to adjust the contrast of the image. The
effect is to multiply each grayscale intensity value by N%. The factor N can
be greater or less than 100. If not specified, the contrast is left at 100%.
For example: /c85 give 85% contrast.

The contrast adjustment is applied AFTER the brightness adjustment. The
histogram option can give you an idea of what kind of adjustments to make to
the brightness and contrast; see below.



===================
WHITEOUT BACKGROUND
===================

Simple GIFs (as found in QPICS, for example) often have a solid color
background that will just clutter things up when printed in black-and-white.
You can eliminate that color by specifying its color index as N in the /wN
option. This will yield a nice clear background in the WPG image.

But, how to find out the background color? Print out the histogram (see
below) and look for a color that is used FAR more often than the rest. That
is probably the background color. Or simply experiment.

===============
PRINT HISTOGRAM
===============

The /p option causes a histogram to be kept on the distribution of color
indices in the GIF image. The RGB levels and relative brightness of each
color, as well as the number of occurences of each value, are printed on
the screen when the translation is complete.

Here's a technique that is often helpful in improving the resulting WPG image:

Translate your GIF file, using the /p option to get a histogram. You can
re-direct the histogram printout to a file or the printer with DOS file
redirection, e.g.:

GIF2WPG YERGIF /p >lpt1

If you like the resulting WPG file, you're done! But if not, take a look at
the histogram. See if the lowest brightness actually used in the picture is
well above 0%. If so, you might want to adjust the brightness downward. See
also if the total range of brightness is well under 100%. If so, you might
want to adjust the contrast upward to avoid a washed-out look (especially if
you adjust the brightness downward).



========
EXAMPLES
========

1) Suppose you have a GIF file called "earthm.gif". You want to create a WPG
file version of this image without worrying about the details. You can
translate this to a WPG file by typing (at the DOS prompt):

GIF2WPG earthm

and you will see something like:
-----
GIF-to-WPG Translator: V3.6a ... Copyright 1988-90 by W.J.Hinkle

From GIF 640x350x16 file: earthm.gif
to WPG 1280x700 file: earthm.WPG
dithered error diffused with +0% brightness, 100% contrast.
"Natural" picture size is 6.400W x 4.800H inches.
-----
Note that both the GIF image resolution and color range are shown:
GIF Width x Height x # of Colors

Also shown is the final WPG image resolution:
WPG Width x Height

Also shown are the "natural" size of the final image, and the file names.




2) Suppose you have a GIF file called "yikes.gif". You can translate
this to a WPG file by typing (at the DOS prompt):

GIF2WPG yikes /h4

and you will see something like:
-----
GIF-to-WPG Translator: V3.6a ... Copyright 1988-90 by W.J.Hinkle

From GIF 156x131x16 file: yikes.gif
to WPG 624x524 file: yikes.WPG
halftoned into a 4x4 pixel matrix with +0% brightness, 100% contrast.
"Natural" picture size is 1.560W x 1.170H inches.
-----



======
HELP!?
======

Should you have any difficulties using this program, you can contact me
(Bill Hinkle) through CompuServe EMAIL to [71121,3211], in the PICS forum,
or at the address on the first page of this document. General feedback is
welcome, especially on better methods of color reduction, grayscale halftoning
and dithering, and problem GIF files.

Thanks to Bob Cancilla [76077,354] for his prototype testing & help on
the original GIF2BIT for Lotus Manuscript.
Thanks to Jeff Lewis [72717,1033] for ideas on halftoning and dithering.
Thanks to Kyle Powell [76044,2215] for his public domain LZW decoder 85GIF.
Thanks to Floyd & Steinberg for the error diffused dither algorithm.

Thanks to the many CIS beta testers and folks who reported problems.

=============
REVISION INFO
=============

* Version number Date Explanation *
* -------------- ------ -------------------------- *
* 3.0 14 Oct 88 Original Release, based on GIF2BIT V3.0 *
* 3.1 21 Nov 88 Added color map & output attributes *
* 3.2 13 Dec 88 fixed row decoding problem where there *
* was more rows encoded than the GIF *
* header indicated. *
* Also added /g option (grayscale weight) *
* 3.3 25 Jan 88 (unreleased) *
* Fixed the reverse video problem *
* and added /b brightness switch *
* and fixed density set to use screen *
* dimensions, not image dimensions *
* and added /w color-to-white conversion *
* and the blank box problem *
* 3.4 15 Feb 88 Fixed the brightness overflow problem *
* and forced halftone for interlace GIF *
* and cleaned up the help messages *
* 3.5 ** unreleased ** *
* 3.6 09 May 90 Updated to track other utilities, now *
* allows error diffused dither of *
* interlaced GIFs. Compresses WPGs. *
* 3.6a 27 May 90 Modified to handle large interlaced GIFs*