## Surface Temperature Version TBD Release Notes ## Note: The products produced by this software are considered provisional. Release Date: TBD, 2026 See git tag [TBD-\] This project contains application source code for producing Surface Temperature products using the Single Channel algorithm. ## Product Descriptions See the [Landsat Surface Temperature (ST) Product Guide](https://www.usgs.gov/media/files/landsat-surface-temperature-product-guide) for information about the Surface Temperature products. ## Release Notes * Version change to release date * No longer make elevation band to cover points outside scene extent * Extrapolate VZA to cover points in the fill region * Set saturated pixels to fill ## Installation ### Dependencies * ESPA raw binary libraries, tools, and its dependencies. [Found here](https://code.chs.usgs.gov/eros/lsrd/espa-product-formatter) * Python 3.11.5+ and Numpy/Scipy/netCDF4/GDAL Python libraries * [GDAL](http://www.gdal.org/) 3.8.4 - The GDAL command line tools are utilized for some of the processing steps. - PROJ libraries (9.3.1 or most current) -- https://proj.org/en/9.4/download.html ### Environment Variables * Required for building this software (For an example see setup-build-environment.sh) ``` export PREFIX="path_to_Installation_Directory" export XML2INC="path_to_LIBXML2_include_files" export XML2LIB="path_to_LIBXML2_libraries" export LZMALIB="path_to_LZMA_libraries_for_linking" export ZLIBLIB="path_to_ZLIB_libraries_for_linking" export ESPAINC="path_to_ESPA_PRODUCT_FORMATTER_include_files" export ESPALIB="path_to_ESPA_PRODUCT_FORMATTER_libraries" export PROJX_INC="path_to_PROJX_include_files" export PROJX_LIB="path_to_PROJX_libraries" ``` ### Build Steps * Clone the repository and replace the defaulted version(master) with this version of the software ``` git clone https://code.chs.usgs.gov/eros/lsrd/espa-surface-temperature.git cd espa-surface-temperature git checkout version_ ``` * Build and install the application specific software ``` make make install ``` ## Usage See `surface_temperature.py --help` for command line details. For the --st_algorithm parameter, use SINGLE_CHANNEL. The Single Channel algorithm is the default, so you can also skip that parameter if you want to produce a product using the Single Channel algorithm. For the Single Channel algorithm, for the --reanalysis parameter, use MERRA-2 or GEOS-IT. These select Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2) or GEOS for Instrument Teams (GEOS-IT), respectively. ### Environment Variables * PATH - May need to be updated to include the following - `$PREFIX/bin` * ST_MERRA_AUX_PATH - Points to the local MERRA-2 data archive created using [ESPA auxiliary](https://code.chs.usgs.gov/eros/lsrd/espa-auxiliary). - `export ST_MERRA_AUX_PATH="/usr/local/auxiliaries/LST/MERRA2"` * ST_GEOSIT_AUX_PATH - Points to the local GEOS-IT (GEOS - instrument team) data archive created using [ESPA auxiliary](https://code.chs.usgs.gov/eros/lsrd/espa-auxiliary). - `export ST_GEOSIT_AUX_PATH="/usr/local/auxiliaries/LST/GEOSIT"` * ST_DATA_DIR - Points to the installed static file - `export ST_DATA_DIR="/usr/local/espa-surface-temperature/st/static_data"` * MODTRAN_PATH - Points to the installed MODTRAN location - `export MODTRAN_PATH="/usr/local/bin"` * MODTRAN_DATA_DIR - Points to the directory containing the MODTRAN "DATA" directory - `export MODTRAN_DATA_DIR="/usr/local/auxiliaries/MODTRAN_DATA"` * RTTOV_DATA_DIR - Points to the directory containing RTTOV - `export RTTOV_DATA_DIR="/usr/local/auxiliaries/rttov"` * ASTER_GED_SERVER_NAME - `export ASTER_GED_SERVER_NAME="e4ftl01.cr.usgs.gov"` * ASTER_GED_SERVER_PATH - `export ASTER_GED_SERVER_PATH="/ASTT/AG100.003/2000.01.01/"` * CAMEL_ARCHIVE_PATH - `export CAMEL_ARCHIVE_PATH="/usr/local/auxiliaries/LST/CAMEL_V003"` ### Data Processing Requirements This version of the Single Channel Surface Temperature application requires the input products to be in the ESPA internal file format. The following input data are required to generate the Surface Temperature product: * Level 1 Product from Landsat 4, 5, 7, 8, or 9 - The thermal band from the level 1 product is used. * Top of Atmosphere Reflectance (TOA) - TOA products can be generated using the [LEDAPS](https://code.chs.usgs.gov/eros/lsrd/espa-surface-reflectance) or [L89_SR](https://code.chs.usgs.gov/eros/lsrd/espa-surface-reflectance) software found in our [espa-surface-reflectance](https://code.chs.usgs.gov/eros/lsrd/espa-surface-reflectance) project. TOA products can also be generated through our on-demand processing system [ESPA](https://espa.cr.usgs.gov). Be sure to select the ENVI output format if using our [ESPA](https://espa.cr.usgs.gov) on-demand system. * Elevation - Elevation data is expected to be in the same projection, resolution, and image dimensions as the TOA products as well as identified in the XML metadata file and in the ENVI file format. The filename is also expected be `_elevation.img`: where sceneid is the Landsat Scene ID of the data being processed. * ASTER GED - ASTER GED data can be [found here](https://lpdaac.usgs.gov/data_access/data_pool). External users will need to set up an alternate ASTER GED data retrieval method. One potential method is to create a NASA Earthdata account as [described here](http://e4ftl01.cr.usgs.gov/ASTT), and update the automated ST procedure to supply the login information before accessing the ASTER GED data. * Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2) and GEOS - Instrument Team (GEOS-IT) - For MERRA-2 and GEOS-IT data, it would be best to use the software provided in the [ESPA auxiliary](https://code.chs.usgs.gov/eros/lsrd/espa-auxiliary) project to download and build your own archive for the dates you require. This software archives a reduced set of parameters from each source file, only using the parameters required for ST generation. See the README file in that project for details. ## Split Window Surface Temperature Version TBD Release Notes ## Note: The products produced by this software are considered provisional. Release Date: TBD, 2026 See git tag [TBD-\] This project contains application source code for producing Surface Temperature products using the Split Window algorithm. ## Product Descriptions Currently no product description document is available for the Split Window ST algorithm. ## Release Notes * Version change to release date * Reuse warped aster_ndvi, fv_ls, and fv_aster for 2nd Split Window band * Fix artifact around TPW edges * Use TPW model trained with AERONET * No longer read BT metadata * Set saturated pixels to fill * Add test tool for comparing pixels * Set emissivity coefficients to the Single Channel values ## Installation ### Dependencies * ESPA raw binary libraries, tools, and its dependencies. [Found here](https://code.chs.usgs.gov/eros/lsrd/espa-product-formatter) * Python 3.11.5+ and Numpy/Scipy/GDAL/xgboost/pandas/netCDF4 Python libraries * [GDAL](http://www.gdal.org/) 3.8.4 - The GDAL command line tools are used for some of the processing steps. ### Environment Variables * Required for building this software (For an example see setup-build-environment.sh) ``` export PREFIX="path_to_Installation_Directory" export XML2INC="path_to_LIBXML2_include_files" export XML2LIB="path_to_LIBXML2_libraries" export LZMALIB="path_to_LZMA_libraries_for_linking" export ZLIBLIB="path_to_ZLIB_libraries_for_linking" export ESPAINC="path_to_ESPA_PRODUCT_FORMATTER_include_files" export ESPALIB="path_to_ESPA_PRODUCT_FORMATTER_libraries" ``` ### Build Steps * Clone the repository and replace the defaulted version(master) with this version of the software ``` git clone https://code.chs.usgs.gov/eros/lsrd/espa-surface-temperature.git cd espa-surface-temperature git checkout version_ ``` * Build and install the application specific software ``` make make install ``` ## Usage See `surface_temperature.py --help` for command line details. For the --st_algorithm parameter, use SPLIT_WINDOW. ### Environment Variables * PATH - May need to be updated to include the following - `$PREFIX/bin` * ST_DATA_DIR - Points to the installed static file - `export ST_DATA_DIR="/usr/local/espa-surface-temperature/st/static_data"` * ASTER_GED_SERVER_NAME - `export ASTER_GED_SERVER_NAME="e4ftl01.cr.usgs.gov"` * ASTER_GED_SERVER_PATH - `export ASTER_GED_SERVER_PATH="/ASTT/AG100.003/2000.01.01/"` * CAMEL_ARCHIVE_PATH - `export CAMEL_ARCHIVE_PATH="/usr/local/auxiliaries/LST/CAMEL_V003"` ### Data Processing Requirements This version of the Split Window Surface Temperature application requires the input products to be in the ESPA internal file format. The following input data are required to generate the Surface Temperature product: * Level 1 Product from Landsat 8 or 9 - The thermal bands from the level 1 product are used. - Earlier Landsat satellites are not supported for Split Window because the algorithm requires 2 thermal bands, which the instruments on those satellites don't have. * Top of Atmosphere Reflectance (TOA) - TOA products can be generated using the [L89_SR](https://code.chs.usgs.gov/eros/lsrd/espa-surface-reflectance) software found in our [espa-surface-reflectance](https://code.chs.usgs.gov/eros/lsrd/espa-surface-reflectance) project. TOA products can also be generated through our on-demand processing system [ESPA](https://espa.cr.usgs.gov). Be sure to select the ENVI output format if using our [ESPA](https://espa.cr.usgs.gov) on-demand system. * ASTER GED - ASTER GED data can be [found here](https://lpdaac.usgs.gov/data_access/data_pool). External users will need to set up an alternate ASTER GED data retrieval method. One potential method is to create a NASA Earthdata account as [described here](http://e4ftl01.cr.usgs.gov/ASTT), and update the automated ST procedure to supply the login information before accessing the ASTER GED data. ### Data Postprocessing After compiling the [espa-product-formatter](https://code.chs.usgs.gov/eros/lsrd/espa-product-formatter) libraries and tools, the `convert_espa_to_gtif` and `convert_espa_to_hdf` command-line tools can be used to convert the ESPA internal file format to HDF or GeoTIFF. Otherwise the data will remain in the ESPA internal file format, which includes each band in the ENVI file format (i.e. raw binary file with associated ENVI header file) and an overall XML metadata file. ### Support Information This project is unsupported software provided by the U.S. Geological Survey (USGS) Earth Resources Observation and Science (EROS) Land Satellite Data Systems (LSDS) Project. For questions regarding products produced by this source code, please contact us at custserv@usgs.gov. ### Disclaimer This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software.