------------------------------------------
                  CoastWatch Image Plotting Software (CWIPS)
                             Version 2.0, 6/93
                  ------------------------------------------

                     Dr. David J. Schwab and Glenn C. Muhr
	      NOAA Great Lakes Environmental Research Laboratory
			    2205 Commonwealth Blvd.
                           Ann Arbor, MI 48105-2945
                                 734-741-2120
                            Fax: 734-741-2055

                   Internet: schwab@glerl.noaa.gov
                             muhr@glerl.noaa.gov




Section        Title
-------        -----

   1.      Introduction
   2.      Information Files
   3.      Executing the Program
   4.      Choosing the Output Format
   5.      Choosing the Color Palette
   6.      Specifying the Input File Name
   7.      Selecting the Temperature or Reflectance Range
   8.      Specifying Image Displacement
   9.      Shoreline and Latitude/Longitude Grid Overlays
  10.      Decompression
  11.      Processing Menu
  12.      Writing to an Output File
  13.      Subregion Definition
  14.      Masking
  15.      Acknowledgements



1. Introduction
   ------------

CWIPS is a PC-based program to read NOAA CoastWatch SST and visible image files
(SSTMAP, IMGMAP and OCNMAP) and produce color image output files in several
formats: Adobe PostScript, Microsoft BitMap and unformatted 8 bit digital image.
The output is not displayed on the PC's screen, so the program does not require
any particular graphics capability on the PC.  The program is presented in two
versions, depending on the configuration of the user's system.  One version
utilizes the capabilities of a resident numeric coprocessor, while the other
does not and is somewhat slower as a result.  If speed is a concern, it is
suggested that a numeric coprocessor be used.


2. Information Files
   -----------------

In addition to the executable program file CWIPS.EXE, two information files must
be available to execute CWIPS: CWIPS-PS.DEF and CWIPS.PAL.  These two files are
provided on the distribution disk.  CWIPS-PS.DEF is the prolog for Adobe Post-
Script output files and CWIPS.PAL contains a library of color palettes which is
used in the creation of PostScript and BitMap output files.  A third information
file CWIPSPAL.CUR is created upon the initial execution of CWIPS, and contains
the name of the default palette. The file F77L.EER is not necessary for the
execution of CWIPS, but is included in the event of run-time errors.  It contains
Lahey FORTRAN error messages to improve error diagnosis.


3. Executing the Program
   ---------------------

To start the program, type CWIPS at the MS-DOS prompt.  The command line may include
an MS-DOS path specification to tell the program where to find the above mentioned
information files. For instance:


     C:> CWIPS C:\CWIPS\


This command line specifies that subdirectory C:\CWIPS\ contains the CWIPS-PS.DEF
and CWIPS.PAL information files.  If these files are present in the current default
directory, it is not necessary to include a path specification on the command
line.  This option is available to give the user the flexibility to store the CWIPS
information files in a directory other than the current default directory.

If you wish to provide input to the program from a file instead of the keyboard,
use MS-DOS input redirection on the command line. For example:


     C:> CWIPS < INPUT.DAT

  
This executes the program using lines of the file INPUT.DAT as an alternate input
stream substituted for the answers you would have typed from the keyboard.


4. Choosing the Output Format
   --------------------------

The initial CWIPS prompt determines the output format to be used for the current
execution of the program.  The placement of this prompt at the beginning of the
execution is based on the assumption that the user will typically be using a
single output format.  This enables the production of multiple output files
without being prompted each time for the output format.

Output files in the PostScript format (.PS) may be sent to a color PostScript printer
using the MS-DOS PRINT command.  PostScript output files are about 600 Kb in size.
A commercial PostScript interpreter such as UltraScript or Freedom of Press may
be used to print the file on a non-PostScript printer like HP PaintJet, HP LaserJet,
or even a dot-matrix printer. There are also commercial image printing services
available that will make 35mm slides, color hardcopy, and color transparencies
from PostScript files.

Output files in the Microsoft BitMap format (.BMP) vary in size depending on the
subregion selected.  A full image will yield a BMP file of about 260 Kb in size.
BMP files may be processed by several commercial software packages including the
Paintbrush application of MS-Windows, and also by the shareware program Graphic
Workshop for both Windows and MS-DOS.  Graphic Workshop is available on most
bulletin boards and features numerous output formats.

