User's Guide

Convert a Landsat-7 HDF file to LAS image(s).

Function:

L7HDF2LAS receives a Landsat-7 HDF image file from disk or CD and converts it to LAS image(s).

Parameters:

COMMENT(--)
Description of CD(s). A text string sent to the operator's terminal. The operator uses this text to find the CD(s) to be mounted. Therefore, COMMENT should be as descriptive as possible. It should include both the ID number and a short description which allows the operator to ensure the correct media is mounted. If multiple media are specified the user must specify them so that the image data is in band sequential order. These comments should be comma-separated and one comment for each CD to mount. For example, COMMENT=("Please mount CD1/4", "Please mount CD2/4", "Please mount CD3/4", "Please mount CD4/4") If the source media is disk, leave this field blank.

INFILE(--)
The full unix pathname of the input image on disk or CD. Windowing and banding is not supported in the filename. The user must specify windowing and banding using the WINDOW and BANDS parameters. Only one HDF filename may be specified for INFILE. INFILE is case-insensitive, however the L0R, L1R, and L1G DFCBs specify the base filename must be upper case lettering. If lower case is found in the HDF file name, L7HDF2LAS will create upper-case links to the lower-case file names and use the links to process the files to work around HDF format limitations.

The user may leave INFILE blank if a CD is being mounted with a COMMENT. In this case, the file name will be searched for on the CD. If the data is on disk or locally mounted CD, at least the path to the data needs to be specified and a portion of the input file name. L7HDF2LAS will search the directory for HDF files that match the partial name specified. For either CD or disk, if more than one HDF file is found, then only the first HDF file will be processed.

BANDS(--)
Band numbers. List of band numbers to be placed into the LAS image(s). The default indicates that all available bands will be processed. For Landsat-7 the valid list of bands are 1, 2, 3, 4, 5, 61, 62, 7, and 8. Optionally, 6 may be entered for band 61, and 9 may be entered for 62.

NBANDS(--)
NBANDS specifies how the bands in the BANDS parameter should be grouped together when creating the output files. For example, if BANDS=(1,3,2,4) and NBANDS=(2,1,1), three output files will be created with the first output file containing bands 1 and 3, the second containing band 2, and the third containing band 4. If NBANDS is specified, BANDS must be specified and the number of bands in BANDS must equal the sum of the bands in NBANDS. Also the number of NBANDS entries must match the number of entries in OUT.

WINDOW(--)
If UNITS is LS, the window specifies the start line, start sample, number of lines, and number of samples for the window. If only the start line and sample are entered, the number of lines and number of samples will default to the end of the image. If UNITS is not LS, the window specifies the upper left Y, upper left X, lower right Y, and lower right X coordinates. If the WINDOW is not specified, it defaults to the entire image. If a window is specified, it is applied to all of the bands.

In the case of specifying line/sample, if all bands are of the same resolution, then the window values shall be specified for that resolution. If the bands are not of the same resolution, then the window values shall be specified for the visible bands (even if no visible bands are being processed). The line/sample window values for the thermal and pan bands will be calculated from the values specified for the visible bands. The relationship (2N-1, N, 4N-3) for (30m, 60m, 15m) will be used for these calculations.

UNITS(LS)
Units for the WINDOW parameter.

  = LS:  Line/Sample
  = DEG: Degrees
  = DMS: Degrees Minutes Seconds
           (+DDDMMMSSS.SS)
  = PRO: Projection coordinates

OUT
Pathname of the output LAS image. The number of images specified in OUT must either be one, equal to the number of input bands specified in BANDS (if NBANDS is not specified), or equal to the number of band groupings specified in NBANDS. OUT may be specified in either TAE format or UNIX format. A .img extension will automatically be added as the extension to OUT. If $DELFLG is set and an error occurs, then all output files created by this application will be automatically deleted.

ODTYPE(SAME)
Output data type. The data type of the output images. When processing L1R imagery (which is scaled 16-bit), if the user chooses to output the image as byte data the pixels will be truncated to fall between 0 and 255.

  = SAME: Same as input
  = BYTE: BYTE      (8-bit unsigned integer)
  = I*2:  INTEGER*2  (16-bit signed integer)
  = I*4:  INTEGER*4  (32-bit signed integer)
  = R*4:  REAL*4     (32-bit signed real)

PTYPE(--)
This parameter MAY be required. IAS, LPGS and NLAPS do not report the corner coordinates for SOM projection in the metadata files (MTL) the same. This software can detect how to calculate the corner coordinates only if the PROCESSING_SOFTWARE parameter exists in the MTL file. Some older versions of MTL metadata files do not have this parameter, so it will rely on the user for this information. This parameter will be ignored if the PROCESSING_SOFTWARE parameter exists.

