User's Guide

MKLEVEL1B

Generate Level 1b file(s) on disk or ANSI labeled tape

Function:

Generate Level 1b file(s) on disk or ANSI labeled tape from AVHRR archive image(s). Associated data are also written, including the terabit memory (TBM) header or, for KLM series satellites, the Archive Retrieval System (ARS) header, the data set header, dropped line information, telemetry data, sun zenith angles, earth location data, and calibration coefficients. This program can be used to create tapes or disk files for HRPT, LAC, and GAC images. The input image may be sub-banded. Three windowing options are available in the following subcommands:

  LINE      The window is specified by starting and
	    ending line.
  LATLONG   The window is specified by starting and
	    ending latitude and longitude.
  LATRANGE  The window is specified by minimum and
	    maximum latitudes.

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 ANSI labeled tape. A text string sent to the operator's terminal describing the tape to mount. If a new tape is being created, the comment should indicate the type of tape to be used. For example, "please mount a 8MM ANSI labeled tape." If there is a specific tape the images are to be placed on, then the comment should contain the tape library identification number and a short description of the tape. This will allow the operator to ensure that the correct tape is mounted. If more than one tape will be required, the same comment will be used to request another tape when the first is full. If COMMENT is defaulted, INFILE must be specified.

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.

SUMFLG(NO)
Summary flag. Determines whether or not a product summary is printed for each individual scene that is written.

MVOLFLG(YES)
Multi-volume flag. Indicates whether more than one tape may be used for the order. The available options are:

  = YES: Multiple tapes may be used for this tape set.

  = NO:  Only one tape will be used.  If logical tape end
	 is reached, processing stops and remaining part
	 of image is not written to tape.

Note: single images will not be split across multiple tapes.

ACCTNUM(--)
Account number. The account number to which this order will be sent and billed.

ORDERNUM(--)
Order number. The order number that includes this item.

UNITNUM(--)
Unit number. The Level 1b unit number of the specified order.

ADDRESS(--)
Shipping address. This address will be printed on the tape label and the shipping form.

PRODESC(LEVEL1B)
Product description. A description of the Level 1b product which will appear on the Product Summary. If there is a special description for the product, it should be placed in PRODESC.

TAPEDENS(&$TPDENS)
Tape density. The density of the tape in bytes per inch. The default is defined by the TAE global $TPDENS. The list of valid densities are defined by the TAE global $TPVAL.

  = 0:    drive default
  = 800:  800 bpi
  = 1600: 1600 bpi
  = 6250: 6250 bpi

TTYPE(&$TTYPE)
Tape type. Type of tape that is to be stacked. The default is defined by the TAE global $TTYPE. The list of valid tape types is defined by the TAE global $TTYPEVAL.

MAXBYTES(&$MAXBYTES)
Maximum megabytes. The maximum number of megabytes that can be written to a tape. The default is defined by the TAE global $MAXBYTES. The list of valid values for each tape type is defined by the TAE global $MAXBYTESVAL.

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 ANSI labeled tape. A text string sent to the operator's terminal describing the tape to mount. If a new tape is being created, the comment should indicate the type of tape to be used. For example, "please mount a 8MM ANSI labeled tape." If there is a specific tape the images are to be placed on, then the comment should contain the tape library identification number and a short description of the tape. This will allow the operator to ensure that the correct tape is mounted. If more than one tape will be required, the same comment will be used to request another tape when the first is full. If COMMENT is defaulted, INFILE must be specified.

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.

SUMFLG(NO)
Summary flag. Determines whether or not a product summary is printed for each individual scene that is written.

MVOLFLG(YES)
Multi-volume flag. Indicates whether more than one tape may be used for the order. The available options are:

  = YES: Multiple tapes may be used for this tape set.

  = NO:  Only one tape will be used.  If logical tape end
	 is reached, processing stops and remaining part
	 of image is not written to tape.

Note: single images will not be split across multiple tapes.

ACCTNUM(--)
Account number. The account number to which this order will be sent and billed.

ORDERNUM(--)
Order number. The order number that includes this item.

UNITNUM(--)
Unit number. The Level 1b unit number of the specified order.

ADDRESS(--)
Shipping address. This address will be printed on the tape label and the shipping form.

PRODESC(LEVEL1B)
Product description. A description of the Level 1b product which will appear on the Product Summary. If there is a special description for the product, it should be placed in PRODESC.

TAPEDENS(&$TPDENS)
Tape density. The density of the tape in bytes per inch. The default is defined by the TAE global $TPDENS. The list of valid densities are defined by the TAE global $TPVAL.

  = 0:    drive default
  = 800:  800 bpi
  = 1600: 1600 bpi
  = 6250: 6250 bpi