Output files in unformatted 8-bit digital image format (.UNF) may be used with most
image processing packages, such as IMDISP, VIDAS, IDL, PV-WAVE, PCI, etc.


5. Choosing the Color Palette
   --------------------------

The next prompt determines the color palette to be used for Adobe PostScript
and Microsoft BitMap output formats.  This prompt is bypassed if 8 bit output
is selected.

The library of color palettes supplied with the program is contained in the file
CWIPS.PAL. This library contains 40 palettes, and includes the two palettes which
are used most frequently by GLERL CoastWatch operations.

The default palette is selected by pressing the return key upon being prompted
for the palette number.  The default palette is defined as the last palette
which has been used. If the user wishes to select another palette, the menu of
available palettes may be displayed by typing a zero at the palette prompt.

The first color of each palette corresponds to the lowest temperature (or reflectance), 
the last color to the highest.  If you wish to reverse this mapping,
(use the first color for the highest temperature/reflectance and the last for
the lowest), then type a minus sign in front of the palette number you select.
For instance, type -3 to select the third palette and have the first color in
the palette correspond to the highest temperature/reflectance and the last for
the lowest.

Customized palette libraries may be substituted for the palette library supplied
with the distribution diskette.  The file must be named CWIPS.PAL, and must have
the same structure as in the supplied version.  A palette entry in the library
file consists of a palette name followed by 256 sets of red, green and blue
intensities (00-FF hexadecimal), one set for each of the 256 colors in the palette.
If a palette file is not available, the program will not execute for PostScript
or BitMap formats.

A file named CWIPSPAL.PS, containing a PostScript color plot of the palette library
is supplied on the distribution diskette, and may be printed on a color PostScript
printer using the MS-DOS PRINT command.  A program called MKPS-PAL.EXE, which
produces CWIPSPAL.PS using CWIPS.PAL, is included on the distribution diskette
if you wish to display your customized palettes.


6. Specifying the Input File Name
   ------------------------------

After the output format and the palette are determined, the file name of the
CoastWatch image is entered.  The program recognizes only compressed 512 x 512
pixel CoastWatch image files with a 1024 byte NESDIS header. The filename may
include an MS-DOS path if required. If the file is a valid CoastWatch image,
information from the image header is displayed on the screen, including satellite
and orbit number, date and time, latitude and longitude range of the image,
horizontal and vertical offsets, and the type of data represented in the image.

MS-DOS commands may be executed from the file name prompt (especially useful for
obtaining directory listings) by typing a greater than sign ">" as the first
character in response to the prompt, followed by the MS-DOS command:


     Enter CoastWatch image file name (RETURN to quit): >DIR G9*.*

      Volume in drive D is DISK1_VOL2
      Directory of  D:\WRK

     G9209620 LD1   317440   4-05-92   9:20p
     G9213120 MD1   328704   5-10-92   9:27p
     G9313720 LC1   384000   5-19-93  12:07p
             3 File(s)  40116224 bytes free


7. Selecting the Temperature or Reflectance Range
   ----------------------------------------------

Data in the CoastWatch thermal image files can cover a wide range of temperatures.
CWIPS requires that the user select a specified portion of the entire available
temperature range.  The specified temperature/reflectance range is divided into
256 increments.  Each increment is assigned a color from the current color palette.
Pixels with temperature/reflectance values higher than the specified maximum
temperature/reflectance are assigned the same color as the maximum.  Pixels with
temperature/reflectance values lower than the minimum are assigned the same color
as the minimum value.

For thermal images, enter the lower and upper bounds for the Centigrade temperature
range you wish to depict in the image.  The two numbers should be entered on one
line, separated by a space or a comma.  If the default temperature range shown in
the prompt is acceptable, just press return.  For visible and near-infrared images,
the reflectance range values are in percent.  The default range is 0 to 30 percent
reflectance.


8. Specifying Image Displacement
   -----------------------------

CWIPS allows for a linear translation of the image relative to the image window
before the image is plotted.  In response to the "Enter image offset" prompt,
enter values for eastward and northward displacement in pixels as a pair of
numbers I,J separated by a comma or space, or press return for no displacement.
The shoreline and latitude/longitude grid overlays are not affected by this
displacement.


