User's Guide

AVHRRCAL

Calibrate AVHRR data (NOAA-6 through NOAA-18)

Function:

Calibrates AVHRR data for the NOAA-6 through NOAA-18 satellites. Calibration coefficients are calculated and applied to the raw data. The reflectance or radiance is calculated for the visible channels and the temperature is calculated for the infrared channels. The calibrated data may be scaled in one of several ways to maintain desired accuracies.

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 lines or samples is not allowed.

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.

CALTYPE(PRELAUNCH)
Optical calibration degradation method. This method defines previously calculated gains and intercepts for linearly calibrating the visible bands.

  = PRELAUNCH: Visible calibration coefficients will be
               calculated based on NOAA's prelaunch values.

  = KAUFMAN:   Visible calibration coefficients will be
               calculated based on Kaufman-Holben values, which
               take into account a linear degradation of the
               visible sensors in flight.

  = TEILLET:   Visible calibration coefficients will be
               calculated using a piece-wise linear
               interpolation, based on days since launch, using
               values recommended by Teillet & Holben.

  = VERMOTE:   Visible calibration coefficients will be
               calculated using preliminary post launch values.
               Gain values are from Eric Vermote, GSFC; dark
               count offsets are from deep space counts recorded
               at EDC, and values for effective band width and
               filtered solar irradiance (for reflectance
               calibration only) are from Gunar Fedosejevs of
               CCRS, attributable to Stanley Brown of NOAA.

  = RAO:       Rao employed the vicarious calibration technique
               of using a bright desert surface as a
               radiometrically stable calibration target.
               The isotropic albedo of the calibration target,
               based on a long-term time series of AVHRR
               measurements was used to establish the in-
               orbit degradation of the visible AVHRR channels.
= NOAA:        NOAA values

ILLUMFLG(NO)
Illumination correction flag. This flag indicates whether or not illumination correction should be calculated for the two sets of visible band coefficients (bands one and two). Illumination correction can only be applied if the data will be calibrated to reflectance. If ILLUMFLG = YES then RADOPT must be set to REFLECTANCE.

  = YES:  Coefficients are corrected for differences
          in earth-sun distance and position of the
          sun relative to the satellite.

  = NO:   Coefficients will be constant for all lines
          of the image.

CALPER(5)
Calibration period. This is the number of lines over which the blackbody and space data are averaged, for use in calculating coefficients for the thermal bands.

NCALS(10)
Number of calibration periods. The number of calibration periods for computing PRT averages, for use in calculating coefficients for the thermal bands. PRT data is averaged over a number of calibration periods, each of which is CALPER lines long.

The product of CALPER and NCALS is the number of lines used to initialize the coefficients. This product must be at least 50 and must be less than the number of lines in the image.

Note that specifying a NCALS value of 10 will not necessarily mean 10 sample values of PRT data will be averaged. If CALPER is not five (the calibration period inherent for PRT data), the number of values averaged may be more or less than 10.

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
For the NOAA-KLM satellite series, there is only one CWN for all temperature ranges. Consequently, any temperature range specification is correct.

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. NOTE: For NOAA-9 through NOAA-12, if specified, this correction is applied to the temperature value. For NOAA-14, if specified, this correction is applied to the energy (radiance) value. For the NOAA-KLM series, this correction is ALWAYS applied to the energy (radiance) value regardless of the specified value of ERRFLG.


  = 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 in AVHRRCAL.


  = 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. If RADOPT=RADIANCE then ILLUMFLG must be set to NO.

  = 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> avhrrcal in=westus(:1) out=westcal calfile=vermote illumflg=no satchan=3 odtype=i*2 temprng=3 errflg=yes scalopt=global print=summary

    Band 1 from the LAS image WESTUS, which corresponds to AVHRR channel 3, will be read line by line. Coefficients will be generated using the VERMOTE calibration file and a summary file, SUMMARY;PRT, will be created. A calibrated image named WESTCAL will be created. The central wave number (CWN) is calculated for channel 3 of satellite NOAA-14 ( the satellite number is gotten from the ddr file) in temperature range three ( 275K to 320K degrees ). These temperature values are then scaled using the global scaling option (see User Notes) to maintain as much precision as possible.