TTYPE(&$TTYPE)
Tape type. Type of tape that is to be stacked. The default is defined by the TAE global $TTYPE. The list of valid tape types is defined by the TAE global $TTYPEVAL.

MAXBYTES(&$MAXBYTES)
Maximum megabytes. The maximum number of megabytes that can be written to a tape. The default is defined by the TAE global $MAXBYTES. The list of valid values for each tape type is defined by the TAE global $MAXBYTESVAL.

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 ANSI labeled tape. A text string sent to the operator's terminal describing the tape to mount. If a new tape is being created, the comment should indicate the type of tape to be used. For example, "please mount a 8MM ANSI labeled tape." If there is a specific tape the images are to be placed on, then the comment should contain the tape library identification number and a short description of the tape. This will allow the operator to ensure that the correct tape is mounted. If more than one tape will be required, the same comment will be used to request another tape when the first is full. If COMMENT is defaulted, INFILE must be specified.

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.

SUMFLG(NO)
Summary flag. Determines whether or not a product summary is printed for each individual scene that is written.

MVOLFLG(YES)
Multi-volume flag. Indicates whether more than one tape may be used for the order. The available options are:

  = YES: Multiple tapes may be used for this tape set.

  = NO:  Only one tape will be used.  If logical tape end
	 is reached, processing stops and remaining part
	 of image is not written to tape.

Note: single images will not be split across multiple tapes.

ACCTNUM(--)
Account number. The account number to which this order will be sent and billed.

ORDERNUM(--)
Order number. The order number that includes this item.

UNITNUM(--)
Unit number. The Level 1b unit number of the specified order.

ADDRESS(--)
Shipping address. This address will be printed on the tape label and the shipping form.

PRODESC(LEVEL1B)
Product description. A description of the Level 1b product which will appear on the Product Summary. If there is a special description for the product, it should be placed in PRODESC.

TAPEDENS(&$TPDENS)
Tape density. The density of the tape in bytes per inch. The default is defined by the TAE global $TPDENS. The list of valid densities are defined by the TAE global $TPVAL.

  = 0:    drive default
  = 800:  800 bpi
  = 1600: 1600 bpi
  = 6250: 6250 bpi

TTYPE(&$TTYPE)
Tape type. Type of tape that is to be stacked. The default is defined by the TAE global $TTYPE. The list of valid tape types is defined by the TAE global $TTYPEVAL.

MAXBYTES(&$MAXBYTES)
Maximum megabytes. The maximum number of megabytes that can be written to a tape. The default is defined by the TAE global $MAXBYTES. The list of valid values for each tape type is defined by the TAE global $MAXBYTESVAL.

Examples:

  1. LAS> mklevel1b-line infile=(al14070297131200, al14070297131438) comment="please mount a 8mm ansi labeled tape" mvolflg=no acctnum="123456789" ordernum="91121800004" unitnum=3 ttype=8hi address=("address line 1","address line 2","address line 3")

    The two images will be written to 8MM tape. All five channels, all lines and samples will be written since channel and line specifications are defaulted. Multiple volumes are not allowed. This tape is being created for account number 123456789, unit three, of order 9112180004. Default PRODESC is "LEVEL1B", and the default tape density will be used. Product summary information will not be printed. Order will be sent to the address specified.

  2. LAS> mklevel1b-latlong infile=ag14102297082302 chans=(1,2,3) nchans=3 slat=25.0 slong=14.0 elat=20.0 elong=54.0 sumflg=yes

    Channels 1, 2 and 3 of the image ag14102297082302 will be written to disk. 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. The output file name will be based on the time and date of the first line of the resulting image. A product summary file will be created and printed. No accounting or address information is provided and will be blank on the summary report.

  3. LAS> mklevel1b-latrange infile=ag14102297082302 outfile=xxx slat=20.0 elat=25.0

    All channels of ag14102297082302 will be written to the disk file XXX;L1B. The window specified will be the area in the image between 25.0 degrees north latitude and 20.0 degrees north latitude, including all longitude ranges (all samples across a line). No product summary information will be created or printed.

  4. LAS> mklevel1b-line infile=(arc1,arc2,arc3) chans=(1,1,2,3,2,4) nchans=(1, 3, 2)

    Three archive images: ARC1, ARC2, and ARC3 will be converted to Level 1b images. The output file names will be based upon their respective scene ID's. Band windowing is specified as band 1 for ARC1; bands 1, 2 and 3 for ARC2; and bands 2 and 4 for ARC3.

Description/Algorithm:

