User's Guide

INGEST1B

Convert Level 1b image(s) to a Level 0 archive image(s)

Function:

Convert Level 1b image(s) to a Level 0 archive image(s). The input image(s) may be on tape or disk. The output archive image(s) are written to disk only. The input image(s) may be sub-banded. Three windowing options are available in the following subcommands:

    LINE      The window is specified by starting line
              number and number of lines.
    LATLONG   The window is specified by starting and
              ending latitude and longitude.
    LATRANGE  The window is specified by starting and
              ending latitudes.

Parameters:

Subcommand -LINE:
Line window specification. The window is specified by starting line number and number of lines.

INFILE
Input image. A Level 1b image name that exists on disk. If no file extension is specified, it will default to "l1b".

COMMENT(--)
Description of tape. A text string sent to the operator's terminal describing the tape to mount. The comment should contain enough information (tape library ID number and brief description) to allow the operator to insure the correct tape is mounted. If the comment is NULL a disk file name 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

OUT(--)
Output file name. This name will be appended with the extension "arch" for the archive file, An associated file with the extension "ahdr" is also created. If OUT is NULL, a file name will be built based on the satellite ID, date and time.

SL(1)
Starting line. The line number of the upper left corner of the window. The default will set SL to the first line in the image.

NL(--)
Number of lines. The number of lines to be processed from the input file. The default will process all lines starting with SL to end of file. The default value NULL can be replaced by the value -1 when more than one NL specification is entered.

CHANS(--)
Satellite channels. This is a sequential list of channels to be extracted from each input file. Values in NCHANS indicate how many channels in the list apply to each input file. The default writes all five channels of the archive image.

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.
Subcommand -LATLONG:
Latitude and longitude window specification. The window is specified by starting and ending latitude and longitude in decimal degrees. The latitude and longitude values may be entered in any order and any combination. The four corners of the window are calculated, and the appropriate window is chosen to include all four corners.

INFILE
Input image. A Level 1b image name that exists on disk. If no file extension is specified, it will default to "l1b".

COMMENT(--)
Description of tape. A text string sent to the operator's terminal describing the tape to mount. The comment should contain enough information (tape library ID number and brief description) to allow the operator to insure the correct tape is mounted. If the comment is NULL a disk file name 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

OUT(--)
Output file name. This name will be appended with the extension "arch" for the archive file, An associated file with the extension "ahdr" is also created. If OUT is NULL, a file name will be built based on the satellite ID, date and time.

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

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

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

ELONG
Ending longitude. The ending longitude value of the window, specified in decimal degrees.

CHANS(--)
Satellite channels. This is a sequential list of channels to be extracted from each input file. Values in NCHANS indicate how many channels in the list apply to each input file. The default writes all five channels of the archive image.

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.
Subcommand -LATRANGE:
Latitude range window specification. The window is specified as minimum and maximum latitude values in decimal degrees.

INFILE
Input image. A Level 1b image name that exists on disk. If no file extension is specified, it will default to "l1b".

COMMENT(--)
Description of tape. A text string sent to the operator's terminal describing the tape to mount. The comment should contain enough information (tape library ID number and brief description) to allow the operator to insure the correct tape is mounted. If the comment is NULL a disk file name 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

OUT(--)
Output file name. This name will be appended with the extension "arch" for the archive file, An associated file with the extension "ahdr" is also created. If OUT is NULL, a file name will be built based on the satellite ID, date and time.

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

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

QUADNUM(5)
Quadrant number. The quadrant number that indicates the area that the latitude range should be selected from.

    = 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. In those cases, AREAOPT is used to indicate which crossing is to be selected.

    = FIRST:   First area of interest
    = SECOND:  Second area of interest

CHANS(--)
Satellite channels. This is a sequential list of channels to be extracted from each input file. Values in NCHANS indicate how many channels in the list apply to each input file. The default writes all five channels of the archive image.

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.

Examples:

  1. LAS> ingest1b-line infile=image

    The disk file IMAGE;L1B will be converted to an archive image. The entire file will be converted since all windowing options are left as default. The output image name will be built from the scene ID.

  2. LAS> ingest1b-line comment="please mount tape a12345" infile=--

    All Level 1b files on tape A12345 will be converted to archive images. Each file will be converted completely since windowing options are default. Each image name will be built from the scene ID.

  3. LAS> ingest1b-line infile=(image1, image2, image3) out=(arc1, arc2, arc3) chans=(1, 1, 2, 3, 2, 4) nchans=(1, 3, 2)

    Three Level 1b files: IMAGE1;L1B, IMAGE2;L1B and IMAGE3;L1B will be converted to archive images. Output images will be named with prefixes arc1, arc2 and arc3. Band windowing is specified as band 1 for arc1; bands 1, 2 and 3 for arc2; and bands 2 and 4 for arc3.

  4. LAS> ingest1b-latlong comment="please mount tape a12345" filenum=(3, 7, 14) fileflg=select infile=-- slat=25.0 slong=14.0 elat=20.0 elong=54.0

    The 3rd, 7th and 14th files on tape A12345 will be converted to archive images. Each file will be windowed with the same specification. The window specified is a rectangular area whose upper left corner is 25.0 degrees north latitude, 14.0 degrees east longitude, and whose lower right corner is 20.0 north latitude, 54.0 degrees east longitude. Each image will be named based on its windowed scene ID.

  5. LAS> ingest1b-latrange comment="please mount tape a12345" filenum=(1, 5) fileflg=range infile=-- slat=(10.0, -10.5, 0.0, 20.0, 25.5) elat=(-10.0, -20.0, -10.0, 0.0, -10.0)

    The 1st through the 5th files on tape A12345 will be converted to archive images. Each file will be windowed with a different specification. File 1 will contain the lines in the area between 10.0 and -10.0 degrees latitude. File 2 will have lines between -10.5 and -20.0 degrees latitude and so on. The image names will be based on their windowed scene ID's.