Description/Algorithm:

AVHRRCAL uses a generalization of the process NOAA uses to generate calibration coefficients. NOAA averages the blackbody and space data over one five-line calibration period and the PRT data over 10 calibration periods. Like NOAA, AVHRRCAL averages the blackbody and space data over one calibration period. However, the number of lines in a calibration period may be specified by the user. The PRT data are averaged over the number of calibration periods the user specifies. The following method is used:

1. Initial values for the visual coefficients are calculated
   using the CALTYPE calibration table.

2. Initial values for the thermal band coefficients are 
   calculated using a set of lines from the image minor frame 
   file and the following method:

   a. Four PRT mean counts (Xi) are calculated based on NCALS
      calibration periods.

   b. The PRT mean counts are converted to temperature by the
      following equation:

	Ti = SUM (aij)(Xi**j)

      where aij = coefficients retrieved from the satellite
		  calibration table

   c. The average temperature of the internal target is
      calculated as:

	 T = SUM (bi)(Ti)

      where bi = weighting factor retrieved from the satellite
      calibration table

   d. Compute the calibration coefficients

      1. For a linear response function (prior to NOAA-KLM
	 series):

      The gain is calculated by:

   	    G = (Nsp - Nt)/(Xsp - Xt)

         where:

	       Nsp = radiance of space (read from satellite
		     calibration table)
	       Nt  = radiance of internal target (calculated from
		     data in satellite calibration table)
	       Xsp = mean instrument space count
	       Xt  = mean instrument internal target count

         The intercept is calculated by:

	    I = Nsp - G*Xsp

         This method assumes a linear response of the detectors,
         where:

            energy = G*(count value of target) + I.

      2. For the NOAA-KLM series:

          The channel 3B coeff are linear from:

	         nt ( xsp - Ce )
   	   Ne = ----------------------
	          ( xsp - xt )
	
	   where Ne is radiance, Ce is count of earth data, xsp is count
	   of space data, and xt count of internal target.  Note that
	   a "non-zero" radiance of space is NOT used.

          Channel 4 and 5 coeff are quadratic from:

	       Ne = Nlin + Ncor				(1

				       ( xsp - Ce )
	       Nlin = C0 + ( nt - C0 )---------------	(2
				       ( xsp - xt )
	    
	       Ncor = C1 + C2*Nlin + C3*Nlin^2		(3

	   The coeff a, b and c from:

	       Ne = a + b*Ce + c*Ce^2
	
	   are obtained by substituting for Nlin and Ncor in equations
	   (1 and (3 and combining the Ce terms.  (The algebra is left
	   as an exercise for interested programmers) The constants C0,
	   C1, C2, and C3 are found in NOAA KLM section 7.1.2.3.2 and
	   in the noaa15.cal/noaa16.cal/noaa17.cal file as Table
	   NON-LINEAR CORRECTION FACTORS.  They are stored in the
	   calibration structure member corr.
	
3. The visual coefficients may be left constant or recalculated
   throughout the image, depending on ILLUMFLG.  This 
   recalculation corrects differences in earth-sun distance
   and position of the sun related to the satellite.

4. Calibration coefficients for all lines in the image
   are then recalculated every CALPER lines.  The coefficients
   calculated for the previous CALPER lines will be applied to
   the current CALPER lines.

5. If PRINT is not NULL, a report of the mean and standard 
   deviation of each coefficient is generated.  The 
   coefficients for visible channels are computed in gain (G) 
   and intercept (I) values which may be used to convert 
   detector output to albedo by the equation:
               albedo = G * (detector output) + I.  
   The coefficients for thermal channels are reported in 
   quadratic or order 2 (Q), gain or order 1 (G), and intercept
   or order 0 (I) such that:
               energy = (Q * D * D) + (G * D) + I.

   where D = detector output.

Once the calibration coefficients are generated, these coefficients are used to calculate the output image values in the following manner:


Visible Channels
__________________________

  The gain coefficient and the intercept coefficient 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.

Thermal Channels
______________________________

  The gain coefficient and the intercept coefficient are used in
  the following formula:

	E = Q*D*D + G*D + I

  where E is energy, D is the data value from the input image,
  Q is the quadratic coefficient, G is the gain, and I is
  the intercept.  Q is always zero (0) except for channels 4 and
  5 of the NOAA-KLM series.

  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.  

  Then:

     T = A + (B * Te)

  Where Te is the "effective" temperature.
  EXPLAINATION:  For satellites prior to the NOAA-KLM series,
  there are 4 CWN to use, depending on the estimated temperature
  range of the surface being analyzed.  For these satellites,
  the A and B correction coefficients are 0.0 and 1.0
  respectively (no correction).  For the NOAA-KLM satellites,
  there is only one CWN for all temperatures, but correction
  coefficients A and B to apply to the "effective" temperature
  coming out of the inverse of Planck's radiation function
  defined above.

  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.

  For the NOAA-KLM satellite series, channels 4 and 5 energy
  values will always 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 a completion message is displayed.

Nonfatal Error Messages:

  1. [avhrrcal-warn] Nonfatal error encountered

    A nonfatal error was encountered. Refer to the preceding message for details. Processing will continue.

  2. [avhrrcal-wind] Windowing is not allowed -- full image size will be used

    The entire lines and samples within an input image will be calibrated by AVHRRCAL, windowing will be ignored. Band specifications however, are honored.

Fatal Error Messages:

  1. [avhrrcal-fatal] Fatal error encountered

    A fatal error was encountered. Refer to the preceding message for details. Processing will terminate.

  2. [avhrrcal-opt] Illegal combination of options: ILLUMFLG=YES and RADOPT=RADIANCE

    Applying illumination correction to radiance values is not appropriate. Illumination correction should only be applied to reflectance values. If radiance values are desired ensure that ILLUMFLG=NO and run the program again.

  3. [avhrrcal-wsiz] Image windows differ in size

    The image window specified in IN must all be the same size. Ensure they are all the same size, and rerun.

  4. [avhrrcal-bands] Too many bands specified

    Too many bands were specified, at most 5 channels may be specified.

  5. [avhrrcal-mult] Multiple input files not allowed

    Multiple file specification is not allowed (Example: IN="file1(:1),file2(:3)") because of the minor frame label services file that would be associated with each image. Respecify the IN parameter with one input image.

  6. [avhrrcal-chans] Number of channels and bands are not equal

    The number of AVHRR channels specified in SATCHAN and the number of bands specified in IN must be equal. Respecify these parameters so that they match.

  7. [avhrrcal-few] Too few lines specified for coefficient initialization

    There must be at minimum (NCALS * CALPER) lines available to initialize the calibration coefficients. This same criteria applies following the reconfiguration of the sensors, when applicable. Specify a larger image, or reduce the product of the two parameters above.

  8. [avhrrcal-many] Too many lines specified for coefficient initialization

    The product of (NCALS * CALPER) exceeds the number of lines in the input image. Specify a larger image, or reduce the product of the two parameters above.

  9. [avhrrcal-alloc] Error allocating dynamic memory

    An error occurred allocating dynamic memory. If this error persists, contact the system administrator.

  10. [avhrrcal-open] Error opening <XXXXX> file

    An error occurred opening the specified file. Ensure the file exists with the appropriate permissions.

User Notes:

  1. AVHRRCAL is a procedure which replaces the obsolete modules MAKENCAL and HRPTCAL. Most of the work is done within the support routines c_calcoeff() and c_appcoeff(). MKLEVEL1B is also related in that it calls c_calcoeff() to generates calibration coefficients and stores them in the Level 1B format.

  2. Information on calculating and using calibration coefficients can be found in the NOAA Polar Orbiter Data Users' Guide and NOAA KLM User's Guide.

  3. The calibration degradation files are stored in the ADAPSTABLES directory.

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

  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.

    Geoffrey Goodrum, Katherine B. Kidwell, Wayne Winston, NOAA KLM User's Guide, National Oceanic and Atmospheric Administration, Washington, D.C. March, 1999.