User's Guide

IPMATH

Performs mathematical and statistical functions on an image(s).

Function:

IPMATH allows the user to perform the following mathematical operations:

  = MINMAX:  Minimum and Maximum at the pixel location
  = MEAN:    Mean and Standard Deviation
  = BANDS:   Number of bands used to perform calculations
  = MEDIAN:  Median and Mean Absolute Deviation about the Mean (MADAM)

Parameters:

IN
Input images(s). 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 performing the specified calculations on all the input bands. The output data type is determined by ODTYPE. The number of output bands is based on the options specified in PROCOPT.

PROCOPT(MEAN,MINMAX,BANDS)
Processing options. The specified mathematical options will be performed on the input image bands. The output image will contain bands in the specified order.
  = MEAN:    The Mean and Standard Deviation
  = MINMAX:  The Minimum and Maximum 
  = BANDS:   The number of bands used in calculations
  = MEDIAN:  The Median and Mean Absolute Deviation About the 
             Median (MADAM) 
ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input 
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)
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.

PIXVAL(0)
Pixel value. The pixel value that is to be inserted into the output location when all pixel values are masked out for one location.

Examples:

LAS> ipmath 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 windows of the input images LANDSAT.DATE1 and LANDSAT.DATE2 are used to calculate the default options: mean, standard deviation, minimum, maximum, and number of bands. The resultant image created is LANDSAT.MDATE. All of the input bands are used to produce the bands in the output image. If any pixel value is equal to the mask value of 25, the value is not used in the calculations.
LAS> ipmath procopt=mean,median,minmax,bands in="wash.dcl + wash.dc2" out=wash.out maskval="0.0-25.0" pixval=0
The pixel values in the input images WASH.DC1 and WASH.DC2 are used to calculate the output image WASH.OUT. WASH.OUT will consist of seven bands with pixel values representing: mean, standard deviation, median, MADAM, minimum, maximum, and number of bands. If the pixel values are between the mask value range of 0 through 25, they are not used in the calculations. If all values at a pixel location are masked values, the PIXVAL, 0, will be used at that location in the mean, standard deviation, median, and MADAM bands. The output type will be the same as the input type.
LAS> ipmath procopt=mean in="spot.one(1,1,30,30) spot.two(20,20,30,30)" out=spot.mean odtype=r*4
A 30 x 30 window of both input images SPOT.ONE and SPOT.TWO are calculated together to produce two bands for the output image SPOT.MEAN. The first band is the mean of the images, and the second band of the image is the standard deviation of the images SPOT.ONE and SPOT.TWO. The output image SPOT.MEAN has the data type of REAL*4.

Description/Algorithm:

IPMATH has four options to perform various mathematical computations on an image. The MEAN option will output a mean band followed by a standard deviation band. The MEDIAN option will output a median band followed by the mean absolute deviation. The MINMAX option will output the minimum band followed by the maximum band. The BANDS option outputs the number of bands used in the calculation of each pixel location.
If MASKVAL, each pixel is checked against the masked value(s). Any pixel value which is a masked value will not be used in the computations. If all values at one location are a mask value, then PIXVAL is assigned to the output image. The appropriate algorithm is performed to generate an image on a pixel-by-pixel basis for all bands in the input image(s).
IPMATH can create up to seven bands with the following algorithms:

MEAN:
  The mean band has the following algorithm:

       OUT(i,j) = (IN[band1(i,j)] + IN[band2(i,j)] + ...)
		   ---------------------------------------
			     Number of bands
 
  The standard deviation band has the following algorithm:

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

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

MEDIAN:
  The median band has the following algorithm:

       ARRAY = SORT(IN[band1(i,j)],IN[band2(i,j)],...)

    If the total number of bands, n, is odd:
       OUT(i,j) = ARRAY(n/2)

    If n is even:
       OUT(i,j) = ARRAY(n/2) + ARRAY((n/2) - 1)
                  -----------------------------
                               2
       
  The mean absolute deviation about the median (MADAM) is defined by:

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

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

MINMAX:
  The minimum band has the following algorithm:

       ARRAY = SORT(IN[band1(i,j)],IN[band2(i,j)],...)

       OUT(i,j) = ARRAY(0)

  The maximum band has the following algorithm:

       OUT(i,j) = ARRAY(n-1)

  where n-1 is the last value in the array

BANDS:
  The bands band has the following algorithm:

       OUT(i,j) = Number of bands

where (i,j) is a pixel location.

Nonfatal Error Messages:

[ipmath-bands] BANDS output value exceeds 255
If there are 256 input bands used in calculations and BANDS is specified, the number exceeds the pixel maximum of 255 for BYTE data. Respecify ODTYPE and re-run.
[ipmath-warn] Nonfatal error encountered
A nonfatal error was encountered during processing. Processing continues.

Fatal Error Messages:

[ipmath-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. Respecify the windows or re-run.
[ipmath-type] Input images have different data types
This module will not process images which differ in their data types. Run COPY or MAP to convert the images to a single data type.
[ipmath-mask] Error in mask value range encountered
The mask value(s) are not specified in the correct order. Rerun specifying the mask value range in ascending order.
[ipmath-fatal] Fatal error encountered
A fatal error was encountered during processing. Processing is terminated. The error message that is displayed immediately preceding this message is the specific error that was encountered.
[ipmath-alloc] Error allocating dynamic memory
An error occurred while allocating dynamic memory for processing. Re-run and if the error persists, contact the system administrator.

User Notes:

The mean and standard deviation, median and mean absolute deviation, minimum and maximum, are written as pairs in the output image in the order specified. For example, specifying PROCOPT=(MEAN,MEDIAN) would produce the following four-band output image:
```
BAND 1  Mean of the input images
BAND 2  Standard deviation of the input images
BAND 3  Median of the input images
BAND 4  MADAM of the input images
```
MATH2 is a related module.