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

visDn : Object: A dictionary of false color visualization parameters for MSS DN images.
visRad : Object: A dictionary of false color visualization parameters for MSS radiance images.
visToa : Object: A dictionary of false color visualization parameters for MSS TOA reflectance images.
visNdvi : Object: A dictionary of visualization parameters for MSS NDVI images.

Functions

getWrs1GranuleGeom(granuleId) > ee.Dictionary: 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.
getCol(params) > ee.ImageCollection: 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'.
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).
calcRad(img) > ee.Image: Converts DN values to radiance.
calcToa(img) > ee.Image: Converts DN values to TOA reflectance.
addNdvi(img) > ee.Image: Adds NDVI transformation as a band ('ndvi') to the input image.
addTc(img) > ee.Image: Adds Tasseled Cap indices brightness ('tcb'), greenness ('tcg'), yellowness ('tcy'), and angle ('tca') to the input image. See Kauth and Thomas, 1976
addQaMask(img) > ee.Image: Adds the 'BQA' quality band as mask band ('BQA_mask') indicating good (1) and bad (0) pixels. Learn more about the 'BQA' band.
applyQaMask(img) > ee.Image: 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.
addMsscvm(img) > ee.Image: 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.
applyMsscvm(img) > ee.Image: Applies the MSScvm mask to the input image, i.e., pixels identified as cloud or cloud shadow are masked out. Learn about MSScvm.

visDn : `Object`

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()');

visRad : `Object`

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()');

visToa : `Object`

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()');

visNdvi : `Object`

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()');

getWrs1GranuleGeom(granuleId) > `ee.Dictionary`

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

Param	Type	Description
granuleId	`string`	The PPPRRR granule ID.

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');

getCol(params) > `ee.ImageCollection`

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: ee.ImageCollection - An MSS image collection.

Param	Type	Default	Description
params	`Object`		An object that provides filtering parameters.
[params.aoi]	`ee.Geometry`		The geometry to filter images by intersection; those intersecting the geometry are included in the collection.
[params.maxRmseVerify]	`number`	`0.5`	The maximum geometric RMSE of a given image allowed in the collection, provided in units of pixels (60 m), conditioned on the 'GEOMETRIC_RMSE_VERIFY' image property.
[params.maxCloudCover]	`number`	`50`	The maximum cloud cover of a given image allowed in the collection, provided as a percent, conditioned on the 'CLOUD_COVER' image property.
[params.wrs]	`string`	`"1&2"`	An indicator for what World Reference System types to allow in the collection. MSS images from Landsat satellites 1-3 use WRS-1, while 4-5 use WRS-2. Options include: '1' (WRS-1 only), '2' (WRS-2 only), and '1&2' (both WRS-1 and WRS-2).
[params.yearRange]	`Array`	`[1972, 2000]`	An array with two integers that define the range of years to include in the collection. The first defines the start year (inclusive) and the second defines the end year (inclusive). Ex: [1972, 1990].
[params.doyRange]	`Array`	`[1, 365]`	An array with two integers that define the range of days to include in the collection. The first defines the start day of year (inclusive) and the second defines the end day of year (inclusive). Note that the start day can be less than the end day, which indicates that the day range crosses the new year. Ex: [180, 240] (dates for northern hemisphere summer images), [330, 90] (dates for southern hemisphere summer images).
[params.excludeIds]	`Array`		A list of image IDs to filter out of the image collection, given as the value of the image's 'LANDSAT_SCENE_ID' property.

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']
});

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

Param	Type	Default	Description
col	`ee.ImageCollection`		MSS DN image collection originating from the `msslib.getCol()` function.
params	`Object`		An object that provides visualization parameters.
[params.unit]	`string`	`"toa"`	An indicator for what units to use in the display image. Use: 'dn' (raw digital number), 'rad' (radiance), or 'toa' (TOA reflectance). The selected unit will be calculated on-the-fly.
[params.display]	`string`	`"nir\|red\|green"`	An indicator for how to display the image thumbnail. Use 'nir\|red\|green' (RGB) or 'ndvi' (grayscale). Default visualization parameters for color stretch are applied.
[params.visParams]	`Object`		A custom visualization parameter dictionary as described here. If set, overrides the `params.display` option and default.

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'});

