Help for ASTRTCHR

 PURPOSE:

"astrtchr" is a general purpose VICAR applications program which performs 
automatic linear stretches on floating point and fullword integer pictures.
"astrtchr" can also be used to make pictures of GALGEN light transfer
calibration files.
 EXECUTION:

The input image may either be fullword floating point or fullword integer
data.  The SIZE parameter specifies the portion of the image that will be 
stretched and then written to the output file. The AREA parameter specifies 
the portion of the input image to use in determining the stretch limits. 
The default for both the AREA and SIZE parameters is to use the full input 
image.  Both AREA and SIZE give the starting pixel number and number of 
pixels per line instead of values measured in bytes. 

The output image may either be byte or halfword data.  The size of the output
image is determined by the SIZE parameter. 

Program "astrtchr" uses dynamic memory allocation (using subroutine STACKA)
to avoid imposing restrictions on the image size.
TAE COMMAND LINE FORMAT
      The following command line formats show the major allowable forms:
      "astrtchr" INP=a OUT=b optional parameters
      "astrtchr" a b optional parameters

       Here 'a' represents the input image file name, and
       'b' represents the output image file name.
EXAMPLE

      "astrtchr" INP=A OUT=B  PERCENT=2 EXCL=(1000 1.0E10)

      In this example the output file B is a byte data image derived
      from the input image A.  The data format of A is obtained from the
      VICAR label for A.  The image is stretched to the default limits of 
      0 to 255. The linear stretch is defined to produce 1 percent saturation
      at each end of the output DN range.  The EXCL parameter effectively
      excludes input DNs greater than or equal to 1000 in the determination
      of the linear function used for stretching.  If the STREXCL keyword
      is specified, then the values supplied in the EXCL parameter are
      also excluded from the actual stretch operation, and are instead set
      to the REPLACE value.

RESTRICTIONS

1. The input image must be floating point (REAL*4) or fullword
   integer (INTEGER*4) data.
2. The output image must be byte or halfword data.

 OPERATION:

"astrtchr" is called an automatic linear stretch program because the user
does not have to specify the range of DNs in the input image to use in
defining the linear function used for the stretch.  Program "astrtchr" follows
a two step process.  The first step determines the linear function (stretch)
to use based on the contents of the input image file and options specified
by the user.  The second step applies the linear function to the DNs of
the input image and writes the result to the output file.  The net effect
is that the image is stretched to the specified limits without requiring
the user to know the range of DNs in the input image.

The way in which the linear function is determined depends on several
parameters. The AREA parameter specifies the portion of the input image
to examine in determining (perhaps approximately) the range of input DNs
for the linear function.  The range is determined as follows.  From the
portion of the image determined by the AREA parameter, the program selects
N evenly spaced pixels, where N is the value of the SORT parameter.  The
DNs for these pixels are examined and any DNs excluded by the EXCL parameter
are removed from the list of sample DNs.  This list is then sorted to produce
a sort of histogram.  The PERCENT parameter ( or the LPERCENT and HPERCENT
parameters) are then applied to the sorted list to determine the range of
DNs to use for the linear function.  If the PERCENT parameter is 0 or is
defaulted, then the minimum and maximum DNs in the list are used as the range.
Otherwise, the range is obtained by skipping the specified percentage of
DNs at the ends of the sorted list.

For example, suppose the AREA parameter specified a full 1000 by 1000 image,
the SORT parameter was 10000, no EXCL parameter was entered, and PERCENT=2
was specified.  The program would sample DNs at 10000 pixels spaced 10 lines
and 10 pixels apart.  The program would then select the 101st and 9900th DNs
in the sorted list as the range of DNs for the linear function.

Once the range of input DNs is determined, the linear function that maps
the range to the stretch limits (specified through the LIMITS parameter)
can be determined algebraicly.  This function is then applied to the input
DNs in the region specified by the SIZE parameter to produce the output
image.  Since the range of input DNs used to determine the linear function
is not necessarily the minimum and maximum DNs in the input image, output
DNs outside of the range of the stretch limits are possible.   (See the
NOCLIP parameter.)  The output data format may restrict the output DN values,
however.  For byte data output files, output DN values less than 0 are changed
to 0 and output DN values greater than 255 are set to 255. For halfword data
output files, output DN values less than -32768 are changed to -32768 and
output DN values greater than 32767 are set to 32767. 

"astrtchr" writes a history label for the output file to show what linear
function (stretch) was used to produce the output file. VICAR keywords
STRETCH_MINIMUM and STRETCH_MAXIMUM correspond to the limits of the 
input data and the output DN values to which they map. For example,
if input image DN values ranged from -1,204 to 32,431 in halfword format,
and the output limits were specified as (0,255), then the values of 
STRETCH_MINIMUM would be (-1204,0) and the values of STRETCH_MAXIMUM would
be (32431,255). These keywords are also PDS Data Dictionary keywords and 
their VICAR/PDS definitions are as follows:

STRETCH_MINIMUM
The stretch_minimum element provides a sequence of values, the first value 
representing the lowest sample value in an input image to be mapped to the
lower output limit and the second value representing the lowest output
sample value in the output image (first value in the LIMITS parameter.) 
Sample values between stretch_minimum and stretch_maximum are interpolated 
over the range of DNs as specified by other parameters of "astrtchr".

STRETCH_MAXIMUM
The stretch_maximum element provides a sequence of values, the first value 
representing the highest sample value in an input image to be mapped to the
upper output limit and the second value representing the highest output
sample value in the output image (second value in the LIMITS parameter.) 
Sample values between stretch_minimum and stretch_maximum are interpolated 
over the range of DNs as specified by other parameters of "astrtchr".

 WRITTEN BY:             Steve Pohorsky              11 Jan 1984
 COGNIZANT PROGRAMMER:   Steve Pohorsky              11 Jan 1984

 MIPS TRACEABILITY:	 MIPS FRD D-4419 Rev. C, Req. 4.1.2.3 <205>

 REVISION:               6                           13 Apr 1987

 January 17, 1994	JFM	Added to VICAR history label the PDS standard
				keywords STRETCH_MINIMUM and STRETCH_MAXIMUM
				as an alternate way of expressing input and
				output stretch limits. (FR 82901 for GLL NIMS)
 April 4, 1994          CRI     Ported to UNIX 

PARAMETERS: