Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gee-community/msslib

An Earth Engine JavaScript library for working with Landsat MSS image data.
https://github.com/gee-community/msslib

Last synced: about 1 month ago
JSON representation

An Earth Engine JavaScript library for working with Landsat MSS image data.

Awesome Lists containing this project

README 

        
# 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](https://jdbcode.github.io/MSScvm/imgs/braaten_et_al_2015_automated%20cloud_and_cloud_shadow_identification_in_landsat_mss_imagery_for_temperate_ecosystems.pdf)

cloud mask.



![](/docs/msscvm_demo_01.png)



## Guide



### Module import



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



```js

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.



```js

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.



```js

var mssDnCol = msslib.getCol({

  aoi: ee.Geometry.Point([-122.239, 44.018]),

  doyRange: [170, 240] 

});

```



View image thumbnails to get a sense for quality.



```js

msslib.viewThumbnails(mssDnCol);

```



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

previously.



```js

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.



```js

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

```



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



```js

mssToaCol = mssToaCol.map(msslib.addNdvi);

```



Apply the MSS clear-view-mask

([MSScvm](https://jdbcode.github.io/MSScvm/index.html)) to all images in the

collection to remove clouds and cloud shadows.



```js

mssToaCol = mssToaCol.map(msslib.applyMsscvm);

```



Apply QA band to all images in the collection.



```js

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**  

```js

// 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**  

```js

// 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**  

```js

// 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**  

```js

// 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**  

```js

// 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**  

```js

// 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](https://developers.google.com/earth-engine/image_visualization#mapVisParamTable).     If set, overrides the `params.display` option and default. |



**Example**  

```js

// 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**  

```js

// 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**  

```js

// 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**  

```js

// 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](https://docs.lib.purdue.edu/cgi/viewcontent.cgi?article=1160&context=lars_symp)



**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**  

```js

// 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](https://www.usgs.gov/land-resources/nli/landsat/landsat-collection-1-level-1-quality-assessment-band).



**Kind**: global function  



| Param | Type | Description |

| --- | --- | --- |

| img | ee.Image | MSS image originating from the `msslib.getCol()`     function. |



**Example**  

```js

// 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](https://www.usgs.gov/land-resources/nli/landsat/landsat-collection-1-level-1-quality-assessment-band).



**Kind**: global function  



| Param | Type | Description |

| --- | --- | --- |

| img | ee.Image | MSS image originating from the `msslib.getCol()`     function. |



**Example**  

```js

// 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](https://jdbcode.github.io/MSScvm/imgs/braaten_et_al_2015_automated%20cloud_and_cloud_shadow_identification_in_landsat_mss_imagery_for_temperate_ecosystems.pdf).



**Kind**: global function  



| Param | Type | Description |

| --- | --- | --- |

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



**Example**  

```js

// 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](https://jdbcode.github.io/MSScvm/imgs/braaten_et_al_2015_automated%20cloud_and_cloud_shadow_identification_in_landsat_mss_imagery_for_temperate_ecosystems.pdf).



**Kind**: global function  



| Param | Type | Description |

| --- | --- | --- |

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



**Example**  

```js

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

```