home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Graphics / Graphics.zip / blendgif.zip / blendgif.doc < prev    next >
Text File  |  1999-07-12  |  38KB  |  895 lines
  1. 24 May 1999. Daniel Hellerstein (danielh@econ.ag.gov) 
  2.  
  3.      BlendGif ver 1.15 -- A  WWW-aware utility for building animated GIFS.
  4.  
  5. Abstract:
  6.   BlendGif is a WWW-aware OS/2 utility that will create animated GIFS.  
  7.   At it's simplest, BlendGif will combine several single-frame
  8.   GIF files into a new, animated GIF file.  But this is just the
  9.   beginning -- BlendGif's real strength is it's ability to create
  10.   "intermediate" images to be used as frames in the animated GIF.  
  11.   These intermediate images allow one to easily create fade, pan,
  12.   dissolve, rotation, and other interesting effects.
  13.  
  14.   BlendGIF can be run from an OS/2 command prompt, as a CGI-BIN script,
  15.   or as an addon for the SRE-http web server. 
  16.  
  17.  
  18.                 ------------------------------------------------------------
  19. Contents:
  20.  
  21. I.      Installation and usage
  22. I.a.        Installing BlendGIF
  23. I.b.        Some Installation Reminders and Notes
  24. I.c.        Using BlendGIF
  25. II.     Parameters
  26. II.a.      Global parameters
  27. II.b.      Image-pair "default" parameters
  28. II.c       Image-pair "specific" parameters
  29. II.d       Image-specific transformation parameters
  30. III.    Using BlendGIF input files.
  31. III.a      A list of parameters and their permissible values
  32. IV.     Disclaimer
  33.  
  34.                 ------------------------------------------------------------
  35.  
  36. I. Installation and Usage
  37.  
  38. To use BlendGif, you MUST have several libraries, including:
  39. RXGDUTIL.DLL and REXXLIB.DLL. If you don't have these libraries,
  40. please see  the READ.ME file (that comes with BLENDGIF.ZIP) for
  41. details on how to obtain them for free.
  42.  
  43. Given the above.... installation of BLENDGIF is fairly simple
  44. (simple enough that I didn't bother writing an INSTALL.CMD program).
  45.  
  46. I.a: Installing BlendGIF
  47.  
  48. First, you should  create a directory for BlendGIF, say:
  49.    D:\SERVER\BLENDGIF.
  50. Then, unzip BLENDGIF.ZIP into this directory.
  51.  
  52. The next steps depend on how you intend to use BlendGIF.
  53.  
  54.  A) as a cgi-bin script:
  55.     i.  copy BLENDGIF.CMD to your CGI-BIN directory
  56.    ii.  copy the varions BLEND*.HTM files, and BLNDLOGO.GIF, to a 
  57.         web accessible directory.
  58.         You'll have to edit BLENDGIF.HTM (see the comments in BLENDGIF.HTM)
  59.   iii. Modify parameters set at the top of BLENDGIF.CMD.
  60.        In particular, you MUST set the BLENDGIF_ROOT parameter -- 
  61.           say, set it equal to D:\SERVER\BLENDGIF
  62.  
  63.  B) as an SRE-http addon
  64.     i.  copy BLENDGIF.CMD to your \GOSERVE\ADDON directory
  65.    ii.  copy BLENDGIF.HTM and BLNDLOGO.GIF to your GoServe data directory
  66.         (or to some other web accessible directory)
  67.   iii. Optional: modify parameters set at the top of BLENDGIF.CMD --
  68.        especially the BLENDGIF_ROOT parameter; say, to D:\SERVER\BLENDGIF.
  69.        If you don't set it,  your TEMPFILE_DIR directory (typically, the 
  70.        \TEMP subdirectory of your GoServe data directory) will be used.
  71.    iv. Optional: enable the "Blendgif/ShowDIR" option.
  72.        This requires that you:
  73.          iv.1.  Create an IMGLIB directory under your BLENDGIF_ROOT directory
  74.          iv.2.  Set a "javascript" parameter in  BLENDGIF.HTM (see note below)
  75.  
  76.   C) from the command line
  77.     i. Optional: modify parameters set at the top of BLENDGIF.CMD --
  78.        especially the BLENDGIF_ROOT parameter.
  79.      
  80. You are now ready to use BLENDGIF!
  81.  
  82.  
  83. CAUTION:
  84.     If you run BLENDGIF from the command line and  get an error with a code 
  85.     of "43", you might need to:
  86.       a) make sure you have the latest version of RXGDUTIL.DLL
  87.       b) make sure RXGDUTIL.DLL and REXXLIB.DLL are in your LIBPATH,
  88.          or in the same directory as BLENDGIF
  89.       c) reboot your machine
  90.  
  91.  
  92. I.b. Some Installation Reminders and Notes
  93.  
  94. *  Reminder: 
  95.      Before trying BlendGIF, you should set the BLENDGIF_ROOT parameter
  96.      in BLENDGIF.CMD -- it should point to a directory where BLENDGIF
  97.      can place temporary files.
  98.  
  99. *  A caution on timeouts:
  100.       Since BlendGIF may take a minute or more to generate
  101.       output, there is a chance that your server will "inactive
  102.       timeout" the request (while BlendGIF is still working).
  103.       When run as a an SRE-http addon, SRE-http use "multi-part" sends to
  104.       send intermediate (status) messages, followed by the GIF image.
  105.       Not only does this strategy prevent "inactive timeouts",
  106.       it also assures the client that something is happening.
  107.       Unfortunately, cgi-bin does not support (at least plain vanilla
  108.       CGI-BIN does not support) "multi-part" sends, so this trick can
  109.       not be used.
  110.  
  111. *  Special note for SRE-http users: Enabling Blendgif's ShowDIR option.
  112.       When run as an SRE-http addon, BlendGIF can be told to display
  113.       a set of links to .GIF files in subdirectories of the 
  114.       BLENDGIF_ROOT directory. When clicked, the GIF file will then be
  115.       displayed. Note that this ONLY works with subdirectories of the
  116.       BLENDGIF_ROOT directory -- it does not subvert site security.
  117.  
  118.      BLENDGIF.HTM can provide a front-end to this option (when it open's it's 
  119.      VIEWER window).  To enable this front-end, you should
  120.         a) Make sure you specify the BLENDGIF_ROOT option in BLENDGIF.CMD
  121.         b) Create an IMGLIB/ directory under this BLENDGIF_ROOT directory.
  122.           Thus, if BLENDGIF_ROOT='D:\GOSERVE\BLENDGIF', then
  123.                 you should create D:\GOSERVE\BLENDGIF\IMGLIB
  124.        c) Copy GIF files to this directory. These should be GIF files
  125.           you'd like to make  available as "files on this server".  
  126.        d) Edit BLENDGIF.HTM, and set the do_imglib parameter (the details
  127.           of how to do this are in BLENDGIF.HTM).
  128.  
  129. I.c. Using BlendGIF
  130.  
  131. To actually use BlendGIF, you can:
  132.  
  133.  * run BLENDGIF from a command prompt, just enter 
  134.        BLENDGIF outfile
  135.    where outfile is the name of the output file you want to create
  136.   (if you do not enter outfile, BLENDGIF.GIF will be created).
  137.   You will then be asked the values of several parameters.
  138.  
  139.  * invoke it thorough your browser, by pointing your browser at 
  140.    BLENDGIF.HTM, and filling out the form (it's got lots of options,
  141.    all of which can be ignored by beginners).
  142.  
  143.  * If you are using a browser that supports maintained connections
  144.    (NetScape 2.0 and above), you can "immediately" display
  145.    the animated GIF. If not, or if you want to save the GIF to a 
  146.    file, you should check the "Do NOT immediately upload image?"
  147.    checkbox.
  148.  
  149. If you are ambitious, you can create your own HTML form to use as
  150. a front-end for BlendGIF.  To do that, you'll need to work with the 
  151. parameters. 
  152.  
  153. Perhaps more importantly, BlendGIF can read a special BlendGIF
  154. input file, which will set the values of the various BlendGIF parameters.
  155. This allows the savvy user to readily specify the desired effects (which
  156. may be quite complicated, especially if you are using more then a few
  157. images)
  158.  
  159. So without further adieu, consider the BlendGIF parameters ....
  160.  
  161. Woah, one more thing.  Even if you aren't going to run BlendGIF as a script,
  162. you might want to peruse BLENDGIF.HTM  with your favorite javascript enabled
  163. browser -- it starts where this "technical" manual leaves off, and provides a 
  164. good overview of what BlendGIF is capable of.
  165.  
  166.                 ------------------------------------------------------------
  167.  
  168.  
  169. II. The BlendGIF parameters
  170.  
  171. Before starting, how about a few definitions:
  172.  
  173.   Image-File
  174.      A GIF file used in creating the animated GIF. You can specify
  175.      2 to a zillion image-files.
  176.   Frame:
  177.     In the context of BlendGIF, "frame" refers to one image in a 
  178.     multiple-image animated GIF. This image may be directly from an image-
  179.     file, it might be a transformation of one of these image-file images,
  180.     files, or it might be a "blending" of two image-file images.
  181.   Intermediate Frames: 
  182.      Frames derived by "blending" two image files.
  183.   Image-Pair: 
  184.      A pair of image-files, from which a set of intermediate frames
  185.      will be created. If one specifies N image files, there
  186.      will be N-1 image pairs:  image 1 and image 2,...,Image N-1 and Image N
  187.   Image-specific:
  188.      Parameters that apply just to this image. This is in contrast to "image-pair"
  189.      specific, which refers actions taken on a pair of images.
  190.   Global Image, or the "screen"
  191.      The "global image" refers to the animated GIF you wish.  It will have
  192.      a fixed size (the "screen" size), and will contain the various
  193.      frames of the animated GIF>
  194.   .n
  195.     A "tail" used in "stem" variables. Can refer to the "nth" image,
  196.     or to the "nth" image-pair.
  197.     to create; we can think of it's size as being the "screen size".
  198.     The size of this "global image" is set by the RESIZE_MODE parameter.
  199.     Image "n" refers to the image specified by INFILE.n.
  200.  
  201.  
  202. There are four types of BlendGIF parameters:
  203.  
  204.   a) global parameters -- these apply to all images. 
  205.   b) defaults -- these are used for each image-pair when "image-pair
  206.      specific" parameters aren't defined.
  207.   c) image-pair specific -- these define parameters that are used in 
  208.      blending two images.
  209.   d) image-specific -- these define transformations (scaling, rotating,
  210.      and translation) of images.
  211.  
  212.  To define image-pair specific parameters, you should use the 
  213.  xxx.n notation; where xxx is the parameter name, and n is
  214.  an integer which defines the image pair. Thus, 
  215.     frames.2=5
  216.  sets the "number of frames" for the second image-pair (5 frames
  217.  will be added between the second and third GIF file).
  218.  
  219.  Similarly, the default parameters are specified without a .n;
  220.  for example, frames=4 means "unless a image-pair value for
  221.  frames is specified, use 4 frames between images".
  222.  
  223.  Note that there are a few parameters which have a xxx.m structure --
  224.  for these parameters, image-pair specific parameters are defined
  225.  by specifying xxx.m.n (for example, mask.1.!thresh and
  226.  mask.1.!thresh.2)
  227.  
  228.                                ------------
  229.  
  230. II.a. Global Parameters, in more or less alphabetical order.
  231.  
  232. BLENDGIF_ROOT: default directory for input files
  233.    You can set the default directory for input files by
  234.    setting BLENDGIF_ROOT (when BLENDGIF_ROOT='', then the
  235.    default directory is the "current" directory).
  236.    This is especially useful when running BLENDGIF as a
  237.    web script (since what BLENDGIF sees as the "current"
  238.    directory may be somewhat unpredictable).
  239.  
  240.  
  241. R_BACK          Color values use for the 0 pixel. These are not often,
  242. G_BACK          displayed; their major purpose is for use as a background
  243. B_BACK          color for transformed images.
  244.  
  245. CT_NEWLEN -- length of "global" color table
  246.    This must be a value between 16 and 256 (inclusive).
  247.    BlendGif will create a combined color table using all the
  248.    images you specify. This "global" color table is used
  249.    to display the intermediate images. 
  250.  
  251.        Example: ct_newlen=200  
  252.  
  253.    Note that the original images (defined using the INFILE. parameters)
  254.    will be displayed with their own "local" color table.
  255.  
  256. CT_MAKE_SPEC: how to create the  global color table
  257.   Since it's quite possible that the combined number of colors is 
  258.   greater then 256 (256 is the maximum number of colors a GIF can
  259.   use), BlendGif may need to pick and choose which colors to use.
  260.   CT_MAKE_SPEC is used to select from three different methods:
  261.       0 = use the most frequent colors
  262.       1 = use the most frequent colors, but also use some "average"
  263.           colors (these are chosen to minimize the "distance" of
  264.           all colors in all images to the closest color in the global color
  265.           table.
  266.       2 = similar to 1, but create more of the "average" colors.
  267.  
  268.      Method 0 is fastest, but may do a bad job of displaying infrequently
  269.      used colors.  Methods 1 and 2 provide some insurance against this
  270.      problem, but are slower.
  271.  
  272.    Example: ct_make_spec=0     
  273.  
  274. CYCLE: Cycle images back to first image
  275.     You can create a "cyclical" animated GIF, with the display of
  276.     intermediate images reversed.  This is a nice way of smoothing
  277.     repeated displays, you avoid discontinuous jumps between the last
  278.     and first image.   Alternatively, one could specify a sequence of
  279.     images that start with a first image, have the "last" image in
  280.     the middle, and end with the first image -- but that doubles
  281.     the processing time required.
  282.  
  283.     A value of 1 means "create a cycle of images", 0 means "do not
  284.     create a cycle of images".
  285.  
  286.         Example: CYCLE=1
  287.  
  288.  
  289. DISPOSAL: Image disposal
  290.    How to "dispose" of images.  You can use a number between 0 and 4,
  291.    we recommend 1.
  292.  
  293. FADE_REGIONS: Controls how to process "fades"
  294.    Processing fades requires matching colors determined on the fly to
  295.    a color in the global color table. To expedite this process, a 3
  296.    dimensional index is created.  FADE_REGIONS sets the size of this
  297.    index -- larger values tend to yield smoother fades, but can  greatly
  298.    increase processing time.
  299.  
  300.        Example: FADE_REGIONS=16
  301.  
  302.    This value (16) seems to be a reasonable compromise between speed and
  303.    quality.
  304.  
  305.  
  306. HEIGHT1:  Height of image (in pixels)
  307.         This is only used when RESIZE_MODE=2
  308.  
  309.  
  310. ITERATIONS: Number of times to display the set of images
  311.      Iterations should be an integer greater then 0.
  312.         Example: iterations=4
  313.  
  314. INFILE. : the list of GIF images to "blend"
  315.     You can specify as many images to "blend" as you want by
  316.     creating a sequence of INFILE.j and INFILE.j.!nth parameters, 
  317.     where:
  318.         INFILE.0 - the number of images (must be at least 2)
  319.         INFILE.j - the jth GIF file (n=1...INFILE.0)
  320.         INFILE.j.!nth - the nth frame in the jth GIF file.
  321.                 If you don't specify this, the first "frame"
  322.                 in the file will be used.
  323.                 Note: animated GIFs consist of several "frames",
  324.                       non-animated GIFs contain only 1 "frame".
  325.  
  326.     Examples:
  327.  
  328.       infile.0=2
  329.       infile.1='hello.gif'
  330.       infile.2='goodbye.gif'
  331.  
  332.       infile.0=3
  333.       infile.1='good.gif'
  334.       infile.2='better.gif'
  335.       infile.3='best.gif'
  336.  
  337.       infile.0=2
  338.       infile.1='help.gif'
  339.       infile.2='morehelp.gif'
  340.       infile.2.!Nth=2
  341.  
  342.     Notes:
  343.        *  infile.n can be a relative file name, a fully qualified
  344.           file name, or a fully qualified URL (that starts
  345.           with http://).
  346.        *   BLENDGIF will use socket calls to retrieve URLS.
  347.            The content returned from the server must have a
  348.            content-type response header of image/gif.
  349.        *  in any case, the file must be a GIF file (BMP, JPEG,
  350.           etc. will not be read).
  351.        *  the size of the animated gif will be the size of the 
  352.           first (j=1) image -- if necessary, all other images will be 
  353.           shrunken (or expanded) to be this size.
  354.  
  355. INPUT_FILE_UPLOAD: the contents of BlendGIF input file.
  356.  
  357.     INPUT_FILE_UPLOAD can contain the contents of a BlendGIF input file.
  358.  
  359.      Note that INPUT_FILE_UPLOAD should ONLY be specified in an INPUT 
  360.      element, within a multi-part FORM, that contains a type="file" attribute. 
  361.      See BLENDGIF.HTM for an example of such a FORM.    
  362.      
  363. NO_TRANSPARENT: suppress transparency
  364.    If NO_TRANSPARENT=1, then none of the images in the animated gif
  365.    will be "transparent", otherwise transparency is based on
  366.    whether the specified images were transparent.
  367.  
  368.    Transparency seems to cause odd problems, hence we recommend using
  369.    NO_TRANSPARENT=1
  370.  
  371.  
  372. OUTFILE: The output file
  373.     The output file to be created -- any preexisting file of this name
  374.     will be overwritten.
  375.        Example: outfile='anim.gif'     
  376.  
  377. RESIZE_MODE
  378.     Use this to determine the size of the image.
  379.      0 = Resize everything to the size of the first image
  380.      1 = Resize everything to be max(width) x max(height) (max determined
  381.          over all images)
  382.      2 = Use WIDTH1 and HEIGHT1 parameters.
  383.  
  384. STOP_AFTER: Stop after this many frames
  385.      Instead of creating all the frames, stop after you've drawn
  386.      this many frames. This can create some interesting 
  387.      partial replacements, especially when combined with
  388.      the cycle-back option.
  389.       
  390.      Note: if STOP_AFTER=0, or is greater then the number of images,
  391.            it is ignored.
  392.  
  393.      Examples:
  394.            STOP_AFTER=0
  395.            STOP_AFTER=3
  396.  
  397.  
  398. SAVE_TEMPFILE
  399.     When SAVE_TEMPFILE=1, BlendGIF will save the animated GIF to
  400.     a temporary file (in the BLENDGIF_ROOT directory).  
  401.     Furthermore, BlendGIF will return a link (using the SHOWFILE
  402.     option) to this file. Thus, the client will not immediately
  403.     see his animated GIF -- he has to click on the link to 
  404.     this temporary file.
  405.  
  406.     This option must be used by clients with older browsers that
  407.     do not support "maintained connections".  In addition, clients
  408.     who want to save their animated GIF to a file should also use
  409.     this option.
  410.  
  411.  
  412. SHRINK_IMAGE
  413.     BlendGIF is somewhat inefficient about creating animated gifs --
  414.     it always creates "full sized frames". To save some space, BlendGIF
  415.     can examine a complete GIF file and try to retain only the
  416.     portion of "intermediate" frames that have changed.
  417.          SHRINK_IMAGE = 1 -- try to shrink image
  418.          SHRINK_IMAGE = 0 -- do not try
  419.  
  420.    WARNING: some browsers do not like the "disposal" method used to 
  421.             "shrink" images.
  422.  
  423.  
  424. VERBOSE:   Controls amount of status messages.
  425.    0 means quiet, 1 means verbose.
  426.       Example: verbose=1        
  427.  
  428.  
  429. UPFILE.:  UPFILE.n can contain a GIF image-file uploaded from a client's machine.
  430.           If present, the contents of an UPFILE.n will override the URL 
  431.           (or file name) specified in an INFILE.n
  432.              
  433.           Note that UPFILE. should ONLY be specified in type="file"
  434.           element within a multi-part form.
  435.  
  436.  
  437. WIDTH1:  Width of image (in pixels)
  438.         This is only used when RESIZE_MODE=2
  439.  
  440.                                ------------
  441.  
  442. II.b. Image-pair default parameters.  
  443.    These are used if no "image-pair" specific parameters are specified. 
  444.  
  445. ANIM_TYPE: Type of "blending" effect.      
  446.    The following general types are supported (where first and second
  447.    image refers to images in an image 
  448.         ADD:  Add an image -- this is a replacement. It is optimized
  449.               for use with  "transformed" images; with ADD, you
  450.               can easily create a moving-series of a particular image.
  451.      BALLOON: The first image is replaced by an expanding "balloon"
  452.               of the second image.
  453.      CURTAIN : The second images is a curtain pulled over the first image
  454.      DISSOLVE: The first images dissolves into the second image
  455.      FADE: The first images fades into the second image.
  456.      MASK : "Mask" files are used to overlay portions of the second image
  457.             onto the first image.
  458.  
  459.      Example: anim_type='balloon'
  460.  
  461. FRAMES: Number of frames between each image pair.
  462.    Example: frames=4 
  463.  
  464. FRAME_DELAY:  delay between frames, 1/100th seconds                    
  465.    Example: frame_delay=50       
  466.  
  467. The  following parameters are used to fine tune the ANIM_TYPE.
  468.  
  469. BALLOON_TYPE: Type of "balloon" 
  470.    Four types are recognized:
  471.      1 = SQUARE: A square balloon
  472.      2 = DIAMOND: A diamond balloon
  473.      3 = OCTAGON: An octagon balloon
  474.      4 = CIRCLE: A circular balloon.
  475.  
  476.    Example: balloon_TYPE=4      
  477.  
  478. BALLOON_PUSH: What to do with the first image.
  479.   When using a "circular" (balloon_type=4) "BALLOON" ANIM_TYPE, there 
  480.   are several ways of dealing with the first image:
  481.     0 = Overwrite -- second image overwrites first image
  482.     1 = Push -- second images "pushes" first images sideways and down
  483.     2 = Squoosh -- second images "squooshes" first image sideways and down.
  484.     10 = Push columns -- similar to 1, but don't push down
  485.     20 = Squoosh columns -- similar to 2, but don't squoosh down
  486.  
  487.  
  488. CENTERX and CENTERY: location of the center of the balloon
  489.     Two fractions (between 0 and 1) that locate the center of the
  490.     balloon. CENTERX refers to the center column, CENTERY 
  491.     is the center row.
  492.  
  493.     Example (balloon center will be in the middle column, 
  494.              about 1/4 of the height down from the top):
  495.         centerx=0.50        
  496.         centery=0.25
  497.  
  498. CURTAIN_TYPE: Direction of CURTAIN.
  499.    There are three types:
  500.      T_B : Top to bottom "dropping curtain"
  501.      L_R : Let to write "drawn curtain"
  502.      MIDDLE: Two curtains converging in the middle (from left and right)
  503.      
  504.      Example: CURTAIN_TYPE='T_B' 
  505.  
  506. CURTAIN_OVERWRITE: How to dispose of "first" image
  507.      There are 3 overwrite options for "overwriting" first
  508.      image (of an image pair) pixels
  509.         OVERWRITE -- pixels from the second image overwrite first
  510.                      image pixels
  511.         PUSH     -- the first image is "pushed" away
  512.         SQUOOSH  -- the first image is "squooshed" down
  513.  
  514.  
  515. DISSOLVE_SPEC: Used to control speed of dissolve.
  516.    DISSOLVE works by randomly replacing image1 pixels with image2
  517.    pixels; with latter frames containing a greater proportion of
  518.    image2 pixels.  You can customize this proportion using the
  519.    DISSOLVE_SPEC parameter.
  520.  
  521.    DISSOLVE_SPEC should contain a space delimited list of integers
  522.    between 0 (0 percent-- use image 1 pixels) to 100 (100 percent --
  523.    use image2 pixels).  The values in DISSOLVE_SPEC are used to
  524.    create a graph, with each frames "probability threshold" read
  525.    from the graph.  That is, if you specify 4 values in DISSOLVE_SPEC,
  526.    and an 8 frame image, then the "threshold" for the 4th frame
  527.    will be a linear interpolation of the 2nd 3rd values.     
  528.  
  529.    Examples:
  530.      DISSOLVE_SPEC='1'  -- a linear ramp (starting from 0 to 100)
  531.      DISSOLVE_SPEC=' 1 10 80 90 '   
  532.  
  533.  
  534. FADE_TYPE: How to generate fades
  535.     There are several ways of specifying a fade
  536.    0 - Frequency sorted color table. Fast, but not very pretty
  537.    1 - Brightness sorted color table. Fast, and can be nice for fairly
  538.        similar images.
  539.    2 - Color specific brightness sort. Similar to 1, but several
  540.        different "sets of colors" are sorted, which can improve
  541.        the fade.
  542.    3 - Best match.  Each pixel of each image is assigned a unique
  543.        color, which is then mapped to the closest matching color
  544.        in the global color table. This produces very nice fades,
  545.        but can be very slow to produce (note the use of the FADE_REGIONS
  546.        parameter to control speed & accuracy of this matching).
  547.   string - a string containing a REXX math expression that uses
  548.           the R G and B variables, to specify a  ct sort.
  549.  
  550.   Examples:
  551.      fade_type=3 
  552.      fade_type='2*R + G '
  553.  
  554.  
  555. MASK.: Mask files to use (with ANIM_TYPE='MASK')
  556.   You must specify:
  557.     MASK.0 : the number of mask files
  558.                 Example: mask.0=3              
  559.     MASK.n, n=1,...,MASK.0 : The mask files
  560.         Example:
  561.           mask.1='forever0.GIF'    
  562.           mask.2='forever1.GIF'
  563.           mask.3='forever2.GIF'
  564.     MASK.n.!thresh : The "thresholds" (a pixel value)
  565.         If the jth row and nth column of MASK.n is > MASK.n.!thresh, then 
  566.         replace the jth row and nth column of image1 with the corresponding
  567.         element in image 2.  Note that the mask files are replicated (or 
  568.         clipped)to assure that their size corresponds to the size of the 
  569.         images.
  570.            Example:
  571.              mask.1.!thresh=0      
  572.              mask.2.!thresh=0
  573.              mask.3.!thresh=0
  574.  
  575. MASK_LIST: An alternative to MASK.
  576.     MASK_LIST is an alternative to the use of MASK.n method of specifying
  577.     mask files.  MASK_LIST should contain a spaced delimited list of
  578.     files (relative to the BLENDGIF_ROOT directory), or fully qualified
  579.     URLs.  
  580.        Example: mask_list='mask1.gif  mask23.gif sillyfax.gif '
  581.  
  582.     Notes:
  583.       * A threshold of 1 (pixels greater then or equal to 1) is used
  584.         for all files/urls listed in the mask_list. That is, there is
  585.         no equivalent to the .!thresh modifier.
  586.       * A mask_list overrides mask.n entries -- if you specify a mask_list,
  587.         mask.n and mask.n.!thresh entries are ignored.
  588.  
  589.  
  590.                                ------------
  591.  
  592.  
  593. II.c. Image-pair specific parameters
  594.  
  595.   "Image-pair" specific parameters are optional; if you don't 
  596.   specify a particular parameter for a particular image pair, the 
  597.   image-pair default parameter values (described above) will be used.
  598.  
  599.   To specify a parameter, simply add a ".n" (without the
  600.   quotes) to the end of the parameter name, where "n" is 
  601.   the image pair.  Thus, .2 refers to "the animation frames
  602.   derived from infile.2 and infile.3".
  603.  
  604.   The following parameter can have "image=pair" specific values:
  605.         NFRAMES    ANIM_TYPE       BALLOON_TYPE  BALLOON_PUSH
  606.         MASK.n     MASK.n.!THRESH  MASK_LIST
  607.         CENTERX    CENTERY         FADE_TYPE
  608.         CURTAIN_OVERWRITE CURTAIN_TYPE 
  609.         DISSOLVE_SPEC   DELAY 
  610.  
  611.   Examples:
  612.       NFRAMES.1=10 
  613.       NFRAMES.2=5
  614.       ANIM_TYPE.1='BALLOON'
  615.       BALLOON_TYPE.1=4
  616.       BALLOON_PUS.1=0
  617.       ANIM_TYPE.2="FADE"
  618.       FADE_TYPE.2=1
  619.  
  620.                                ------------
  621.  
  622. II.d. Image-specific transformations
  623.  
  624. Instead of resizing all images to the desired "global image"
  625. size, you can transform each image separately.  There are three 
  626. types of transformations:  scaling, translating (moving), and 
  627. rotation.
  628.  
  629.  
  630. The parameters used to specify image-specific transformations are:
  631.  
  632.    TRANSFORM.n : Enable image-specific transformations for image n
  633.    NUWIDTH.n   : Set the width of image n. 
  634.    NUHEIGHT.n  : Set the height of image n
  635.    XMOVE.n     : Translate the image to the left or right
  636.    YMOVE.n     : Translate the image up or down
  637.    ZROTATE.n    : Rotate image about Z axis (horizontally)
  638.    YROTATE.n    : Rotate image about Y axis (flip along a vertical line)
  639.    XROTATE.n    : Rotate image about X axis (flip along a horizontal line)
  640.    BKG_TRANSPARENT: Control display of background pixels
  641. where n is the image you wish to transform.
  642.  
  643. Note that NUHEIGHT.n, NUWIDTH.n, XMOVE.n, YMOVE.n, ZROTATE.n, YROTATE.n
  644. and XROTATE.n may have:
  645.   a) no parameters (default values will be used)
  646.   b) 1 parameter (the same value will be used for all images in a 
  647.      moving-series of images)
  648.   c) more then 1 parameter. These multiple parameters define a graph
  649.      of values; frame (in an "ADD" animation-type moving-series) will be 
  650.      assigned a value from this graph (as a function of the frame number).
  651.  
  652.  
  653. TRANSFORM.n 
  654.    (when set equal to 1) tells BLENDGIF to use the
  655.    transformation parameters -- if not equal to 1, the other
  656.    transformation parameters (such as NUHEIGHT.n) are ignored.
  657.  
  658. NUWIDTH.n and NUHEIGHT.n 
  659.     can be specified in absolute pixels, or as a fraction of the 
  660.     image's current size.  To specify absolute pixels, enter an integer.
  661.     To specify a fraction (of the image's current size), enter a real
  662.     number (that is, a number with a decimal point).
  663.   In other words:
  664.       NUWIDTH.n=4  means "4 pixels wide" (this is NOT a recommended value!)
  665.       NUWIDTH.n=4.0 means "4 times the current width of the image"
  666.  
  667. XMOVE.n and YMOVE.n
  668.      can also be specified as an absolute move
  669.     (in columns or rows, respectively), or as a fraction of the global
  670.     image's width and height. Please note that this is the "global image's"
  671.     width and height, and NOT the width and height of the current image!
  672.         Examples:
  673.              YMOVE.2=30
  674.              XMOVE.3='10 30 70 150'  (accelerating move of image across screen)
  675.  
  676. ZROTATE., YROTATE.n, XROTATE.n
  677.      should be in degrees (between -180 and +180).  
  678.       * The Z-axis "sticks out of the screen" -- rotation about the z-axis is
  679.          just rotation of a flat image in the usual way.
  680.        * The Y-axis is the vertical axis
  681.        * The X-axis is the horizontal axis
  682.        * Some examples:  XROTATE.1=30
  683.                         ZROTATE.2=10 40 60 80 90 100 (decelerating spin)
  684.  
  685. BKG_TRANSPARENT 
  686.      controls how "background" pixels are displayed. Background
  687.      pixels are pixels that are not covered by the transformed image.
  688.  
  689.      BKG_TRANSPARENT values can be 0, 1, or 2:
  690.        bkg_transparent = 0  
  691.             Use the R_BACK, G_BACK, and B_BACK colors
  692.        bkg_transparent =1
  693.           "background pixels" are never used --  the "first image's" pixels
  694.           are used instead (that is, background pixels are "transparent"
  695.        bkg_transparent =2 
  696.            similar to 1, but also converts "transparent pixels" (specified 
  697.            in the original image") into "background" pixels.
  698.                    
  699.     Note that setting bkg_transparent=0, the "do NOT suppress transparency"
  700.     option, and "background disposal" can be used as an alternative to
  701.     bkg_transparent=1
  702.  
  703.  
  704. The algorithm used for transformation is :
  705.  
  706. 1) A buffer, with the same size as the "global image" is initialized 
  707.    with the background pixel (with a value of 0), whose color is set using 
  708.    R_BACK, G_BACK, and B_BACK.
  709. 1) The center of the image is placed at the center of the "buffer"
  710. 2) The image is scaled (about this center)
  711. 3) The image is rotated (in 3 space).
  712. 4) The image is translated (moved)
  713. 5) The "3rd dimension" is removed (it's projected back into 2 space)
  714. 5) Portions of the transformed image that lie outside of the buffer
  715.    (say, that are less then 0 in row space, or greater then WIDTH1 in
  716.    column space) are clipped
  717. 6) Note that pixels in the buffer that are not "overwritten" by a pixel
  718.    from the transformed image will retain the background value
  719. 7) This buffer is then used by BlendGif in the usual fashion --
  720.    with the exception that (given that bkg_transparent=1),
  721.    "background" pixels do NOT overwrite pixels from a prior image.
  722. 8) If multiple parameters were specified for any of these (NUHEIGHT.
  723.    to XROTATE) parameters, and if the # of frames is greater then 0, then 
  724.    a "moving-series" of images will be created by consecutively
  725.    repeating steps 1 through 7 with different parameters; and with
  726.    the transformed image being added to the "original image" (of
  727.    the image pair) in NON-cumulative fashion.
  728.  
  729.  
  730.                 ------------------------------------------------------------
  731.  
  732. III. Using BLENDGIF input files
  733.  
  734. BLENDGIF input files are simple text files that are used to set the various
  735. BlendGIF parameters.
  736. The principal advantage of BLENDGIF input files is the ability to specify lots of 
  737. parameters in an easy to edit fashion.  The disadvantage is the sequential process,
  738. you have to create the file, run BlendGIF (or hit BLENDGIF.HTM with your browser),
  739. feed in the input file, and wait for results. However, for complicated images (say,
  740. images with 10 or so GIFS, each one transformed differently, use of BlendGIF input
  741. files is almost unavoidable.
  742.  
  743. Each line of a BLENDGIF input file should have the structure:
  744.   Parameter_Name =  Parameter_Value
  745. In addition, lines that begin with a ; are comments.
  746.  
  747. The following is a simple example of a BlendGIF input file
  748.       ; sample input file for BlendGIF -- use the hello and goodbye gif files
  749.       ; that come packaged with BLENDGIF.ZIP
  750.       infile.0=2
  751.       infile.1=hello.gif
  752.       infile.2=goodbye.gif
  753.       anim_type=balloon
  754.      balloon_push=squoosh
  755.      balloon_type=circle
  756.                                ------------
  757.  
  758. III.a. A list of parameters and their permissible values
  759.  
  760. Basically, any parameter discussed above can be used in a BlendGIF input file.
  761. To make like a bit easier, the following lists these parameters, and lists the
  762. allowable values.  
  763.  
  764. Note that:
  765.   .nrefers to "image n" (the image selected by the INFILE.n parameter).
  766.   For descriptions of these options, see section II.
  767.   Unless otherwise noted, the default values are set in BLENDGIF.CMD
  768.  
  769. Parameter name        Permissible Values
  770. --------------        ----------------------------------------
  771. INFILE.0              An integer > 0
  772. INFILE.n              a filename (relative to the BLENDGIF_ROOT directory)
  773.                       or fully qualified URL
  774. R_BACK, G_BACK,       An integer between 0 and 255 (inclusive). These are color 
  775. B_BACK                   intensities.
  776.      
  777. CT_NEWLEN             An integer between 16 and 255 (length of color table)
  778. CT_MAKE_SPEC          0 (frequency), 1 (some averaging), or 2 (more averaging)   
  779. CYCLE                 0 or 1 (1 = yes)
  780. DISPOSAL              0,1,2, or 3
  781. FADE_REGIONS          An integer (16 is the recommended value)
  782. HEIGHT1               An integer >0 
  783. WIDTH1                An integer > 0
  784. ITERATIONS            An integer > 0
  785. NO_TRANSPARENT        0 (no suppression), 1 (suppression), 2 (suppression for
  786.                       intermediate frames)
  787. RESIZE_MODE           0 (first image), 1 (max width & height), 
  788.                       2 (use HEIGHT1 and WIDTH1)
  789. SHRINK_IMAGE          0 (do not shrink), 1 (do shrink)
  790.  
  791. ANIM_TYPE and         ADD, BALLOON, CURTAIN, DISSOLVE, FADE or MASK
  792. ANIM_TYPE.n
  793. FRAMES and FRAMES.n   An integer > 0
  794. STOP_AFTER and        An integer > 0
  795. STOP_AFTER.n
  796. FRAME_DELAY and       An integer >0 (in 100/th seconds)
  797. FRAME_DELAY.n
  798. BALLOON_TYPE and      SQUARE, DIAMOND, OCTAGON, or CIRCLE
  799. BALLOON_TYPE.n
  800. BALLOON_PUSH and      OVERWRITE, PUSH, SQUOOSH, 10, or 20
  801. BALLOON_PUSH.n         10 is "push columns only", 20 is "squoosh columns only"
  802. CENTERX& CENTERX.n    A fraction between 0.0 and 1.0
  803. CENTERY& CENTERY.n    A fraction between 0.0 and 1.0
  804. CURTAIN_TYPE          T_B, L_R, and MIDDLE
  805. CURTAIN_OVERWRITE and OVERWRITE, PUSH, or SQUOOSH
  806. CURTAIN_OVERWRITE.n
  807. DISSOLVE_SPEC and     A space delimited list of numbers between 0 and 100
  808. DISSOLVE_SPEC.n
  809. FADE_TYPE and         FREQUENCY, BRIGHTNESS, COLOR_BRIGHTNESS, BEST_MATCH, or
  810. FADE_TYPE.n           an equation in R, G, and B.
  811. MASK.0 and           Number of mask files to use
  812. MASK.0.n
  813.  
  814. MASK.m and          A filename (relative to BLENDGIF_ROOT), or a fully 
  815. MASK.m.n            qualified URL
  816. MASK.m.!thresh and  Integer value between 0 and 255 (threshold value)
  817. MASK.m.!thresh.n
  818. MASK_LIST and       Space delimited list of mask files (or urls)
  819. MASK_LIST.n
  820. TRANSFORM.n         0 or 1 (1=enable transformation)
  821. NUWIDTH.n           An integer >2, or a fraction > 0.0
  822. NUHEIGHT.n              Default=1.0
  823. XMOVE.n             An integer > or equal to 0, 
  824. YMOVE.n                  or a fraction or equal to > 0.0. 
  825. ZROTATE.n            An angle (in degrees).  O
  826. YROTATE.n
  827. XROTATE.n
  828. BKG_TRANSPARENT.n   0, 1, or 2.
  829. UPFILE.n            A file name (used for status messages), followed by a base64
  830.                     encoded GIF file (see the following Notes for details)
  831. Notes:
  832.  
  833.   * UPFILE.n has a special syntax. Instead of a   varname = value
  834.     structure, UPFILE.n entries should have the following structure:
  835.         A_VARIABLE = my_value
  836.         UPFILE.n = a file name, or other info, used for status messages
  837.         lines of base64 encoded stuff
  838.         ....
  839.         lines of base64 encoded stuff
  840.  
  841.         SOME_OTHER_VAR = a_value
  842.     Where the end of the base64 encoding is signaled by an empty line (or by
  843.     the end of the file).
  844.  
  845.     See BLENDGIF.IN for an example of how UPFILE.n is used.
  846.  
  847.   * To specify a "moving-series" of images (for use with the ADD
  848.     animation type), enter space delimited list of values in any of 
  849.     NUHEIGHT., NUWIDTH., XMOVE., YMOVE., ZROTATE., YROTATE. or XROTATE.
  850.  
  851.   * You can NOT specify INPUT_FILE_UPLOAD, in a BlendGIF  input file.
  852.   * When uploaded (from a web browser using INPUT_FILE_UPLOAD), the input
  853.     file parameters are read last -- hence, they override any other parameter
  854.     setting.
  855.   * Similarly, when selected from BlendGIF's command line mode, input 
  856.     parameters in a BLENDGIF input file override any other parameter setting.
  857.  
  858.     
  859.                 -------------------------------------------------
  860.  
  861. IV. Disclaimer 
  862.  
  863.   Copyright 1999 by Daniel Hellerstein. Permission to use this program
  864.   for any purpose is hereby granted without fee, provided that
  865.   the author's name not be used in advertising or publicity
  866.   pertaining to distribution of the software without specific written
  867.   prior permission.
  868.  
  869.  
  870.     THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS
  871.     OR IMPLIED WARRANTY.
  872.     THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE,
  873.     INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
  874.     IN NO  EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR
  875.     INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY
  876.     SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  877.     RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  878.     OF CONTRACT,NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  879.     IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE.
  880.  
  881.  
  882.    BlendGIF and associated files were developed on the personal time of 
  883.    Daniel Hellerstein, and are not supported, approved, or in any way an 
  884.    official product of my employer (USDA/ERS).
  885.  
  886.  
  887.    BlendGIF uses the RXGDUTIL library, and REXXLIB, libraries.  RXGDUTIL
  888.    is freeware, while REXXLIB is a commercial produce for which the authors own
  889.    an unlimited distribution license.  If you need these libraries, please  
  890.    read BlendGIF's READ.ME for details on how to get them.
  891.  
  892.  
  893.  
  894.  
  895.