landsat¶

Examples¶

Accessing Landsat metadata

Sometimes you need to access landsat metadata from its MTL file in a programmatic fashion. We have a class for that, called landsat_metadata. This class exists almost entirely for its attributes, which are built from an input MTL file quite easily.

Here is some example syntax for delcaring the object, exploring attributes, and accessing specific attributes.

from dnppy import landsat
meta = landsat.landsat_metadata(my_MTL_filepath) # create object

from pprint import pprint                        # import pprint
pprint(vars(meta))                               # pretty print meta contents
scene_id = meta.LANDSAT_SCENE_ID                 # access specific attribute

You can read more about landsat_metadata in the code help below!

Converting to Top-of-Atmosphere Reflectance

Raw Landsat data comes in a collection of tiff files that whose values (Digital Numbers) are on a 8-bit (Landsat 4, 5, and 7) or 16-bit (Landsat 8) scale. These tiffs often need to be converted to reflectance values, such that each pixel represents the proportion of radiation, scaled from 0 to 1, in that band’s bandwidth that is reflected. Note that this includes atmospheric conditions that may be responsible for reflecting a portion of that radiation. Processing these data is now very easy in dnppy, as shown in the code below. First, import the landsat module from dnppy. Then, type in the command landsat.toa_reflectance_457 or landsat.toa_reflectance_8. The first parameter to fill out is the list of band numbers you wish to convert, which should be entered as [1,2,3,4,5,7] for example. The second parameter is the file path to the Landsat scene’s metadata file, which ends in _MTL.txt. The last parameter, which is optional, is the directory you wish to deposit the output tiffs in. If left out, the output tiffs will be placed in the same folder as the input data. Now just close the parentheses and execute the command to convert the data.

from dnppy import landsat

band_nums = [1,2,3,4,5,7]
meta_path = r"C:\folder\LE70410362002335EDC00\LE70410362002335EDC00_MTL.txt"
outdir = r"C:\folder\output"

landsat.toa_reflectance_457(band_nums, meta_path, outdir)

Code Help¶

Auto-documentation for functions and classes within this module is generated below!

atsat_bright_temp_8(meta_path, outdir=False)[source]¶

Converts Landsat 8 TIRS bands to at satellite brightnes temperature in Kelvins

To be performed on raw Landsat 8 level 1 data. See link below for details see here http://landsat.usgs.gov/Landsat8_Using_Product.php

Parameters:	band_nums – A list of desired band numbers, which should be [10,11] meta_path – The full filepath to the metadata file for those bands outdir – Output directory to save converted files. If left False it will save ouput files in the same directory as input files.
Return output_filelist:
	A list of all files created by this function

atsat_bright_temp_457(meta_path, outdir=None)[source]¶

Converts band 6 from Landsat 4 and 5 or bands 6 VCID 1 and 2 from Landsat 7 to at satellite brightness temperature in Kelvins

To be performed on raw Landsat 4, 5, or 7 level 1 data.

Parameters:	meta_path – The full filepath to the metadata file, labeled ‘_MTL.txt’, which must be in the same folder as band 6 or 6_VCID_1 and 6_VCID_2 outdir – Output directory to save converted files. If left False it will save ouput files in the same directory as input files.
Return output_filelist:
	A list of all files created by this function

make_cloud_mask_457(B2_TOA_Ref, outdir=None, Filter5Thresh=2.0, Filter6Thresh=2.0)[source]¶

Creates a binary mask raster for removal of cloud-covered pixels in raw Landsat 4, 5, and 7 bands.

To be performed on Landsat 4, 5, or 7 data. Must be processed first with landsat.toa_reflectance_457 for bands 2, 3, 4, and 5 and landsat.atsat_bright_temp_457 for band 6.

Note that for this function to run properly, bands 2, 3, 4, 5, and 6 must each be in the same folder and have the correct naming convention output by the landsat.toa_reflectance_457 and landsat.atsat_bright_temp_457 functions (e.g. LT50410362011240PAC01_B2_TOA_Ref.tif, LT50410362011240PAC01_B6_Temp.tif).

Parameters:	B2_TOA_Ref – The full filepath to the band 2 top-of-atmosphere reflectance tiff file outdir – Output directory to the cloud mask and TOA band tiffs Filter5Thresh – Optional threshold value for Filter #5, default set at 2 Filter6Thresh – Optional threshold value for Filter #6, default set at 2
Return cloud_mask_path:
	Filepath to newly created cloud mask

make_cloud_mask_8(BQA_path, outdir=None)[source]¶

Creates a cloud mask tiff file from the Landsat 8 Quality Assessment Band (BQA) file. Requires only the BQA tiff file included in the dataset.

Parameters:	BQA_path – The full filepath to the BQA file for the raw Landsat 8 dataset outdir – Output directory to save cloudless band tifs and the cloud mask
Return cloud_mask_path:
	Filepath to newly created cloud mask

