home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Graphics / Graphics.zip / gif_info.zip / gif_info.doc < prev   
Text File  |  1998-02-03  |  12KB  |  311 lines
  1. 3 Feb 1998:
  2. Author: Daniel Hellerstein danielh@econ.ag.gov
  3.  
  4.          GIF_INFO: A REXX procedure for extracting information from GIF files.
  5.  
  6.  
  7. GIF_INFO is an OS/2 REXX procedure that will extract information from a GIF file.
  8. This information includes the height, width and color table information for
  9. the "global" image as well as for each (of possibly several) images in 
  10. an animated GIF file. GIF_INFO can also be used to extract comments, "application
  11. blocks", and "plain text" blocks from GIF files.
  12.  
  13. GIF_INFO is freeware; with the usual "use at your own risk" disclaimer (see
  14. below for the details).
  15.  
  16.                         ---------------------------
  17.  
  18. Usage:
  19.  
  20.      stuff=GIF_INFO(gif_file,infotype,imgnum,idmess)
  21.  
  22. Parameters:
  23.  
  24.   gif_file: A fully qualified file name. 
  25.                  OR
  26.             A string containing the contents of a gif_file
  27.  
  28.  infotype: Type of information to extract
  29.  
  30.    imgnum:  Selects nth image
  31.  
  32.    idmess: If specified, then GIF_FILE contains the contents of a gif_File
  33.            with a name of idmess. If not specified, GIF_FILE is a file name.
  34.            In the former case, idmess should have no embedded spaces.
  35.  
  36. Returns:
  37.  
  38.   Depends on the value of infotype.
  39.  
  40.  
  41.                         ---------------------------
  42.  
  43. Description of INFOTYPE:
  44.  
  45.  INFOTYPE='' or INFOTYPE='S',  IMGNUM is ignored
  46.      Write a report to stdout. Returns a value of 1.
  47.  
  48.  INFOTYPE='BASIC', IMGNUM=0 or IMGNUM=''
  49.      Return basic image info in a space delimited list.
  50.          i)If no such file, return ''
  51.         ii)If not a GIF file, return: fully_qualified_filename  -1
  52.        iii) Otherwise,return:
  53.                fqn #_imgs #_cmts #_apps #_ptext img_wd img_ht img_ct 
  54.             where;
  55.                 fqn : the fully qualified name of the gif file
  56.              #_imgs : the number of images
  57.               #cmts : the number of comment blocks
  58.              #_apps : the number of application control blocks
  59.             #_ptext : the number of plain text blocks
  60.   img_wd and img_ht : "global" width and height 
  61.              img_ct : # of colors in the global color table;
  62.                       or 0, if (rarely)no global color table specified
  63.  
  64.  INFOTYPE='BASIC', IMGNUM=nn (nn>0) 
  65.      Return basic info on image # nn
  66.         i) If no such file, return ''
  67.        ii) If not a GIF file, return: fqn  -1
  68.       iii) If fewer then nn images, return: fqn -2
  69.        iv) Otherwise, return:
  70.               fqn wd ht tc_index delay int_flag ct 
  71.            where;
  72.               fqn : same as above
  73.          tc_index : transparent color index (-1 if not specified)
  74.            wd, ht : width and height of this image
  75.                ct : # of colors for this image's own color table.
  76.                     This is typically equal to 0; which means "use
  77.                     global color table"
  78.              delay: Delay in 1/100ths seconds (-1 means not specified)
  79.          int_flag : 1 if interlaced image
  80.                      
  81.  INFOTYPE='IMAGE', IMGNUM=nn
  82.  
  83.       Return the nn'th image.
  84.  
  85.         i) If no such file, return: ''
  86.        ii) If not a GIF file, return: fully_qualified_filename  -1
  87.       iii) If no such image (i.e.; nn># of images), return:
  88.               fully_qualified_filename -2
  89.        iv) Otherwise, return: 
  90.                  fqn  wd ht tc_index delay int_flag ct jbytes,image_data
  91.            where the values are as specified above, with;
  92.                jbytes:   byte size of compressed data
  93.            image_data:  "jbytes" of image data; compressed. 
  94.  
  95.        Note the use of a comma after the jbyte value.
  96.        Immediately following this comma will be the jbytes of the image data. 
  97.        This is not the raw image, you'll have to lzw decompress it.
  98.  
  99.  INFOTYPE='TABLE', IMGNUM=0 or IMGNUM=''
  100.       Return the 3 * img_ct elements of the global color table.
  101.         i) If no such file, return: ''
  102.        ii) If not a GIF file, return: fully_qualified_filename  -1
  103.       iii) Otherwise, return:
  104.               fqn img_ct,color_table_data
  105.         where;
  106.             fqn and img_ct: defined above
  107.             ct_data: The color table data; arranged Red0,Green0,Blue0,Red1,
  108.                      ...,Blue255 (1 byte per value). Note that it immediately
  109.                      follows a comma.
  110.  
  111.  INFOTYPE='TABLE', IMGNUM=nn; nn>0
  112.       Return the 3 * img_ct elements of the local color table for image nn
  113.         i) If no such file, return: ''
  114.        ii) If not a GIF file, return: fully_qualified_filename  -1
  115.       iii) If no such image (i.e.; nn># of images), return:
  116.               fully_qualified_filename -2
  117.        iv) Otherwise, return:
  118.               fqn ct,color_table_data
  119.         where;
  120.             fqn and img_ct:defined above (ct is the "number of colors in the
  121.                            local color table"
  122.             ct_data: The color table data; arranged Red0,Green0,Blue0,Red1,
  123.                      ...,Blue255 (1 byte per value). Note that it 
  124.                     immediately follows a comma.
  125.        Typically, ct_data will be 0.
  126.  
  127.  
  128.  INFOTYPE='COMMENT, IMGNUM=nn; nn>0
  129.       Return the nn'th comment.
  130.         i) If no such gif_file, return: ''
  131.        ii) If not a GIF file, return: fully_qualified_filename  -1
  132.       iii) If no such image (i.e.; nn># of images), return:
  133.               fully_qualified_filename -2
  134.        iv) Otherwise, return:
  135.               fqn jbytes,comment
  136.         where;
  137.             fqn and jbytes: defined above
  138.             comment: The comment. Note that it immediately follows a comma.
  139.  
  140.         Comments are usually straight (7 bit) ascii text.
  141.  
  142.  
  143.  INFOTYPE='PLAINTEXT', IMGNUM=nn; nn>0
  144.       Return the nn'th Plaintext block
  145.         i) If no such gif_file, return: ''
  146.        ii) If not a GIF file, return: fully_qualified_filename  -1
  147.       iii) If no such image (i.e.; nn># of images), return:
  148.               fully_qualified_filename -2
  149.        iv) Otherwise, return:
  150.  
  151.                 fqn pt_left pt_top pt_width pt_height jbytes,ptext
  152.         where;
  153.             fqn and jbytes: defined above
  154.                    pt_left: left corner
  155.                     pt_top: top corner
  156.                   pt_width: width of text block (in pixels)
  157.                  pt_height: height of text block (in pixels)
  158.                      ptext: The Plaintext message. Note that it immediately follows
  159.                             a comma.
  160.  
  161.         Plaintext are usually straight (7 bit) ascii text. They are rarely
  162.         used.
  163.  
  164.  INFOTYPE='APP', IMGNUM=nn; nn>0
  165.       Return the nn'th Application block
  166.         i) If no such gif_file, return: ''
  167.        ii) If not a GIF file, return: fully_qualified_filename  -1
  168.       iii) If no such image (i.e.; nn># of images), return:
  169.               fully_qualified_filename -2
  170.  
  171.        iv) Otherwise, return:
  172.              fqn,app_id app_auth,jbytes,appdata
  173.         where;
  174.  fqn and jbytes: defined above
  175.          app_id:  8 bytes naming the application
  176.        app_auth: 3 byte application authorization code
  177.         appdata: Data meant for the application. Note that appdata follows a comma.
  178.  
  179.         Note that app_id is always 8 bytes, and app_auth is always 3 bytes. Also
  180.         note that a comma appears just BEFORE app_id, and just AFTER app_auth.
  181.  
  182.  
  183.                         ---------------------------
  184.  
  185. Errors:
  186.  
  187.  Error codes are returned when a bad .GIF file is encountered. 
  188.  The return has the form:
  189.     ERROR n
  190.  where n can be:
  191.     0  : Unrecognized "INFOTYPE" parameter
  192.    -1  : Bad Extension label
  193.    -2  : Bad Descriptor label
  194.    -3  : Error in application block
  195.    -33 : Overrun reading Application block data
  196.    -4  : Error in plain text block
  197.    -44 : Overrun reading Plain Text block data
  198.    -6  : Overrun reading Image Descriptor data
  199.    -7  : Overrun  reading Comment data
  200.    -8  : Bad terminator in Graphics control block
  201.  
  202. Note that errors need not occur in a "relevant" block. For example, if plaintext
  203. block #1 precedes image #2, and this plaintext block is corrupted, then
  204. an error will occur (even though you may not care about the contents of
  205. this plaintext block).  This stringency is motivated by the sequential structure 
  206. of .GIF files; where corruption of one part may degrade the entire
  207. remaining portions.
  208.  
  209.                         ---------------------------
  210.  
  211.  
  212. Notes:
  213.  
  214.   *  For gif89a specs, please see http://member.aol.com/royalef/gif89a.txt
  215.   *  Remember that data values are typically preceded by a comma -- the 
  216.      actual data begins immediately after this comma (that is, there are no
  217.      intervening spaces).
  218.   *  If you use the "string" mode of GIF_INFO, gif_text must be a verbatim
  219.      .GIF file; say, as read with:
  220.             gif_file=charin(afile,1,chars(afile))
  221.  
  222.   *  As noted, the IMAGE data returned is compressed. If someone would like to
  223.      provide some LZW decompression code (and GIF has a few variants of that),
  224.      I'll be happy to include it (remember, this is freeware, so the copyright
  225.      stuff should not be problem).
  226.    
  227.  
  228.                         ---------------------------
  229.  
  230. Sample Program:
  231.  
  232.   You can use this to extract information from one (or several) .GIF files. Just
  233.   be sure that GIF_INFO.CMD is in the same directory.
  234.  
  235. /***************************************************/
  236. /* Sample program that uses GIF_INFO.CMD to retrieve information from a gif file */
  237. parse arg gfile
  238.  
  239. if gfile='' then do
  240.    call charout," Enter gif file name: "; parse pull gfile
  241. END
  242. if pos('.',gfile)=0 then gfile=gfile'.gif'
  243.  
  244. /* just show Basic info on lots of .gif files */
  245.  
  246. if pos('*',gfile)>0 then do
  247.     aa=sysfiletree(gfile,oys,'FO')
  248.     do mm=1 to oys.0
  249.         agfile=oys.mm
  250.         aa=gif_info(agfile)
  251.         if aa<0 then say " Error; code= " a
  252.         call charout,' (hit enter to get next file )';parse pull .
  253.     end /* do */
  254.     exit
  255. end /* do */
  256.  
  257. /* single image retrieval -- multiple rounds of info*/
  258.  
  259. a=stream(gfile,'c','query exists')
  260. if a='' then do
  261.     say " no such file "gfile
  262.     exit
  263. end /* do */
  264. gg=charin(gfile,1,chars(gfile))
  265. oo=stream(gfile,'c','close')
  266. do forever
  267.   call charout," Enter info type (S,B,I,T,C,P,A,X to exit): " ;  pull atype
  268.   if atype='X' then exit
  269.   call charout," Enter image # (or 0 for image info): " ; parse pull aval
  270.   oo=gif_info(gg,atype,aval,gfile)
  271.   say "Result= " oo
  272.   say
  273. end
  274.  
  275.  
  276.                         ---------------------------
  277.  
  278.  
  279. Basic copyright and it's never our fault disclaimer:
  280.  
  281.   Copyright 1998 by Daniel Hellerstein. Permission to use this program
  282.   for any purpose is hereby granted without fee, provided that
  283.   the author's name not be used in advertising or publicity
  284.   pertaining to distribution of the software without specific written
  285.   prior permision.
  286.  
  287.   This includes the right to subset and reuse the code, with proper attribution, 
  288.  and subject to the proviso:
  289.  
  290.       We, the authors of GIF_INFO and any potentially affiliated institutions,
  291.       disclaim any and all liability for damages due to the use, misuse, or
  292.       failure of the product or subsets of the product.
  293.  
  294.     THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS
  295.     OR IMPLIED WARRANTY.
  296.     THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE,
  297.     INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
  298.     IN NO  EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR
  299.     INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY
  300.     SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  301.     RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  302.     OF CONTRACT,NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
  303.     IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE.
  304.  
  305.  
  306.    GIF_INFO was developed on the personal time of Daniel Hellerstein,
  307.    and is not supported, approved, or in any way an official product
  308.    of my employer (USDA/ERS).
  309.  
  310.  
  311.