Awesome

msslib

The aim of msslib is to make it easy to work with Landsat MSS data in Earth Engine. It assembles image collections across the five satellites that carried the MSS sensor, filters images for quality, calculates TOA reflectance, and calculates the MSScvm cloud mask.

Guide

Module import

Include the following line at the top of every script to import the library.

var msslib = require('users/jstnbraaten/modules:msslib/msslib.js');

Example workflow

This example demonstrates how to assemble an MSS image collection, view thumbnails to assess quality, reassemble collection to remove bad images, transform the images to TOA reflectance, add an NDVI band, and apply QA and cloud/shadow masks.

Import the msslib module.

var msslib = require('users/jstnbraaten/modules:msslib/msslib.js');

Get an MSS image collection filtered by region and day of year, as well as default settings for cloud and RMSE.

var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240] 
});

View image thumbnails to get a sense for quality.

msslib.viewThumbnails(mssDnCol);

Retrieve an image collection again, but this time exclude bad images identified previously.

var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240],
  excludeIds: ['LM10480291974234GDS03', 'LM20490291975185GDS03']
});

Convert the collection to top of atmosphere reflectance.

var mssToaCol = mssDnCol.map(msslib.calcToa);

Add the NDVI transformation as a band to all images in the collection.

mssToaCol = mssToaCol.map(msslib.addNdvi);

Apply the MSS clear-view-mask (MSScvm) to all images in the collection to remove clouds and cloud shadows.

mssToaCol = mssToaCol.map(msslib.applyMsscvm);

Apply QA band to all images in the collection.

mssToaCol = mssToaCol.map(msslib.applyQaMask);

Components

Constants

Functions

<a name="visDn"></a>

visDn : <code>Object</code>

A dictionary of false color visualization parameters for MSS DN images.

Kind: global constant
Example

// Get an MSS image.
var mssDnImg = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  yearRange: [1987, 1987],
  doyRange: [170, 240],
  wrs: '2'
}).first();

// Use with Map.addLayer().
Map.centerObject(mssDnImg, 8);
Map.addLayer(mssDnImg, msslib.visDn, 'From Map.addLayer()');

// Use with ee.Image.visualize().
var visImg = mssDnImg.visualize(msslib.visDn);
Map.addLayer(visImg, null, 'From ee.Image.visualize()');

<a name="visRad"></a>

visRad : <code>Object</code>

A dictionary of false color visualization parameters for MSS radiance images.

Kind: global constant
Example

// Get an MSS image.
var mssDnImg = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  yearRange: [1987, 1987],
  doyRange: [170, 240],
  wrs: '2'
}).first();

// Convert DN to radiance.
var mssRadImg = msslib.calcRad(mssDnImg);

// Use with Map.addLayer().
Map.centerObject(mssRadImg, 8);
Map.addLayer(mssRadImg, msslib.visRad, 'From Map.addLayer()');

// Use with ee.Image.visualize().
var visImg = mssRadImg.visualize(msslib.visRad);
Map.addLayer(visImg, null, 'From ee.Image.visualize()');

<a name="visToa"></a>

visToa : <code>Object</code>

A dictionary of false color visualization parameters for MSS TOA reflectance images.

Kind: global constant
Example

// Get an MSS image.
var mssDnImg = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  yearRange: [1987, 1987],
  doyRange: [170, 240],
  wrs: '2'
}).first();

// Convert DN to TOA.
var mssToaImg = msslib.calcToa(mssDnImg);

// Use with Map.addLayer().
Map.centerObject(mssToaImg, 8);
Map.addLayer(mssToaImg, msslib.visToa, 'From Map.addLayer()');

// Use with ee.Image.visualize().
var visImg = mssToaImg.visualize(msslib.visToa);
Map.addLayer(visImg, null, 'From ee.Image.visualize()');

<a name="visNdvi"></a>

visNdvi : <code>Object</code>

A dictionary of visualization parameters for MSS NDVI images.

Kind: global constant
Example

// Get an MSS image.
var mssDnImg = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  yearRange: [1987, 1987],
  doyRange: [170, 240],
  wrs: '2'
}).first();

// Convert DN to TOA and add NDVI band.
var mssNdviImg = msslib.addNdvi(msslib.calcToa(mssDnImg));

// Use with Map.addLayer().
Map.centerObject(mssNdviImg, 8);
Map.addLayer(mssNdviImg, msslib.visNdvi, 'From Map.addLayer()');

// Use with ee.Image.visualize().
var visImg = mssNdviImg.visualize(msslib.visNdvi);
Map.addLayer(visImg, null, 'From ee.Image.visualize()');

<a name="getWrs1GranuleGeom"></a>

getWrs1GranuleGeom(granuleId) > <code>ee.Dictionary</code>