9. Shoreline and Latitude/Longitude Grid Overlays
   ----------------------------------------------

If you wish to include the shoreline and/or latitude/longitude grid overlay data
in the image plot, press return after both overlay prompts. The shoreline and
latitude/longitude grid data in the image are plotted with the color corresponding
to the lowest temperature/reflectance except where the image is this color.  In
this case, the color corresponding to the highest temperature/reflectance is used.


10. Decompression
    -------------

After defining the temperature/reflectance range, the offset and overlays, the
image is then decompressed into a 512 x 512 byte array which may be manipulated
before producing output files. The decompression will take a few moments, and
you will notice disk activity during this time. Image decompression on a 486-PC
running at 33 MHz (with a numeric coprocessor) will take about 20 seconds for a
typical image.


11. Processing Menu
    ---------------

The processing menu is displayed after completion of decompression.  From this menu,
parameters pertaining to the output file are defined.  Several output files may be
produced from the same image, without repeated decompression.

Before listing the processing options, the name of the current image and subregion
are displayed.  A full frame is defined as (0:511,0:511).


     -----------------------------
         Image: G9209620.LD1
     Subregion: (0:511,0:511)
     -----------------------------

     Processing options:

     1) Write image to Adobe PostScript output file
     2) Define image subregion
     3) Apply mask to image from file

     Enter selection (RETURN to specify new image): 


MS-DOS commands may also be executed from the processing menu using the same
procedure described in Section 6.


12. Writing to an Output File
    -------------------------

Select the first option on the processing menu if you wish to write the current
image subregion to an output file.  A default name derived from the image name and
output format is provided as part of the file specification prompt, and is invoked
if the return key is pressed.  Otherwise, specify the file name (including path if
necessary) where you wish the output to be written. Be aware that if the specified
file already exists, the program overwrites it. When writing of the output file is
complete, which usually takes half a minute or so, the processing menu will reappear.

MS-DOS commands may also be executed from the output file name prompt using the same
procedure described in Section 6.


13. Subregion Definition
    --------------------

The second option on the processing menu allows the user to specify a square
subregion within the 512 x 512 CoastWatch image.  This subregion will then be
used as the area written to output files, until the subregion is redefined. The
subregion definition prompt requires three values I,J,K separated by commas or
spaces. These are the coordinates of the SW corner pixel of the subregion (I,J),
followed by the size of the square's edge in pixels (K). The pixel coordinates
start with 0,0 at the SW corner of the full 512 x 512 image. The value of I
increases eastward and J increases northward.

For example, 128,300,100 specifies a 100 x 100 pixel subregion with the SW
corner at I = 128, J = 300 within the full 512 x 512 image frame. The selected
subregion cannot extend outside the original 512 x 512 image. If a subregion
is currently in effect, pressing return at this prompt restores the subregion
to the full frame.


14. Masking
    -------

The 512 x 512 image array may also be manipulated prior to production of an
output file. This is the function of the third option of the processing menu.
The concept of masking an image involves the use of a file consisting of 262144
bytes (512*512), with each byte corresponding to a pixel of a full 512 x 512
CoastWatch image.  The byte stream begins at the NW corner of the image and
continues west to east, north to south.  The user specifies which byte values
from the mask file will replace the corresponding pixels of the CoastWatch image,
by defining a range of pixel values that will be considered transparent in the
mask file.  Values outside this range will replace pixels in the current image
array.

For example, suppose a mask file contains bytes with values >= 1 where the byte
corresponds to an over-water pixel, and a value of 0 elsewhere.  If you wanted
to mask the over-land pixels, you would define the transparent range as being
from 1 to 255.  This means that image pixels where the mask byte values were from
1 to 255 would be unchanged, while the rest would be set to the value of the mask
byte (0).

After an image is masked, the original image can be restored into memory only by
once again decompressing the image. Subregions of masked images may be defined just
as with unmasked images.

MS-DOS commands may be executed from the mask file name prompt using the same
procedure described in Section 6.


15. Acknowledgements
    ----------------

We appreciate your comments and suggestions for improving CWIPS to better suit
your needs.  If you create any useful new color palettes, we would appreciate
copies so they can be included in future distributions of CWIPS.

This software was developed under the sponsorship of the NOAA CoastWatch/Coastal
Ocean Program.