User's Guide

SCATTER

Create a scatter plot of the data in two bands of an input image

Function:

Creates a scatter plot of the data using two bands of an input image or two input images. The data specified in the first band is used as the Y variable (axis), and the data in the second band is used as the X variable (axis). The specified characters are output on the plot if there is an occurrence of the (x,y) values for the data.

Parameters:

IN
Input image. Specifies which two of the input image bands are to be used for creating the scatter plot. The values in the first band will be used for the Y variable (axis), and the values in the second band will be used for the X variable (axis). The input data type may be BYTE, INTEGER*2, INTEGER*4, or REAL*4. The input images must be of the same data type and the same size. Window and/or band options may be specified. If one multiband image is specified, only the first two bands are used. If two multiband images are specified, only the first two bands of the first image are used.

INFILE(--)
Input file. An ASCII file containing three columns of data: a set of characters, the beginning of the range, and the end of the range for each character of the character set. When a file is specified, the values in PLOTCHR, MINVAL, and MAXVAL are ignored and the values in the file are used. The values in the file must be placed in three columns, one for each of the described data sets (PLOTCHR, MINVAL, MAXVAL). Any data after the third column will be ignored. Up to 94 rows of data may be specified. If file extension is not specified, the program assumes extension ".dat". The user can override this default by specifying "filename;extension".

PRINT(LP)
Output destination. Specifies the destination for the output scatter plot. If TERM or Filename is specified, it is assumed that 132 columns will be used for display. When the scatter diagram is written to the line printer, the 114 x 114 array requires two pages.
  = TERM:  Terminal.  Displays the scatter plot on
           the user's terminal.

  = LP:    Line printer.

  = filename:  User-specified file name.
NBINS(16)
Number of bins. Specifies the number of character bins. A minimum of one and a maximum of 94 bins may be specified. If MINVAL and MAXVAL values are specified, NBINS will be defaulted to equal the total number of MINVAL or MAXVAL values.

SCALOPT(SAME)
Scaling option. The X and Y axes will be scaled based on the minimum and maximum of the input bands.
  = IND:   Independent scaling.  Each of the X and Y
           axes will be scaled independently based on
           the minimum and maximum of each of the
           input bands.
  = SAME:  Same scaling.  Both axes are scaled the
           same based on the largest of the X and Y
           maximum values and the smallest of the X
           and Y minimum values.  If RANGE1 or 
           RANGE2 is specified, this option is 
           ignored.
RANGE1(-- )
Data range limits for the first image (Y axis). Specifies the minimum and maximum values of data to be used for output. If values are specified, SCALOPT will be ignored.

RANGE2(-- )
Data range limits for the second image (X axis). Specifies the minimum and maximum values of data to be used for output. If values are specified, SCALOPT will be ignored.

MINVAL(--)
Minimum value. Specifies the minimum value of the bin range. A maximum of ninety-four values may be given. MINVAL must contain the same number of values as specified in MAXVAL. If the count of MINVAL or MAXVAL does not equal NBINS, NBINS will be set to the count of MINVAL or MAXVAL values.

MAXVAL(--)
Maximum value. Specifies the maximum value of the bin range. A maximum of ninety-four values may be given. MAXVAL must contain the same number of values as specified in MINVAL. If the count of MINVAL or MAXVAL does not equal NBINS, NBINS will be set to the count of MINVAL or MAXVAL values.

PLOTCHR(--)
Plotting characters. Allows the user to specify at least one and up to ninety-four different characters to use in creating the scatter plot. PLOTCHR can be used to illustrate multiple occurrences of common pixel-pair values. If allowed to default the value of PLOTCHR is: " ", ".", ",", "?", "<", ">", "%", "/", ";", ":", "'", "\\", "|", "$", "!", "@", "#", "^", "&", "*", "(", ")", "-", "_", "=", "+", "`", "~", "{", "}", "[", "]", "a", "s", "d", "f", "g", "h", "j", "k", "l", "q", "w", "e", "r", "t", "o", "p", "z", "x", "c", "v", "b", "n", "m", "A", "S", "D", "F", "G", "H", "J", "K", "L", "Q", "W", "E", "R", "T", "Y", "U", "I", "O", "P", "Z", "X", "C", "V", "B", "N", "M", "1", "2", "3", "4", "5", "6", "7","8", "9", "0"

Examples:

LAS> scatter in=test.img
A scatter diagram is created using the first two bands from the input image TEST.IMG. Each axis is scaled in the same way. If there are more than two bands in the input image, only the first two bands are used. The 16 default PLOTCHR are used. Output of the scatter plot is sent to the line printer.
LAS> scatter in="test.img(10,10,10,10:2,3)" print=term nbins=2 scalopt=ind minval=(5,20) maxval=(19,35) plotchr="0#"
A scatter diagram is created using bands 2 and 3 of the input image TEST.IMG. The user has specified that a "0" and a "#" are to be the only two characters to be plotted for the scatter histogram with the specified ranges. Each axis is scaled independently. The output of the scatter plot is sent to the user's terminal.
LAS> scatter in=test.img infile=test.dat print=test scalopt=ind range1=(100,150)
A scatter diagram is created using the first two bands from the input image TEST.IMG. The userspecified PLOTCHR, MINVAL, and MAXVAL values from INFILE are used to create the scatter diagram. Only the pixel values between 100 and 150 for the first image (Y axis) are plotted while all values for the second image (X axis) are plotted. Each axis is scaled independently. The output is sent to the file TEST.PRT in the user's directory.

Description/Algorithm:

The program obtains the minimum and maximum values for each band needed to keep the plotted output within the 114 columns and lines (two adjacent printed pages). If RANGE1 and RANGE2 are specified, they are verified and used as the minimum and maximum values for each band. Points defined by the X and Y intersection are output on the scatter diagram. The first position of the PLOTCHR array should typically be left as a blank since this position is used when there are no matches. The plotted character is dependent upon the position within the PLOTCHR array.
The frequency of the plotted character depends on which of the parameters are specified. If MINVAL and MAXVAL values are not specified, the frequency of the characters depends on the number of characters specified by NBINS (1 through 94) and the maximum number of matches found within the two bands. If MINVAL and MAXVAL values are specified, the frequency is the difference between the MINVAL and MAXVAL values. NBINS is ignored if MINVAL and MAXVAL are set. If INFILE is used, the frequency of the character is also the range between MINVAL and MAXVAL. Up to 94 rows of data may be specified in INFILE.
The X and Y axes are scaled based on the user's response to the SCALOPT. If values are specified in RANGE1 or RANGE2, this parameter is ignored. The output is based on the user's response to PRINT.

Nonfatal Error Message:

[scatter-tobnd] More than two input bands specified Only the first two bands will be used
More than two input bands were specified. Rather than abort, SCATTER will continue using only the first two bands.

Fatal Error Messages:

[scatter-dtype] Input images with different data types are not allowed
Input images must be of the same data type. Rerun the program with the appropriate images.
[scatter-equal] Number of MINVAL and MAXVAL values must be equal
The MINVAL and MAXVAL parameters work as pairs and must contain the same number of values.
[scatter-format] File format error
Three values--PLOTCHR, MINVAL, MAXVAL--must be entered on each line in INFILE.
[scatter-hist] Maximum size for histogram has been exceeded
The histogram size is limited to be 114 x 114. Use windows to break the image to be histogrammed into smaller parts.
[scatter-lim] Specified data range limits not within data boundaries
RANGE1 or RANGE2 are not within the minimum or maximum pixel values for the image(s) specified by IN.
[scatter-nbnd] Input image must contain two bands
The scatter plot is two-dimensional so it requires two bands. Only one was specified. Change the input to specify two bands and rerun the program.
[scatter-prtopen] Error occurred while retrieving the print file name
The print file name could not be retrieved successfully. The most likely reason for this error is that a print file of that name already exist. Rerun the program with a new print file name.
[scatter-range] Too many chars and range values
Only 94 values for the PLOTCHR, MINVAL, and MAXVAL are allowed in INFILE.
[scatter-window] Image windows differ in size
When windows are specified with the input image, care must be taken that they are of the same size. Rerun the program with the correct window specifications.

User Notes:

The first position of the PLOTCHR array should typically be left as a blank since this position is used when there are no matches.
The default 16 character set is: " ", ".", ",", "?", "<", ">", "%", "/", ";", ":", "'", "\", "|", "$", "!", "@".

The MIN COUNT values listed in the last page of the output represent the minimum number of matches that must be found before the corresponding SYMBOL value will be printed. The following example illustrates the interpretation:


      BIN #     :      1      2      3      4      5
      SYMBOL    :             .      ,      ?      <
      MIN COUNT :      0      1    394    786   1179

      when      1  <=  #matches  <   393  print a '.'
              394  <=  #matches  <   785  print a ','
              786  <=  #matches  <  1178  print a '?'