User's Guide

LTWGIN

Reads LTWG full-scene formatted images.

Function:

Reads LTWG (Landsat Technical Working Group) full scene images and SAR (Synthetic Aperture Radar) 8-bit imagery from tape, CD or disk and creates LAS images. All of the bands are written to one image or each band may be written to its own image. The existing image may be windowed or subbanded when copied. Ancillary files may also be written to disk.

Parameters:

COMMENT(-- )
Description of tape(s) or CD(s). A text string sent to the operator's terminal describing the tape(s) or CD(s) to be mounted. COMMENT should contain the tape/CD library identification number and a short description of the media. This will allow the operator to ensure the correct media is mounted. If the source media is disk, leave this field blank. See User Notes 2 and 3.

INFILE(-- )
The full host pathname of the input image on disk. If the source media is tape or CD, leave this field blank. If COMMENT is specified as well as INFILE, the mounting comment will take precedence and be used to ingest from tape and INFILE will be ignored. Depending on the ground station and/or image format, this may be either a directory or a root filename.

DIRNUM(--)
Number of the scene to ingest (directory number). This should only be used when processing from CD. If COMMENT is specified as well as DIRNUM, the mounting comment will take precedence and be used to ingest from tape and DIRNUM will be ignored. If there is only one scene on the CD, it is not necessary to provide a value for this parameter. If multiple scenes are on the CD, the user may use this parameter to specify the number of the directory which contains the file they wish to ingest (which scene). See User Note 9.

OUT
Output image(s). OUT defines up to seven LAS images. The number of images specified in OUT must either be one or equal to the number of bands specified in BANDS. If only one output image is specified, all of the bands will be written to that image. The size of the output image(s) is determined by information from the leader file or the values specified in WINDOW and BANDS. The output data type is BYTE.

WINDOW(--)
Window specification. Specifies the starting line, starting sample, number of lines, and number of samples to be processed. The default indicates that the entire image will be processed.

BANDS(--)
Band number(s). The image bands to be processed. The default indicates that all bands present are processed. See User Note 4.

WRTDSK(LEAD)
Write to disk. Specifies which associated files/or records are to be copied from the media. These files are associated with the output image with the specified extensions. Any combination of these files may be specified.

  = VDF:  Volume Directory file.  The volume directory file is 
          written to "<xxxxx>;vdf". 
  = LEAD: Leader file.  The leader file is written to 
          "<xxxxx>;lead".
  = TRAI: Trailer file.  The trailer file is written to 
          "<xxxxx>;trai".  See User Note 3.
  = SUPP: Supplemental file. The supplemental file is written 
          to "<xxxxx>;supp".  See User Note 3.
  = IDR:  Image Data Records.  The image file descriptor record 
          and the prefix and suffix data from each image line are 
          written to "<xxxxx>;idr".

Example:

  1. LAS> ltwgin comment=("bb0707","bb0705") out="tai.image" window=(100,100,1024,1024) bands=(2 4)

    The tape bb0707 is mounted on a drive. The user has specified that a 1024x1024 window be copied from tape starting at line 100, sample 100. Only bands 2 and 4 will be copied to TAI.IMAGE. By default, the leader file will be copied to the disk. Because the trailer and supplemental files are not being copied, only those tapes that contain bands 2 and 4 (bb0707 and bb0705) need to be specified.

  2. LAS> ltwgin infile="[sg2@cd1.scene11]" out="mada" wrtdsk=(lead trai vdf supp)

    LTWGIN reads image data from the directory /sg2@cd1/scene11 and creates a LAS image in the current directory. Since no window or band specifications are provided, the entire image will be copied. LTWGIN will also copy the image leader, trailer, supplemental, and volume directory files.

  3. LAS> ltwgin comment=("119567") out=("band1","band3") bands=(1,3)

    The tape 119567 is mounted on a drive. Band 1 will be copied to band1 and band 3 will be copied to band3. Since no window or band specifications are provided, the entire image will be copied. By default, the leader file will be copied to the disk.

  4. LAS> ltwgin comment=("cd3825") dirnum=4 out="img1"

    CD3825 will be mounted on a drive. The imagery contained in the fourth directory (Scene4) will be ingested. Since no window or band specifications are provided, the entire image will be copied to the output image "IMG1.img". By default, the leader file will be copied to the disk.

  5. LAS> ltwgin comment=("cd3825") out="img2"

    CD3825 will be mounted on a drive. Since no directory number was specified for which scene to ingest, scene 1 will be ingested. Since no window or band specifications are provided, the entire image will be copied to the output image "IMG2.img". By default, the leader file will be copied to the disk.

Description/Algorithm:

LTWGIN begins by opening the media if the image is to be ingested from tape or CD. If the image data is in a CD or standard disk directory, the filenames in that directory are scanned so that LTWGIN can determine which file naming convention is being used. The volume directory file (VDF) and the leader file are read to obtain necessary processing information, i.e., band format, record size, etc.. These files are written to disk if requested, will be associated with the first output LAS image, and will have the extensions ";VDF" and ";LEAD".