Get the geometry for a given WRS-1 granule. Returns a dictionary with three elements: 'granule' a ee.Feature, granule 'centroid' a ee.Geometry, and granule 'bounds' ee.Geometry with a 40 km buffer. Note that it will only return results for granules that intersect land on the descending path.

Kind: global function

Example

// Get granule geometry for WRS-1 path/row granule 049030.
var granuleGeom = msslib.getWrs1GranuleGeom('049030');

// Print the results.
print(granuleGeom);

// Display the results.
var granule = ee.Feature(granuleGeom.get('granule'));
var centroid = ee.Geometry(granuleGeom.get('centroid'));
var bounds = ee.Geometry(granuleGeom.get('bounds'));
Map.centerObject(centroid, 8);
Map.addLayer(bounds, {color: 'blue'}, 'Bounds');
Map.addLayer(granule, {color: 'black'}, 'Granule');
Map.addLayer(centroid, {color: 'red'}, 'Centroid');

<a name="getCol"></a>

getCol(params) > <code>ee.ImageCollection</code>

Assembles a Landsat MSS image collection from USGS Collection 1 T1 and T2 images acquired by satellites 1-5. Removes L1G images and images without a complete set of reflectance bands. Additional default and optional filtering criteria are applied, including by bounds, geometric error, cloud cover, year, and day of year. All image bands are named consistently: ['green', 'red', 'red_edge', 'nir', 'BQA']. Adds 'wrs' property to all images designating them as 'WRS-1' or 'WRS-2'.

Kind: global function
Returns: <code>ee.ImageCollection</code> - An MSS image collection.

Example

// Filter by geometry intersection, cloud cover, and geometric RMSE.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  maxCloudCover: 25,
  maxRmseVerify: 0.25
});

// Filter by geometry intersection, year range, and day of year.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  yearRange: [1975, 1980],
  doyRange: [170, 240] 
});

// Filter by geometry intersection and exclude two images by ID.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  excludeIds: ['LM10490291972246AAA04', 'LM10480291973113AAA02']
});

<a name="viewThumbnails"></a>

viewThumbnails(col, params)

Prints image collection thumbnails to the console with accompanying image IDs for use in quickly evaluating a collection. The image IDs can be recorded and used as entries in the params.excludeIds list of the msslib.getCol() function to exclude the given image(s).

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240] 
});

// View DN image thumbnails in the console.
viewThumbnails(mssDnCol, {unit: 'dn'});

<a name="calcRad"></a>

calcRad(img) > <code>ee.Image</code>

Converts DN values to radiance.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240] 
});

// Convert DN to radiance for a single image.
var mssRadImg = msslib.calcRad(mssDnCol.first());

// Convert DN to radiance for all images in a collection.
var mssRadCol = mssDnCol.map(msslib.calcRad);

<a name="calcToa"></a>

calcToa(img) > <code>ee.Image</code>

Converts DN values to TOA reflectance.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240] 
});

// Convert DN to TOA for a single image.
var mssToaImg = msslib.calcToa(mssDnCol.first());

// Convert DN to TOA for all images in a collection.
var mssToaCol = mssDnCol.map(msslib.calcToa);

<a name="addNdvi"></a>

addNdvi(img) > <code>ee.Image</code>

Adds NDVI transformation as a band ('ndvi') to the input image.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240] 
});

// Convert DN to TOA for all images in a collection.
var mssToaCol = mssDnCol.map(msslib.calcToa);

// Add NDVI band to each image in a collection.
var mssToaColNdvi = mssToaCol.map(msslib.addNdvi);

<a name="addTc"></a>

addTc(img) > <code>ee.Image</code>

Adds Tasseled Cap indices brightness ('tcb'), greenness ('tcg'), yellowness ('tcy'), and angle ('tca') to the input image. See Kauth and Thomas, 1976

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
  aoi: ee.Geometry.Point([-122.239, 44.018]),
  doyRange: [170, 240] 
});

// Convert DN to TOA for all images in a collection.
var mssToaCol = mssDnCol.map(msslib.calcToa);

// Add Tasseled Cap bands to each image in a collection.
var mssToaColTc = mssToaCol.map(msslib.addTc);

<a name="addQaMask"></a>

addQaMask(img) > <code>ee.Image</code>

Adds the 'BQA' quality band as mask band ('BQA_mask') indicating good (1) and bad (0) pixels. Learn more about the 'BQA' band.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
        aoi: ee.Geometry.Point([-122.239, 44.018]),
        doyRange: [170, 240]
    });

// Select a single image.
var mssDnImg = mssDnCol.filter( 
        ee.Filter.eq('LANDSAT_SCENE_ID', 'LM30490291982193AAA03')).first();

