Google Earth Engine (GEE) is a high-performance cloud-based platform for processing geospatial data.
There is a myriad of processing toolboxes in GEE, but this repository/package aims to contribute to the GEE community for making terrain analysis seamlessly.
Terrain Analysis in Google Earth Engine (TAGEE) is a repository that contains the GEE Javascript code and a Python API implementation with reproducible examples for both.
You can use TAGEE in the Earth Engine code editor with a require statement.
var TAGEE = require('users/zecojls/TAGEE:TAGEE-functions');Or install the Python package from pip:
pip install tagee
Additional examples information are below.
Available terrain attributes:
| Attribute | Unit | Description |
|---|---|---|
| Elevation | meter | Height of terrain above sea level |
| Slope | degree | Slope gradient |
| Aspect | degree | Compass direction |
| Hillshade | dimensionless | Brightness of the illuminated terrain |
| Northness | dimensionless | Degree of orientation to North |
| Eastness | dimensionless | Degree of orientation to East |
| Horizontal curvature | meter | Curvature tangent to the contour line |
| Vertical curvature | meter | Curvature tangent to the slope line |
| Mean curvature | meter | Half-sum of the two orthogonal curvatures |
| Minimal curvature | meter | Lowest value of curvature |
| Maximal curvature | meter | Highest value of curvature |
| Gaussian curvature | meter | Product of maximal and minimal curvatures |
| Shape Index | dimensionless | Continuous form of the Gaussian landform classification |
The users are referred to Florinsky (2016) for mathematical concepts of geomorphometry, a historical overview of the progress of digital terrain modelling, and the notion of the topographic surface and its limitations.
Florinsky, Igor. Digital terrain analysis in soil science and geology. Academic Press, 2016.
Please, cite the following paper when using TAGEE:
Safanelli, J.L.; Poppiel, R.R.; Ruiz, L.F.C.; Bonfatti, B.R.; Mello, F.A.O.; Rizzo, R.; Demattê, J.A.M. Terrain Analysis in Google Earth Engine: A Method Adapted for High-Performance Global-Scale Analysis. ISPRS Int. J. Geo-Inf. 2020, 9, 400. DOI: https://doi.org/10.3390/ijgi9060400
As TAGEE uses spheroidal geometries and elevation nodes from a 3x3 moving window to calculate partial derivatives and hence terrain attributes, the visualization of the outputs is affected by the scale, which require the adjustment of the histogram for proper visualization. This happens because GEE produces different pyramids from your data (from the local up to the global scale) and consequently the pixel size changes dynamically, affecting the range of the estimated attribute values. Until you specify your final resolution, say 30m/pixel, the pyramids will dynamically affect the visualization of an output for different visualizaiton scales. You can determine your final resolution by exporting the results to assets and importing back further processing or map composition.
OPEN THE EXAMPLE DIRECTLY IN THE GEE CODE EDITOR.
NOTE: Any Earth Engine user with the above link can use it to view and run the example code. However, you need to login.
// Importing module
var TAGEE = require('users/zecojls/TAGEE:TAGEE-functions');
// World bounding box
var bbox = ee.Geometry.Rectangle({coords: [-180, -60, 180, 60], geodesic: false});
// Water mask
var hansen_2016 = ee.Image('UMD/hansen/global_forest_change_2016_v1_4').select('datamask');
var hansen_2016_wbodies = hansen_2016.neq(1).eq(0);
var waterMask = hansen_2016.updateMask(hansen_2016_wbodies);
// Loading SRTM 30 m
var demSRTM = ee.Image('USGS/SRTMGL1_003').rename('DEM');
// Smoothing filter
var gaussianFilter = ee.Kernel.gaussian({
radius: 3, sigma: 2, units: 'pixels', normalize: true
});
// Smoothing the DEM with the gaussian kernel.
var demSRTM = demSRTM.convolve(gaussianFilter).resample("bilinear");
// Terrain analysis
var DEMAttributes = TAGEE.terrainAnalysis(TAGEE, demSRTM).updateMask(waterMask);
print(DEMAttributes.bandNames(), 'Parameters of Terrain');
// Visualization
var vizVC = TAGEE.makeVisualization(DEMAttributes, 'VerticalCurvature', 'level2', bbox, 'rainbow');
Map.addLayer(vizVC, {}, 'VerticalCurvature');
Map.setCenter(0,0,2);In the Javascript code editor https://code.earthengine.google.com/, it is necessary to import the module TAGEE-functions.
var TAGEE = require('users/zecojls/TAGEE:TAGEE-functions');Then, you need to define the bounding box (study region limits) and import the Digital Elevation Model for terrain analysis (e.g. SRTM 30 m). Note that the bounding box is only necessary for generating a visualization.
// World bounding box
var bbox = ee.Geometry.Rectangle({coords: [-180, -60, 180, 60], geodesic: false});
// Water mask
var hansen_2016 = ee.Image('UMD/hansen/global_forest_change_2016_v1_4').select('datamask');
var hansen_2016_wbodies = hansen_2016.neq(1).eq(0);
var waterMask = hansen_2016.updateMask(hansen_2016_wbodies);
// Loading SRTM 30 m
var demSRTM = ee.Image('USGS/SRTMGL1_003').rename('DEM');
// Smoothing filter
var gaussianFilter = ee.Kernel.gaussian({
radius: 3, sigma: 2, units: 'pixels', normalize: true
});
// Smoothing the DEM with the gaussian kernel.
var demSRTM = demSRTM.convolve(gaussianFilter).resample("bilinear");Finally, you can run the TAGEE module for calculating the terrain attributes.
// Terrain analysis
var DEMAttributes = TAGEE.terrainAnalysis(TAGEE, demSRTM).updateMask(waterMask);
print(DEMAttributes.bandNames(), 'Parameters of Terrain');Console output (don't copy):
List (13 elements){
0: Elevation
1: Slope
2: Aspect
3: Hillshade
4: Northness
5: Eastness
6: HorizontalCurvature
7: VerticalCurvature
8: MeanCurvature
9: GaussianCurvature
10: MinimalCurvature
11: MaximalCurvature
12: ShapeIndex}
TAGEE has an additional feature for making the visualization easier and adapated to a dynamic scale (legend), once the pixel distances for the derivatives calculations are influenced by the visualization level. The legend limits are estimated by the 5th and 95th percentiles existing within the bounding box.
// Visualization
var vizVC = TAGEE.makeVisualization(DEMAttributes, 'VerticalCurvature', 'level2', bbox, 'rainbow');
Map.addLayer(vizVC, {}, 'VerticalCurvature');
Map.setCenter(0,0,2);For the function makeVisualization, you need to specify:
- Attributes in multiband object
- Attribute name (string, e.g. 'VerticalCurvature')
- Visualization level (string, e.g. 'level2')
- Bounding box object
- Color pallete (string, e.g. 'rainbow')
The visualization levels are:
| Visualization level | Pixel resolution (m) |
|---|---|
| 'level0' | 157000 |
| 'level1' | 78000 |
| 'level2' | 39000 |
| 'level3' | 20000 |
| 'level4' | 10000 |
| 'level5' | 5000 |
| 'level6' | 2000 |
| 'level7' | 1000 |
| 'level8' | 611 |
| 'level9' | 306 |
| 'level10' | 153 |
| 'level11' | 76 |
| 'level12' | 38 |
| 'level13' | 19 |
| 'level14' | 10 |
| 'level15' | 5 |
Available color palettes: 'rainbow', 'inferno', 'cubehelix', 'red2green', 'green2red', 'elevation', 'aspect' and 'hillshade'.
The Python TAGEE package is implemented very similarly to the JS version.
# import & initialize the earth engine API
import ee
ee.Initialize()
# import relevant function
from tagee import terrainAnalysis
# set up a smoothed DEM
gaussianFilter = ee.Kernel.gaussian(
radius=3, sigma=2, units='pixels', normalize=True
)
srtmSmooth = ee.Image("USGS/SRTMGL1_003").convolve(gaussianFilter).resample("bilinear")
# Calculate terrain metrics over a given geometry.
geom = ee.FeatureCollection(ee.Geometry.Rectangle(-111, 40, -110.9, 40.1))
terrainMetrics = terrainAnalysis(srtmSmooth)
# Summarize the metrics in the geometry
reduction = terrainMetrics.reduceRegions(
geom,
ee.Reducer.median()
)
print(reduction.getInfo())For any request, comment and suggestion, please send me a email (my github nickname at gmail.com)