The image file descriptor record is then read to obtain image size, band count, data type, blocking factor, and the number of prefix and suffix bytes within each image line. This record is written to disk if requested, will be associated with the first output LAS image, and have the extension ";IDR".

The output LAS image(s) are created and opened for writing. For each line and band to be read, the image data is extracted from the physical tape record or CD/disk file and written to disk. If specified, the image data suffix and prefix data for each image line is written to disk in the ";IDR" file.

Once all the requested image data is read, the trailer and supplemental files are copied to disk if they were requested. These files will be associated with the first output LAS image and will have the extensions ";TRAI" and ";SUPP". If the image is being read from tape, the third tape is mounted if necessary to read these files.

Nonfatal Error Messages:

  1. [ltwgin-band] Band <x> does not exist in image

    The band entered in BANDS does not exist in the image. Processing will continue with the remaining bands being copied from the image.

  2. [ltwgin-bands] Only three bands are available

    SPOT scenes created by the Sweden receiving station only have three bands instead of the seven expected for LGSOWG data.

  3. [ltwgin-bands] Only four bands are available

    South Africa CDs and Canadian and Japanese MSS data only have four bands instead of the seven expected for LGSOWG data.

  4. [ltwgin-corn] Corner coordinates will be approximate

    The image did not contain map projection information. The corners of the image will be approximated. See User Note 5.

  5. [ltwgin-nonfatal] Nonfatal error encountered

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

  6. [ltwgin-proj] Unable to determine projection information

    The image did not contain projection information or the projection is not currently handled by LTWGIN. The image will be created with an invalid DDR. Contact the LAS system administrator.

  7. [ltwgin-supp] No supplemental file

    The specified media did not contain a supplemental file and WRTDSK specified that one should be written to disk. Processing continues.

  8. [ltwgin-supp] Thailand data has no supplemental file

    LTWG data created by the Thailand receiving station is missing the supplementary data file. Unable to write the requested file to disk.

  9. [ltwgin-window] Specified window is too large

    The specified window is larger than the image data on the media. The window has been reset to be the intersection of the window specification and the actual image.

  10. [ltwgin-station] Station unrecognized - assuming CANADA

    The Station ID was not recognized, CANADA was assumed.

  11. [ltwgin-fileskip] Error skipping files on tape

    There was an error reading the imagery data from tape. The tape format does not agree with the format expected by ltwgin.

  12. [ltwgin-ddrinfo] Could not retrieve the <xxxxx>

    An error occurred while attempting to use sscanf to retrieve the indicated value from the leader file. Certain DDR fields may not be able to be filled in due to this value being unavailable.

  13. [ltwgin-ddrinfo] The <xxxxx> record was not present; some DDR information will not be available

    The indicated leader file record was not present. Certain DDR fields will not be able to be filled in due to the missing record.

  14. [ltwgin-info] CD contains multiple scenes and the scene to ingest was not specified. Ingesting scene1. See User Note 9.

    The user did not specify which scene to ingest from the given CD, which contains multiple scenes. Defaulting to scene 1. More information can be found in User Note 9.