// Add BQA mask band to the single image.
var mssDnImgQaMask = msslib.addQaMask(mssDnImg);

// Display the results.
Map.centerObject(mssDnImgQaMask, 9);
Map.addLayer(mssDnImgQaMask, msslib.visDn, 'DN image');
Map.addLayer(mssDnImgQaMask, {
    bands: ['BQA_mask'],
    min: 0,
    max: 1,
    palette: ['grey', 'green']
}, 'BQA mask');

// Add BQA mask band to all images in collection.
var mssDnColQaMask = mssDnCol.map(msslib.addQaMask);
print(mssDnColQaMask.limit(5));

<a name="applyQaMask"></a>

applyQaMask(img) > <code>ee.Image</code>

Applies the 'BQA' quality band to an image as a mask. It masks out cloud pixels and those exhibiting radiometric saturation, as well pixels associated with missing data. Cloud identification is limited to mostly thick cumulus clouds; note that snow and very bright surface features are often mislabeled as cloud. Radiometric saturation in MSS images usually manifests as entire or partial image pixel rows being highly biased toward high values in a single band, which when visualized, can appear as tinted red, green, or blue. Learn more about the 'BQA' band.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
        aoi: ee.Geometry.Point([-122.239, 44.018]),
        doyRange: [170, 240]
    });

// Select a single image.
var mssDnImg = mssDnCol.filter( 
        ee.Filter.eq('LANDSAT_SCENE_ID', 'LM30490291982193AAA03')).first();

// Apply BQA mask to the single image.
var mssDnImgQaMask = msslib.applyQaMask(mssDnImg);

// Display the results.
Map.centerObject(mssDnImgQaMask, 9);
Map.setOptions('SATELLITE');
Map.addLayer(mssDnImg, msslib.visDn, 'DN image');
Map.addLayer(mssDnImgQaMask, msslib.visDn, 'DN image masked');

// Apply BQA mask to all images in collection.
var mssDnColQaMask = mssDnCol.map(msslib.applyQaMask);
print(mssDnColQaMask.limit(5));

<a name="addMsscvm"></a>

addMsscvm(img) > <code>ee.Image</code>

Adds the MSScvm band ('msscvm') to the input image. Value 0 designates pixels as clear, 1 as clouds, and 2 as shadows. Learn about MSScvm.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
        aoi: ee.Geometry.Point([-122.239, 44.018]),
        doyRange: [170, 240],
        yearRange: [1983, 1986],
        wrs: '2'
    });

// Convert DN to TOA.
var mssToaCol = mssDnCol.map(msslib.calcToa);

// Select a single image.
var mssToaImg = mssToaCol.filter(
        ee.Filter.eq('LANDSAT_SCENE_ID', 'LM50450301986215AAA03')).first();

// Add MSScvm band to the single image.
var mssToaImgMsscvm = msslib.addMsscvm(mssToaImg);

// Display the results.
Map.centerObject(mssToaImgMsscvm, 9);
Map.addLayer(mssToaImgMsscvm, msslib.visToa, 'TOA image');
Map.addLayer(mssToaImgMsscvm, {
    bands: ['msscvm'],
    min: 0,
    max: 2,
    palette: ['27ae60', 'FFFFFF', '000000']
}, 'MSScmv');

// Add MSScvm band to all images in collection.
var mssToaColMsscvm = mssToaCol.map(msslib.addMsscvm);
print(mssToaColMsscvm.limit(5));

<a name="applyMsscvm"></a>

applyMsscvm(img) > <code>ee.Image</code>

Applies the MSScvm mask to the input image, i.e., pixels identified as cloud or cloud shadow are masked out. Learn about MSScvm.

Kind: global function

Example

// Get an MSS image collection.
var mssDnCol = msslib.getCol({
        aoi: ee.Geometry.Point([-122.239, 44.018]),
        doyRange: [170, 240],
        yearRange: [1983, 1986],
        wrs: '2'
    });

// Convert DN to TOA.
var mssToaCol = mssDnCol.map(msslib.calcToa);

// Select a single image.
var mssToaImg = mssToaCol.filter(
        ee.Filter.eq('LANDSAT_SCENE_ID', 'LM50450301986215AAA03')).first();
        
// Apply MSScvm to the single image.
var mssToaImgMsscvm = msslib.applyMsscvm(mssToaImg);

// Display the results.
Map.centerObject(mssToaImgMsscvm, 9);
Map.setOptions('SATELLITE');
Map.addLayer(mssToaImg, msslib.visToa, 'TOA image');
Map.addLayer(mssToaImgMsscvm, msslib.visToa, 'TOA image masked');
        
// Apply MSScvm to all images in collection.
var mssToaColMsscvm = mssToaCol.map(msslib.applyMsscvm);
print(mssToaColMsscvm.limit(5));