Get Started with Earth Engine

This Get Started guide is intended as a quick way to start programming with the Earth Engine JavaScript API. For an introductory look at JavaScript and more in-depth exercises with the Earth Engine API, see the tutorials. For suggestions on JavaScript coding style, see the Google JavaScript Style Guide.

Google Earth Engine allows users to run algorithms on georeferenced imagery and vectors stored on Google's infrastructure. The Google Earth Engine API provides a library of functions which may be applied to imagery for display and analysis. Earth Engine's public data catalog contains a large amount of publicly available imagery. Vector datasets are available through Google Fusion Tables. Developers can access existing vector datasets or create their own.

playground
Figure 1. The Earth Engine Code Editor at code.earthengine.google.com

The Code Editor is an interactive environment for developing Earth Engine applications (Figure 1). The center panel provides a code editor. Above the editor are buttons that save the current script, run it, and clear the map. The Get Link button generates a unique URL for the script in the address bar. The map in the bottom panel contains the layers added by the script. At the top is a search box for datasets and places. The left panel contains code examples, your saved scripts, and a searchable API reference. The right panel has an inspector for querying the map, an output console, and a manager for long-running tasks. The Help button contains links to this Guide, the help forum and a list of useful keyboard shortcuts for Code Editor features. Learn more from the Code Editor section.

Opening and running code in the Code Editor

The steps below demonstrate how to open Earth Engine and execute a custom script that displays an image. For best results, you may want to install the latest version of Chrome, Google’s web browser, available here.

  1. Open the Earth Engine Code Editor here: code.earthengine.google.com. If you have not already, you will need to enable access by logging in using a registered Google account.
  2. Navigate to the Scripts tab located on the far left of the Code Editor. There you will find a collection of example scripts that access, display, and analyze Earth Engine data.
  3. Under “Image Collection,” select the “Filtered Composite” example. You will see a script appear in the center console. Press the Run button to execute the script. The Filtered Composite example selects Landsat 7 images that intersect or are within the boundaries of Colorado and Utah. It then displays a true color composite of the selected images. The samples introduce you to commonly used methods, such as filter(), clip(), and Map.addLayer().

Earth Engine data structures

The two most fundamental geographic data structures in Earth Engine are Image andFeature corresponding to raster and vector data types, respectively. Images are composed of bands and a dictionary of properties. Features are composed of a Geometry and a dictionary of properties. A stack of images (e.g. an image time series) is handled by an ImageCollection. A collection of features is handled by a FeatureCollection. Other fundamental data structures in Earth Engine include Dictionary, List, Array, Geometry, Date, Number and String. It is important to remember that these are all server-side objects. That is, your client browser does not know anything about the objects in your script unless you explicitly request information about them. That request triggers a message being passed from Google to the Code Editor. If the message is large, there will be a corresponding slow down.

Earth Engine algorithms

There are several ways to run operations in the API:

  • Calling methods that are attached to objects.
  • Calling algorithms.
  • Calling Code Editor specific functions.
  • Defining new functions.

The Docs tab of the Code Editor lists the methods of each API class. For example, the Image class has an add() method:

var image3 = image1.add(image2);
      

This method adds the bands of image2 to the bands of image1. The ee.Algorithms category contains a list of currently supported algorithms for specialized or domain specific processing. For example, to create topographic layers from an input Digital Elevation Model (DEM):

var terrainImage = ee.Algorithms.Terrain(dem);
      

Code Editor specific functions include the Map and Export methods, which control how layers are added to the map panel or exported to Google Drive, respectively. Functions can also be created in JavaScript using

var myFunction = function(args) {
  // do something
  return something;
};
      

As illustrated in the Mapping section, user defined functions are useful for creating custom functionality or modifying the elements of a collection using:

var collection2 = collection1.map(aFunction);
      

The following sections illustrate these concepts for various simple use cases.

‘Hello world!’ JavaScript

Printing out information to the console is a basic task for getting information about an object, displaying the numeric result of a computation, displaying object metadata or helping with debugging. The iconic ‘Hello World!’ example in the Code Editor is:

print('Hello world!');
      

Copy this line into the code editor of the Code Editor and click Run. Note that the output is displayed in the Console tab, on the right of the Code Editor. For a more remote sensing relevant example, the following prints the metadata of a Landsat 8 image:

print(ee.Image('LANDSAT/LC8_L1T/LC80440342014077LGN00'));
      