apply_cloud_mask(mask_path, folder, outdir=None)[source]¶

Removal of cloud-covered pixels in Landsat 4, 5, 7, or 8 bands using the mask created with landsat.make_cloud_mask_8 or landsat.make_cloud_mask_457.

Parameters:	folder – The folder containing the raw or processed band tiffs to remove clouds from mask_path – The full filepath to the mask file created by make_cloud_mask_8 or make_cloud_mask_457 outdir – Output directory to save cloudless band tiffs, default is same as “folder”
Return no_clouds_list:
	List of files created by this function with cloud mask applied.

grab_meta(filename)[source]¶

Legacy metadata function simply wraps the newer landsat_metadata class. You should use landsat_metadata instead of this function, and can refer to that class for further explanation.

Parameters:	filename – filepath to an MTL file
Return landsat_metadata:
	Metadata object with MTL attributes.

ndvi_8(Band5, Band4, outdir=None)[source]¶

Simple calculator of Normalized difference vegetation index on some Landsat 8 OLI data. Output file will have same name as inputs with “NDVI” in place of “B5”, so inputs of files “LC80140342014347LGN00_B5.tif” and “LC80140342014347LGN00_B4.tif” will generate a file named “LC80140342014347LGN00_NDVI.tif”

Parameters:	Band5 – The full filepath to the band 5 tiff file, the OLI NIR band Band4 – The full filepath to the band 4 tiff file, the OLI Visible Red band outdir – directory to store output “NDVI” tiff
Return ndvi8:	Name of output file created by this function

ndvi_457(Band4, Band3, outdir=None)[source]¶

Simple calculator of Normalized difference vegetation index on some Landsat 4/5/7 TM/ETM+ data. Output file will have same name as inputs with “NDVI” in place of “B5”, so inputs of files “LC70140342014347LGN00_B4.tif” and “LC70140342014347LGN00_B3.tif” will generate a file named “LC70140342014347LGN00_NDVI.tif”

Parameters:	Band4 – The full filepath to the band 4 tiff file, the TM/ETM+ NIR band Band3 – The full filepath to the band 3 tiff file, the TM/ETM+ Visible Red band outdir – directory to store output “NDVI” tiff
Return ndvi457:	Name of output file created by this function

surface_reflectance(meta_path, toa_folder, dem_path, dew_point, outdir=False, kt=1.0)[source]¶

This function will estimate surface reflectance for Landsat 4 TM, 5 TM, 7 ETM+, or 8 OLI data.

Note this function will calculate surface reflectance for Landsat 4, 5, and 7 bands 1, 2, 3, 4, 5, and 7 or Landsat 8 bands 2, 3, 4, 5, 6, and 7. All 6 bands should be in the toa_folder and have “TOA_Ref” in their filenames as per the landsat.toa_reflectance convention.

The Landsat 8 Coastal Aerosol band (1) and Cirrus band (9) will not be calculated as they do not have a corresponding band in TM or ETM+. To be performed on Top-of-Atmosphere Reflectance data processed with the landsat.toa_reflectance_457 or the landsat.toa_reflectance_8 function.

Resources