calcRad(img) > `ee.Image`

Converts DN values to radiance.

Kind: global function

Param	Type	Description
img	`ee.Image`	MSS DN image originating from the `msslib.getCol()` 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);

calcToa(img) > `ee.Image`

Converts DN values to TOA reflectance.

Kind: global function

Param	Type	Description
img	`ee.Image`	MSS DN image originating from the `msslib.getCol()` 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);

addNdvi(img) > `ee.Image`

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

Kind: global function

Param	Type	Description
img	`ee.Image`	MSS image originating from the `msslib.getCol()` function. It is recommended that the image be in units of radiance or TOA reflectance (see `msslib.calcRad()` and `msslib.calcToa()`).

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);

addTc(img) > `ee.Image`

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

Param	Type	Description
img	`ee.Image`	MSS image originating from the `msslib.getCol()` function. It is recommended that the image be in units of radiance or TOA reflectance (see `msslib.calcRad()` and `msslib.calcToa()`).

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);

addQaMask(img) > `ee.Image`

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

Param	Type	Description
img	`ee.Image`	MSS image originating from the `msslib.getCol()` 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));

applyQaMask(img) > `ee.Image`

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

Param	Type	Description
img	`ee.Image`	MSS image originating from the `msslib.getCol()` 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));

addMsscvm(img) > `ee.Image`

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

Param	Type	Description
img	`ee.Image`	MSS TOA image originating from `msslib.getCol()` and `msslib.calcToa()`.

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));

applyMsscvm(img) > `ee.Image`

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

Param	Type	Description
img	`ee.Image`	MSS TOA image originating from `msslib.getCol()` and `msslib.calcToa()`.

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));

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

msslib

Guide

Module import

Example workflow

Components

Constants

Functions

visDn : `Object`

visRad : `Object`

visToa : `Object`

visNdvi : `Object`

getWrs1GranuleGeom(granuleId) > `ee.Dictionary`

getCol(params) > `ee.ImageCollection`

viewThumbnails(col, params)

calcRad(img) > `ee.Image`

calcToa(img) > `ee.Image`

addNdvi(img) > `ee.Image`

addTc(img) > `ee.Image`

addQaMask(img) > `ee.Image`

applyQaMask(img) > `ee.Image`

addMsscvm(img) > `ee.Image`

applyMsscvm(img) > `ee.Image`

Files

README.md

Latest commit

History

README.md

File metadata and controls

msslib

Guide

Module import

Example workflow

Components

Constants

Functions

visDn : Object

visRad : Object

visToa : Object

visNdvi : Object

getWrs1GranuleGeom(granuleId) > ee.Dictionary

getCol(params) > ee.ImageCollection

viewThumbnails(col, params)

calcRad(img) > ee.Image

calcToa(img) > ee.Image

addNdvi(img) > ee.Image

addTc(img) > ee.Image

addQaMask(img) > ee.Image

applyQaMask(img) > ee.Image

addMsscvm(img) > ee.Image

applyMsscvm(img) > ee.Image

visDn : `Object`

visRad : `Object`

visToa : `Object`

visNdvi : `Object`

getWrs1GranuleGeom(granuleId) > `ee.Dictionary`

getCol(params) > `ee.ImageCollection`

calcRad(img) > `ee.Image`

calcToa(img) > `ee.Image`

addNdvi(img) > `ee.Image`

addTc(img) > `ee.Image`

addQaMask(img) > `ee.Image`

applyQaMask(img) > `ee.Image`

addMsscvm(img) > `ee.Image`

applyMsscvm(img) > `ee.Image`