Carefully inspect the output in the console to see metadata available for Landsat images.

Adding data to the map

In addition to printing information to the console, adding data to the Map is the way to visualize geographic data. Use Map.addLayer() to do that. In the following example, an Image is instantiated (how to find these images is covered later) using ee.Image(), added to the map with Map.addLayer() and the map is centered over the image:

// Load an image.
var image = ee.Image('LANDSAT/LC8_L1T/LC80440342014077LGN00');

// Center the map on the image.
Map.centerObject(image, 9);

// Display the image.
Map.addLayer(image);
      

The second parameter of Map.centerObject() is a zoom level, where higher numbers indicate larger scale (more zoomed in). The parameters for the Map functions are described in depth in the API reference accessible from the Docs tab. If the appearance of the image is unsatisfactory, configure the display parameters with an additional argument to Map.addLayer(). For example:

// Load the image from the archive.
var image = ee.Image('LANDSAT/LC8_L1T/LC80440342014077LGN00');

// Define visualization parameters in an object literal.
var vizParams = {bands: ['B5', 'B4', 'B3'], min: 5000, max: 15000, gamma: 1.3};

// Center the map on the image and display.
Map.centerObject(image, 9);
Map.addLayer(image, vizParams, 'Landsat 8 false color');
      

Observe that the visualization parameters are defined by an object literal, which includes a list of bands to display, a minimum and maximum digital number and a gamma value. (Learn more about Landsat bands here. Learn more about image visualization here).

Use Map.addLayer() to add features and feature collections to the map. For example,

var counties = ee.FeatureCollection('ft:1S4EB6319wWW2sWQDPhDvmSBIVrD3iEmCLYB7nMM');
Map.addLayer(counties, {}, 'counties');
      

Note that the encrypted key of this table is everything after the ft: and before the quote.

Finding images, image collections and feature collections

Images and image collections are discoverable by searching the Earth Engine data catalog. For example, entering ‘Landsat 8’ into the search field results in a list of raster datasets. (The complete listing of Earth Engine datasets is at code.earthengine.google.com/datasets). Click on the dataset name to get a brief description, information about the temporal availability, data provider and ImageCollection ID. Click the Import button to automatically create an Imports section at the top of your script with a variable for this collection.

Alternatively, copy the ImageCollection ID and paste it into your code. For example, choose the first result of the ‘Landsat 8’ search and copy the ID as follows:

var collection = ee.ImageCollection('LANDSAT/LC8_L1T');
      

Since this is a collection of many images spanning the Earth land surface, finding an individual image in the collection requires filtering in order to narrow down the search. Alternatively, the collection of images can be reduced to a single image using compositing and mosaicking techniques. More on filtering and compositing (see Reducing) in the next sections.

Feature collections are not as easy to find since there is not a curated catalog of Fusion Tables as there is for imagery. However, searching from the Code Editor will also list ‘Table’ (vector) datasets. These are generally user uploaded content of varying quality and completeness. Some useful datasets are listed here. To create a Fusion Table, upload CSV or KML text with geographic coordinates. Learn more about importing vector datasets here.

Filtering and Sorting

It is often necessary to filter a collection by space and/or time in order to limit the number of results. For example, consider the task of sorting the Landsat 8 scene collection in order to find a cloud-free scene for San Francisco. First, it’s necessary to define the region of interest. A point is often useful for that. Activate the Inspector tab on the right side of the Code Editor and click near the center of your area of interest, copy the coordinates from the Inspector tab, then construct a Point using:

var point = ee.Geometry.Point(-122.262, 37.8719);
      

Construct start and end dates:

var start = ee.Date('2014-06-01');
var finish = ee.Date('2014-10-01');
      

Filter the Landsat 8 collection using the point and the dates, then sort using a metadata property (discovered during inspection of the Landsat 8 scene metadata):

var filteredCollection = ee.ImageCollection('LANDSAT/LC8_L1T')
  .filterBounds(point)
  .filterDate(start, finish)
  .sort('CLOUD_COVER', true);
      

This collection can be safely printed and inspected. (If the collection has too many images, printing it will either be very slow, time out, or return an error). Observe that the images in the collection are a List stored in the ‘features’ property of the ImageCollection. The ID of any image in the collection can be copied into the Image constructor as above. Alternatively, get the first image (lowest cloud cover):

