Landsat Algorithms

Landsat collection structure

The USGS has moved to using a collection-based strategy for producing Landsat scenes. On May 1st, 2017, they stopped producing old-style (pre-Collection) scenes and now are only producing Collection 1 versions.

The USGS now produces data in 3 categories for each satellite:

  • Tier 1 (T1) - Data that meets geometric and radiometric quality requirements
  • Tier 2 (T2) - Data that doesn't meet the Tier 1 requirements
  • Real Time (RT) - Data that hasn't yet been evaluated (it takes as much as a month).

In order to allow access to both the validated T1 data and the newest real-time data together, we've sorted the scenes into 3 collections (per each satellite) as follows:

ID Description
LANDSAT/LC08/C01/T1_RT Landsat 8, Collection 1, Tier 1 + Real Time
LANDSAT/LC08/C01/T1 Landsat 8, Collection 1, Tier 1 only
LANDSAT/LC08/C01/T2 Landsat 8, Collection 1, Tier 2 only

Newly acquired scenes are added to the T1_RT collection daily. Once an RT scene gets reprocessed and categorized as either T1 or T2, it will be removed from the T1_RT collection and the new version will be added to the appropriate collection(s). If your work is sensitive to removals or potentially mis-registered scenes, you might want to stick to the T1 collection, but in general, it's very uncommon that any misregistration is large enough to notice on newly acquired scenes.

Each of these collections contains the raw data (i.e., scaled, at-sensor radiance). In addition, for each collection that contains T1 data, we are also providing a TOA collection containing the top-of-atmosphere reflectance. (e.g.: LANDSAT/LC08/C01/T1_RT_TOA).

Finally, because pre-Collection 1 scenes are no longer being produced, we will not be able to update the "old-style" Landsat collections (e.g.: LANDSAT/LC8_L1T). We plan to keep these collections for a while even after we've obtained all of the C1 data, but they will eventually be phased out.

Landsat processing methods

Earth Engine contains a variety of Landsat specific processing methods. Specifically, there are methods to compute at-sensor radiance, top-of-atmosphere (TOA) reflectance, surface reflectance (SR), cloud score and cloud-free composites.

At-sensor radiance and TOA reflectance

The ‘raw’ scenes in Earth Engine contain imagery with digital numbers (DNs) that represent scaled radiance. The conversion of DNs to at-sensor radiance is a linear transformation using coefficients stored in scene metadata (Chander et al. 2009). The ee.Algorithms.Landsat.calibratedRadiance() method performs this conversion. Conversion to TOA (or at-sensor) reflectance is a linear transformation that accounts for solar elevation and seasonally variable Earth-Sun distance. The TOA conversion is handled by the ee.Algorithms.Landsat.TOA() method. The TOA method converts thermal bands to brightness temperature. See Chander et al. (2009) (or this USGS site for Landsat 8) for more information about computing TOA reflectance or brightness temperature. The following example shows conversion from raw data to radiance and TOA reflectance for a Landsat 8 image:

// Load a raw Landsat scene and display it.
var raw = ee.Image('LANDSAT/LC8_L1T/LC80440342014077LGN00');
Map.centerObject(raw, 10);
Map.addLayer(raw, {bands: ['B4', 'B3', 'B2'], min: 6000, max: 12000}, 'raw');

// Convert the raw data to radiance.
var radiance = ee.Algorithms.Landsat.calibratedRadiance(raw);
Map.addLayer(radiance, {bands: ['B4', 'B3', 'B2'], max: 90}, 'radiance');

// Convert the raw data to top-of-atmosphere reflectance.
var toa = ee.Algorithms.Landsat.TOA(raw);

Map.addLayer(toa, {bands: ['B4', 'B3', 'B2'], max: 0.2}, 'toa reflectance');

Surface reflectance

Conversion to surface reflectance generally requires some sort of atmospheric compensation. USGS uses the LEDAPS software (Schmidt et al. 2013) to convert raw Landsat data to surface reflectance. LEDAPS requires a variety of atmospheric inputs to constrain an atmospheric model. These include outputs of a 6S model run, a DEM, total column ozone, National Centers for Environmental Prediction (NCEP) modeled surface pressure, temperature and water vapor (Kalnay et al. 1996).

You can access pre-computed surface reflectance images directly from the SR collections. For example, to load a Landsat 8 surface reflectance image, use:

var srImage = ee.Image('LANDSAT/LC8_SR/LT50440342008045EDC00');

The surface reflectance collections for pre-Collection 1 Landsat 4 through 8 are:

var surfaceReflectanceL4 = ee.ImageCollection('LANDSAT/LT4_SR');
var surfaceReflectanceL5 = ee.ImageCollection('LANDSAT/LT5_SR');
var surfaceReflectanceL7 = ee.ImageCollection('LANDSAT/LE7_SR');
var surfaceReflectanceL8 = ee.ImageCollection('LANDSAT/LC8_SR');

Landsat 5 or 7 surface reflectance images that are unavailable in these collections may be in the LEDAPS collections, though the SR collections shown above represent more up-to-date processing and are recommended over the LEDAPS collections:

var ledapsReflectanceL5 = ee.ImageCollection('LEDAPS/LT5_L1T_SR');
var ledapsReflectanceL7 = ee.ImageCollection('LEDAPS/LE7_L1T_SR');

Simple cloud score

For scoring Landsat pixels by their relative cloudiness, Earth Engine provides a rudimentary cloud scoring algorithm in the ee.Algorithms.Landsat.simpleCloudScore() method. (For details on the implementation, see this Code Editor sample script). The following example uses the cloud scoring algorithm to mask clouds in a Landsat 8 image:

// Load a cloudy Landsat scene and display it.
var cloudy_scene = ee.Image('LANDSAT/LC8_L1T_TOA/LC80440342014269LGN00');
Map.addLayer(cloudy_scene, {bands: ['B4', 'B3', 'B2'], max: 0.4}, 'TOA', false);

// Add a cloud score band.  It is automatically called 'cloud'.
var scored = ee.Algorithms.Landsat.simpleCloudScore(cloudy_scene);

// Create a mask from the cloud score and combine it with the image mask.
var mask =['cloud']).lte(20);

// Apply the mask to the image and display the result.
var masked = cloudy_scene.updateMask(mask);
Map.addLayer(masked, {bands: ['B4', 'B3', 'B2'], max: 0.4}, 'masked');

// Load a Landsat 8 composite and set the SENSOR_ID property.
var mosaic = ee.Image(ee.ImageCollection('LANDSAT/LC8_L1T_8DAY_TOA').first())
  .set('SENSOR_ID', 'OLI_TIRS');

// Cloud score the mosaic and display the result.
var scored_mosaic = ee.Algorithms.Landsat.simpleCloudScore(mosaic);
Map.addLayer(scored_mosaic, {bands: ['B4', 'B3', 'B2'], max: 0.4},
    'TOA mosaic', false);


If you run this example in the Code Editor, try toggling the visibility of the TOA layers to compare the difference between the masked and unmasked imagery. (See this section of the Code Editor docs for instructions on how to do that). Observe that the input to simpleCloudScore() is a single Landsat TOA scene. Also note that simpleCloudScore() adds a band called ‘cloud’ to the input image. The cloud band contains the cloud score from 0 (not cloudy) to 100 (most cloudy). The previous example uses an arbitrary threshold (20) on the cloud score to mask cloudy pixels. To apply this algorithm to an Earth Engine mosaic of Landsat scenes, set the SENSOR_ID property:

// Load a Landsat 8 composite and set the SENSOR_ID property.
var mosaic = ee.Image(ee.ImageCollection('LANDSAT/LC8_L1T_8DAY_TOA').first())
  .set('SENSOR_ID', 'OLI_TIRS');

// Cloud score the mosaic and display the result.
var scored_mosaic = ee.Algorithms.Landsat.simpleCloudScore(mosaic);
Map.addLayer(scored_mosaic, {bands: ['B4', 'B3', 'B2'], max: 0.4},
    'TOA mosaic', false);

SENSOR_ID is a property of individual images. When Earth Engine makes a mosaic of many images, it has to throw out individual image metadata, including the SENSOR_ID property. To cloud score a mosaic, Earth Engine looks for that property and can't find it, resulting in an error. Set the property manually to avoid that. The sensor IDs of Landsat 5, 7 and 8 are 'TM', 'ETM+' and 'OLI_TIRS', respectively.

Simple composite

For creating simple cloud-free Landsat composites, Earth Engine provides the ee.Algorithms.Landsat.simpleComposite() method. This method selects a subset of scenes at each location, converts to TOA reflectance, applies the simple cloud score and takes the median of the least cloudy pixels. This example creates a simple composite using default parameters and compares it to a composite using custom parameters for the cloud score threshold and the percentile:

// Load a raw Landsat 5 ImageCollection for a single year.
var collection = ee.ImageCollection('LANDSAT/LT5_L1T')
    .filterDate('2010-01-01', '2010-12-31');

// Create a cloud-free composite with default parameters.
var composite = ee.Algorithms.Landsat.simpleComposite(collection);

// Create a cloud-free composite with custom parameters for
// cloud score threshold and percentile.
var customComposite = ee.Algorithms.Landsat.simpleComposite({
  collection: collection,
  percentile: 75,
  cloudScoreRange: 5

// Display the composites.
Map.setCenter(-122.3578, 37.7726, 10);
Map.addLayer(composite, {bands: ['B4', 'B3', 'B2'], max: 128}, 'TOA composite');
Map.addLayer(customComposite, {bands: ['B4', 'B3', 'B2'], max: 128},
    'Custom TOA composite');

Note that the input to the simple composite is a collection of raw imagery. Also note that by default, reflective band output is reflectance scaled to 8-bits and thermal band output is Kelvin minus 100, to fit in the 8-bit range. You can change this behavior by setting the asFloat parameter to true, to get un-scaled, un-shifted float output.

Send feedback about...

Google Earth Engine API