User's Guide

HRPTCAL

Calibrate AVHRR data from NOAA 6 through 14

Function:

Calibrates AVHRR data from NOAA 6 through 14 satellites using calibration coefficients stored in a labeled table file. The reflectance or radiance is calculated for the two visible channels (1,2) and the temperature is calculated for the three infrared channels (3,4,5). The calibrated data can be scaled in one of several ways to maintain desired accuracies. See the User Notes for scaling options.

Parameters:

IN
Input image. The input image to be calibrated. The SATCHAN parameter must be used to specify which of the original satellite channels each of the input band(s) correspond to. Subbanding is allowed but windowing is not. The coefficients needed for calibration are read from a labeled table file associated with the image. The extension for this associated LT file must be ;CAL.

OUT
Output image. The output image will be the same size as the input image. The data type of the output image is specified by the parameter ODTYPE.

SATCHAN(1,2,3,4,5)
Satellite channels. The original channels of the satellite that correspond to the bands in the input image.

ODTYPE(SAME)
Output data type. This will be the data type of the output image. The output values will be scaled to fit within the data type range. See the User Notes for scaling and offset factors for each data type.


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

TEMPRNG(3)
Temperature range. This is the estimated temperature range (Kelvin) of the surface being analyzed. The central wave number (CWN) used in the calculation of the temperature for channels 3, 4, and 5 is derived from the temperature range specified. For satellites NOAA-6, 7, 8, 9, 10, and 11, the ranges are:


  = 1: 180-225 degrees
  = 2: 225-275 degrees
  = 3: 275-320 degrees
  = 4: 270-310 degrees

For satellites NOAA-12 and NOAA-14, the ranges are:


  = 1: 190-230 degrees
  = 2: 230-270 degrees
  = 3: 270-310 degrees
  = 4: 290-330 degrees

ERRFLG(YES )
Error flag. The flag to correct for nonlinearity errors. Since the detectors used for channels 4 and 5 are slightly nonlinear and since the inverse of Planck's equation used to calculate the temperature is a linear function, a correction factor can be added to the temperature to correct for these nonlinearity errors.


  = YES:  Correct for nonlinearity errors
  = NO:   Do not correct for nonlinearity errors

SCALOPT(NONE)
Scale option. Scaling option desired by the user. See User Notes.


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

ROSOPT(ZERO )
Radiance of space option. The coefficients calculated for bands 4 and 5 of NOAA-9 can be calculated with zero or non-zero radiance of space. The nonlinearity correction factors that can be applied are not the same for each of these calculations. In general, a nonzero radiance of space was used to calculate the coefficients before September 30, 1986, orbit number 927273; since then, a zero radiance of space has been used to calculate the coefficients.


  = ZERO:      Zero radiance of space 
  = NON-ZERO:  Nonzero radiance of space 

RADOPT(RADIANCE )
Radiance conversion option. Option to output the visible calibrated data in reflectance or radiance.

  = REFLECTANCE:   Output reflectance
  = RADIANCE:	   Output radiance

PRINT(--)
Output destination. The destination of the calibration saturation report. If PRINT=LP, the report will be sent to the printer specified in the TAE global variable $PRINTER. If NULL, no summary report will be generated.

  = TERM:      Output is sent to the user's terminal.

  = LP:        Output is sent to the printer defined
               by $PRINTER.

  = Filename:  Output is sent to the user-supplied
               file with the extension ";prt".

Examples:

  1. LAS> hrptcal in="westus(:2)" out=westcal satchan=2 odtype=byte scalopt=us print=clipsum

    Band 2 of WESTUS, which corresponds to AVHRR channel 2, will be read line by line. The coefficients needed to calculate the radiance are read from the associated labeled table WESTUS;CAL. The radiance of each value will be calculated and scaled using the US scaling option (see User Notes) to maintain as much precision as possible for BYTE data. A summary of the saturated pixels will be created in CLIPSUM;PRT.

  2. LAS> hrptcal in="westus(:1,2,3)" out=westcal satchan=(3,4,5) odtype=i*2 temprng=3 errflg=yes scalopt=global

    Bands 1, 2, and 3, from the LAS image WESTUS, which correspond to AVHRR channels 3, 4, and 5, will be read line by line. The coefficients needed to calculate the temperature of each of the values are read from the associated labeled table file WESTUS;CAL. The central wave number (CWN) is calculated for channels 3,4, and 5 of satellite 11 (satellite number gotten from the AVHRR ddr file) in temperature range three (275K to 320K degrees). The CWN and coefficients are used to calculate the temperature values for each of the channels. The nonlinearity error corrections for NOAA-11 are added to the temperatures of channels 4 and 5. These temperature values are then scaled using the global scaling option (see User Notes) to maintain as much precision as possible.

Description/Algorithm:

After reading the parameters, IN and OUT are opened for read and write access, respectively. The labeled table associated with the input image is opened and the gain and intercept coefficients are read. These coefficients are used to calculate the output image values in the following manner:


CHANNELS 1 and 2 (visible)
__________________________

  The gain coefficient in the associated LT is divided by 2**30
  and the intercept coefficient in the associated LT is divided
  by 2**22 before they are used in the following formula: 
  
	A = G * D + I

  where A is the reflectance, D is the data value from
  the input image, G is the gain, and I is the intercept. 

  The following formula is used to convert the reflectance
  value to radiance:

        R = A (F / (100 * PI * W))

  Where:
        R - Radiance
        A - Reflectance
        F - Integrated solar spectral irradiance,
        W - Equivalent width of the spectral response function

  Table 3.3.2-2, on page 3-19 of the NOAA Polar Orbiter Data
  Users Guide, July 1991, contains the values of W and F derived
  from Neckel and Labs (1984)

  See User Note 6 for an explanation of how the data is scaled
  to maintain as much precision as possible for each data type.

