USER'S MANUAL DECCON Version 1.0 by Bill Townsley 08/01/93 DECompression and CONversion of NESDIS CoastWatch Imagery Files INTRODUCTION DECCON is a program which decompresses NESDIS CoastWatch imagery files in IMGMAP format and converts the data to GIF, TIFF, SunRaster, and plain raster image file formats. DECCON was created to increase the accessibility of CoastWatch satellite imagery to the user community. Formerly, users who did not have IDIDAS workstations had limited capabilities to decompress the satellite image files produced by the CoastWatch program. Fortran programs for PC and VAX existed to decompress imagery into 8-bit raster files but these programs did not provide decompression of the overlay or header data. DECCON was developed by Rick Stumpf and Bill Townsley of the U.S. Geological Survey's Center for Coastal Geology to enable the user community to decompress and save NESDIS CoastWatch header, imagery, and graphics data. Included in the DECCON package are a public domain image viewer for Sun SPARCstations and a shareware image viewer for IBM PCs. INSTALLATION DECCON can be compiled on any machine with a C compiler and has been tested on Sun SPARCstations, IBM-PCs and IBM RS/6000s. Installation is easy... 1. Place the DECCON package in an arbitrary directory. 2. Untar/Unzip the DECCON package by typing one of the following commands: SPARC: 'tar xvf deccon.tar' IBM-PC: 'pkunzip deccon.zip' RS/6000: 'tar xvf deccon.tar' These files should now exist in the working directory: HEADER.DOC - IMGMAP header description IMGFILE.DOC - IMGMAP data format description albedo.h - Albedo percentages data base clrmaps.h - Colormaps data base dcn_lib.c - Source code dcn_lib.h - DECCON typedefs and definitions deccon - Sun SPARCstation executable deccon.c - DECCON source code deccon.exe - IBM PC executable deccon.x - IBM RS/6000 executable param.eg - Sample parameter file raster.h - SunRaster format definition temps.h - Temperatures database tiff.h - TIFF definition vpic60.zip - GIF file viewer for IBM PCs xv - Image viewer for Sun SPARCstations xv.man - xv manual page The .DOC files describe in detail NESDIS CoastWatch imagery files. The .c and .h files are DECCON source code and include files. deccon, deccon.exe, and deccon.x are DECCON executables which have been compiled on a Sun SPARCstation, an IBM PC, and an IBM RS/6000 respectively. param.eg is an example parameter file (see PARAMETER FILES). vpic60 is a shareware GIF file viewer for IBM PCs. xv is a public domain image file viewer for Sun SPARCstations. xv.man is the manual for xv. 3. If you have an ANSI compliant C compiler and wish to compile DECCON yourself to produce the executable file, deccon or deccon.exe, use one of the following commands: SPARC: 'gcc -o deccon deccon.c dcn_lib.c -lm' IBM-PC: 'tcc -ml -edeccon deccon.c dcn_lib.c' RS/6000: 'cc -o deccon.x deccon.c dcn_lib.c -lm' Note: Compilers which are not ANSI compliant, such as Sun's cc, may not compile DECCON correctly. 4. Place the executable file in the directory of your choice. The directory path should be a searched one or you should modify your path to include the directory. COMMAND LINE OPTIONS After DECCON has been properly installed, the first time user will find it easy to decompress a NESDIS CoastWatch imagery file and create output suitable for viewing or for intended applications. The command line options and their purposes are... [-h] - will print the DECCON help page to the screen. This page has more lines than will fit on a screen, so it would be best to pipe the command into a scrolling text browser such as more (eg. 'deccon -h | more'). Any other options supplied on the command line with the -h option will be ignored. [-v] - will run DECCON in verbose mode. When supplied with additional options described below, the -v option causes DECCON to print to the screen information on the status of image decompression, image subtraction, image conversion, image adjustment, graphics decompression, file creation and program completion. [-p pfile] - will specify pfile as a parameter file. When pfile is supplied as an argument, DECCON will read its parameters from that file rather than initiate an interactive sequence (see INTERACTIVE SEQUENCE). You can create a parameter file yourself (see PARAMETER FILES), or you can have DECCON create one for you at the end of the interactive sequence. Using a parameter file can save a great deal of time when processing multiple imagery files. [-s sfile] - will inform DECCON to subtract sfile from ifile (see below). DECCON will decompress imagery data from sfile and subtract it from the imagery data in ifile. This feature is intended specifically to allow you to obtain an image of water reflectance corrected for some aerosols by subtracting channel 2 albedo from channel 1 albedo. This is useful for detecting turbidity patterns in coastal areas. The feature corrects for the solar zenith angle at the scene center. This option presumes that the inputs (ifile and sfile) are channel 1 and channel 2 albedo images, which are normally supplied by CoastWatch. In the parameter file or the interactive sequence specify albedo image as output. The sfile must be a compressed NESDIS CoastWatch imagery file (see INTERACTIVE SEQUENCE and PARAMETER FILES). ifile - DECCON will use ifile as the main input file. The ifile must be a compressed NESDIS CoastWatch imagery file. DECCON will decompress header, imagery and graphics data from ifile and use ifile's name as the base for all output file names. This argument is required unless the -h option is given. The following are examples of DECCON command line arguments and their results. 'deccon s9316309.sc1' will use s9316309.sc1 as the main input file and prompt the user for parameters in an interactive sequence. 'deccon -p params s9316309.sc1' will read parameters to DECCON from a file named params (no interactive sequence) and use s9316309.sc1 as the main input file. 'deccon -v -p params s9316309.sc1' will display program activity in verbose mode, read parameters to DECCON from a file named params and use s9316309.sc1 as the main input file. 'deccon -v -s s9316309.sc2 s9316309.sc1' will prompt the user for parameters in an interactive sequence, display program activity in verbose mode and subtract the imagery data in s9311209.sc2 from the imagery of s9316309.sc1. INTERACTIVE SEQUENCE The DECCON parameters determine the output it will create. These parameters may be read from a file as described above in COMMAND LINE OPTIONS or entered during an interactive seqeuence in which the user will be prompted to specify... 1. Output image file format - DECCON allows the imagery to be converted into several common image file formats including GIF, TIFF, SunRaster, and plain raster. GIF is also primarily a viewing format and does not necessarily preserve data values. The other formats can be used for quantitative analysis. GIF format requires image compression and is therefore the most efficient option in terms of storage, but it is the most CPU intensive and slowest to create. SunRaster format is an obvious option for Sun systems. The TIFF option produces the most portable of all the file formats, though they are also the largest. A plain raster option is also available and creates a file containing only 8-bit imagery and/or graphics data with no formatting of any kind. Enter the number of the image file format you wish DECCON to create. 2. Which colormap to use - 2 colormaps, an equal RGB colormap (essentially black and white) and a spectrum colormap are supplied with DECCON. The equal RGB colormap produces standard black and white images. The spectrum colormap was supplied by Rick Stumpf of the U.S. Geological Survey's Center for Coastal Geology and produces images of spectral reflectance. The colormap option is not available if plain raster output is specified. Enter the number of the colormap you wish DECCON to use. Additional colormaps may be added, see file clrmaps.h. 3. Whether to perform an albedo or centigrade temperature conversion - NESDIS CoastWatch image data can be converted to albedo percentages or centigrade temperatures. The 11-bit data is converted and the range specified (see below) is fit to 8-bits, actually 1-250. If none is specified, the full range of values is truncated from 11-bits to 8-bits by discarding the 3 least significant bits. This is equivalent to dividing the original value by 8. Enter the number of the conversion you wish DECCON to perform or zero for none. 4. A range of values for the conversion - Conversions are mapped to a range of values. You may specify this range by entering numerical values at the prompts or 'd' for the default values. 5. Whether to adjust the image and by how many pixels - Due to navigational errors, image data may need a linear adjustment in order for ground features to correctly line-up with graphics overlay planes. DECCON allows an up or down, left or right correction by pixel unit. If you wish DECCON to perform an image adjustment enter the direction of the adjustment and the distance in pixels to move in that direction. Enter zero for no adjustment. 6. Which graphics overlay planes to display - NESDIS CoastWatch images include up to 4 graphics overlay planes. These graphics planes define such things as latitude/longitude and coastlines. Enter 'y' for yes if you wish the overlay plane diplayed or 'n' for no if you do not wish the overlay plane displayed. 7. Whether to embed or separate the graphics overlay planes - The graphics may be separate in which case two files will be created, one containing imagery data and one containing graphics data. The graphics may also be embedded and one image file will be created containing both the imagery data and whatever overlay planes have been chosen. Enter 0 to separate the graphics or 1 to embed the graphics in the imagery data. 8. Overlay and background color - The color of the overlay planes and background color may be specified to ensure maximum contrast to the underlying imagery. For example, when using the equal RGB colormap, specify overlay color as 0 (black) and background color as 255 (white) for maximum contrast. 9. Whether to record the header data - The header data from NESDIS CoastWatch images may be recorded in an ASCII file. Enter 'y' for yes if you would like to record the header data in a separate file or 'n' for no if you would not like to record the header data. 10. Whether to record the parameters - A parameter summary is printed to the screen after the interactive sequence. You may save these parameters in a separate file if you wish to use them at a later time. Enter 'y' for yes if you would like to record the parameters in a separate file or 'n' for no if you would not like to record the parameters. PARAMETER FILES A DECCON parameter file consists of numerical entries which represent DECCON parameters. Using a parameter file instead of initiating the interactive sequence each time you wish to process an imagery file can save considerable time. In addition, using a parameter file ensures identical processing of multiple imagery files. You may give the parameter file any name you wish. You may even desire to keep several of them on hand with names such as gif_param which could be used to create a particular output file format type, or FL_param which could be used on imagery files of a particular area-of-interest and contain the proper adjustment values or conversions. In a parameter file, a single value for every parameter must be present on a line by itself and in the correct order. Comments may also be included in a parameter file provided that each line of comment is preceeded by the character '#'. The proper order and numerical value of the parameters are as follows: Entry #1: Output Image File Format 1 = SunRaster 2 = GIF (87a) 3 = TIFF (5.0) 4 = plain raster Entry #2: Colormap 1 = Equal RGB Colormap (Black & White) 2 = Spectrum Colormap Entry #3: Conversion 0 = Perform no conversion 1 = Convert data to albedo percentages 2 = Convert data to centigrade temperatures Entry #4: Low Conversion Range Value (ignored if #3 = 0) A single floating point value (0.000000 or greater for an albedo conversion) (-95.250008 or greater for a temperature conversion) (ignored if #3 = 0) Entry #5: High Conversion Range Value (ignored if #3 = 0) A single floating point value (99.902298 or less for an albedo conversion) (109.249992 or less for a temperature conversion) (ignored if #3 = 0) Entry #6: Vertical Adjustment 0 = Perform no vertical adjustment 1 = Adjust image up 2 = Adjust image down Entry #7: Vertical Adjustment Value The distance in pixels to move the image up or down (ignored if #6 = 0) Entry #8: Horizontal Adjustment 0 = Perform no horizontal adjustment 1 = Adjust image to the left 2 = Adjust image to the right Entry #9: Horizontal Adjustment Value The distance in pixels to move the image left or right (ignored if #7 = 0) Entry #10-13: Graphics Overlay Planes 1-4 0 = Do not display 1 = Display Entry #14: Overlay Display 0 = Create 2 output image files, 1 containing only imagery data and the other containing only graphics 1 = Create 1 output image file containing both imagery and graphics data Entry #15: Overlay Color Any value between 0 and 255 (use this value as the color index of all overlays) Entry #16: Background Color Any value between 0 and 255 (use this value as the color index of the background) Entry #17: Record NESDIS CoastWatch header data 0 = Do not write header data to disk 1 = Write header data to disk Example Parameter File: #This is an example parameter file which creates a #SunRaster output image file using an equal RGB colormap. #The data will be converted to albedo percentages using the #DECCON default range. No vertical adjustment will be #performed, but the image will be adjusted left by 3 pixels. #Overlays 1-4 will be displayed and written to a separate #file. The overlays will be black and background color will #be white. Header information will be recorded. #FORMAT: 1=SunRaster, 2=GIF, 3=TIFF, 4=plain raster 1 #COLORMAP: 1=Equal RGB, 2=Spectrum Colormap 1 #CONVERSION: 0=None, 1=Albedo, 2=Temperature 1 #LOW RANGE VALUE: 0.00000 #HIGH RANGE VALUE: 12.50000 #VERTICAL ADJUSTMENT: 0=None, 1=Up, 2=Down 0 #VERTICAL NUMBER OF PIXELS: 0 #HORIZONTAL ADJUSTMENT: 0=None, 1=Left, 2=Right 1 #HORIZONTAL NUMBER OF PIXELS: 3 #OVERLAYS 1-4: 0=not displayed, 1=displayed 1 1 1 1 #OVERLAY DISPLAY: 0=Separate, 1=Embedded 0 #OVERLAY COLOR: Color range = 1-255 0 #BACKGROUND COLOR: Color range = 1-255 255 #RECORD HEADER DATA: 0=FALSE, 1=TRUE 1 DECCON OUTPUT DECCON output filenames are based upon the name of the main input NESDIS CoastWatch imagery file plus a prefix indicative of the data contained within the output file. This naming convention was chosen since only the last 9 digits of NESDIS CoastWatch imagery file names are unique (see IMGFILE.DOC) The prefix IMG indicates output imagery data, SUB pertains to imagery data that has had an image subtraction performed on it, GFX signifies graphics data, DAT refers to output header data, and PRM labels an output parameter file. For example, depending upon parameters, command line options and using the file s9316309.sc1 as the main input file (ifile), DECCON could produce the following output files: IMG16309.sc1 - an imagery data image file SUB16309.sc1 - an imagery data image file (after subtraction) GFX16309.sc1 - an graphics data image file DAT16309.sc1 - an ASCII file of header information PRM16309.sc1 - an ASCII parameter file DECCON ERRORS If DECCON encounters an error it will print a descriptive message to the screen (stderr) and terminate. Storage space is assumed to be adequate for DECCON output and no error checking is performed when writing output files to disk. DECCON will print an error and terminate under the following conditions. Failure to access a file Failure to create a file Failure to read from a file Failure to skip through a file Invalid parameters Failure to allocate memory Unexpected end of file CAVEAT 1 The standard NESDIS CoastWatch imagery file contains an image that is 512 rows by 512 columns, though files containing larger images do exist. DECCON was designed to decompress and convert any NESDIS CoastWatch imagery file with up to 1400 rows. However, when installed on a PC, DECCON may not work with images larger than the standard 512 rows. Therefore, if you use a PC, it is recommended that you modify the constant definition of MAX_SIZE in file dcn_lib.h from 1400 to 512 before compiling. The definition of MAX_SIZE as 1400 appears on line 108 of the file dcn_lib.h. If you are installing DECCON on a PC, change the 1400 on line 108 to 512 (ie #define MAX_SIZE 512).