Help for NIMSMASK

PURPOSE		

NIMSMASK generates a 1250x1750 pixel mask for NIMS multispectral data including:

	1) A "summary image" spatial display of the merged mosaic;

	2) Collection of mean and standard deviation plots, or spectral plots,
	   for at most six spatial areas of the merged mosaic;

	3) Histograms of the raw and stretched summary image;

	4) Two-dimensional histogram of the merged mosaic in false color 
	   - DN/IOF versus band number; and 
	
	5) Listing of vital information concerning the displayed information
	   and the associated NIMS observation.
EXECUTION

NIMSMASK  ( MM files, HIST2D files, SPECPLOT files )  MASK.IMG  user-parameters

This is the general command line for NIMSMASK.  There are three groups of input
files that are required.  The MM (Merged Mosaic) files are the red, green and
blue bands of the output mask's summary image.  Each band may be a ratio of 
up to five spectral bands of the merged mosaic. The files should all have the
same dimension and should not exceed a dimension of 600x600 square pixels.
In the TUBE option, these files are not bands from the merged mosaic cube,
but instead contain graphics generated by program NIMSTSI.

The HIST2D files are three files in all representing the red, green and blue 
planes of the false color two dimensional histogram image.  These files are the
output of programs HIST2D and LOOKUP.  User parameter PS is a required input; 
this is the IDX pseudocolor table code number used to produce the three input 
files.  This is required to produce the correct color scale bar immediately to 
the right of the two dimensional histogram.
EXECUTION continued

Finally, the SPECPLOT files are the mean and standard deviation or spectral
plots, six being the largest number to be stored in the output mask.  Each 
plot is a product of the program SPECPLOT.

An output file specification should follow the three input groups.  The output
is a 1250 x 1750 color image (dimensions 1250x1750x3 = 12818 blocks).
USER PARAMETERS

Parameters ASTRETCH, RSTRETCH, GSTRETCH, BSTRETCH 

The user may specify whether an adaptive or a fixed contrast enhancement, or
stretch, is to be performed on the MM spatial display.  ASTRETCH accepts the 
sample and saturation percentages, in that order, for an adaptive stretch.  
The adaptive stretch is performed on all three input bands.  The adaptive 
stretch can be superseded by fixed stretches on a color band basis, RSTRETCH, 
GSTRETCH or BSTRETCH.  Each specifies a fixed stretch for the red, green or 
blue input images, with lower and upper limits of the stretch in DN. If the
cube from which image planes are extracted contains radiances scaled to the
halfword range, then the fixed stretch limits should be specified in units 
of radiance;  in this case the R/G/B planes should be extracted using
NIMSFLOAT (which converts the halfword DNs back to radiances) and should
contain positive data only.  (See proc SYSNIMS, which runs these planes
through program ASTRTCHR in order to ensure this.)
USER PARAMETERS continued

Parameters TCA, RFORMULA, GFORMULA, BFORMULA

These are string inputs: time to closest approach (TCA) having 13 characters, 
and the formulae (xFORMULA) restricted to 35 characters.  TCA should be in the 
form -DDD HH:MM:SS; it appears in the annotation area of the mask beside item
OBSNAME.  RFORMULA, GFORMULA and BFORMULA also appear on the mask below the 
histogram of the raw image as RED, GRN and BLU.  These formulae represent the 
ratio of spectral bands used to produce the red, green and blue planes of the 
MM spatial display.  
USER PARAMETERS continued

Parameter PS

This is the IDX pseudocolor table number used for the mapping of the two-
dimensional monochrome histogram to its false color equivalent.  Although this 
mapping is done outside of NIMSMASK, the mask program still needs to know what 
color table was used such that it can be replicated in the color scale of the 
mask, immediately to the right of the two-dimensional histogram on the mask.  
PS defaults to IDX table 3 because it has the greatest resolution.  
Valid IDX color table numbers are one (1) through seven (7).
USER PARAMETERS continued