var first = filteredCollection.first();
      

Access the complete Earth Engine filtering functionality using filter() with an ee.Filter as the argument. (The filterBounds() and filterDate() methods used above are shortcuts). For example, the following creates a Filter, uses it to filter a FeatureCollection and displays the result:

// Load a feature collection from a Fusion Table.
var featureCollection = ee.FeatureCollection('ft:1fRY18cjsHzDgGiJiS2nnpUU3v9JPDc2HNaR7Xk8');

// Filter the collection.
var filteredFC = featureCollection.filter(ee.Filter.eq('Name', 'California'));

// Display the collection.
Map.addLayer(filteredFC, {}, 'California');
      

The link below contains the code used until this point. Get these links by clinking the Get Link button at the top of the Code Editor and copying the URL from the address bar in the browser: https://code.earthengine.google.com/74508b22766c10e74e87a7ebaccec9e7

Band math

Perform mathematical operations on images using Image methods. This may include band recombinations (spectral indices), image differencing or mathematical operations such as multiplication by a constant. For example, compute the difference between Normalized Difference Vegetation Index (NDVI) images 20 years apart:

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LT5_L1T_TOA/LT50440341990155XXX03');
var image2 = ee.Image('LT5_L1T_TOA/LT50440342010162EDC00');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);
      

Notice the use of a user defined function in this example. More on functions in the next section.

Mapping (what to do instead of a for-loop)

Use map() to iterate over items in a collection. (For loops are NOT the right way to do that in Earth Engine and should be avoided). The map() function can be applied to an ImageCollection, a FeatureCollection or a List and accepts a function as its argument. The argument of the function is an element of the collection over which it is mapped. This is useful for modifying every element of the collection in the same way, for example adding. For example, the following code adds an NDVI band to every image in an ImageCollection:

// This function gets NDVI from Landsat 8 imagery.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// Load the Landsat 8 raw data, filter by location and date.
var collection = ee.ImageCollection('LANDSAT/LC8_L1T')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the collection.
var ndviCollection = collection.map(addNDVI);
      

Another common task is adding a new property (or ‘attribute’ or ‘field’) to features in a FeatureCollection. In the following example, the new property is a computation involving two existing attributes:

// This function creates a new property that is the sum of two existing properties.
var addField = function(feature) {
  var sum = ee.Number(feature.get('property1')).add(feature.get('property2'));
  return feature.set({'sum': sum});
};

// Create a FeatureCollection from a list of Features.
var features = ee.FeatureCollection([
  ee.Feature(ee.Geometry.Point(-122.4536, 37.7403),
    {property1: 100, property2: 100}),
    ee.Feature(ee.Geometry.Point(-118.2294, 34.039),
    {property1: 200, property2: 300}),
]);

// Map the function over the collection.
var featureCollection = features.map(addField);

// Print a selected property of one Feature.
print(featureCollection.first().get('sum'));

// Print the entire FeatureCollection.
print(featureCollection);
      

Note the cast to ee.Number required for the property value to be recognized as a number in order to use the add() method). The type of the collection can be changed by map(). For example:

// This function returns the image centroid as a new Feature.
var getGeom = function(image) {
  return ee.Feature(image.geometry().centroid(), {foo: 1});
};

// Load a Landsat 8 collection.
var collection = ee.ImageCollection('LANDSAT/LC8_L1T')
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-06-01', '2014-10-01');

// Map the function over the ImageCollection.
var featureCollection = ee.FeatureCollection(collection.map(getGeom));

// Print the collection.
print(featureCollection);
      

Note the added property (foo) for each feature created from the image centroid. In the final line, the cast makes the resultant collection recognizable as a FeatureCollection.

Reducing

Reducing is the way to aggregate data over time, space, bands, arrays and other data structures in Earth Engine. Various methods exist for this purpose in the API. For example, to make a composite of an ImageCollection, use reduce() to reduce the images in the collection to one Image. A simple example is creating the median composite of the five least cloudy scenes in the Landsat 8 collection defined earlier:

// Load a Landsat 8 collection.
var collection = ee.ImageCollection('LANDSAT/LC8_L1T')
  // Filter by date and location.
  .filterBounds(ee.Geometry.Point(-122.262, 37.8719))
  .filterDate('2014-01-01', '2014-12-31')
  // Sort by increasing cloudiness.
  .sort('CLOUD_COVER');

