Level 2 Help for ASTRTCHR

Four integer values are entered for SIZE. These determine the position
and size of the portion (of the image) that will be stretched and then written
to the output file.  The default is to stretch the full input image.  The first
two values for the SIZE parameter are the starting line and starting pixel
number within the line.  The last two values for the SIZE parameter are the
number of lines and number of pixels per line.  The second and fourth values 
are specified in terms of fullword pixels instead of in terms of bytes.
Although the SIZE and AREA values are often the same in practice, they
are seen as mutually independent by the program.

Four integer values are entered for AREA.  These determine the position and
size of the portion (of the image) that will be used for sampling pixels to
determine the range of input DNs. The default is to use the full input image. 
The first two values for the AREA parameter are the starting line and starting
pixel number within the line.  The last two values for the AREA parameter are
the number of lines and number of pixels per line.  The AREA parameter differs
from the standard VICAR SIZE parameter in that the second and fourth values are
specified in terms of fullword pixels instead of in terms of bytes. Although
the SIZE and AREA values are often the same in practice, they are seen as
mutually independent by the program.  Thus the AREA parameter does not affect
the size of the output file. 

If INFMT is not specified, the format is obtained from the input image label. 
If the format is not in the label, real data is assumed.   In TAE command 
mode the user should enter 'FULL or 'REAL as stand-alone keywords.

The default format is byte data.  If HALF is specified, the output pixels
may have any valid halfword value.  In TAE command mode the user should 
enter 'BYTE or 'HALF as stand-alone keywords.

This parameter is entered in the form  LIMITS=(l,u) where l is the lower
stretch limit and u is the upper stretch limit.  The linear function for the
stretch is determined so that lower and upper percent values from the
sorted list of sampled pixels are mapped respectively to the lower and
upper stretch limits.  For byte output data, the default limits are 0 and 255.
For halfword output data, the default limits are 0 and 10000.  l and u must 
be valid values for the output data format.  For either data format, output
DNs are allowed outside of the range from l to u as long as they are valid for
the output data type and if NOCLIP is specified.  The image may be 'inverted' by
specifying l greater than u and specifying NOCLIP. 

The NOCLIP parameter causes the range of output DNs to be limited by the 
output data format instead of by the LIMITS parameter.

The PERCENT parameter (or the LPERCENT and HPERCENT parameters) determines
which input DN gets mapped to the lower stretch limit and which input DN gets
mapped to the upper stretch limit.  Each of these parameters is refers 
to a percentage of the elements in the sorted list of sampled pixels.
Each of these parameters is a real number in the range from 0.0 to 100.0.  
PERCENT=p is equivalent to LPERCENT=p/2 and HPERCENT=p/2.  If LPERCENT=l,
then the input DN which gets mapped to the lower stretch limit is the element
in the sorted list l percent from the beginning of the list.  If HPERCENT=h,
then the input DN which gets mapped to the upper stretch limit is the element
in the sorted list h percent from the end of the list.  The default for these
parameters is 0 percent.  If the percent parameters are 0 or are
defaulted, then the minimum and maximum DNs in the list are used.

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.

(See under PERCENT.)

(See under PERCENT.)

The SORT parameter tells the program how much space to allocate for the list
of sampled pixels.  The number of pixels sampled is the minimum of the SORT
value and the number of pixels in the AREA area.  The default for SORT is 
10000.

The default for SINC is 1.  SINC is of use in generating pictures of GALGEN
calibration files. If SINC=N, then for a given line in the SIZE area the
program processes the starting pixel and every Nth pixel thereafter. Thus the
number of pixels per output line is smaller than the number of pixels per line
in the SIZE area by a factor of N.  Also, if SINC=N, the sampling is
restricted in a given line (in the AREA area) to the starting pixel and every 
Nth pixel thereafter.  This restriction is important for GALGEN files to assure
that the sorted list contains only pertinent DNs. 

The default for LINC is 1.  If LINC=N, then the program processes the starting
line and every Nth line thereafter in the SIZE area.  Thus the number of 
output lines is smaller than the number of lines in the SIZE area by a 
factor of N.

One or more pairs of numbers can be entered for the EXCL parameter.  Each
pair specifies a range of input DNs from the first value in the pair to the
second value in the pair.  Any DNs of sampled pixels that lie in one of the
EXCL ranges are removed from the list of sample pixels.  The values can be 
entered as real numbers or integers to match the input file data format.

Specifying this keyword causes DN values that are in the range(s) specified
by the EXCL parameter to be excluded from the stretch operation itself, not
just from the computation of the stretch parameters.  These DNs are set to
the value specified by the REPLACE parameter.

This parameter is only used if keyword STREXCL is specified, and it supplies
the replacement value to be used for DNs excluded from the stretch operation.

This can yield a lot of numbers.  The default is to not print the numbers.
In TAE command mode the user should enter 'PRINT as a stand-alone keyword.