Description/Algorithm:

Input parameters are checked for proper number and specification. If more than one input image is specified as well as default windowing, the defaults are applied to all input files. A loop is entered that calls INGEST1B_ once for each input image. The loop terminates when all input is processed or when an end of tape or end of volume is encountered.

To create a Level 0 archive file from a Level 1b tape or disk image, the specified Level 1b file is opened for reading and the AVHRR model is filled based on the image header records. If the input file is on tape, the appropriate number of files are skipped. The user requested bands are checked against the bands that exist in the image. A window is calculated based on the parameters specified for the subcommand -- LINE, LATLONG, or LATRANGE. The Level 0 archive file is opened for writing.

Each line of the input image that is in the specified window is read. The bands are extracted from the input line and the resulting line is converted to the Level 0 format and written to the output file. Dropped lines (zero-filled) are also written where necessary and a dropped line structure is built. Note that there are only two line formats in Level 0 files -- GAC and LAC/HRPT. Therefore output files with the same window parameters and input file will be the same size regardless of any sub-banding. The missing band information is simply zero-filled.

When line processing is complete, the associated file is created from the AVHRR model and dropped line structure and written to disk. The input and output images are closed and the output images are renamed to the user specified name or they are given a name based on the satellite ID, date and time.

Nonfatal Error Messages:

  1. [ingest1b-close] Error closing <xxxxxxx>.

    An error occurred closing a file. If more than one input image is specified, processing will continue with the next image.

  2. [ingest1b-dupl] Duplicate channel specified.

    The same channel was specified more than once. Processing will continue but the channel will not be duplicated in the output.

  3. [ingest1b-gaps] The number of dropped line gaps exceeds the limit of MAX_GAPS (2165) at line <n>.

    The number of dropped line segments within the image exceeds the maximum, MAX_GAPS. Contact the system administrator.

  4. [ingest1b-renm] Error renaming output file <xxxxxxx>.

    A system rename error occurred. The temporary filename will be used for the file. Check with system administrator if problem persists.

  5. [ingest1b-warn] Error writing archive header file.

    Processing continues. The archive header may not be valid.

  6. [ingest1b-wind] Error creating windowed model.

    An error occurred while determining a windowed model. Processing continues but the model, and subsequently the archive header, may not be valid.

Fatal Error Messages:

  1. [ingest1b-alloc] Error allocating dynamic memory.

    An error occurred trying to dynamically allocate memory. Contact the system administrator.

  2. [ingest1b-cnot] Specified channel <x> not in input file.

    The specified channel is not present in the input file. Remove the channel from the CHANS parameter and re-run.

  3. [ingest1b-inf] Input file does not exist.

    Check that the input file was entered correctly or is in the proper directory.

  4. [ingest1b-open] Error opening <xxxxxxx>.

    Unable to open the indicated file. If the file is an input, make sure it exists or was properly entered in the parameter. For output files insure there is sufficient disk space before continuing.

  5. [ingest1b-read] Error reading first line.

    The first line of the image could not be read. If reading from tape, check with the operator to make sure the tape is mounted the tape unit is operating properly.

  6. [ingest1b-rprm] Error returning parameter to TAE.

    An error occurred when returning the tape status to TAE. Contact the system administrator.

  7. [ingest1b-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.

  8. [ingest1b-seek] Error locating first line.

    An error occurred locating the starting line of the input image. If reading from tape, check with the operator to make sure the tape is mounted and the tape unit is operating properly.

  9. [ingest1b-skip] Error skipping to file on tape.

    An error occurred while skipping to the next file on tape. Check with the operator to make sure the tape is mounted and the tape unit is operating properly.

  10. [ingest1b-windp] Error converting window parameters.

    The input parameters could not be converted to an image window. The error message preceding this one is the specific error. The specified window did not intersect the imaage or was completely outside the image. Retry with restricted input parameters.

  11. [ingest1b-write] Error writing archive.

    An error occurred writing to the archive image. Check that there is sufficient disk space before continuing.

User Notes:

  1. Windowing of the image in the sample direction is not allowed.

  2. HRPT and LAC Level 1b tapes have the same data format.

  3. See the NOAA Polar Orbital User's Guide for a description of the Level 1b tape format.

  4. If line numbers acquired from the records in the input file are not in sequence, dropped lines are inserted into the output image to make up the difference.

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

  6. INGEST1B will terminate when an EOV mark or EOT mark is encountered on the tape, or when NL lines of data have been read. The line count found in the data set header record is used only for verification.

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

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

  9. Archive files created from the same Level 1b image but windowed in the channels, will be the same size. The channels not present in the archive file are substituted with zero values.

  10. 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 does not 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.

  11. 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 the user specified.

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

  13. Windowing is done by finding the time stamp range from the specified inputs. Windowing is done relative to a North up image. In other words, for an ascending image, the windowed lines are counted from the end of the file, instead of the beginning.

  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.