User's Guide

NORMD

Calculate a normalized difference image

Function:

Calculates a normalized difference (ND) image from two bands of image data. The bands may be two bands of a single image or bands of two separate images. In the first case, the resulting ND image is a single-band image. In the second case, the resulting ND image can be a multi-band image. The corresponding bands from both input images are used to calculate a ND band in the output image.

Parameters:

IN
Input image. IN must be two images or a single image containing a minimum of two bands. When IN contains two images, the images must have the same number of bands and the normalized difference calculations are performed on the corresponding bands of each image. When IN is a single image with multiple bands, the normalized difference calculations are performed on the first two bands.

OUT
Output image. This image contains the resulting normalized difference image computed from the input image(s).

ODTYPE(SAME)
Output data type. The data type of the output image. By default the output image will be the same data type as the input.

  = SAME:  Same as input 
  = BYTE:  BYTE
  = I*2:   INTEGER*2
  = I*4:   INTEGER*4
  = R*4:   REAL*4

OFFSET(1.0)
Offset value. An offset value added to the normalized difference calculation before scaling. OFFSET should be used in conjunction with SCALFACT to maintain as much precision as possible in the output data. The default for OFFSET is based on BYTE output. See User Note 1.

SCALFACT(100.0)
Scale factor. The scaling factor is a positive real number used to scale the calculated normalized difference values into the ODTYPE data range. SCALFACT can be used in conjunction with OFFSET to maintain as much precision as possible in the output data. The default for SCALFACT is based on BYTE output. See User Note 1.

ROUNDOPT(ROUND)
Round option. Option to round or truncate the normalized difference calculation before being written to the output image. ROUNDOPT is ignored for REAL*4 output.

  = ROUND:  Round the data.
  = TRUNC:  Truncate the data.

NORMLIM(--)
Normalized limit. Any normalized difference values greater than the specified limit are set to zero. These values are considered invalid by the user for the type of data used. The specified value must take into account the values specified for OFFSET and SCALFACT. The default is (1 + OFFSET) * SCALFACT.

SCALOPT(NONE)
Scale option. Scaling option used to create IN. This indicates if the input image(s) have been scaled and require the pixel values to be unscaled prior to calculating the normalized difference values. The default indicates the input image(s) are not scaled.

  = GLOBAL: Global scaling
  = NONE:   No scaling
  = US:     US scaling

Examples:

  1. LAS> normd in="img1(:2,3)+img2(:1,4)" out=out odtype=byte scalfact=50

    The ND image is calculated for two bands from IMG1 and IMG2. An offset of 1.0 and a scale factor of 50 are applied to the ND value, and the result is rounded. OUT is a two-band, BYTE image that is the same size as IMG1 and IMG2. The first band of OUT is the ND of band two from IMG1 and band one from IMG2. The second band of OUT is the ND of band three from IMG1 and band four from IMG2.

  2. LAS> normd in="uimg(:1,3)" out=out scalfact=127.0 offset=11.0 roundopt=trunc normlim=1500

    The ND image is calculated using the first and third bands of the multi-band image UIMG. An offset of 11 and a scale factor of 127 are applied to the ND values and are truncated in the output image. ND values greater than 1500 are set to zero in the output image. The output image will be of the same data type and have the same size as the input image.

  3. LAS> normd in="in1(100,200,256,256:3)+in2(:2)" out=out odtype=r*4 offset=0.0 scalfact=1000.0

    The ND image is calculated using band three of the 256 line by 256 sample window, starting at line 100 and sample 200 from IN1 and band two from image IN2. IN2 must be a 256 line by 256 sample image. The result is then scaled by 1000. OUT is a single-band, REAL*4 image that is 256 lines by 256 samples.

  4. LAS> normd in="chan1+chan2" out=ndvi odtype=byte scalopt=global

    The ND image is calculated for images CHAN1 and CHAN2. The output image will be named NDVI and will be a BYTE image. Since the user has indicated the input image has been stored using the GLOBAL scaling scheme, both CHAN1 and CHAN2 have mask values of zero through nine. These values have been reserved for special meaning and should not have a ND value calculated but should be copied directly to the output image. To reserve these pixel values, the input images have had an offset of ten added to each pixel value. This offset should be subtracted from each input pixel prior to calculating the ND values. After applying both OFFSET and SCALFACT to the calculated ND value, it is checked against the default NORMLIM of 200, and finally, ten will be added back to the output pixel value to retain the mask values of zero through nine.

