home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / gif / gif2wp32.arc / GIF2WPG.DOC next >
Text File  |  1988-12-13  |  12KB  |  304 lines
  1.  
  2.  
  3.  
  4.  
  5.               GIF2WPG V3.2 GIF -to- Word Perfect Graphics File Translator
  6.               Copyright 1988 by William J. Hinkle [71121,3211]
  7.                                 13 Dec 1988
  8.  
  9.  
  10.            GIF and 'Graphics Interchange Format' are trademarks of
  11.                          CompuServe, Incorporated.
  12.                             an H&R Block Company
  13.  
  14.                             === User's Guide === 
  15.  
  16. The GIF2WPG program  was created to allow graphics files created as GIF
  17. (Graphics Interchange Format) files to be used in Word Perfect documents.
  18. To do this, the program translates the GIF file into a WPG bit-mapped
  19. raster graphics file.  In the process, GIF2WPG converts the GIF image's
  20. colors into shades of gray, which it tries to reproduce in the WPG image.
  21.  
  22. There are zillions of GIF files available on CompuServe in the QPICS
  23. and GALLERY forum, as well in other forums, and from other sources.
  24. Generally they are in color, which GIF2WPG changes into grayscale and then
  25. dithers (default) or halftones.
  26.  
  27. The translator is a single file: GIF2WPG.EXE.
  28.  
  29. THE CATCH
  30. =========
  31. Note that this program is being released by the author, and is NOT supported
  32. by Word Perfect Corporation, or by CompuServe Inc.
  33.  
  34. It is NOT public domain!
  35.  
  36. In fact, if you use this utility extensively, the author will be glad to
  37. accept your contribution of $10.00 to offset costs of developing this program.
  38. If you use GIF2WPG in a commercial or business environment, please consider
  39. this imperative.  Please see the very end of this document for details!
  40.  
  41.  
  42.  
  43.  
  44. OPERATION
  45. =========
  46. First get a GIF file contains the graphics image you want to integrate into
  47. your document.  These are usually "paint" or "screen capture" images.  See
  48. GO PICS on CompuServe.  It should  have the standard .GIF file extension
  49. (i.e., fname.GIF).
  50.  
  51. To create a .WPG file, type in:
  52.  
  53. GIF2WPG fname
  54. or
  55. GIF2WPG fname.GIF
  56. or
  57. GIF2WPG fname.GIF fname.WPG
  58.  
  59. from the DOS command prompt.  The .GIF extension is assumed if you do not
  60. specify one.  The .WPG extension is assumed whether you specify one or not.
  61. The .WPG file name is made the same as the .GIF if not otherwise specified.
  62. Full DOS pathnames can be specified.  You can specify just a directory
  63. (ending in \) or a drive (ending in :) instead of the second filename; the
  64. WPG file will use the name of the GIF file, with a WPG extension, and be
  65. placed on that path.
  66.  
  67. The .GIF file will be translated to a .WPG file.
  68. The .GIF file will not be erased.  You can also specify scaling factors, but
  69. the defaults often work the best (see below).
  70.  
  71. Some GIF files are "interlaced" -- they are specially constructed for on-line
  72. viewing.  GIF2WPG can only process this type of GIF file if you specify the
  73. /hN or /dN options, where N is a decimal number.  See below for details.
  74. You'll get an error message mentioning this fact if you try to translate such
  75. a GIF file with the default settings.
  76.  
  77.  
  78.  
  79.  
  80.  
  81. COMPLEAT USAGE
  82. ==============
  83. If you invoke GIF2WPG from DOS without any other parameters, it will
  84. display the following help message.  This illustrates some of the
  85. other options:
  86.  
  87. -----
  88. GIF-to-WPG Translator: V3.2 ... Copyright 1988 by W.J.Hinkle
  89.  
  90. Press a key to get a little help...
  91.  
  92. (You press a key here!)
  93.  
  94. Usage: GIFWPG fname1 [fname2] [option] [option] ...
  95. where: fname1.GIF ... GIF format input file
  96.        fname2.WPG ... Word Perfect WPG file (default is fname1.WPG)
  97.        /iN        ... option: select sub-image N (default is 1)
  98.        /xN        ... option: x density = N pixels-per-inch
  99.        /yN        ... option: y density = N lines-per-inch
  100.        /v         ... option: reverse video
  101.        /hN        ... option: force halftone block to NxN
  102.        /dN        ... option: force dither block to NxN (<=0 =error diffused)
  103.        /cN        ... option: change contrast by N%
  104.        /l         ... option: linearize colors (ignore color maps)
  105.        /g         ... option: equal color weighting for grayscale GIF
  106.        /p         ... option: print pixel histogram data
  107.  
  108. Press a key to continue...
  109.  
  110. (You press a key here, too...)
  111.  
  112. GIFWPG is a translator from CompuServe GIF files to Word Perfect WPG
  113. graphics files.
  114.  
  115. The GIF colors are converted to grayscale intensity using the weighting:
  116. Red 30%, Green 59%, Blue 11%.  You can specify that the GIF uses only gray
  117. tones with the /g flag; equal color weighting will then be used.
  118.  
  119. The grayscale is dithered error diffused, by default.  A pattern block
  120. size can be used instead: select with /dN, N=1,2,4 or 8 for pattern dither
  121. or with /hN, N=1,2,3 or 4 for pattern halftone.
  122.  
  123. The X density defaults to 100 pixels-per-inch times the halftone block
  124. size (if any).  The Y density is set for 4/3 aspect ratio, unless set by
  125. use of the /xN and /yN options.
  126.  
  127. GIF and 'Graphics Interchange Format' are trademarks of CompuServe Inc.
  128.  
  129. By: William J. Hinkle, CIS [71121,3211]
  130.  
  131. -----
  132. If your GIF file contains multiple sub-images, you can specify which one
  133. to extract and translate by specifying the /iN option, where N is the sub-
  134. image number 1,2,3... etc.  Normally, you can ignore this option; the 1st
  135. (or only!) image will be translated.  If there are additional sub-images
  136. beyond the one selected, a warning is issued and they are ignored.
  137.  
  138. Normally GIF2WPG decides that the image's X density (for width) is
  139. 100 pixels (or lines) per inch, times the halftone block size (see below).
  140. The Y density (for height) is set by by computing the density required to
  141. create a 4/3 aspect ratio in order to simulate a CRT screen.  This is done
  142. because most GIF images are a single full screen image.  This allows
  143. computation of a "natural" size for the graphics image.
  144.  
  145.  
  146.  
  147.  
  148. You can specify a different density by specifying the /xN option switch (e.g.
  149. /x300 is 300 pixels per inch horizontally).  The corresponding Y density is
  150. computed as above.  You can also alter the aspect ratio by specifying both
  151. the /x and /y option switches, with different density values.  The overrides
  152. are NOT further adjusted for halftoning or error-diffused multiplication!
  153.  
  154. Most GIF files are in color.  GIF2WPG transforms the color mapping into
  155. intensity of grayscale using the above mentioned weights.  If you know for
  156. a fact that the GIF uses gray tones only, you can specify the /g option to
  157. use equal color weights.
  158.  
  159. Once in grayscale, the image can be either dithered (the default) or
  160. halftoned.
  161.  
  162. Dithering tries to average the image brightness over a small area of the
  163. image.  The default is to use double the size of the image in both axes,
  164. and use error-diffused dithering.  You can vary the multiplication factor
  165. by specifying the /dN option with a negative N, where N is the size multiplier.
  166. In other words, the default dithering is equivalent to /d-2.  This type of
  167. dithering tends to ease problems image artifacts if you later scale the image.
  168.  
  169. If you specify the /dN option with positive N (/d1, /d2, /d4, or /d8), the
  170. image size is not multiplied and a patterned dither is used with an NxN
  171. dither block.  This can give smaller WPG files, but not very good visual
  172. results.
  173.  
  174. A better option is halftoning, which replaces each GIF pixel with a block of
  175. on/off pixels that have a corresponding optical density.  Halftoning will be
  176. done instead of dithering if you specify the /hN option (which will halftone
  177. with an NxN block).  For example: /h1, /h2, /h3, or /h4.
  178.  
  179. Normally GIF2WPG flips the photometric interpretation of the GIF file colors:
  180. the brightest colors have the fewest pixels in the WPG file.  This is because
  181. GIF files are generally optimized for screen viewing, but Word Perfect will
  182. (eventually) put the image on paper.  However, if you want a reverse video
  183. effect, use the /v option switch.
  184.  
  185.  
  186.  
  187.  
  188. You can override the GIF file's color map by specifying the /l option (that's
  189. an "el", not a "one").  This "linearizes" the color mapping: color indices
  190. will be transformed directly into grayscale without worrying about how
  191. bright the colors really ought to be.  This sometimes gives a more detailed,
  192. though probably less accurate, image.  It may be most useful for charts
  193. and such.
  194.  
  195. The /cN option can be specified to crudely adjust the contrast of the image
  196. before halftoning or dithering.  The effect is to multiply each grayscale
  197. intensity value by N%.  The factor N can be greater or less than 100.  If not
  198. specified, the contrast is left at 100%.  For example: /c85 give 85% contrast.
  199.  
  200. The /p option causes a histogram to be kept on the distribution of color
  201. indices in the GIF image.  The RGB levels and relative brightness of each
  202. color, as well as the number of occurences of each value, are printed on
  203. the screen when the translation is complete.  This can sometimes be helpful
  204. in adjusting the /cN contrast option.
  205.  
  206. EXAMPLES
  207. ========
  208. 1) Suppose you have a GIF file called "earthm.gif".  You want to create a WPG
  209. file version of this image without worrying about the details.  You can
  210. translate this to a WPG file by typing (at the DOS prompt):
  211.  
  212. GIF2WPG earthm
  213.  
  214. and you will see something like:
  215. -----
  216. GIF-to-WPG Translator: V3.2 ... Copyright 1988 by W.J.Hinkle
  217.  
  218. From GIF 640x350x16 file: earthm.gif
  219.   to WPG 1280x700 file: earthm.WPG
  220.   dithered error diffused with 100% contrast.
  221. "Natural" picture size is 6.400W x 4.800H inches.
  222. -----
  223. Note that both the GIF image resolution and color range are shown:
  224. GIF Width x Height x # of Colors
  225.  
  226. Also shown is the final WPG image resolution:
  227. WPG Width x Height
  228.  
  229. Also shown are the "natural" size of the final image, and the file names.
  230.  
  231.  
  232.  
  233.  
  234.  
  235. 2) Suppose you have a GIF file called "yikes.gif".  You can translate
  236. this to a WPG file by typing (at the DOS prompt):
  237.  
  238. GIF2WPG yikes /h4
  239.  
  240. and you will see something like:
  241. -----
  242. GIF-to-WPG Translator: V3.2 ... Copyright 1988 by W.J.Hinkle
  243.  
  244. From GIF 156x131x16 file: yikes.gif
  245.   to WPG 624x524 file: yikes.WPG
  246.   halftoned into a 4x4 pixel matrix with 100% contrast.
  247. "Natural" picture size is 1.560W x 1.170H inches.
  248. -----
  249.  
  250.  
  251. CAVEAT
  252. ======
  253. Should you have any difficulties using this program, you can contact
  254. me through CompuServe EMAIL to [71121,3211], if you like, or at the address
  255. below.  General feedback is welcome, especially on better methods of color
  256. reduction, grayscale halftoning and dithering, and problem GIF files.
  257.  
  258. Thanks to Bob Cancilla [76077,354] for his prototype testing & help on
  259. the original GIF2BIT for Lotus Manuscript.
  260. Thanks to Jeff Lewis [72717,1033] for ideas on halftoning and dithering.
  261. Thanks to Kyle Powell [76044,2215] for his public domain LZW decoder 85GIF.
  262. Thanks to Floyd & Steinberg for the error diffused dither algorithm.
  263.  
  264. Thanks to the many CIS beta testers and folks who reported problems.
  265.  
  266.  
  267.  
  268.  
  269. REVISION INFO
  270. =============
  271. *    Version number    Date        Explanation                                *
  272. *    --------------    ------        --------------------------                *
  273. *        3.0            14 Oct 88    Original Release, based on GIF2BIT V3.0    *
  274. *         3.1            21 Nov 88    Added color map & output attributes     *
  275. *        3.2            13 Dec 88    fixed row decoding problem where there    *
  276. *                                 was more rows encoded than the GIF        *
  277. *                                 header indicated.                        *
  278. *                                Also added /g option (grayscale weight)    *
  279.  
  280. COPYRIGHT INFO
  281. ==============
  282. This program GIF2WPG.EXE was written by
  283.  
  284.     William J. Hinkle
  285.  
  286. who retains the copyright.  All rights are reserved, except as follows.
  287.  
  288. Copy and use GIF2WPG.EXE and GIF2WPG.DOC freely.  Distribute it to whomever
  289. you want.  But:
  290.  
  291. === DO NOT distribute modified versions.
  292. === DO NOT remove the copyright notice.
  293. === ALWAYS distribute with the documentation.
  294.  
  295. If you feel that this program has been of some utility, feel free to send
  296. me a few bucks (say, $10.00) to help defray the CompuServe costs run up
  297. in developing this utility.  If you are using this program in a commercial
  298. environment, please consider this mandatory.
  299.  
  300. William J. Hinkle [71121,3211]
  301.  
  302. 420 E.Boston Mills Rd.
  303. Hudson, OH 44236-1111
  304.