• DEM

  • NASA Shuttle Radar Topography Mission (SRTM) up to 30m resolution. [http://www2.jpl.nasa.gov/srtm/cbanddataproducts.html]
  • NASA Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER) Global Digital Elevation Model (GDEM) [http://asterweb.jpl.nasa.gov/gdem.asp]
  • USGS National Elevation Dataset (NED) [http://nationalmap.gov/elevation.html] downloadable in 30 meter resolution through The National Map Viewer

• Dew Point

  • NOAA Daily Observational Data: Global Summary of the Day (GSOD) - GIS Data Locator [http://gis.ncdc.noaa.gov/map/viewer/#app=clim&cfg=cdo&theme=daily&layers=0001&node=gis]. Select a weather station within the Landsat scene’s extent, follow the link, and enter the scene’s acquisition date. This will output a text file, with dew point under DEWP. More NOAA climatic data available at [https://www.climate.gov/data/maps-and-data]

Parameters:	meta_path – The full filepath to the metadata file (ending in MTL.txt) for the dataset toa_folder – The filepath to the folder containing the TOA_Ref tiffs to be processed dem_path – The full filepath to a DEM tif that covers the desired Landsat scene Note that the DEM should be resampled to the Landsat bands’ resolution (30m) and pixel alignment. Also ensure there are no gaps in the dataset. dew_point – The number (e.g. 57.7) for the dew point at the time and place of scene acquisition outdir – Output directory to save converted files. If left False it will save output files in the toa_folder directory. kt – Unitless turbidity coefficient. Default set at 1.0 for clean air. Set at 0.5 for extremely turbid, dusty, or polluted air.
Return output_filelist:
	A list of all files created by this function

surface_temp_8(band4_toa, meta_path, path_rad, nbt, sky_rad, outdir=False, L=0.5)[source]¶

Calculates surface temperature from Landsat 8 OLI and TIRS data. Requires band 4 and 5 Top-of-Atmosphere Reflectance tiffs and the unprocessed band 10 and 11 tiffs.

Note: if the default values of 0, 1, and 0 are used for the Path Radiance, Narrowband Transmissivity, and Sky Radiance constants, atmospheric conditions will not be accounted for and the surface values may be off. Values are attainable using MODTRAN.

Parameters:	band4_toa – Filepath to the Band 4 Top-of-Atmosphere Reflectance tiff. use landsat.toa_reflectance_8 meta_path – Filepath to the metadata file (ending in _MTL.txt) path_rad – Path Radiance constant (default 0) nbt – Narrowband Transmissivity constant (default 1) sky_rad – Sky Radiance constant (default 0) outdir – Path to the desired output folder. If left False the output tiff will be place in band4_toa’s folder L – Soil brightness correction factor, between 0 and 1. used to calculate Soil Adjusted Vegetation Index. Default L = 0.5 works well in most situations. when L = 0, SAVI = NDVI.
Return surface_temp_8:
	Full filepath of tif created by this function

surface_temp_457(band3_toa, meta_path, path_rad, nbt, sky_rad, outdir=False, L=0.5)[source]¶

Calculates surface temperature from Landsat 4/5 TM or 7 ETM+ data. Requires band 3 and 4 Top-of-Atmosphere Reflectance tiffs and the unprocessed band 6 (or 6_VCID_1 for Landsat 7) tiff.

Note: if the default values of 0, 1, and 0 are used for the Path Radiance, Narrowband Transmissivity, and Sky Radiance constants, atmospheric conditions will not be accounted for and the surface values may be off. Values are attainable using MODTRAN.

Parameters:	band3_toa – Filepath to the Band 3 Top-of-Atmosphere Reflectance tiff. use landsat.toa_reflectance_457 meta_path – Filepath to the metadata file (ending in _MTL.txt) path_rad – Path Radiance constant (default 0) nbt – Narrowband Transmissivity constant (default 1) sky_rad – Sky Radiance constant (default 0) outdir – Path to the desired output folder. If left False the output tiff will be place in band4_toa’s folder L – Soil brightness correction factor, between 0 and 1. used to calculate Soil Adjusted Vegetation Index. Default L = 0.5 works well in most situations. when L = 0, SAVI = NDVI.
Return surface_temp_457:
	Full filepath of tif created by this function

toa_radiance_8(band_nums, meta_path, outdir=None)[source]¶

Top of Atmosphere radiance (in Watts/(square meter x steradians x micrometers)) conversion for landsat 8 data. To be performed on raw Landsat 8 level 1 data. See link below for details: see here http://landsat.usgs.gov/Landsat8_Using_Product.php

Parameters:	band_nums – A list of desired band numbers such as [3, 4, 5] meta_path – The full filepath to the metadata file for those bands outdir – Output directory to save converted files.
Return output_filelist:
	List of filepaths created by this function.

toa_radiance_457(band_nums, meta_path, outdir=None)[source]¶

Top of Atmosphere radiance (in Watts/(square meter x steradians x micrometers)) conversion for Landsat 4, 5, and 7 data. To be performed on raw Landsat 4, 5, or 7 level 1 data.

Parameters:	band_nums – A list of desired band numbers such as [3, 4, 5] meta_path – The full filepath to the metadata file for those bands outdir – Output directory to save converted files.
Return output_filelist:
	List of filepaths created by this function.

toa_reflectance_8(band_nums, meta_path, outdir=None)[source]¶

Converts Landsat 8 bands to Top-of-Atmosphere reflectance. To be performed on raw Landsat 8 level 1 data. See link below for details see here [http://landsat.usgs.gov/Landsat8_Using_Product.php]

Parameters:	band_nums – A list of desired band numbers such as [3,4,5] meta_path – The full filepath to the metadata file for those bands outdir – Output directory to save converted files. If left False it will save ouput files in the same directory as input files.
Return output_filelist:
	List of files created by this function

toa_reflectance_457(band_nums, meta_path, outdir=None)[source]¶

This function is used to convert Landsat 4, 5, or 7 pixel values from digital numbers to Top-of-Atmosphere Reflectance. To be performed on raw Landsat 4, 5, or 7 data.

Parameters:	band_nums – A list of desired band numbers such as [3,4,5] meta_path – The full filepath to the metadata file for those bands outdir – Output directory to save converted files. If left False it will save ouput files in the same directory as input files.
Return output_filelist:
	List of files created by this function