To create a Level 1b tape or file, the specified AVHRR archive format image is opened for reading. The appropriate window of the image is calculated and the AVHRR model is filled.

The two header records are created from a windowed model. The first is a 122-byte terabit memory (TBM) or, for KLM series satellites, a 512-byte Archive Retrieval System (ARS) header, that includes the type of data, satellite ID, starting and ending latitude and longitude, channels selected, and start and stop date and time of the selected window. The second record is the data set header, that also describes the data set and is the same length as the image data records. The output is opened for writing and the header records are written. For non-KLM LAC and HRPT data, an extra dummy header record the same length as the image data record is written to create a set of two records in a format similar to the LAC/HRPT image data records (see below). Non-KLM data and GAC data does not require this dummy header because their image data records are not in sets of two.

Next, the actual image data are written. One line of image data includes the line number, time stamp code, calibration coefficients, zenith angles, earth location data, telemetry data, and the actual pixel values. The length of a line of image data depends on the data type, number of channels, and whether or not the data is packed. For non-KLM GAC data, two lines of the image are written into physical one record; for non-KLM LAC and HRPT data, one line of the image is written into two physical records. All KLM data contain one line of data per record. If less than five channels have been specified, the image data are written in an unpacked format as one ten-bit pixel value in one 16-bit word. If five channels are specified, the data may be written in unpacked format, or may have three ten-bit pixels packed into one 32-bit word. If the logical end of the tape is encountered during writing, another tape will be requested if MVOLFLG is YES. Processing will stop if MVOLFLG is NO.

After all the desired lines have been written, the input and output files are closed. A label for each tape is created and a Level 1b product summary is generated.

Nonfatal Error Messages:

  1. [mklevel1b-imgcler] Error closing archive image

    An error occurred trying to close the archive image file. Check with system administrator if problem persists.

  2. [mklevel1b-ltend] Logical tape end reached

    The logical tape end, parameter MAXBYTES, was reached before writing the entire image. If MVOLFLG is YES another tape will be mounted and the full scene will be written to the new tape. If MVOLFLG is NO processing stops. The partial image is left on the first tape (see user note 4).

  3. [mklevel1b-renm] Error renaming output file

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

  4. [mklevel1b-vbupder] Error updating variable block

    The TAE variable block was not updated properly. Check with system administrator if problem persists.

Fatal Error Messages:

  1. [mklevel1b-bdimagwr] Error writing image line

    An error occurred trying to write the image data to tape or disk file. If writing to tape, contact the operator to see if the tape and drive are functioning correctly. If writing to disk, ensure there is enough disk space for the output file.

  2. [mklevel1b-cfncalc] <xxxx> coefficients were not calculated

    The specified thermal or optical coefficients were not calculated due to errors in the calculation routines. Ensure the OSS, DGRD table and calibration file for the satellite exist in the ADAPSTABLES directory.

  3. [mklevel1b-env] Error retrieving ADAPSTABLES

    MKLEVEL1B was unable to retrieve the value of the specified environment variable. Ensure the variable is set.

  4. [mklevel1b-exists] <xxxx> already exists

    The output file specified already exists. Change the output file name or rename existing file.

  5. [mklevel1b-fatal] Fatal error encountered

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

  6. [mklevel1b-open] Error opening <xxxx>

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

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

User Notes:

  1. 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 MINLAT as the latitude before crossing the pole and MAXLAT as the latitude after crossing the pole. An area of interest crossing both poles (8) will use MINLAT as the latitude before crossing the first pole encountered and MAXLAT as the latitude after crossing the other pole.

  2. The standard Level 1b product has 2048 samples for LAC/HRPT data and 409 samples for GAC data. The window specified by the user may not include all samples across a scan line, but the actual window written will include the entire line. The user-specified window will be recorded on the Product Summary.

  3. If a latitude range specified for a certain quad 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.

  4. When the MVOLFLG is set to YES and all files will not fit on a single tape, partial files may be present at the end of all but the last tape in the set. This is due to peculiarities in certain tape drives that do not allow proper back spacing. To skirt this problem, when logical tape end is reached the drive is simple closed and the current file is put on the next tape in the set.

  5. A Level 1b tape or file is created in response to a customer order for AVHRR data. The customer's account number, the order number, and the unit number of that order are recorded on the Product Summary and tape labels. If the Level 1b tape/file is not being generated for an order, the user may enter dummy values for ACCTNUM, ORDERNUM, and UNITNUM.

  6. For more information about the Level 1b format, refer to the NOAA Polar Orbital User's Guide.

  7. To ensure that tapes generated by MKLEVEL1B can be uniquely identified, only ANSI labeled tapes may be used when specifying tape as the output media.

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