User's Guide

ANGINTERP

Create AVHRR angle bands by interpolating from grids

Function:

Creates the satellite zenith, solar zenith, and the relative azimuth angles for a reprojected AVHRR LAS image. These bands are created using angle values from selected grid points stored in an angles grid. See User Note 1.

Parameters:

IN
Input image. The reprojected AVHRR LAS image that the angle bands are to be created for. Windowing is ignored.

OUT
Output image. OUT will contain the angle values specified in BANDS and will be in the same projection as IN.

ANGGRID(--)
Angles grid. Grid file containing the angle values for each grid point in IN. If NULL, the root file name of IN is used with an ;ANG extension. See User Note 1.

SCALOPT(GLOBAL)
Scale. Scaling option desired by the user. See User Note 2.

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

BANDS(1,2,3)
Bands to be created. The bands may be placed in the output image in any order.

  = 1:  Satellite zenith angle
  = 2:  Solar zenith angle
  = 3:  Relative azimuth (absolute difference of the
        satellite and solar azimuth angles)

ODTYPE(SAME)
Output data type. The data type of the output image. The output values will be scaled to fit within the data type range.

  = SAME:  Same as input
  = BYTE:  BYTE      (8-bit  unsigned integer)
  = I*2:   INTEGER*2 (16-bit unsigned integer)
  = I*4:   INTEGER*4 (32-bit unsigned integer)
  = R*4:   REAL*4    (32-bit signed real)

Examples:

  1. LAS> anginterp in=test1 out=test2

    TEST1;ANG is used to create angle bands for TEST1;IMG. TEST2;IMG will contain bands of satellite zenith, solar zenith, and relative azimuth angles in the same data type as TEST1;IMG. The angles will be scaled using the GLOBAL scaling method.

  2. LAS> anginterp in=test1 out=test2 anggrid=angles scalopt=us bands=(3,2) odtype=byte

    The angle grid ANGLES;ANG will be checked to ensure it matches the projection and size of TEST1;IMG. The output image TEST2;IMG will be created as a BYTE image with relative azimuth angles as band one and solar zenith angles as band two. The angles will be scaled using the US scaling method.

Description/Algorithm:

The angle grid is checked to ensure it matches the input image (size, projection parameters, etc.). The requested angle values are then computed for each pixel by interpolating the values at the four surrounding grid points. Each of the angle values are scaled according to the selected scaling option and the output data type. See User Note 2.

Nonfatal Error Messages:

  1. [anginterp-trunc] <xxxxx> angles have been truncated

    Some of the specified angle values have been truncated to their minimum or maximum value. To avoid angle value truncation use another scaling option or an output data type with a higher precision.

  2. [anginterp-warn] Nonfatal error encountered

    A nonfatal error was encountered from a support function. All angle values are unaffected.

Fatal Error Messages:

  1. [anginterp-alloc] Error allocating memory

    ANGINTERP was unable to dynamically allocate memory. Rerun the program and, if the error persists, contact the system administrator.

  2. [anginterp-dtype] Invalid data type for <xxxxx> scaling

    The <xxxxx> output data type is not allowed for the selected scaling option. Select another output data type or scaling option. See User Note 2.

  3. [anginterp-exist] Angle grid file does not exist

    The specified angle grid does not exist. Ensure the correct file name was specified for ANGGRID.

  4. [anginterp-fatal] Fatal error encountered

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

  5. [anginterp-grid] Grid does not contain expected data type

    Angle grids are expected to store the angle values at each grid point in the EREAL data type. The specified angle grid contains angle values of a different data type. Reproduce the angle grid using RECTIFY.

  6. [anginterp-match] Angle grid does not match image

    The specified input image and angle grid do not match in size and/or projection. Ensure the specified angle grid was created for the input image.

  7. [anginterp-nlines] Lines per grid cell cannot exceed <xxxxx>

    ANGINTERP allocates enough memory to buffer at most <xxxxx> lines of image data. The number of lines in each grid cell of the specified grid is larger than this value. Create another angle grid using RECTIFY with NLGRID set to a value less than or equal to <xxxxx>.

  8. [anginterp-read] Error reading angle grid

    An error was encountered reading the angle grid. Ensure the user has read permission for the grid file.

  9. [anginterp-start] Angle grid does not start at (1,1)

    The angle grid does not start at line, sample (1, 1). Reproduce the angle grid for IN using RECTIFY.

  10. [anginterp-write] Error writing to output image

    An error was encountered writing to the output image. Ensure the user has write permission in the output directory.

User Notes:

  1. RECTIFY can optionally create a grid containing the satellite zenith, solar zenith, and relative azimuth angles at each grid point. ANGINTERP uses this grid to generate an image containing the view angles for every pixel by interpolating the values at the surrounding grid points.

  2. All angle values are stored in degrees, have valid ranges, and are scaled according to SCALOPT and ODTYPE. The angle values are scaled to retain as much precision as possible for each of the output data types. When the user selects SCALOPT=NONE the output data type BYTE is not allowed (BYTE data cannot represent enough values to store the angles without some form of scaling). The actual angle values may be computed using the following equations and the appropriate scaling factor and offset values.

    	Stored_Angle_Value = (Actual_Angle_Value * scale) + offset
    

    Actually, the formula for global scaling is more complex, namely:

    	Stored_Value = ((Actual_Value + shift) * scale) + offset
    

    This formula can be expanded as follows:

    	Stored_Value = (Actual_Value * scale) + (shift * scale) + offset
    
    	Stored_Value = (Actual_Value * scale) + offset + (shift * scale)
    
    	Stored_Value = (Actual_Value * scale) + offset2
    
    	Where offset2 = offset + (shift * scale)
    

    Thus, the formula for global scaling is that of US scaling except that the offset term is slightly more complex for global scaling. See the ADAPS Overviews for the scale, shift, and offset values used for each data type and scaling option.

    When no scaling is specified, all offset and scaling values are 0.0 and 1.0, respectively.

    The appropriate equation for unscaling the angle values is stored in the SOURCE field of the DDR for each of the angle bands generated. In general, the formula for unscaling is as follows:

    	Actual_Angle_Value = (Stored_Angle_Value - offset) / scale
    

    The relative azimuth angles are stored as absolute values for US scaling. It is common for the satellite zenith angles to be truncated in opposite corners of the output image which lie on either side of the satellite's nadir track.

  3. The angle values at each pixel within the output image are computed by interpolating the values at four surrounding grid points.

    In some areas of an image the relative azimuth angles change from large positive values, near 180, to large negative values, near -180. In these areas it is undesirable to interpolate through zero. The solution is to use a nearest neighbor algorithm when at least one of the surrounding grid points is positive and at least one is negative. This algorithm will also be used when the angle values are near zero. The effects in these cases are minimal.

  4. ANGGRID is checked to ensure it matches IN in size and projection.

  5. A similar function is SUNSAT, which generates zenith and azimuth angles for an AVHRR LAS image.