User's Guide

CONSTRETCH

Local range modification (LRM) contrast stretch.

Function:

Performs a local range modification (LRM) contrast stretch.

Parameters:

IN
Input image. The input image may be BYTE, INTEGER*2, INTEGER*4, or REAL*4 data. Window and/or band options may be specified.

OUT
Output image. The output image is a single or multi-band file. The output image size is the same as the input image window input window.

NUMCELLS(10,10)
Number of cell in image x and y directions. The input image(s) are divided into a grid of nx by ny cells.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 
MAXVAL(255.0)
Maximum value. The upper limit of input pixel value range.

MINVAL(0.0)
Minimum value. The lower limit of input pixel value range.

BORDERS(ON)
Flag denoting whether to contrast stretch image borders. If ON (default), the image border cells will be contrast stretched such that the border pixels may be modified. If OFF, the border pixels will not be modified. This is useful for cases in which the stretched image is to be merged back into a larger image from which it was extracted.

THRSHOLD(0.0)
A real number representing the mininum contrast range considered for individual cells. Any cell with a contrast range below the threshold will be left unchanged. The threshold value is used to control whether image regions with very little contrast are to be stretched. Stretching regions with effectively no variation will give a noisy appearance to the resulting image.

MASKVAL(--)
Mask value(s). The pixel value or range of values that are used to designate masked areas or areas of bad data. Pixel values with this value are not used in the calculations.

Examples:

LAS> constretch in=dc out=stretch numcells=(10,10) odtype=i*2 borders=on thrshold=0.
The output is a I*2 image whose pixel values are contrast stretched based on the local min and max pixel values. The local min and max values are those within each cell, where where the input image is divided into a 10x10 grid of cells. The image window borders will be contrast stretched. Thresholding of individual cell contrast ranges is effectively turned off.
LAS> constretch in=orig out=new numcells=(15,20) borders=off thrshold=20. maskval=(220-255)
The input image ORIG is broken into a grid of 15 rows by 20 columns. Each cell is contrast stretched over the range of the input data type. Cells with an intensity range of less than 20 are left unchanged. Pixel values between 220 and 255 are left unchanged. The output image border pixels are unchanged from those of the input image.

Description/Algorithm:

Get the user-specified parameters and TAE global variables.
Open input image(s). 
for each input image do
   for each input band do
      Get the cell min and max values for all cells.
   end do
end do
Compute the node min and max values.
for each input image do
   for each input band do
      Compute the new pixel values based on linear interpolation
        between the four corner node min and max values.  The absolute
        min and max values are constrained by the user input MINVAL,
        MAXVAL values.
   end do
end do
Update the output image DDR, min/max values, and history.

Nonfatal Error Message:

[constretch-warn] Nonfatal error encountered.
The image data is probably valid and therefore saved. The message that is displayed immediately preceding this message is the specific error that was encountered. Processing continues.

Fatal Error Messages:

[constretch-alloc] Error allocating dynamic memory
A problem in allocating the dynamic memory required for contrast stretching was encountered.
[constretch-diftyp] Input images are not of same data type
The output image's data type was to be the same as the input image, but the input images are not of the same data type. The user can either ensure all input images have the same data type or specify ODTYPE, the data type of the output image.
[constretch-dtype] Invalid data type
The data type is invalid.
[constretch-fatal] Fatal error encountered
A fatal error was encountered during processing. The output image is not deleted, and processing is terminated. The error message that is displayed immediately preceding this message is the specific error that was encountered.
[constretch-kerbnd] Invalid cell size
The cell size is out of range. Check the input cell size.
[constretch-large] Invalid number of cells -- Cannot have more cells than samples
The image cannot be broken into cells smaller than a single sample. Check the NUMCELL entries.
[constretch-mask] Error in mask value range
An error has occurred while reading the mask values. Ensure that the range mask values are in ascending order.
[constretch-maxram] Invalid maximum RAM specified
The amount of maximum RAM is invalid. Check the header file containing the MAXRAM definition.
[constretch-minmax] MINVAL outside range for data type [constretch-minmax] MAXVAL outside range for data type
The input MINVAL (MAXVAL) value is below (above) the limit for the input image data type.
[constretch-minmax] MAXVAL less than MINVAL
The input MAXVAL is smaller than the input MINVAL.
[constretch-small] Invalid number of cells -- Must be greater than 0
The image must have at least one cell defined. Check the NUMCELL entries.
[constretch-smallb] Buffer too small for full cell
The specified amount of RAM available is too small to load a full cell into memory. Reduce the cell size, or increase the value of MAXRAM and recompile.
[constretch-window] Invalid window specified
The specified window to constretch within the image is invalid.
[constretch-windsiz] Input images do not have the same window size
Define the window dimensions such that they are of equal size.