home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / graphics / utilities / gifmachine_405 / gifmachine.docs < prev    next >
Text File  |  1990-11-17  |  9KB  |  173 lines
  1.  
  2.                                 GIFMachine
  3.  
  4.                  Copyright 1990 by Christopher A. Wichura
  5.                            (caw@miroc.chi.il.us)
  6.  
  7.  
  8. Legal mumbo jumbo:
  9.  
  10. GIFMachine is not in the public domain.  All source files, along with the
  11. resulting executable, are copyright by C. Wichura.  You may not sell
  12. GIFMachine.  The only allowed charge that may be placed on GIFMachine is
  13. for media and/or mailing costs.
  14.  
  15. GIFMachine may be freely redistributed via BBSs, InterNet/Usenet, and disk
  16. libraries such as Fred Fish's, as long as the archive is not modified.
  17. Disk magazines and services that charge extra for file transfers may not
  18. distribute GIFMachine.
  19.  
  20. In using GIFMachine, you accept the responsibility for any damage or loss of
  21. productivity/money that may occur through or during its use.  C. Wichura is
  22. not and can not be held accountable.
  23.  
  24.                             What is GIFMachine?
  25.                             ~~~~~~~~~~~~~~~~~~~
  26. GIFMachine is a program that converts pictures stored in the CompuServe GIF
  27. (Graphics Interchange Format) format into IFF SHAM format.  There are very
  28. few programs that do this, and most have many problems (not that GIFMachine
  29. doesn't either -- see below).
  30.  
  31. For a long time, I used a program called ShamSharp to convert GIFs to IFF
  32. format.  ShamSharp was the only thing I would even consider using (execpt
  33. for ASDG's The Art Department, a very fine commercial product!).  However,
  34. there were a number of things about it that irked me.
  35.  
  36.    1)  If a picture had >16 colours and a width >320, ShamSharp would
  37.        __ALWAYS__ halve the width of the image.  Not only that, but it
  38.        did so by simply skipping every other pixel of the original GIF.
  39.        This resulted in a tremendous loss in resolution.
  40.  
  41.        I, myself, would rather have the entire picture converted and be
  42.        able to use my favorite viewer (Mostra, by S. Vigna) to scroll
  43.        around the image.  Thus, by default, GIFMachine will not halve
  44.        the picture's width.  There is a command line switch to make it
  45.        do so, however, in which case it actually thinks about it a bit
  46.        rather than just dropping the odd pixels.
  47.  
  48.    2)  If an image had more than 400 lines in it, ShamSharp would
  49.        GURU the system if the SHAM mode flag was used.  GIFMachine handles
  50.        large pictures well (that was one of the primary concerns I had
  51.        while writing it) and has been tested with images as large as
  52.        1152x890!
  53.  
  54.    3)  ShamSharp would write bad IFF files for me on a regular basis.  I
  55.        suspect this is because of some subtle bug in the cmpByteRun1
  56.        compression routine ShamSharp uses.  Anyway, GIFMachine has yet to
  57.        write a bad IFF on me.  (Cross Fingers, Cross Fingers :-)
  58.  
  59. GIFMachine also offers the user the ability to automatically remove a
  60. border area in a picture, among its other toys.  (I just hate it when you
  61. have an image floating in the middle of the screen with inches of nothing
  62. around it.)
  63.  
  64.                           Drawbacks of GIFMachine
  65.                           ~~~~~~~~~~~~~~~~~~~~~~~
  66. If you are looking for speed, go someplace else.  GIFMachine was written
  67. with the idea of getting the best possible image from a GIF file, not as
  68. something to view GIFs in a quick and dirty manner.  Usually what I do is
  69. use something like HAMGIF to see if the GIF is actually worth the effort
  70. and then convert a series of GIFs in one shot by specifying multiple
  71. filepspecs.  On a stock 500, the average picture takes around 25 minutes to
  72. convert (half that if the image is interlaced, which is often the case when
  73. the width is halved).
  74.  
  75. GIFMachine knows how to write only one thing: SHAMs.  If a picture only
  76. uses <= 16 colours, SHAM is not needed.  It would be much faster to write a
  77. normal IFF and skip the SHAM conversion calculations.  In such a case, it
  78. would be better to go back and use something like ShamSharp.  (Note that
  79. this has changed with GIFMachine v2:  You can now write 24bit deep ILBMs as
  80. well.)
  81.  
  82. The only viewer I know of that properly handles SHAMs with >400 lines is
  83. Mostra.  SuperSham 3.2 (?) will display the image, but does not allow
  84. scrolling around.  The latest version of Christian Weber's ShowIFF
  85. (included in the v18.? distribution of his iff.library) will also display
  86. SHAMs and let one scroll around.  However, he does not rebuild the copper
  87. list during vertical scrolling and thus the image turns to muck if one
  88. scrolls down.
  89.  
  90.                              Using GIFMachine
  91.                              ~~~~~~~~~~~~~~~~
  92. GIFMachine requires that you have KickStart 2.0 or greater (hey, I have a
  93. 3000 and SAS C with 2.0 includes so I dumped ARP in favor of 2.0).  It also
  94. requires a fair amount of RAM (though it does not have to be CHIP RAM or
  95. contiguous).  Alas, memory requirements have gone up with v2; the primary
  96. image now requires three bytes to store a pixel instead of two.   A 640x480
  97. GIF now requires about a meg of free memory to convert.
  98.  
  99. GIFMachine uses the 2.0 ReadArgs() argument parser.  Thus, one can always
  100. enter `GIFMachine ?' on the command line for help.  GIFMachine can not be
  101. run from the WorkBench.
  102.  
  103. GIFMachine accepts the following arguments:
  104.  
  105. <filespec1> ... <filespecN> [TO <directory or filespec>] [ALL]
  106.                             [NOBORDER <line thresh>] [XCOMP] [DITHER]
  107.                             [XFLIP] [YFLIP] [DEEP] [BUFSIZE <Size in KBytes>]
  108.  
  109. Each filespec may contain any valid 2.0 wildcards (really regular
  110. expressions).
  111.  
  112. The TO option allows one to specify where to put the IFFs.  If not given,
  113. they will be placed in the current directory.  It is generally advised that
  114. TO point at a directory.  However, if you are converting only a single GIF
  115. file then there is no reason one can not specify a full filespec.
  116.  
  117. The ALL option will cause GIFMachine to recursively descend into any
  118. directories while matching filespecs.
  119.  
  120. The NOBORDER option instructs GIFMachine to remove the border area from an
  121. image.  It takes, as its <line thresh> parameter, an integer between 0 and
  122. 100 that indicates what percentage of a line can differ from the border
  123. colour and still have the line removed.  This option has been slightly
  124. modified in the v2 release:  Before, GIFMachine assumed that the value at
  125. coordinate 0,0 was the colour of the entire border area.  This is not
  126. always the case, however.  Take, for example, a GIF with the image right up
  127. in the upper left corner with a large empty region to the right and below
  128. of it.  Such an image would have almost none of the offending border
  129. removed.  GIFMachine will now attempt to run the stripper four times, using
  130. each of the four corners' colour for the border check.  For the most part,
  131. this does not slow this function down because a border check is aborted as
  132. soon as the <line thresh> is exceeded and GIFMachine moves to the next
  133. corner.
  134.  
  135. The next option, XCOMP, tells GIFMachine to halve the width of images.
  136.  
  137. When the DITHER option is specified, a boustrophedonic Floyd-Steinberg
  138. error diffusion algorythm will be used when reducing the colour palette to
  139. 12 bits.  This can help eliminate colour banding that occurs in places
  140. where subtle shadows occur.
  141.  
  142. The XFLIP and YFLIP options will flip the image horizontally and
  143. vertically, respectively.
  144.  
  145. The DEEP option will cause GIFMachine to write a 24bit deep ILBM instead of
  146. a SHAM file.  The DITHER option will be ignored in this mode, however.
  147. Writing deep ILBMs if much faster than writing SHAMs because no
  148. computations need to be made.  Please note that files written with this
  149. option in effect can be quite large.  Expect a 640x480 XCOMPed image to be
  150. over 400k in length, for example.
  151.  
  152. The final option, BUFSIZE, allows one to change the read buffer size used
  153. when decompressing GIFs.  It defaults to two Kbytes.  The argument is
  154. specified in number of Kbytes, not bytes.  Thus, if you have memory to burn
  155. and want a large buffer you could specify a BUFSIZE 100 and you would get a
  156. buffer 100k in size.  This command does not effect the writing of the IFF
  157. file, however.
  158.  
  159. Note that if GIFMachine determines that the image can be written interlaced
  160. (depends on aspect ratios) then it will work on two lines at a time instead
  161. of one.  This is because the SHAM format only changes the base colours
  162. every other line when displaying interlaced images.
  163.  
  164. GIFMachine and GIF89a compatibility:  GIFMachine should be able to read any
  165. GIF file written under the GIF89a specs.  GIFMachine does not, however,
  166. perform aspect corrections or process Plain Text Extensions (for obvious
  167. reasons), Graphic Control Extensions, or Application Extensions.
  168. GIFMachine will, however, detect the new Comment Extension blocks.  The
  169. messages contained in such blocks will be stored and output as ANNO chunks
  170. when the IFF file is being written.
  171.  
  172. -=> CAW
  173.