User's Guide

WINDOW1B

Window AVHRR Level 1b image(s) from tape or disk

Function:

Window AVHRR Level 1b image(s) from tape or disk and create Level 1b file(s) on disk.

Parameters:

Subcommand -LINE:
Line window specification. The area to be retrieved is specified by the starting and ending line.

INFILE
Name of input Level 1b file on disk. If INFILE is defaulted, COMMENT must be specified.

COMMENT(--)
Description of tape(s). A text string sent to the operator's terminal describing each tape to be mounted. COMMENT should contain the tape library identification number and a short description of the tape. This will allow the operator to ensure the correct tape is mounted. If COMMENT is defaulted, INFILE must be specified.

FILENUM(--)
File numbers on tape. This is a list of values representing the relative file numbers on tape. The values in the list must be positive and in increasing order. If FILEFLG=RANGE then only two values may be specified in the list.

FILEFLG(ALL)
FILENUM specification flag. This string indicates whether the values listed in FILENUM are individually selected files on tape (SELECT) or if they represent a range of files (RANGE). The default value (ALL) processes all files on tape.

    = All:    Process all files
    = SELECT: Selected file numbers
    = RANGE:  Range of file numbers

OUTFILE(--)
The output image and/or directory name. If OUTFILE is not specified, an image name will be generated from the satellite number, acquisition date, and time at the start of acquisition. This image will be place in the current working directory. If only a directory is specified, the image name will be likewise generated and placed in the specified directory.

CHANS(--)
AVHRR channels. The AVHRR channels to be placed in the output image. The default is to copy all of the channels in the input image to the output image.

  = 1:  Channel 1
  = 2:  Channel 2
  = 3:  Channel 3
  = 4:  Channel 4
  = 5:  Channel 5

NCHANS(--)
Number of channels in CHANS that apply to each file. If NCHANS(1)=3 the first three channels in CHANS are to be extracted from file 1.

PACKFLG(YES)
Flag to pack data. The data in the output image may be packed only if all 5 AVHRR channels are to be written.

  = YES:  Data will be packed.
  = NO:   Data will not be packed.

SL(1)
Starting line. The line number where processing will begin (relative to North-up).

NL(--)
Number of lines. The number of lines to process starting at SL. If the end of the image is encountered before NL lines have been processed, processing will successfully terminate. If NULL, the entire image starting from SL will be processed.
Subcommand -LATLONG:
Latitude and longitude window specification. The area to be retrieved is specified by the starting and ending latitude and longitude (in degrees).

INFILE
Name of input Level 1b file on disk. If INFILE is defaulted, COMMENT must be specified.

COMMENT(--)
Description of tape(s). A text string sent to the operator's terminal describing each tape to be mounted. COMMENT should contain the tape library identification number and a short description of the tape. This will allow the operator to ensure the correct tape is mounted. If COMMENT is defaulted, INFILE must be specified.

FILENUM(--)
File numbers on tape. This is a list of values representing the relative file numbers on tape. The values in the list must be positive and in increasing order. If FILEFLG=RANGE then only two values may be specified in the list.

FILEFLG(ALL)
FILENUM specification flag. This string indicates whether the values listed in FILENUM are individually selected files on tape (SELECT) or if they represent a range of files (RANGE). The default value (ALL) processes all files on tape.

    = All:    Process all files
    = SELECT: Selected file numbers
    = RANGE:  Range of file numbers

OUTFILE(--)
The output image and/or directory name. If OUTFILE is not specified, an image name will be generated from the satellite number, acquisition date, and time at the start of acquisition. This image will be place in the current working directory. If only a directory is specified, the image name will be likewise generated and placed in the specified directory.

CHANS(--)
AVHRR channels. The AVHRR channels to be placed in the output image. The default is to copy all of the channels in the input image to the output image.

  = 1:  Channel 1
  = 2:  Channel 2
  = 3:  Channel 3
  = 4:  Channel 4
  = 5:  Channel 5

NCHANS(--)
Number of channels in CHANS that apply to each file. If NCHANS(1)=3 the first three channels in CHANS are to be extracted from file 1.

PACKFLG(YES)
Flag to pack data. The data in the output image may be packed only if all 5 AVHRR channels are to be written.

  = YES:  Data will be packed.
  = NO:   Data will not be packed.

SLAT
Starting latitude. The starting latitude of the window, specified in degrees.

SLONG
Starting longitude. The starting longitude of the window, specified in degrees.

