Landsat collection structure
The USGS produces data in 3 tiers (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).
See USGS documentation on Collection 1 Tiers for more information.
To allow access to both the validated T1 data and the newest real-time data together, we've grouped the scenes into collections by tier and satellite. Examples for Landsat 8 are 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 the above collections contains the raw data (i.e., scaled, at-sensor radiance). In addition, for each collection that contains T1 or T2 images, TOA (top-of-atmosphere reflectance), SR (surface reflectance), and LST (land surface temperature) products are offered. The following table describes the collection ID for TOA and SR/LST collections using Landsat 8 data as an example.
| ID | Description |
|---|---|
| LANDSAT/LC08/C01/T1_RT_TOA | Landsat 8, Collection 1, Tier 1 + Real Time, TOA |
| LANDSAT/LC08/C01/T1_TOA | Landsat 8, Collection 1, Tier 1 only, TOA |
| LANDSAT/LC08/C02/T1_L2 | Landsat 8, Collection 2, Tier 1 only, SR, and LST |
| LANDSAT/LC08/C01/T2_TOA | Landsat 8, Collection 1, Tier 2 only, TOA |
| LANDSAT/LC08/C01/T2_SR | Landsat 8, Collection 1, Tier 2 only, SR (no LST) |
These data exist for Landsat 4, 5, 7, and 8. Replace 'LC08' in the above collection definitions with IDs from the following table to retrieve collections for the various satellites.
| ID | Description |
|---|---|
| LT04 | Landsat 4, Thematic Mapper (TM) |
| LT05 | Landsat 5, Thematic Mapper (TM) |
| LE07 | Landsat 7, Enhanced Thematic Mapper Plus (ETM+) |
| LC08 | Landsat 8, Operational Land Imager (OLI) |
Landsat collection status
Pre-Collection 1: no longer being produced by USGS, unmaintained by Earth Engine, still available in Earth Engine but will eventually be purged.
Collection 1: produced by USGS until 2022-01-01, maintained by Earth Engine until 2023-01-01.
Collection 2: primary collection produced by USGS, increasing product availability in Earth Engine as ingestion backlog is processed. See the Data Catalog's Landsat page for currently available products.
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/LC08/C02/T1/LC08_044034_20140318');
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
Landsat surface reflectance (SR) data are available in Earth Engine as a copy of the USGS Collection 2, Level 2 archive. Note that Landsat 4, 5, and 7 SR data are generated using the LEDAPS algorithm, while Landsat 8 SR data are generated using the LaSRC algorithm. Learn about these algorithms and their differences from USGS.
You can access a USGS Collection 2, Level 2 Landsat 8 image like this:
var srImage = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20201028');
The surface reflectance datasets for Collection 2 Landsat 4 through 8 are:
var surfaceReflectanceL4 = ee.ImageCollection('LANDSAT/LT04/C02/T1_L2');
var surfaceReflectanceL5 = ee.ImageCollection('LANDSAT/LT05/C02/T1_L2');
var surfaceReflectanceL7 = ee.ImageCollection('LANDSAT/LE07/C02/T1_L2');
var surfaceReflectanceL8 = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2');
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/LC08/C02/T1_TOA/LC08_044034_20140926');
Map.centerObject(cloudy_scene);
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 = scored.select(['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');
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 TOA collection, make 15-day mosaic, set SENSOR_ID property.
var mosaic = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
.filterDate('2019-06-01', '2019-06-16').mosaic()
.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/LT05/C02/T1')
.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.