The following are a couple of examples of how to distinguish between these products. This information can be found on the jewel case insert.

    NLAPS - order numbers starting with 011 or 080
    LPGS - order number starting with 074 or 034

Example:

  1. LAS> infile="/sg1/csb3/l0r/l72edc139912815010_hdf.17431ad" out="[sg1.csb3.las.output]l0rout"

    The input Landsat-7 HDF image file L72EDC139912815010_HDF.17431ad located in directory /sg1/csb3/l0r/ will be output to the LAS image file l0rout.img located in directory [sg1.csb3.las.output]. All bands that are available for this image will be processed, and the entire image will be processed. The visible bands will actually appear in l0rout_vis.img, the thermal bands in l0rout_thm.img, and the pan band in l0rout_pan.img since they are all of different resolutions in an L0R product.

  2. LAS> infile="/sg1/csb3/l0r/l72edc139912815010_hdf.17431ad" out="/sg1/csb3/las/output/l0rout"

    The input Landsat-7 HDF image file L72EDC139912815010_HDF.17431ad located in directory /sg1/csb3/l0r/ will be output to the LAS image file l0rout.img located in directory /sg1/csb3/las/output/. All bands that are available for this image will be processed, and the entire image will be processed. The visible bands will actually appear in l0rout_vis.img, the thermal bands in l0rout_thm.img, and the pan band in l0rout_pan.img since they are all of different resolutions in an L0R product.

  3. LAS> infile="/sg1/csb3/l0r/l72edc139912815010_hdf.17431ad" out=("[sg1.csb3.las]l0rout1", "[sg1.csb3.las]l0rout2") bands=(1,3,5,2,61,8) nbands=(2,4)

    The input Landsat-7 HDF image file L72EDC139912815010_HDF.17431ad located in directory /sg1/csb3/l0r/ will be output to the LAS image files l0rout1.img and l0rout2.img in directory [sg1.csb3.las]. Bands 1 and 3 will be output to l0rout1.img and bands 2, 5, 61, and 8 will be output to l0rout2.img. Since l0rout2.img has different resolution bands, bands 2 and 5 will actually appear in l0rout2_vis.img, band 61 will appear in l0rout2_thm.img, and band 8 will appear in l0rout2_pan.img. All bands will be processed in their entirety.

  4. LAS> infile="/sg1/csb3/l1g/l71146034_03419990819_hdf.l1g" out="[sg1.csb3.las.output]l1gout2" units=pro window=(4109100.0,474900.0,4071900.0,515940.0)

    The input Landsat-7 image file L71146034_03419990819_HDF.L1G located in directory /sg1/csb3/l1g/ will be output to the LAS image file l1gout2.img in directory [sg1.csb3.las.output]. All bands in the input image will be processed and all bands will be windowed in projection units of upper left corner (line/sample) = 4109100/474900 and lower right corner (line/sample) = 4071900/515940.

  5. LAS> comment=("please mount cd 0759912040001 l1g1/1 on sgs20") out="/sg1/csb3/las/output/l1gcdout"

    The input Landsat-7 image file will be determined once the CD is mounted. If more than one Landsat-7 HDF files are found, then the first file will be processed and a message listing the other HDF files will be output. All bands in the input file will be processed in their entirety. The visible bands will appear in l1gcdout_vis.img, the thermal bands in l1gcdout_thm.img, and the pan bands in l1gcdout_pan.img. These files will be output to the /sg1/csb3/las/output/ directory.

  6. LAS> comment=("please mount cd 0759912040001 l1g1/1 on sgs20") infile="l71148033_03319990716_hdf.l1g" out="/sg1/csb3/las/output/l1gcdout"

    The Landsat-7 image file l71148033_03319990716_hdf.l1g will be processed on CD. All bands in the input file will be processed in their entirety. The visible bands will appear in l1gcdout_vis.img, the thermal bands in l1gcdout_thm.img, and the pan bands in l1gcdout_pan.img. These files will be output to the /sg1/csb3/las/output/ directory.

  7. LAS> comment=("please mount cd 0760001120001 l1r1/1", "please mount cd 0760001120001 l1r1/2") out="/sg1/csb3/las/output/l1rcdout"

    The input Landsat-7 image file will be determined once the CD is mounted. If more than one Landsat-7 HDF files are found, then the first file will be processed and a message listing the other HDF files will be output. All bands in the input file will be processed in their entirety. The visible bands will appear in l1rcdout_vis.img, the thermal bands in l1rcdout_thm.img, and the pan bands in l1rcdout_pan.img. These files will be output to the /sg1/csb3/las/output/ directory.

Description/Algorithm:

L7HDF2LAS will read the requested bands from CD or disk. If the image is to be ingested from CD, L7HDF2LAS will mount the specified CDs in order looking for the requested bands. For each line and band to be read, the image data is extracted and written to the appropriate LAS image. If the user specifies to subwindow the image, the subwindow is extracted for each band and written to the appropriate LAS image.

