User's Guide

MAKENCAL

Generalization of NOAA's method for generating calibration

Function:

Generates calibration coefficients for AVHRR LAS images in a manner similar to NOAA. The thermal and visual sensors on board the NOAA satellites experience a degradation of performance over their time, thus making in-flight calibration necessary. The coefficients consist of a gain/intercept pair for each band, which are applied linearly to the detector output count value. The calibration coefficients are stored in OUTLT. An optional report of the mean and standard deviation of each coefficient may be generated.

To calibrate the thermal channels, the sensor takes, along with each image line, a reading of space and a part of its housing which is a constant-temperature internal calibration target (ICT), or blackbody. The blackbody's true temperature is monitored by four on board platinum resistance thermometers (PRT's). The constant zero radiance of space and the radiance from the PRT readings of the blackbody are compared to the sensor's readings of space and the blackbody to provide a two-point (linear) calibration.

NOAA conducts prelaunch calibration of the visible channels. The coefficients may be based on these prelaunch values, or may take into account a linear degradation of the sensor over time, based on how long the satellite has been in orbit. In addition, corrections may be made for variability in solar irradiance and earth-sun distance.

Parameters:

IN
Input image. This AVHRR LAS image must include the associated DDR, ADDR, and MNR files. Bands may be specified, but specifying a window will have no effect. Windows may be specified using SL and NL only, as coefficients are calculated for all samples across a scan line.

OUTLT
Output labeled table. This file contains the calibration period (number of lines for which the coefficients apply), and the gain and intercept values of the calibration coefficients for each of the specified bands.

SL(--)
Starting line. The first line that calibration coefficients should be generated for. If NULL, calibration will begin at the first line.

NL(--)
Number of lines. The number of lines to generate calibration coefficients for. If NL is NULL or greater than the number of lines in the image, processing will continue to the end of the image.

CALFILE(PRELAUNCH)
Optical calibration degradation file. This file contains previously calculated gains and intercepts for linearly calibrating the visible bands (bands one and two).

  = 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 two AVHRR channels.

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 should only be applied if the data will be calibrated 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 (See User Note 1).

PRINT(--)
Output destination. The destination of the calibration summary report. If PRINT=LP, the summary 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> makencal in=image outlt=out1

    Generate calibration coefficients for the image IMAGE. The coefficients will be written to the labeled table OUT1;CAL. Bands one through five will be used for calibration. The default calibration period of five lines will be used, and 10 calibration periods will be used to average the PRT data. The PRELAUNCH calibration file will be used to supply calibration data for visual coefficients.

  2. LAS> makencal in="image(:1)" outlt=out2 illumflg=yes calfile=kaufman print=img

    Coefficients for band one of IMAGE will be generated. Illumination correction will be done on these coefficients. The KAUFMAN calibration file will be used to supply calibration data for the visual coefficients. A summary of the mean and standard deviation of each coefficient will be created in IMG;PRT.

  3. LAS> makencal in="image(1 1 200 200:2 5 3)" outlt=out2 calper=6 ncals=9

    A window has been specified for IMAGE, but since SL and NL are defaulted, coefficients will be generated for all lines of the image. OUT2;CAL will contain gain/intercept pairs for bands two, five, and three in that order. The space and internal data will be averaged over six lines, and the PRT counts will be averaged over nine calibration periods, or 54 lines (See User Note 1).

Description/Algorithm:

MAKENCAL is 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, MAKENCAL 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 CALFILE 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. 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

   e. 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.

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 specified 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 the coefficients are different when they are recalculated,
   they will be written to OUTLT along with the number of lines
   to which they apply.

6. If PRINT is not NULL, a report of the mean and standard 
   deviation of each coefficient is generated.  The 
   coefficients for Channels 1 and 2 are reported 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 Channels 3, 4, and 5 are reported in 
   gain (G) and intercept (I) such that 
               energy = G * (detector output) + I.

Nonfatal Error Messages:

  1. [makencal-lines] Too many lines specified: generating coefficients for <xx> lines

    The value specified for NL was too large--there were not that many lines from SL to the end of the image. NL will be set to include all lines from SL to the end of the image.

Fatal Error Messages:

  1. [makencal-alloc] Error dynamically allocating memory

    An error was encountered allocating memory for the process. Contact the system administrator.

  2. [makencal-bands] Too many bands

    IN must contain at most five bands. Respecify IN so the bands represent the five AVHRR channels.

  3. [makencal-exist] Calibration file already exists

    A calibration file with this name already exists on disk. Choose a new name for OUTLT or remove the existing one.

  4. [makencal-fatal] Fatal error encountered

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

  5. [makencal-few] Too few lines specified for coefficient initialization

    A minimum of 50 lines is required to initialize the calibration coefficients. This number of lines is the product of CALPER and NCALS. Respecify CALPER and NCALS so that their product is greater than or equal to 50.

  6. [makencal-find] Error retrieving value of ADAPSTABLES

    A value for the environment variable ADAPSTABLES could not be found. Set ADAPSTABLES to the directory that contains the satellite calibration tables.

  7. [makencal-many] Too many lines specified for coefficient initialization

    The number of lines requested to initialize the coefficients (CALPER * NCALS) was greater than or equal to the number of lines in the image. Respecify CALPER and NCALS so that their product is less than the number of lines in the image.

  8. [makencal-open] Error opening <xxxx>

    An error was encountered opening the specified file. Verify that the name is correct and the file exists with read permission.

  9. [makencal-read] Error reading <xxxx>

    An error was encountered reading the specified file. Make sure the file has the correct number of records and has not been corrupted.

  10. [makencal-rewind] Error rewinding minor frame file

    An error was encountered rewinding the minor frame file. This must be done because the file is read twice in the program. Contact the system administrator.

  11. [makencal-slbimg] Starting line beyond image

    The line specified in SL is beyond the number of lines in the image. Respecify SL so it lies withing the image.

User Notes:

  1. MAKENCAL averages the blackbody and space data over one calibration period; the PRT data are averaged over the number of calibration periods the user specifies. In the data format, five consecutive lines will contain one reference value and four PRT sample values. The count for one PRT comes every five lines, so if CALPER does not equal five then the PRT average will not be an average of NCALS samples. For example, if CALPER = six and NCALS = 10 (60 total lines), then the PRT average will be an average of 12 PRT sample values.

  2. The number of lines over which PRT data are averaged is the product of CALPER and NCALS. Let us call this number of lines 'A'. If SL is within the first A lines of the image, then lines one through A will be used to initialize the coefficients. If SL is beyond the first A lines of the image, then the A lines immediately preceding SL will be used to initialize the coefficients.

  3. Related modules are HRPTCAL, which applies the coefficients to the image, and MKLEVEL1B, which generates calibration coefficients and stores them in the Level 1B tape format.

  4. Information on calculating and using calibration coefficients can be found in the NOAA Polar Orbiter Data Users' Guide and NOAA Technical Memorandum NESS 107.

  5. The four optical calibration degradation files are stored in the ADAPSTABLES directory.