ELAT
Ending latitude. The ending latitude of the window, specified in degrees.

ELONG
Ending longitude. The ending longitude of the window, specified in degrees.
Subcommand -LATRANGE:
Latitude range window specification. The area to be retrieved is specified by the starting and ending latitude (in degrees).

INFILE
Name of input Level 1b file on disk. If INFILE is defaulted, COMMENT must be specified.

COMMENT(--)
Description of tape(s). A text string sent to the operator's terminal describing each tape to be mounted. COMMENT should contain the tape library identification number and a short description of the tape. This will allow the operator to ensure the correct tape is mounted. If COMMENT is defaulted, INFILE must be specified.

FILENUM(--)
File numbers on tape. This is a list of values representing the relative file numbers on tape. The values in the list must be positive and in increasing order. If FILEFLG=RANGE then only two values may be specified in the list.

FILEFLG(ALL)
FILENUM specification flag. This string indicates whether the values listed in FILENUM are individually selected files on tape (SELECT) or if they represent a range of files (RANGE). The default value (ALL) processes all files on tape.

    = All:    Process all files
    = SELECT: Selected file numbers
    = RANGE:  Range of file numbers

OUTFILE(--)
The output image and/or directory name. If OUTFILE is not specified, an image name will be generated from the satellite number, acquisition date, and time at the start of acquisition. This image will be place in the current working directory. If only a directory is specified, the image name will be likewise generated and placed in the specified directory.

CHANS(--)
AVHRR channels. The AVHRR channels to be placed in the output image. The default is to copy all of the channels in the input image to the output image.

  = 1:  Channel 1
  = 2:  Channel 2
  = 3:  Channel 3
  = 4:  Channel 4
  = 5:  Channel 5

NCHANS(--)
Number of channels in CHANS that apply to each file. If NCHANS(1)=3 the first three channels in CHANS are to be extracted from file 1.

PACKFLG(YES)
Flag to pack data. The data in the output image may be packed only if all 5 AVHRR channels are to be written.

  = YES:  Data will be packed.
  = NO:   Data will not be packed.

SLAT
Starting latitude. The starting latitude of the window, specified in degrees.

ELAT
Ending latitude. The ending latitude of the window, specified in degrees.

QUADNUM(5)
Quadrant number. The quadrant number indicating the area that the latitude range will be selected from. (See user note 5.)

  = 1:  Quadrant 1
  = 2:  Quadrant 2
  = 3:  Quadrant 3
  = 4:  Quadrant 4
  = 5:  Any quadrant
  = 6:  North Pole crossing
  = 7:  South Pole crossing
  = 8:  Both Poles crossed

AREAOPT(FIRST)
Area option. Some GAC passes can cross over an area of interest more than once. AREAOPT is used to indicate which of the multiple passes is to be selected.

  = FIRST:  First pass over area of interest.
  = SECOND: Second pass over area of interest.

Examples:

  1. LAS> window1b-line comment="please mount tape t489" filenum=1 fileflg=select outfile=westus sl=668

    Tape T489 will be mounted onto a tape drive. The user is requesting the first image on tape T489. The output image, WESTUS, will begin with line 668 of the north-most line of the image on tape, and continue until the end of the image is reached. All channels on the tape will be processed since CHANS was not specified. The output data will be packed since PACKFLG was not specified.

  2. LAS> window1b-latrange infile="ag11042993175124;l1b" outfile=eastus slat=-10.5 elat=-5.0 areaopt=first chans=(1,2)

    The input file "ag11042993175124;L1B" will be read from disk. The output image EASTUS will contain lines within the area between -10.5 and -5.0 degrees latitude. If more than one area within the image is defined by SLAT and ELAT, the first area will be processed (this may happen with GAC data). AVHRR channels one and two will be written to the Level 1b output image.

  3. LAS> window1b-latlong infile="eastus;l1b" outfile="coast;l1b" slat=0.0 elat=10.0 slong=160.0 elong=170.0 packflg=yes

    The input file "EASTUS;L1B" will be read from disk. The output image "COAST;L1B" will contain lines which lie between 0.0 and 10.0 degrees latitude and between 160.0 and 170.0 degrees longitude. The output image will contain all 5 AVHRR channels, and will be in packed format.

Description/Algorithm:

The specified input Level 1b file on tape or disk is opened for read access. The Terabit Memory (TBM) or Archive Retrieval System (ARS) (for NOAA KLM series spacecraft) header record as well as the Data Set Header (DSH) are returned. If the TBM/ARS header does not exist within the file, it is created. The AVHRR model information is loaded from the image header information. Seek to the first line of data to be processed, as specified by the user. Open the output Level 1b image file and write the TBM/ARS and DSH headers to it. These headers are relative to the window to be written to the output image. For the window of the image to be processed, read each input line, convert the data to the output format, and write it to the output image. If reading from tape, make certain that the cursor is ultimately positioned at the beginning of the next Level 1b image on tape (ready for the next call from this module). Update the header information in the output image, and close the input and output Level 1b files. Processing continues in this manner until all specified Level 1b files have been processed.

Nonfatal Error Messages:

    None.

Fatal Error Messages:

  1. [window1b-fatal] Fatal error encountered

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

  2. [window1b-exist] Output file already exists

    The output file name specified by OUTFILE already exists on disk. Rerun the process specifying another output file name.

  3. [window1b-openout] Error opening output file

    An error occurred opening the specified output file. Make certain that the proper directory permissions exist.

  4. [window1b-renm] Error renaming the output file

    An error occurred renaming the specified output file. Make certain that a valid output file name has been specified.

  5. [window1b-rprm] Error returning parameter to TAE

    An error was encountered while returning the STATUS parameter to TAE. Contact the system administrator.

  6. [window1b-parm] <parameter specification error message>.

    Input parameters were incorrectly entered. The error message will specify which parameter(s) need correction. Correct the parameter and re-run.

  7. [window1b-order] Error FILENUM must be in ascending order.

    The file numbers specified were not in ascending order. Re-enter file numbers properly.

User Notes:

  1. Windowing the Level 1b image in the sample direction is not allowed.

  2. HRPT and LAC Level 1b files have the same data format. Two data records constitute one line of data. GAC data has two lines of data per record. If an odd number of GAC lines is to be written, a blank line will be added to the last data line. (See User Note 4.)

  3. The TBM/ARS header record may not always be present in the input Level 1b file. The output Level 1b image file generated by WINDOW1B will always contain a TBM/ARS header record.

  4. See the NOAA Polar Orbital User's Guide (July 1991) for a full description of the Level 1b data format.

  5. Quadrants are defined by the axis at the equator (zero latitude) and the meridian of Greenwich (zero longitude).

    
                 Greenwich
           (0 degrees longitude)
                     |
                     |
               2     |    1
                     |
          -----------+-----------        Equator
                     |            (0 degrees latitude)
                     |
               3     |    4
                     |
                     |
    
    When an area of interest crosses more than one quadrant and doesn't cross one or both of the poles, the quadrant number should be set to the quadrant that the pass started in. When the quadrant number is set to any quadrant (5), the image will be windowed at the starting and ending latitudes first encountered. An area of interest crossing a pole (6 or 7) should specify SLAT as the latitude before crossing the pole and ELAT as the latitude after crossing the pole. An area of interest crossing both poles (8) will use SLAT as the latitude before crossing the first pole encountered and ELAT as the latitude after crossing the other pole.

  6. If the -LATRANGE subcommand is chosen, all lines containing the latitude range are included. Thus, the latitude range of the output file may be larger than the range specified by the user.

  7. If a latitude range specified for a certain quadrant is too near a pole, the correct area may not be found with the usual QUADNUM option. One latitude must be at least eight degrees from the pole. The user may have to specify a pole crossing starting or ending at the pole, or use some other method to find the desired area.

  8. Windowing specifications must be relative to a North-up image. Consequently, for an ascending image, the windowed lines are counted from the end of the file, instead of from the beginning.

  9. The output data can only be packed if all 5 AVHRR channels are to be written to the output image. If the PACKFLG parameter is set to YES, but not all 5 channels are to be written, the data will not be packed.

  10. There may be fewer lines than expected in the output file because the Level 1b format does not store drop lines.

  11. If spanning tapes, the last record on the first tape may or may not get read. The reason for this unpredictable behavior is that not all tape drives handle an EOT mark the same way. If this error occurs, it is likely that the set of tapes was made on a tape drive different from the one being used to read the tapes. Try using a different tape drive if the problem persists.

  12. If unique windows are desired for multiple input images, a window must be specified for each input file.

  13. Only one type of windowing, LINE, LATLONG or LATRANGE, is allowed when ingesting multiple files.

  14. When specifying bands other than the default care must be taken to insure the number of channels in NCHANS matches the channels specified in CHANS.