Fatal Error Messages:

  1. [ltwgin-alloc] Error allocating dynamic memory

    An error occurred allocating memory. Re-run, and if the error persists, contact the LAS system administrator.

  2. [ltwgin-count] Invalid number of tapes specified

    The next tape in the volume is needed to continue processing. Enter all the tape IDs of the tape set in COMMENT and re-run.

  3. [ltwgin-diskread] Error reading from disk

    An error was encountered reading from disk, either while trying to open an expected input file or while reading data from one of those files. Verify that the disk or CD is good and conforms to one of the supported directory formats.

  4. [ltwgin-dtype] Data type not handled

    The data type of the image is not currently handled by LTWGIN. Only BYTE is currently handled. Contact the LAS system administrator.

  5. [ltwgin-fatal] Fatal error encountered

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

  6. [ltwgin-notsup] Non-SPOT data from this receiving station not supported

    Certain data from Sweden receiving station, with "Sweden" (vs "Kiruna" which has also been encountered, but is not SPOT data) in the generating country identification string, and from France, with "France" in the id string, in the VDF file is assumed to be SPOT data, since this is true for the data encountered. Assumptions are made throughout the code that all data matching these criteria is SPOT data. If data with one of those id strings who's satellite name is not SPOT is encountered, it cannot be processed.

  7. [ltwgin-read] Error reading from tape

    An error was encountered reading from tape. Verify that the tape is good and conforms to the LTWG tape format.

  8. [ltwgin-skip] Error skipping records

    An error was encountered skipping to the correct location on the tape. Verify that the tape is good and conforms to the LTWG tape format or re-run and do specify a window.

  9. [ltwgin-zero] Zero total bands specified

    No bands specified in BANDS were available in the input image. Respecify BANDS and re-run.

  10. [ltwgin-bndcnt] Number of output images must equal number of bands specified

    If more than one output image is specified, the number of output images must equal the number of bands specified. Respecify OUT and/or BANDS so that the number of output images is equal to the number of bands specified if one band per image is desired, otherwise specify only one OUT image.

  11. [ltwgin-project] Map projection not currently supported

    The map projection used for the image is not currently supported by LAS. The image cannot be ingested using ltwgin.

  12. [ltwgin-numlead] Number of records doesn't match that reported by the VDF file

    The number of leader file records reported by the leader file descriptor record does not match the number of leader file records reported by the VDF file. The data is invalid and cannot be ingested by ltwgin.

  13. [ltwgin-numtrai] Number of records doesn't match that reported by the VDF fle

    The number of trailer file records reported by the trailer file descriptor record does not match the number of trailer file records reported by the VDF file. The data is invalid and cannot be ingested by ltwgin.

  14. [ltwgin-getfiles] Error retrieving filenames from disk

    There was an error encountered when using c_getfiles to retrieve the filenames on disk or CD. Verify the filenames follow the expected format.

  15. [ltwgin-write] Error writing to the trailer file

    There was an error encountered when writing to the trailer file. Verify all files are present and follow the expected format.

  16. [ltwgin-radar] Radarsat data not yet fully supported

    The Radarsat data products are not fully supported yet. If the user sees this error message, the code erroneously determined that Radarsat data is being ingested. Contact the LAS system administrator.

  17. [ltwgin-tpopen] Error mounting the media

    There was an error encounted when mounting the media. Try again and, if the problem persists, contact the LAS system administrator.

  18. [ltwgin-scene] Error determining which scene to ingest

    The directory name of the scene selected, or the directory name for the default of scene 1 was not able to be identified on the CD. Refer to the previous error message for more details of what caused the error.

  19. [ltwgin-scene] Could not locate scene <xxx> on CD

    The specified scene or, if user did not specify which scene to ingest, the default scene 1 was not found on CD. Verify the CD follows the expected format for the scene directories. If the CD contains NLAPS Level 0 data as produced by PDS, this data is not supported yet; contact the LAS administrator.

  20. [ltwgin-hostnam] Error reading the hostname

    The CD drive returned from the mount was a local drive. In order to read from the drive, the host name of the machine the drive is on must be determined. The host name could not be retrieved and processing cannot continue. Try running again on another drive and contact the LAS administrator if the problem persists.

  21. [ltwgin-nodirs] No valid scene directories could be located

    The CD was searched for scene directories and none were found. Verify the directory layout on the CD follows the expected format.

User Notes:

  1. For further information on the LTWGIN format, consult:

    Documents of the LANDSAT-D CCT Standards Committee Presented to the LANDSAT Ground Station Operators Working Group, Draft, August 15, 1978.

    LANDSAT Technical Working Group, Format for the Thematic Mapper CCT, EOSAT, January 1, 1990.

    SPOT Image Corporation, Abbreviated CCT Document, February 9, 1990.

    Synthetic Aperture Radar (SAR) Data Products Format Standard, CEOS-SAR-CCT, March 10, 1989.

    RADARSAT Data Products Specifications, RSI-GS-026, November 7, 1997.

  2. For BSQ tapes, only the tapes with the desired bands need to be mounted unless an image file spans two tapes. For BIL tapes, the first tape in the set must be specified to obtain needed processing information.

  3. If either the trailer or supplemental file are requested, LTWGIN requires that all tapes in the tape set be specified because it retrieves these files from the last tape in the set. If problems are encountered when these files are requested, it is recommend that no subbanding or windowing be specified to allow for a successful run of the different variations of LTWG tapes.

  4. SPOT data, level 1A and 1B, both panchromatic (PAN) and multispectral (XS) can be ingested with this routine.

  5. In some instances, the corner information that is stored in the DDR file is only an approximation. The accuracy of the corner coordinates is unknown. Even though the accuracy is unknown, the corner information is placed in the DDR file because it can be used to provide a rough location of the image. The projection information of the image is unknown. The projection information is provided in the DDR to approximate geographic information of other pixels.

  6. The maximum number of image bands on tape that can be handled by LTWGIN is seven.

  7. A related function is DSPASSOC.

  8. LTWGIN may experience some difficulty ingesting image data from foreign receiving stations, as said data may contain slight deviations from the standard LTWG format. LTWGIN will identify and adjust for some of these discrepancies.

  9. When ingesting data from a CD that has multiple scenes on it, the user may specify the scene they wish to ingest in the DIRNUM parameter. If the CD contains multiple scenes and the user fails or does not wish to specify a scene, scene 1 will be ingested by default. When ingesting data from a CD that has only a single scene on it, this parameter does not need to be specified, nor should it be used when processing from tape or disk either.