CHANNELS 3, 4, and 5 (thermal)
______________________________

  The gain coefficient in the associate LT is divided by 2**30
  and the intercept coefficient in the associated LT is divided
  by 2**22nd before they are used in the following formula:

	E = G*D + I

  where E is energy, D is the data value from the input image,
  G is the gain, and I is the intercept.

  Energy is then converted in temperature (T) by using the
  inverse of Planck's radiation function as shown in the
  following equation.
	                    C2*CWN
         T =     ___________________________
                      ___            ___       
                     |                  |
                     |      C1 * CWN**3 |      
                  ln | 1  + ___________ |      
                     |          E       |      
                     |___            ___|        
                               

  where E is energy from the above formula, C1 is a constant 
  equal to 1.1910659E-5, C2 is a constant equal to 1.438833, 
  and CWN is the central wave number given for each channel of
  each satellite for a specified surface temperature.  
  
  If specified, channels 4 and 5 of satellites 9, 10, 11, and 12
  will have the nonlinearity error correction factors added
  to the temperature.

  If specified for satellite 14, channel 3 will be corrected for
  calibration space view offset, and channels 4 and 5 energy
  values will be corrected for nonlinearity.

  See User Note 6 for an explanation of how the data is scaled
  to maintain as much precision as possible for each data type.

After every input value is calibrated and written to OUT, all the files are closed and the completion message is displayed.

Nonfatal Error Messages:

  1. [hrptcal-wind] Windowing is not allowed -- full image size will be used

    Windowing is not allowed in this function. Processing will continue, but the output image size will be the size of the input image.

  2. [hrptcal-maxval] Some of the values in channel <XXXX> are not within the valid range. Values less than 0 or values greater than the maximum value are set to 0

    Some of the calculated values for the indicated channel are outside the valid range. Negative values are set to 0 and values greater than the maximum value are also set to 0. An output pixel with the value of 0 indicates that the input pixel may be in error. See User Notes for valid ranges.

  3. [hrptcal-warn] Nonfatal error encountered

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

Fatal Error Messages:

  1. [hrptcal-chans] Number of channels and bands are not equal

    The number of channels specified and the number of bands have to be equal. Respecify one or the other so that they are equal.

  2. [hrptcal-cwn] No CWN exists for this satellite, channel, and range

    There is no central wave number (CWN) for this combination of satellite number, channel number, and temperature range. Respecify one or more of these parameters.

  3. [hrptcal-alloc] Error allocating dynamic memory

    Memory could not be allocated for the image buffers; therefore, the output image is not created.

  4. [hrptcal-rang] Input value beyond range of 0-1023

    The pixel value read from the input image is beyond the valid range of 0 to 1023 inclusive. Examine the values within the specified input image.

  5. [hrptcal-fatal] Fatal error encountered

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

User Notes:

  1. Windowing is not allowed for this function. The output image will be the size of the input image.

  2. The calibration coefficients are generated with the LAS routines LACIN or MAKENCAL and written to a labeled table file for input into HRPTCAL. The extension of the labeled table file must be ;CAL. Any changes made to the labeled table format created by LACIN or MAKENCAL will affect the output of this program.

  3. The coefficients needed for calibration are read from a labeled table file associated with the image. The extension for this associated LT file is expected to be ;CAL.

  4. Nonlinearity error correction is only calculated for target temperatures from 205K to 320K for satellites NOAA-09 through NOAA-14. No correction is applied for any other satellites or temperature values outside the above ranges.

  5. When calculating reflectance values for channels one and two, any values outside the valid range (0 to 100) are set to zero. When calculating radiance values for channels one and two, any values outside the valid range (0 - 540) are set to zero. Temperature values for channels three, four, and five outside the valid range (160 to 340) are set to zero. These zero values indicate that the input pixel is in error, probably due to noise. Once a valid pixel has been scaled, it will no longer be within the range of zero. Consequently, a pixel set to zero because of invalid data cannot be confused with an actual data value of zero.

  6. SCALING:

        The following formula is used to scale the values to
        maintain as much precision as possible for the specified
        data type:
    
           OUT_PIXEL = (IN_PIXEL * SCALE) + OFFSET
    
        Actually, the formula for global scaling is more complex,
        namely:
    
           OUT_PIXEL = ((IN_PIXEL + SHIFT) * SCALE) + OFFSET
    
        This formula can be expanded as follows:
    
           OUT_PIXEL = (IN_PIXEL * SCALE) + (SHIFT * SCALE) + OFFSET
    
           OUT_PIXEL = (IN_PIXEL * SCALE) + OFFSET + (SHIFT * SCALE)
    
           OUT_PIXEL = (IN_PIXEL * 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 User Guides for the scale, shift, and offset values
        used for each data type and scaling option.
    

  7. NO SCALING:

        When ODTYPE is not R*4, the output value will be rounded to
        the nearest integer and truncated to the minimum and
        maximum data value for the specified ODTYPE.  For example,
        when ODTYPE is set to BYTE, any values below zero are set
        to zero and any values above 255 are set to 255.
    

  8. UNSCALING:

       RESCALE or MATH functions can be used to unscale the output
       image using the following formula:
    
       OUT_PIXEL = (SCALE_PIXEL - OFFSET) / SCALE
    

  9. Reference:

    Katherine B. Kidwell, NOAA Polar Orbiter Data Users Guide, National Oceanic and Atmospheric Administration, Washington, D.C. July 1991.