Description/Algorithm:

When two multi-band images are specified, the ND values are calculated for the corresponding bands from each input image. Both input images are required to be the same size and have the same number of bands. When a single image (containing at least two bands) is specified, the ND values will be calculated for the first two bands of the image.

The ND calculation generates values in the range of -1.0 to +1.0. OFFSET and SCALFACT should be used in conjunction to scale these values into the correct range for ODTYPE. ROUNDOPT is used to determine if the above calculation is rounded or truncated before being written to the output image.

In some scaling schemes, an offset value is added to every pixel to reserve the first N pixel values for data masks. These values will indicate areas such as no data, water, interrupted projection areas, etc. and should not have a ND value calculated for them. These pixel values should be copied directly to the output image.

The following algorithm is used to compute the ND for each input pixel.

    - If the pixel in either band is a mask value for the
      specified scaling option, the pixel will be copied
      directly to the output image.  The remaining steps are
      skipped.  See User Note 2 for additional details.

    - The appropriate value is subtracted from both pixels to
      remove the input mask values.

    - If both pixels are zero, the ND value is set to (-1 +
      OFFSET) * SCALFACT and the program skips to the last step.

    - The ND value is computed and scaled using OFFSET and
      SCALFACT.  The equation used is:
      
      (((BAND2 - BAND1) / (BAND2 + BAND1)) + OFFSET) * SCALFACT

    - If the ND value is greater than NORMLIM, it is set to
      (-1 + OFFSET) * SCALFACT.

    - The appropriate value is added to the calculated ND value
      to reserve the necessary mask values in the output image.

Nonfatal Error Message:

  1. [normd-nonfatal] Nonfatal error encountered

    A nonfatal error was encountered during processing. The message that is displayed immediately preceding this message is the specific error encountered.

Fatal Error Messages:

  1. [normd-alloc] Error allocating dynamic memory

    An error occurred dynamically allocating memory, which was required for further processing. Contact the system administrator if the problem persists.

  2. [normd-bands] Images do not have same number of bands

    The images specified in IN do not contain the same number of bands. Use the band option to indicate the bands that are to be used, or re-specify IN with images that have the same number of bands.

  3. [normd-fatal] Fatal error encountered

    A fatal error was encountered during processing. The message that is displayed immediately preceding this message is the specific error encountered. Processing terminates.

  4. [normd-in] IN contains less than two bands

    IN must contain at least two bands. The normalized difference is calculated on the first two bands of IN. Re-specify IN and re-run the program.

  5. [normd-msk] Mask values do not agree

    When processing globally scaled images, NORMD expects all mask values to be equal in both input bands. A pixel was encountered that does not have the same mask values. Determine if this is an error in your processing flow. See User Note 2 for additional details.

  6. [normd-window] Images do not have same window size

    The images specified in IN are not the same size. Use the window option to specify a common window for the images.

User Notes:

  1. The normalized difference calculation generates values in the range of -1.0 to +1.0. OFFSET and SCALFACT should be used in conjunction to scale the normalized difference values into the ODTYPE range. The following equation is used to calculate the normalized difference and scale the output:

    
           (((BAND2 - BAND1) / (BAND2 + BAND1)) + OFFSET) * SCALFACT
    

  2. NORMD requires that mask values within globally scaled images must be equal in both input bands. If the mask values are not equal a fatal error will be issued. The one exception is that mask values of zero will take precedence over any other mask value or a data value (ie. a mask value of zero will be placed in the output image).

  3. The default value for NORMLIM is:

    
    	(1 + OFFSET) * SCALFACT
    

    This is the maximum value that can be computed using the specified values of OFFSET and SCALFACT. If SCALOPT=GLOBAL, NORMLIM is applied to the calculated ND value prior to adding the offset value of ten back to the output value.