Parameter BCKGRD

The background DN of NIMSMASK can be given any grey scale desired.  BCKGRD
is a three field parameter accepting (RGB) values.  Currently, BCKGRD must be 
a grey scale; the individual R G B values must all be the same in order to be 
compatible with SPECPLOT image files.  The default value for the background DN,
BCKGRD, is black, (0,0,0).

Parameter BOXCOLOR

The color of area boxes of the MM spatial display, or summary image, can be set
to a constant value.  As a default, NIMSMASK generates the box colors from 
information about the stretched MM image; however this may not always result 
in easily discernable area boxes.  BOXCOLOR accepts a color triplet, (RGB) in 
three fields.
USER PARAMETERS continued

Parameter EXCLUDE

This parameter allows the user to exclude specific DN values from evaluation
in the stretch of the summary image and the stretched image histograms.  NIMS
special values [-32768,-32753] are excluded from the stretch and histogram
evaluations by default.  Additional values, up to a maximum of twenty (20) 
excluded DN values, may be excluded.

Keywords DN, IOF, RAD

These keywords are obsolete as of January 18, 1994.
INPUTS

Merged Mosaic files

MM input is three separate files, each file corresponds to a color plane.  
Each file is composed of some ratio of spectral bands of the original merged 
mosaic of 17, 204 or 408 spectral bands.  Thus, there is a red color plane 
file, MM.RED, a green color plane file, MM.GRN, and a blue color plane file, 
MM.BLU.  All three files are required as the first three inputs of the 
command line in RGB order.

In the TUBE option, these files are not bands from the merged mosaic cube,
but instead contain graphics generated by program NIMSTSI, rendered into
false ecolor by program LOOKUP.

Spectral Plot files

The SPECPLOT files are the output of the VICAR program SPECPLOT.  The files 
are at most six (6) black/white plots of mean and standard deviation of user- 
specified areas of the full spectrum merged mosaic.
INPUTS continued

False-color Two-Dimensional Histogram files

The full spectrum merged mosaic is used to create a two-dimensional histogram 
which is a serial collection of histograms of all spectral bands.  Each sample 
value of HIST corresponds to a spectral band, and for each spectral band, a 
one-dimensional histogram is generated.  Thus, each sample value of the 
two-dimensional histogram contains a one-dimensional histogram describing the 
frequency of occurrences of certain DN or I/F values for a specific spectral 
band.  

The DN or pixel value at any given point corresponds to the relative frequency 
of occurrences of that particular DN or I/F value.  Dn values are mapped to 
various colors to provide better contrast between the DN values.  Program 
LOOKUP does this mapping using IDX pseudocolor tables to generate the red,
green and blue files.  These three files are the HIST2D files that are input
to NIMSMASK. 
GENERAL DESCRIPTION OF NIMS SYSTEMATIC PROCESSING STREAM 

To better understand how NIMSMASK will be used and the data files associated
with its input, a basic outline of the NIMS systematic stream is warranted.

Once NIMS data is merged into EDRs, Experiment Data Records, the VICAR program
NIMSCMM creates a three-dimensional (spatial/spectral) "merged mosaic" file,
also known as a "cube".  The merged mosaic is of the format, line by sample 
by spectral band.  From this merged mosaic (MM), VICAR program SPECPLOT 
produces mean and standard deviation plots for user-specified areas of the MM, 
and program HIST2D produces a two-dimensional histogram of the MM in terms of 
DN, radiance or I/F versus band number.

For each mask generated, MM will be processed by TRAN and F2 to create the 
color plane files to be used as input to NIMSMASK.  NIMSMASK accepts the 
MM files, the spectral plots and the two-dimensional histogram along with some 
user-specified parameters, to create a color mask of NIMS data. 
HISTORY

Original Programmer:    Justin McNeill, Jr.
Written:                June 1, 1990
Cognizant Programmer:   L.W.Kamp