// Compute the median of each pixel for each band of the 5 least cloudy scenes.
var median = collection.limit(5).reduce(ee.Reducer.median());
      

Reducing is also the way to get statistics of an image in the regions defined by a Feature or FeatureCollection. Suppose the task is to compute the mean pixel values within an area of interest. Use reduceRegion() for this purpose. For example:

// Load and display a Landsat TOA image.
var image = ee.Image('LANDSAT/LC8_L1T_TOA/LC80440342014077LGN00');
Map.addLayer(image, {bands: ['B4', 'B3', 'B2'], max: 0.3});

// Create an arbitrary rectangle as a region and display it.
var region = ee.Geometry.Rectangle(-122.2806, 37.1209, -122.0554, 37.2413);
Map.addLayer(region);

// Get a dictionary of means in the region.  Keys are bandnames.
var mean = image.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: region,
  scale: 30
});
      

Learn more about reducers from the Reducers doc.

Masking

Make pixels transparent or exclude them from analysis using masks. Masked pixels are treated as no-data in Earth Engine. Pixels are masked when the mask value is zero. Continuing the image differencing example, this example uses a mask to display areas of increased and decreased NDVI over the difference interval:

// This function gets NDVI from Landsat 5 imagery.
var getNDVI = function(image) {
  return image.normalizedDifference(['B4', 'B3']);
};

// Load two Landsat 5 images, 20 years apart.
var image1 = ee.Image('LT5_L1T_TOA/LT50440341990155XXX03');
var image2 = ee.Image('LT5_L1T_TOA/LT50440342010162EDC00');

// Compute NDVI from the scenes.
var ndvi1 = getNDVI(image1);
var ndvi2 = getNDVI(image2);

// Compute the difference in NDVI.
var ndviDifference = ndvi2.subtract(ndvi1);
// Load the land mask from the SRTM DEM.
var landMask = ee.Image('CGIAR/SRTM90_V4').mask();

// Update the NDVI difference mask with the land mask.
var maskedDifference = ndviDifference.updateMask(landMask);

// Display the masked result.
var vizParams = {min: -0.5, max: 0.5, palette: ['FF0000', 'FFFFFF', '0000FF']};
Map.setCenter(-122.2531, 37.6295, 9);
Map.addLayer(maskedDifference, vizParams, 'NDVI difference');
      

In this example, note that the mask of the NDVI difference is updated by the land mask with updateMask(). This sets the mask of the NDVI difference pixels to the land mask wherever the NDVI difference mask is non-zero.

Masking is also useful for excluding data from the analysis. Consider the reduceRegion() example from the Reducing section. Suppose the task is to compute a seasonal mean NDVI for Santa Cruz, excluding cloudy pixels. The following example demonstrates multiple concepts: filtering, mapping, reducing and the use of a cloud mask:

// This function gets NDVI from a Landsat 8 image.
var addNDVI = function(image) {
  return image.addBands(image.normalizedDifference(['B5', 'B4']));
};

// This function masks cloudy pixels.
var cloudMask = function(image) {
  var clouds = ee.Algorithms.Landsat.simpleCloudScore(image).select(['cloud']);
  return image.updateMask(clouds.lt(10));
};

// Load a Landsat collection, map the NDVI and cloud masking functions over it.
var collection = ee.ImageCollection('LANDSAT/LC8_L1T_TOA')
  .filterBounds(ee.Geometry.Point([-122.262, 37.8719]))
  .filterDate('2014-03-01', '2014-05-31')
  .map(addNDVI)
  .map(cloudMask);

// Reduce the collection to the mean of each pixel and display.
var meanImage = collection.reduce(ee.Reducer.mean());
var vizParams = {bands: ['B5_mean', 'B4_mean', 'B3_mean'], min: 0, max: 0.5};
Map.addLayer(meanImage, vizParams, 'mean');

// Load a region in which to compute the mean and display it.
var counties = ee.FeatureCollection ('ft:1S4EB6319wWW2sWQDPhDvmSBIVrD3iEmCLYB7nMM');
var santacruz = ee.Feature(counties.filter(ee.Filter.eq('FIPS', 6087)).first());
Map.addLayer(santacruz);

// Get the mean of NDVI in the region.
var mean = meanImage.select(['nd_mean']).reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: santacruz.geometry(),
  scale: 30
});
      

Enviar comentarios sobre…

Google Earth Engine API