home *** CD-ROM | disk | FTP | other *** search
/ Voyagers to the Outer Planets 2: Uranus / VoyagestotheOuterPlanetsVol2.cdr / software / softinfo.txt < prev    next >
Text File  |  1988-09-14  |  15KB  |  335 lines
  1. NJPL1I00PDS100000000 = SFDU_LABEL
  2. RECORD_TYPE          = STREAM
  3. OBJECT               = TEXT
  4.   NOTE               = "Description of software provided with the
  5.                         Voyager CD-ROM set."
  6. END_OBJECT
  7. END
  8.  
  9.                     Decompression Software
  10.                     ----------------------
  11.  
  12. The SOFTWARE directory contains software source code files for the
  13. decompression of compressed image files.  In order to make the software
  14. available to a wide community of users, different versions of the
  15. decompression software exist in VAX/VMS FORTRAN, IBM/PC FORTRAN,
  16. C-language, and VAX/VMS Assembler language.  Some modification of these
  17. routines may be required in order to adapt the software to a particular
  18. computer and operating system.  This directory also contains a sample
  19. utility program to read the image index flat table (IMGINDEX.FOR). 
  20.  
  21. These routines assume that the user can access the compressed image
  22. files through normal system input/output (I/O) commands.  Otherwise
  23. special utilities may be needed to move image files from the CD-ROM
  24. to the user's fixed-disk prior to executing the decompression programs.
  25.  
  26. Information describing the compressed image files can be found in the
  27. VOLINFO.TXT file located in the DOCUMENT directory. The document
  28. describes the organization of the CD-ROM. It provides information on how
  29. to access files stored on a CD-ROM, and gives details on the format and
  30. contents of the image files and their supporting supplemental files.
  31.  
  32. The decompression software is supplied as callable subroutine
  33. modules for use with existing applications; as source code for
  34. stand-alone programs which can be copied to the users
  35. host-computer, compiled, linked and executed; and as executables
  36. for IBM PC and VAX users.  The practice of distributing software on
  37. read-only archival media is known to be risky.  The executables
  38. are being placed on this disk for evaluation and no guarantee is
  39. made that they will work in specific computer configurations.
  40.  
  41. SUBROUTINES
  42.  
  43. The decompression software has two subroutines to be called by an
  44. application program. Typically, an application program will open an
  45. image file, read the image data from the file, call the decompression
  46. routines to restore the image, and then transfer the image to the
  47. appropriate output media or display device.
  48.  
  49. The software has two top-level subroutines, DECMPINIT and DECOMPRESS.
  50. They provide a common base from which to call the processing
  51. routines. DECMPINIT builds the Huffman tree from the encoding histogram
  52. and is called only once per image. DECOMPRESS processes one compressed
  53. input line per call and returns the line completely restored.  These
  54. routines are fully documented. Consult the source code files for a full
  55. explanation of their use.
  56.  
  57. A Programmer's View
  58. -------------------
  59.  
  60. From the programmer's view point, the calling sequence of these routines
  61. are as follows:
  62.  
  63. 1) First, extract the encoding histogram from the image file. (Consult
  64.    VOLINFO.TXT document for details). The encoding histogram contains
  65.    511 32-bit elements.  Note, the encoding histogram is configured
  66.    in "least significant byte first" order. This is the order for integer
  67.    values used by VAX and IBM PC computer systems.  Users of other
  68.    computer architectures (IBM Mainframes, Macintosh, SUN, and Apollo)
  69.    will need to swap the byte pairs 1 and 4, and 2 and 3. (Example,
  70.    hexadecimal value AA BB CC DD becomes DD CC BB AA.)
  71.  
  72. 2) Pass the encoding histogram to the DECMPINIT routine to initialize
  73.    the Huffman coding tree.
  74.  
  75. 3) After the initialization call, read compressed image lines, one at
  76.    at a time, from the image file and pass the lines to the DECOMPRESS
  77.    routine for restoration.  After the image line has been restored,
  78.    transfer the line to an output image file or display screen.
  79.  
  80.  
  81. FORTRAN Considerations
  82. -----------------------
  83.  
  84. The VAX/VMS FORTRAN version of the decompression software resides in the
  85. DECOMP.FOR file. This file contains the DECMPINIT and DECOMPRESS
  86. routines, and the internal subroutines DCMPRS, HUFF_TREE, and SORT_FREQ.
  87. A version of these routines for Sun workstations is in file DECOMPS.FOR.
  88. Additionally, for VAX/VMS users there is an assembler language version
  89. of the DCMPRS routine located in the file DCMPRS.MAR. Use of this
  90. routine will improve the performance of the decompression software by a
  91. factor of two. The VAX/VMS assembler routine will only work with the
  92. FORTRAN version of the decompression software. There is also a source
  93. file called BTEST.FOR. This file contains a FORTRAN version of the
  94. VAX/VMS BTEST intrinsic function. Use this routine only if you are not
  95. running under the VAX/VMS environment. Finally, there is a main
  96. program, located in the DETEST.FOR file, which tests the performance
  97. of the decompression software. If you are adapting the software to your
  98. particular hardware configuration, then this program will be useful for
  99. testing the software. A summary of the FORTRAN related files is
  100. presented below.
  101.  
  102.        DECOMP.FOR  - VAX/VMS FORTRAN versions of the decompression
  103.          software. Contains routines DECMPINIT, DECOMPRESS, and
  104.          working routines SORT_FREQ, HUFF_TREE, and DCMPRS.
  105.        DCMPRS.MAR - VAX/VMS macro assembler routine which can replace
  106.          the FORTRAN version of the DCMPRS subroutine.
  107.        BTEST.FOR - Contains the FORTRAN code for the VAX/VMS BTEST
  108.          intrinsic function.
  109.        DETEST.FOR - Tests the decompression subroutines.
  110.  
  111. Example FORTRAN Program
  112. ------------------------
  113.  
  114. The example FORTRAN program shown below demonstrates how to use the
  115. decompression programs.
  116.  
  117.  
  118.   C*******************************************************************
  119.   C
  120.   C HIST   - Buffer to contain 511 elements of the encoding histogram.
  121.   C          The encoding histogram is extracted from the image file.
  122.   C NSI    - Number of bytes obtained from the read of a compressed
  123.   C          line.
  124.   C NSO    - Number of output samples after decompression. For Voyager
  125.   C          images, this value is 836.
  126.   C LINEI  - Buffer containing the input compressed line.
  127.   C LINEO  - Buffer to contain the restored line after decompression.
  128.   C NL     - Number of lines in the image array.  For Voyager images,
  129.   C          this value is 800
  130.   C IL     - DO loop counter for processing image lines.
  131.   C********************************************************************
  132.           INTEGER*4 NSI,NSO,NL,IL
  133.           INTEGER*4 HIST(511)
  134.           BYTE      LINEI(836),LINEO(836)
  135.           .
  136.           .
  137.   C********************************************************************
  138.   C Assume the encoding histogram has been extracted from
  139.   C the image file and has been placed into the HIST array.
  140.   C Pass it to the DECMPINIT routine for initialization
  141.   C********************************************************************
  142.           CALL DECMPINIT(HIST)
  143.           .
  144.           .
  145.   C********************************************************************
  146.   C The DO loop will read one compressed line at a time from the input
  147.   C file and call the DECOMPRESS routine to restore the line
  148.   C********************************************************************
  149.           NL  = 800
  150.           NSO = 836
  151.           DO IL = 1,NL
  152.           .
  153.           .
  154.           (read next compressed line (LINEI) and length of line (NSI))
  155.           CALL DECOMPRESS(LINEI,LINEO,NSI,NSO)
  156.           (line is restored in the LINEO subroutine)
  157.           .
  158.           END DO
  159.           .
  160.           .
  161.           STOP
  162.           END
  163.  
  164.  
  165. C-language Considerations
  166. -------------------------
  167.  
  168. The C-language versions of the decompression subroutines are more
  169. portable than the equivalent FORTRAN versions. These routines have
  170. been tested on a VAX 750 running under version 4.6 of VMS, a
  171. Micro-VAX running under version 2.2 of ULTRIX, a SUN workstation
  172. running under version 4.2 (release 3.4) of UNIX, and an IBM PC
  173. running under MSDOS using versions 4.0 and 3.0 of MICROSOFT C.
  174.  
  175. The C-language version of the decompression software resides in the
  176. DECOMP.C file.  This file contains the decmpinit and decompress
  177. routines, and the working routines dcmprs, huff_tree, and sort_freq.
  178. Also, there is a main program, located in the DETEST.C file, which
  179. tests the performance of the decompression software.  If you are
  180. adapting the software to your paricular hardware and operating system
  181. environment, then this program will be useful for testing the
  182. software.
  183.  
  184. Example C-language Program
  185. --------------------------
  186.  
  187. The example program shown below demonstrates the use of the
  188. decompression subroutines.
  189.  
  190.   /********************************************************************
  191.   *
  192.   * hist   - Buffer to contain 511 elements of the encoding histogram.
  193.   *          The encoding histogram is extracted from the image area.
  194.   * nsi    - Number of bytes obtained from the read of a compressed
  195.   *          line.
  196.   * nso    - Number of output samples after decompression. For Voyager
  197.   *          images, this value is 836.
  198.   * linei  - Buffer containing the input compressed line.
  199.   * lineo  - Buffer to contain the restored line after decompression.
  200.   * nl     - Number of lines in the image array.  For Voyager images,
  201.   *          this value is 800.
  202.   * il     - Loop counter for processing image lines.
  203.   ******************************************************************/
  204.          main ()
  205.          {
  206.           extern void decmpinit(); /* decmpinit is void function*/
  207.           extern void decompress();/* decompress is void fuction*/
  208.           long  nsi,nso,nl,il;
  209.           long  hist[511];
  210.           char  linei[836],lineo[836];
  211.           .
  212.           .
  213.   /********************************************************************
  214.   * Assume the encoding histogram has been extracted from
  215.   * the image file and has been placed into the hist array.
  216.   * Pass it to the decmpinit routine for intialization
  217.   ********************************************************************/
  218.           decmpinit(hist);
  219.           .
  220.           .
  221.   /********************************************************************
  222.   * The loop will read one compressed line at a time from the input
  223.   * file and call the decompress routine to restore the line
  224.   ********************************************************************/
  225.           nl  = 800;
  226.           nso = 836;
  227.           for (il=0; i<nl; ++i)
  228.           {
  229.            .
  230.            .
  231.            (read next compressed line (linei) and length of line (nsi))
  232.            decompress(linei,lineo,&nsi,&nso);
  233.            (line is restored in the LINEO variable.)
  234.            .
  235.           }
  236.           .
  237.           .
  238.          }
  239.  
  240.  
  241.  
  242. Stand-Alone Applications
  243. ------------------------
  244.  
  245. Stand-alone applications which will read a compressed image file,
  246. reformat the labels and decompress the image to an output file
  247. are provided in C and FORTRAN language versions.
  248.  
  249. The program CDCOMP.C includes all routines necessary to compile and
  250. link, producing an executable version of the program.  This program
  251. has been tested on an IBM PC with Microsoft C, version 5.1, on a
  252. VAX 11/780 using VMS C version 2.2-015, and on a Sun workstation
  253. running BSD UNIX 4.2.  IBM PC users will receive three compilation
  254. warnings  which may be ignored.  VAX/VMS users may have to edit the
  255. "#include <stdio.h>" statement at the beginning of the file depending
  256. on their environment setup.
  257.  
  258. The program CDCOMP.C prompts the user for a input file name, output
  259. file format choice, and output file name.  The output file formats
  260. supported by this version of CDCOMP.C include PDS labelled format,
  261. FITS labelled format, a simple VICAR2 labelled format and an
  262. unlabelled binary array format.
  263.  
  264. The following commands should be used to link subroutines and produce
  265. an executable file:
  266.  
  267.     On an IBM PC (using Microsoft C Version 5.1)
  268.     --------------------------------------------
  269.  
  270.     cl /c cdcomp.c
  271.     link  cdcomp/stack:10000;
  272.  
  273.     On a VAX using VMS:
  274.     -------------------
  275.     cc    cdcomp
  276.     link  cdcomp
  277.  
  278.     On a Unix host (Sun, Masscomp)
  279.     ------------------------------
  280.     cc   -o cdcomp cdcomp.c
  281.  
  282.  
  283. The programs VAXDCOMP.FOR and PCDCOMP.FOR are VAX/VMS and IBM PC
  284. versions of a program to decompress image files and write them out to
  285. a PDS formatted file.  Both programs need to be compiled, then linked
  286. with DECOMP.FOR to produce an executable file.  The programs are
  287. identical except for the file open statements and the variable
  288. length record I/O (read) statements.
  289.  
  290.  
  291.     On an IBM PC (using Microsoft FORTRAN Version 4.1)
  292.     --------------------------------------------------
  293.  
  294.     fl pcdriv.for decomp.for
  295.  
  296.     On a VAX/VMS system:
  297.     -------------------
  298.  
  299.     for   vaxdriv,decomp
  300.     link  vaxdriv,decomp
  301.  
  302. There is also a sample program, IMGINDEX.FOR which will read and 
  303. display the contents of the image index table (IMGINDEX.TAB).  It has 
  304. been tested on the VAX and IBM PC.  The image index table must be in
  305. the same directory as the executable for the program to operate 
  306. properly.  The FILE='IMGINDEX.TAB' statement in the OPEN call can be 
  307. edited to reflect the location of the table (for example, on an IBM PC
  308. it might be specified as FILE='L:\INDEX\IMGINDEX.TAB').
  309.  
  310.  
  311. Executables
  312. -----------
  313.  
  314. The CDCOMP program has been compiled and linked on IBM PC and VAX/VMS
  315. systems to produce executable programs for decompressing images.
  316. For users of IBM PC computers, the program PCDCOMP.EXE will prompt
  317. for input and output file names, writing the decompressed file
  318. to the specified file name.  The program also supports writing
  319. the image file out in PDS, FITS and VICAR2 format, or writing
  320. an unlabelled 800 by 800 array of sample values.  The FITS and
  321. VICAR2 formats provide only minimal system labels to allow display
  322. of the image on systems which support these label formats and have
  323. not been carefully tested.  For VAX/VMS users, the equivalent program
  324. is VAXDCOMP.EXE, which writes out fixed-length files of 836-bytes
  325. (PDS format), 2880-bytes (FITS format) or 800-bytes (VICAR2 or
  326. unlabelled formats).  The image histogram and all engineering
  327. parameters discarded when writing the FITS, VICAR2 and unlabelled
  328. formats.
  329.  
  330. No guarantee is made that these programs will work in your computer
  331. configuration.   The VAX program assumes that you have file-access
  332. support for ISO format CD-ROM disks on your system, or that you have
  333. used a CD-ROM utility routine to read the compressed file from CD-ROM
  334. to a magnetic disk.
  335.