User's Guide

MATH2

Performs mathematical functions on an image.

Function:

Allows the user to perform the following mathematical operations:

   ADD - Adds two or more bands or images together to 
         form a single output image.
   SUB - Subtracts a specified band from all bands in 
         an image.
   DIV - Divides all bands of an image by a specified 
         band.
   AVE - Generates an average and standard deviation 
         band from a series of images.

Parameters:

Subcommand -ADD:

Adds all images. The input bands or images are all added, pixel by pixel, to form an output image. The output image is the same size as the input image and contains a single band which is the result of summing the coincident pixels.

IN
Input images. Allowed data types are BYTE, INTEGER*2, INTEGER*4, and REAL*4. Window and/or band options may also be specified.

OUT
Output image. A single-band output image is created by adding all the images together.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input 
  = BYTE:  BYTE      (8-bit unsigned integer)
  = I*2:   INTEGER*2 (16-bit signed integer)
  = I*4:   INTEGER*4 (32-bit signed integer)
  = R*4:   REAL*4    (32-bit signed real)
MASKVAL(--)
Mask value(s). The pixel value or range of values that is used to designate masked areas or areas of bad data. Samples with this value are not used in the calculations.

PIXVAL(0)
Pixel value. The pixel value that is to be inserted into the output location whenever a mask value is encountered.

Subcommand -SUB:

Subtracts an image. The input image bands or images have the specified band subtracted, pixel by pixel, from them to form an output image. The output image is the same size as the input image and contains one less band than the input and is the result of subtracting the coincident pixels.

IN
Input images. Allowed data types are BYTE, INTEGER*2, INTEGER*4, and REAL*4. Window and/or band options may also be specified.

OUT
Output image. The output image is created by subtracting a specific image from the other images. The output contains one less band than the input since the band to be subtracted is not subtracted from itself.

BAND
Band number. The specified band is subtracted from all of the bands of the input image.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input 
  = BYTE:  BYTE      (8-bit unsigned integer)
  = I*2:   INTEGER*2 (16-bit signed integer)
  = I*4:   INTEGER*4 (32-bit signed integer)
  = R*4:   REAL*4    (32-bit signed real)
MASKVAL(--)
Mask value(s). The pixel value or range of values that is used to designate masked areas or areas of bad data. Samples with this value are not used in the calculations.

PIXVAL(0)
Pixel value. The pixel value that is to be inserted into the output location whenever a mask value is encountered.

Subcommand -DIV:

Divides an image. The input image bands or images have the specified band divided, pixel by pixel, from them to form an output image. The output image is the same size as the input image and contains one less band than the input and is the result of dividing the coincident pixels.

IN
Input images. Allowed data types are BYTE, INTEGER*2, INTEGER*4, and REAL*4. Window and/or band options may also be specified.

OUT
Output image. The output image is created by dividing a specific image from the other images. The output contains one less band than the input since the band to be divided is not divided by itself.

BAND
Band number. The specified band is divided into all of the bands of the input image.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input 
  = BYTE:  BYTE      (8-bit unsigned integer)
  = I*2:   INTEGER*2 (16-bit signed integer)
  = I*4:   INTEGER*4 (32-bit signed integer)
  = R*4:   REAL*4    (32-bit signed real)
MASKVAL(--)
Mask value(s). The pixel value or range of values that is used to designate masked areas or areas of bad data. Samples with this value are not used in the calculations.

PIXVAL(0, 0)
Pixel value. The first pixel value is to be inserted into the output location whenever a mask value is encountered. The second pixel value is to be inserted into the output location whenever division by zero is encountered.

Subcommand -AVE:

Averages all images. The input bands or images are averaged together creating an average and a standard deviation band in the user-specified output image.

IN
Input images. Allowed data types are BYTE, INTEGER*2, INTEGER*4, and REAL*4. Window and/or band options may also be specified.

OUT
Output image. A two-band output image is created by averaging all the images together. Band one is an average of each pixel of all the input bands while band two is the standard deviation of the pixels.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input 
  = BYTE:  BYTE      (8-bit unsigned integer)
  = I*2:   INTEGER*2 (16-bit signed integer)
  = I*4:   INTEGER*4 (32-bit signed integer)
  = R*4:   REAL*4    (32-bit signed real)
MASKVAL(--)
Mask value(s). The pixel value or range of values that is used to designate masked areas or areas of bad data. Samples with this value are not used in the calculations.

PIXVAL(0)
Pixel value. The pixel value that is to be inserted into the output location whenever a mask value is encountered.

Examples:

LAS> math2-add in="landsat.date1(1,1,30,30) landsat.date2(20,20,30,30)" out=landsat.mdate odtype=byte maskval=25.0
The pixel values in the window of the input image LANDSAT.DATE1 are added to the pixel values in the window of the input image LANDSAT.DATE2. The resultant image created is LANDSAT.MDATE. If LANDSAT.DATE1 and LANDSAT.DATE2 are multi-band images, all of the bands are added to produce a single-band output image. If any pixel value is equal to the mask value of 25, the default PIXVAL of zero is inserted in LANDSAT.MDATE. The size of the output image LANDSAT.MDATE is 30 x 30 with the data type being BYTE.
LAS> math2-sub in="madison.tm(1,1,30,30)" out=madison.sub band=2 odtype=i*2
The pixel values in the window of the input image MADISON.TM have band 2 subtracted from them, producing the output image MADISON.SUB. The output image MADISON.SUB contains one less band than image MADISON.TM, since the subtraction is not performed upon itself (i.e., band 2 is not subtracted from band 2). The size of the output image MADISON.SUB is 30 x 30 with a data type of INTEGER*2.
LAS> math2-div in="wash.dc(l,l,30,30)" out=wash.out band=3 odtype=byte maskval="0.0-25.0" pixval(1)=30.0
The pixel values in the window of the input image WASH.DC are divided by the pixel values in the third band of WASH.DC. This resultant image, WASH.OUT, contains one less band than image WASH.DC, since the division is not performed on itself. If the pixel values are between the mask value range of 0 through 25, PIXVAL(1) or 30 is inserted in WASH.OUT. If a pixel value of band three is zero, the default PIXVAL(2) of zero is inserted in WASH.OUT. The size of the output image WASH.OUT is 30 x 30 with a data type of BYTE.
LAS> math2-ave in="spot.one(1,1,30,30) spot.two(20,20,30,30)" out=spot.ave odtype=r*4
A 30 x 30 window of both input images SPOT.ONE and SPOT.TWO are averaged together to produce the first band of output image SPOT.AVE. The second band of image SPOT.AVE is the standard deviation of images SPOT.ONE and SPOT.TWO. The output image always contains two bands. The size of image SPOT.AVE is 30 x 30 with a data type of REAL*4.
LAS> math2-add in="us.in(:1-4)" out="us.out" maskval=(5.0-25.0 150.0-200.0) pixval=255.0
The pixel values in the first four bands of US.IN are added together producing the output image US.OUT. If the pixel value is within the range of 5 through 25 or the range of 150 through 200, the pixel value of 255 is inserted in the output image US.OUT. The data type of US.OUT is the same as that of US.IN by default of ODTYPE.

Description/Algorithm:

MATH2 has four options within it to perform various mathematical computations against an image. They each generate an image on a pixel-by-pixel basis for all bands in the input image. If masked values are specified, then each pixel is checked against the masked value(s) and the PIXVAL is assigned to the output image if the masked value exists. Otherwise, the appropriate algorithm is performed.
MATH2-ADD has the following algorithm:

       OUT(i,j) = IN[band1(i,j)] + IN[band2(i,j)] + ...


MATH2-SUB has the following algorithm:

       OUT(i,j) = IN[band1(i,j)] - IN[band(i,j)] 


MATH2-DIV has the following algorithm:

       If IN2 <> 0:
        OUT(i,j) = IN[band1(i,j)]/IN2[band(i,j)

       If IN2 = 0:
	OUT(i,j) = PIXVAL


MATH2-AVE creates two bands with the following algorithm:

  The average band has the following algorithm:

       OUT1(i,j) = (IN[band1(i,j)] + IN[band2(i,j)] + ...)
		   ---------------------------------------
			     Number of bands
 
  The second band is the standard deviation with the following:

       TEMP(i,j) = (IN[band1(i,j)] - mean) * IN[band1(i,j)] - mean)
                 + (IN[band2(i,j)] - mean) * IN[band2(i,j)] - mean)
		 + ...

       OUT2(i,j) = SQUARE ROOT(TEMP(i,j) / Number of bands)

where (i,j) is a pixel location.

Nonfatal Error Messages:

[math2-warn] Nonfatal error encountered
A nonfatal error was encountered during processing. The message that is displayed immediately preceding this message is the specific error that was encountered. Processing continues.

Fatal Error Messages:

[math2-window] Images do not have the same size window
The number of lines or samples for the specified images are different for the corresponding IN elements.
[math2-fatal] Fatal error encountered
A fatal error was encountered during processing. Processing is terminated. The message that is displayed immediately preceding this error message is the specific error that was encountered.
[math2-alloc] Error allocating dynamic memory
An error occurred while allocating dynamic memory for processing. Rerun the function. If the error reoccurs, notify the system manager.
[math2-mask] Error in mask value range encountered
The lower mask value is greater than the higher mask value. Rerun specifying the mask value range in ascending order.

User Notes:

When conversions from a larger data type (such as REAL*4) to a smaller data type (BYTE) are performed, check the output pixels for validity since the conversion is not done by rescaling the input data. See the COPY or MAP modules for better methods of converting between data types.
The module MATH is a related module.