When processing a CD the user may leave the input filename blank. In this case, L7HDF2LAS will automatically determine the name of the HDF file on the CD and process that HDF file. If more than one HDF files are found, then the first HDF file is processed and an informational message containing the other HDF filenames is output. If an error is encountered, the current CD is unmounted if necessary and the application terminates. This application will support ingesting of L0R, L1R, L1G, and L1T (NLAPS) formatted LandsatHDF imagery.

When processing CDs, some CD readers read the input filenames as lower-case. Lower-case names will not work when reading these L7 HDF files, since the internal HDF SDSs are based on the upper-case names. As a work-around when processing CDs or files copied from CDs, upper-case symbolic links are made to the lower-case filenames. The links are created in the output directory determined by the first output filename. Any links that are created get unlinked when processing has been completed. The files that are linked include the HDF filename (_HDF), the metadata (_MTL or _MTP), and the band files (_B##). These links are simply that, just a link. This application does NOT copy the image from the CD.

If $DELFLG is set and an error occurs during processing of this application, then all files created by this application will be deleted.

Nonfatal Error Messages:

  1. [l7hdf2las-find_infilename] Warning: More than one HDF files were found at <xxxxx>. The following files will not be processed: <xxxxx>, <xxxxx>, ...

    More than one L7 HDF files were found in the specified directory. The first file found will be processed by this application. The other files will need to be processed manually by the user. This will involve processing from the same CD, but specifying the filename in the INFILE parameter.

  2. [l7hdf2las-minmax] Warning: Unable to update min/max field

    A problem occurred updating the DDR min/max fields. Skipped the update.

Fatal Error Messages:

  1. [l7hdf2las-get_parms] Error parsing the TAE parameter block for L7DHF2LAS parameters

    An error occurred while reading the TAE parameter block and parsing out the required elements for L7HDF2LAS. A message prior to this message should specify which parameter was invalid or unavailable.

  2. [l7hdf2las-mount_cd] Error mounting the CD

    An error occurred while trying to mount the current CD. Check with the operator to make sure the CD was correctly mounted.

  3. [l7hdf2las-find_infilename] Error reading filenames from the CD

    An error occurred while trying to read an L7 HDF filename on the current CD. Verify that the filenames on the CD following the specified file format in the DFCB.

  4. [l7hdf2las-read_meta] Unable to find the L0R, L1R, L1G, or L1T metadata for file: <xxxxx>

    The application could not find an L0R, L1R, L1G, or L1T metadata file on the CD or DISK. Make sure the _MTP (L0R) or _MTL (L1R/L1G/L1T) file exists and is of the correct file format.

  5. [l7hdf2las-read_product] Error reading the product metadata

    The product metadata was found for the L0R image, but an error occurred while reading the metadata file. The line prior to this error message should provide some insight into which element of the metadata is invalid or unavailable.

  6. [l7hdf2las-read_lpgs] Error reading the LPGS metadata

    The LPGS metadata was found for the L1R/L1G/L1T image, but an error occurred while reading the metadata file. The line prior to this error message should provide some insight into which element of the metadata is invalid or unavailable.

  7. [l7hdf2las-window] Product is not L1G or L1T thus the window must be in line/sample units

    Only L1G and L1T products contain projection information in the metadata, thus only the L1G or L1T products can be windowed in units other than line/sample.

  8. [l7hdf2las-metabands] Error setting bands from the metadata

    An error occurred while setting the default bands to the bands from the metadata.

  9. [l7hdf2las-convert_window_res] Error converting the user-specified window to line/sample

    An error occurred while converting the window from the specified units to line/sample units, or the specified window is an invalid window for this image.

  10. [l7hdf2las-createlinks] Error creating the upper-case symbolic links for CD processing

    An error occurred while creating a file link from the output directory to the same file on CD. The lower-case filenames on CD cannot be processed and therefore an upper-case link to these filenames is made in the output directory specified in the OUT parameter.

  11. [l7hdf2las-srch_dir] Error searching for band files on CD or disk

    An error occurred while trying to find the band files for the input HDF filename. Check to make sure the filenames follow the format specified in the DFCB.

  12. [l7hdf2las-openLASimagery] Error opening the output LAS image: <xxxxx>

    An error occurred trying to open the LAS image for output <xxxxx>. Verify that you have write priveleges to the specified output directory.

  13. [l7hdf2las-openimagery] Error opening the input L7 HDF image (L1R/L1G/L1T): <xxxxx>

    An error occurred while opening the L7 HDF image <xxxxx> for input. Verify that the image exists and that you have read priveleges to the input directory.

  14. [l7hdf2las-openimagery] Error opening the input L7 HDF image (L0R): <xxxxx>

    An error occurred while opening the L7 HDF image <xxxxx> for input. Verify that the image exists and that you have read priveleges to the input directory.

  15. [l7hdf2las-readHDF_writeLAS] Error reading the HDF file and writing to the LAS image

    An error occurred while reading the input L7 HDF image for one of the bands and outputting to the specified LAS image.

  16. [l7hdf2las-closeimagery] Error closing the input L7 HDF image (L0R)

    An error occurred while trying to close the L0R L7 HDF image.

  17. [l7hdf2las-closeimagery] Error closing the input L7 HDF image (L1R/L1G/L1T)

    An error occurred while trying to close the L1R/L1G/L1T L7 HDF image.

  18. [l7hdf2las-closeLASimage] Error closing the output LAS image

    An error occurred while trying to close the output LAS image.

  19. [l7hdf2las-write_ddr] Error writing the DDR

    An error occurred while trying to write the output DDR for the LAS image.

  20. [l7hdf2las-deletelinks] Error deleting the link files created for CD processing

    One of the link files created for CD processing could not be deleted. Verify that these files don't get deleted by the user during processing.

  21. [l7hdf2las-unmount_cd] Error unmounting the CD

    The current CD could not be unmounted. Check with the operator to verify it has not already been unmounted.

  22. [l7hdf2las-merge_vol_files] Error merging the _vol files

    An error occurred while trying to merge the _vol files created while processing a multi-volume CD set.

  23. [l7hdf2las-merge_res_files] Error merging the _res files

    An error occurred while trying to merge the _res files created while processing a multi-resolution image.

  24. [l7hdf2las-projparms] Error parsing <xxx>

    An error occurred while parsing the projection parameters. Consult a developer since there is probably a bug in the software that created the source HDF file.

User Notes:

  1. When processing CDs, some CD readers read the input filenames as lower-case. Lower-case names will not work when reading these L7 HDF files, since the internal HDF SDSs are based on the upper-case names. As a work-around when processing CDs or files copied from CDs, upper-case links are made to the lower-case filenames. The links are created in the output directory determined by the first output filename. Any links that are created get unlinked when processing has been completed. The files that are linked include the HDF filename (_HDF), the metadata (_MTL or _MTP), and the band files (_B##). These links are simply that, just a link. This application does NOT copy the image from the CD.

  2. If $DELFLG is set and an error occurs during processing of this application, then all files created by this application will be deleted.

  3. When processing L1R imagery, the imagery is scaled 16-bit data. If the user chooses to output the image in byte data, then the data will be truncated to fall between 0 and 255.

  4. The L0R file formats are of the following (from the L7 0R DFCB): L7XsssfnYYDOYHHuuv_xxx.DOYMMMC, where X = 0,1,2,3 for the L7 X-band sss = ground station (EDC, AGS, SGS, etc.) f = ETM+ format (1 or 2) n = processor number (0-9) YY = last two digits of the year associated with a contact period (not acquisition time) DOY = Julian day of year of the contact period HH = hour of the contact period within a 24-hour day (00-23) uu = subinterval number within this contact period (00-99) v = data set version number xxx = type of data (MSD, PCD, GEO, HDF, MTA, MTP, B10, B20, B30, B40, B50, B60, B70, B81, B82, B83, C10-C80, O10-O83) The input file name for this field will be the name of the HDF file, which follows the naming convention of a Format 1 file. Both Format 1 and Format 2 products will be processed at one time. These file names must include the full path if the file is not in the current working directory.

    NASA Goddard Space Flight Center, Landsat 7 System Zero-R Distribution Product Data Format Control Book, Volume 5, Book 1, Revision 3, July 1999. (available at http://edcwww.cr.usgs.gov/l7dhf/L7MMO/document.htm#DFCB_vol)

  5. The L1R/L1G/L1T file formats are of the following (from the L7 Level 1 DFCB): L7fppprrr_rrrYYYYMMDD_AAA.XXX, where f = ETM+ format (1 or 2) ppp = starting path of the product rrr_rrr = starting and ending rows of the product YYYYMMDD = acquisition date of the image AAA = file type (B10, B20, B30, B40, B50, B61, B62, B70, B80, CAL, GEO, HDF, MSD, MTA, MTL, PCD, SL0) XXX = product type (L1R/L1G/L1T) The input file name for this field will be the name of the HDF file, which follows the naming convention of a Format 1 file. Both Format 1 and Format 2 products will be processed at one time. These file names must include the full path if the file is not in the current working directory.

    NASA Goddard Space Flight Center, Earth Science Data and Information System (ESDIS) Level 1 Product Output Files Data Format Control Book, Volume 5, Book 2, Revision 4, January 2000. (available at http://edcwww.cr.usgs.gov/l7dhf/L7MMO/document.htm#DFCB_vol)