Comienza a usar Earth Engine

Esta guía de introducción tiene como objetivo ser una forma rápida de comenzar a programar con la API de JavaScript de Earth Engine. Para obtener una introducción a JavaScript y ejercicios más detallados con la API de Earth Engine, consulta los instructivos. Para conocer el estilo de programación de JavaScript recomendado, consulta la Guía de estilo de JavaScript de Google.

Google Earth Engine permite que los usuarios ejecuten algoritmos en imágenes y vectores georreferenciados almacenados en la infraestructura de Google. La API de Google Earth Engine proporciona una biblioteca de funciones que se pueden aplicar a los datos para su visualización y análisis. El catálogo de datos públicos de Earth Engine contiene una gran cantidad de conjuntos de datos vectoriales y de imágenes disponibles públicamente. Los recursos privados también se pueden crear en las carpetas personales de los usuarios.

Cómo usar estos documentos

La documentación de Earth Engine está diseñada para personas familiarizadas con el análisis de datos geoespaciales. La documentación se estructura principalmente por tipo de datos. Por ejemplo, la navegación del lado izquierdo contiene vínculos a secciones o páginas sobre tipos de datos importantes, como Image, ImageCollection, Feature, FeatureCollection, Geometry, Reducer, Chart, Join y Array. En esta guía, se describe solo lo suficiente sobre estos tipos para que puedas comenzar. También hay secciones para el aprendizaje automático, algoritmos especializados o específicos de sensores (p.ej., algoritmos de Landsat), apps orientadas al público, administración de datos (recursos) y detalles importantes sobre el funcionamiento interno de Earth Engine. Antes de profundizar en cualquiera de esos temas, comienza aquí.

El editor de código

El editor de código es un entorno interactivo para desarrollar aplicaciones de Earth Engine (figura 1). El panel central proporciona un editor de código JavaScript. Arriba del editor, hay botones para guardar la secuencia de comandos actual, ejecutarla y borrar el mapa. El botón Obtener vínculo genera una URL única para la secuencia de comandos en la barra de direcciones. El mapa del panel inferior contiene las capas que agregó la secuencia de comandos. En la parte superior, hay un cuadro de búsqueda para conjuntos de datos y lugares. El panel izquierdo contiene ejemplos de código, tus secuencias de comandos guardadas, una referencia de la API que permite realizar búsquedas y un administrador de recursos para datos privados. El panel derecho tiene un inspector para consultar el mapa, una consola de salida y un administrador para tareas de larga duración. El botón de ayuda en la esquina superior derecha contiene vínculos a esta guía y a otros recursos para obtener ayuda. Obtén más información en la guía del editor de código y en la guía de ayuda.

Editor de código
Figura 1. code.earthengine.google.com, el editor de código de Earth Engine

Abrir y ejecutar código en el editor de código

En los pasos que se indican a continuación, se muestra cómo abrir Earth Engine y ejecutar una secuencia de comandos personalizada que muestra una imagen. Para obtener mejores resultados, te recomendamos que instales la versión más reciente de Chrome, el navegador web de Google, disponible aquí.

  1. Abre el editor de código de Earth Engine aquí: code.earthengine.google.com.
  2. Navega a la pestaña Secuencias de comandos ubicada en el extremo izquierdo del editor de código. Allí, encontrarás una colección de secuencias de comandos de ejemplo que acceden a los datos de Earth Engine, los muestran y los analizan.
  3. En “Colección de imágenes”, selecciona el ejemplo “Compuesto filtrado”. Verás que aparece una secuencia de comandos en la consola central. Presiona el botón Ejecutar para ejecutar la secuencia de comandos. En el ejemplo de Filtered Composite, se seleccionan imágenes de Landsat 7 que se cruzan o están dentro de los límites de Colorado y Utah. Luego, muestra una composición de color verdadero de las imágenes seleccionadas. En los ejemplos, se presentan métodos de uso frecuente, como filter(), clip() y Map.addLayer().

Estructuras de datos de Earth Engine

Las dos estructuras de datos geográficos más fundamentales en Earth Engine son Image y Feature, que corresponden a los tipos de datos de trama y vectoriales, respectivamente. Las imágenes se componen de bandas y un diccionario de propiedades. Los objetos se componen de un Geometry y un diccionario de propiedades. Una pila de imágenes (p.ej., una serie temporal de imágenes) se controla con un ImageCollection. Un FeatureCollection controla una colección de atributos. Otras estructuras de datos fundamentales en Earth Engine incluyen Dictionary, List, Array, Date, Number y String (obtén más información sobre los tipos de datos básicos en este instructivo. Es importante recordar que todos estos son objetos del servidor y no se manipulan de la misma manera que los objetos de JavaScript del cliente (obtén más información).

Algoritmos de Earth Engine

Existen varias formas de ejecutar operaciones en la API:

  • Llamar a métodos que se adjuntan a objetos
  • Algoritmos de llamada.
  • Llamar a funciones específicas del editor de código
  • Definir funciones nuevas

En la pestaña Docs del editor de código, se enumeran los métodos de cada clase de la API. Por ejemplo, la clase Image tiene un método add():

Editor de código (JavaScript)

var image3 = image1.add(image2);

Este método agrega las bandas de image2 a las bandas de image1. La categoría ee.Algorithms contiene una lista de los algoritmos admitidos actualmente para el procesamiento especializado o específico del dominio. Por ejemplo, para crear capas topográficas a partir de un modelo digital de elevación (DEM) de entrada, haz lo siguiente:

Editor de código (JavaScript)

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

Las funciones específicas del editor de código incluyen los métodos Map y Export, que controlan cómo se agregan las capas al panel del mapa o se exportan a Google Drive, respectivamente. Las funciones también se pueden crear en JavaScript con

Editor de código (JavaScript)

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

Como se ilustra en la sección Map, las funciones definidas por el usuario son útiles para crear funciones personalizadas o modificar los elementos de una colección con lo siguiente:

Editor de código (JavaScript)

var collection2 = collection1.map(aFunction);

En las siguientes secciones, se ilustran estos conceptos para varios casos de uso sencillos.

"Hello world!" JavaScript

Imprimir información en la consola es una tarea básica para obtener información sobre un objeto, mostrar el resultado numérico de un cálculo, mostrar metadatos de objetos o ayudar con la depuración. El icónico ejemplo de "Hello World!" en el editor de código es el siguiente:

Editor de código (JavaScript)

print('Hello world!');

Copia esta línea en el editor de código del Editor de código y haz clic en Ejecutar. Ten en cuenta que el resultado se muestra en la pestaña Console, a la derecha del editor de código. Para obtener un ejemplo más relevante de teledetección, lo siguiente imprime los metadatos de una imagen de Landsat 8:

Editor de código (JavaScript)

print(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'));

Inspecciona con atención el resultado en la consola para ver los metadatos disponibles para las imágenes de Landsat.

Agrega datos al mapa

Además de imprimir información en la consola, agregar datos al Map es la forma de visualizar datos geográficos. Usa Map.addLayer() para hacerlo. En el siguiente ejemplo, se crea una instancia de un Image (más adelante se explica cómo encontrar estas imágenes) con ee.Image(), se agrega al mapa con Map.addLayer() y el mapa se centra sobre la imagen:

Editor de código (JavaScript)

// Load an image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

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

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

El segundo parámetro de Map.centerObject() es un nivel de zoom, en el que los números más altos indican una escala mayor (más acercamiento). Los parámetros de las funciones Map se describen en detalle en la referencia de la API, a la que se puede acceder desde la pestaña Docs. Si el aspecto de la imagen no es satisfactorio, configura los parámetros de visualización con un argumento adicional para Map.addLayer(). Por ejemplo:

Editor de código (JavaScript)

// Load the image from the archive.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');

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

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

Observa que los parámetros de visualización se definen con un literal de objeto, que incluye una lista de bandas para mostrar, un valor de reflectancia mínimo y máximo, y un valor de gamma. (Obtén más información sobre las bandas de Landsat aquí. Obtén más información sobre la visualización de imágenes aquí).

Usa Map.addLayer() para agregar objetos geográficos y colecciones de objetos geográficos al mapa. Por ejemplo,

Editor de código (JavaScript)

var counties = ee.FeatureCollection('TIGER/2018/Counties');
Map.addLayer(counties, {}, 'counties');

Busca imágenes, colecciones de imágenes y colecciones de objetos

Las imágenes, las colecciones de imágenes y las colecciones de objetos se pueden descubrir buscando en el catálogo de datos de Earth Engine. Por ejemplo, si ingresas "Landsat 8" en el campo de búsqueda, se obtiene una lista de conjuntos de datos de ráster. (La lista completa de conjuntos de datos de Earth Engine se encuentra en el catálogo de datos de Earth Engine). Haz clic en el nombre del conjunto de datos para obtener una breve descripción, información sobre la disponibilidad temporal, el proveedor de datos y el ID de la colección. Haz clic en el botón Importar para crear automáticamente una sección Importaciones en la parte superior de tu secuencia de comandos con una variable para esta colección.

Como alternativa, copia el ID de la colección y pégalo en tu código. Por ejemplo, elige el resultado de TOA de nivel 1 de la búsqueda de "Landsat 8" y copia el ID de la siguiente manera:

Editor de código (JavaScript)

var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');

Como se trata de una colección de muchas imágenes que abarcan la superficie terrestre, para encontrar una imagen individual en la colección, es necesario aplicar filtros para acotar la búsqueda. Como alternativa, la colección de imágenes se puede reducir a una sola imagen con técnicas de composición y mosaico. Obtén más información sobre el filtrado y la composición (consulta Reduce) en las siguientes secciones.

Las colecciones de componentes también están disponibles a través del Data Catalog. Su representación es más pequeña que las colecciones de imágenes, pero encontrarás límites internacionales, censales, de cuencas hidrográficas y de áreas protegidas, por nombrar algunos. Obtén más información para importar tus propios conjuntos de datos vectoriales aquí.

Filtrar y ordenar

A menudo, es necesario filtrar una colección por espacio o tiempo para limitar la cantidad de resultados. Por ejemplo, considera la tarea de ordenar la colección de escenas de Landsat 8 para encontrar una escena sin nubes de San Francisco. Primero, es necesario definir la región de interés. Un punto suele ser útil para eso. Activa la pestaña Inspector en el lado derecho del editor de código y haz clic cerca del centro de tu área de interés, copia las coordenadas de la pestaña Inspector y, luego, construye un Point con lo siguiente:

Editor de código (JavaScript)

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

Crea las fechas de inicio y finalización:

Editor de código (JavaScript)

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

Filtra la colección de Landsat 8 con el punto y las fechas y, luego, ordena con una propiedad de metadatos (descubierta durante la inspección de los metadatos de la escena de Landsat 8):

Editor de código (JavaScript)

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

Esta colección se puede imprimir y, luego, inspeccionar de forma segura. (Si la colección tiene demasiadas imágenes, la impresión será muy lenta, se agotará el tiempo de espera o se mostrará un error). Observa que las imágenes de la colección son un List almacenado en la propiedad "features" de ImageCollection. El ID de cualquier imagen de la colección se puede copiar en el constructor Image como se indicó anteriormente. Como alternativa, obtén la primera imagen (con la menor cobertura de nubes):

Editor de código (JavaScript)

var first = filteredCollection.first();

Accede a la funcionalidad completa de filtrado de Earth Engine con filter() con un ee.Filter como argumento. (Los métodos filterBounds() y filterDate() que se usaron anteriormente son atajos). Por ejemplo, en el siguiente código, se crea un Filter, se usa para filtrar un FeatureCollection y se muestra el resultado:

Editor de código (JavaScript)

// Load a feature collection.
var featureCollection = ee.FeatureCollection('TIGER/2016/States');

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

// Display the collection.
Map.setCenter(-119.604, 37.798, 6);
Map.addLayer(filteredFC, {}, 'California');

Matemáticas de bandas

Realizar operaciones matemáticas en imágenes con métodos Image Esto puede incluir recombinaciones de bandas (índices espectrales), diferenciación de imágenes u operaciones matemáticas, como la multiplicación por una constante. Por ejemplo, calcula la diferencia entre las imágenes del índice de vegetación de diferencia normalizada (NDVI) con 20 años de diferencia:

Editor de código (JavaScript)

// 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('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

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

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

Observa el uso de un function definido por el usuario en este ejemplo. Obtén más información sobre las funciones en la siguiente sección.

Map (qué hacer en lugar de un bucle for)

Usa map() para iterar los elementos de una colección. (Los bucles for NO son la forma correcta de hacerlo en Earth Engine y deben evitarse). La función map() se puede aplicar a un ImageCollection, un FeatureCollection o un List, y acepta un function como argumento. El argumento de la función es un elemento de la colección sobre la que se asigna. Esto es útil para modificar cada elemento de la colección de la misma manera, por ejemplo, agregando. Por ejemplo, el siguiente código agrega una banda de NDVI a cada imagen en un ImageCollection:

Editor de código (JavaScript)

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

// Load the Landsat 8 TOA data, filter by location and date.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .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);

Otra tarea común es agregar una propiedad nueva (o "atributo" o "campo") a los objetos de un FeatureCollection. En el siguiente ejemplo, la propiedad nueva es un cálculo que involucra dos atributos existentes:

Editor de código (JavaScript)

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

Ten en cuenta la conversión a ee.Number que se requiere para que el valor de la propiedad se reconozca como un número para usar el método add(). El tipo de colección se puede cambiar con map(). Por ejemplo:

Editor de código (JavaScript)

// 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 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  .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);

Observa la propiedad agregada (foo) para cada atributo creado a partir del centroide de la imagen. En la última línea, la conversión hace que la colección resultante se reconozca como un FeatureCollection.

Reducir

La reducción es la forma de agregar datos a lo largo del tiempo, el espacio, las bandas, los arrays y otras estructuras de datos en Earth Engine. Existen varios métodos para este propósito en la API. Por ejemplo, para crear un compuesto de un ImageCollection, usa reduce() para reducir las imágenes de la colección a una sola imagen. Un ejemplo sencillo es crear la composición de la mediana de las cinco escenas menos nubladas de la colección de Landsat 8 definida anteriormente:

Editor de código (JavaScript)

// Load a Landsat 8 TOA collection.
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA')
  // 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());

La reducción también es la forma de obtener estadísticas de una imagen en las regiones definidas por un Feature o un FeatureCollection. Supongamos que la tarea consiste en calcular los valores de píxeles promedio dentro de un área de interés. Usa reduceRegion() para este propósito. Por ejemplo:

Editor de código (JavaScript)

// Load and display a Landsat TOA image.
var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318');
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
});

Obtén más información sobre los reductores en el documento Reductores.

Enmascarar

Cada píxel de un ee.Image tiene un valor y una máscara que varía de 0 (sin datos) a 1. Los píxeles enmascarados (en los que mask==0) se tratan como sin datos. Los píxeles con 0 < máscara ≤ 1 tienen un valor, pero la máscara lo pondera para los cálculos numéricos.

Puedes hacer que los píxeles sean transparentes o excluirlos del análisis con máscaras. Los píxeles se enmascaran cuando el valor de la máscara es cero. Continuando con el ejemplo de diferenciación de imágenes, usa una máscara para mostrar las áreas de aumento y disminución del NDVI en el intervalo de diferencia:

// 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('LANDSAT/LT05/C02/T1_TOA/LT05_044034_19900604');
var image2 = ee.Image('LANDSAT/LT05/C02/T1_TOA/LT05_044034_20100611');

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

En este ejemplo, observa que la máscara de la diferencia de NDVI se actualiza con la máscara de tierra con updateMask(). Esto establece la máscara de los píxeles de diferencia del NDVI en la máscara de tierra donde la máscara de diferencia del NDVI no sea cero.

El enmascaramiento también es útil para excluir datos del análisis. Considera el ejemplo de reduceRegion() de la sección Reduce. Supongamos que la tarea consiste en calcular un NDVI medio estacional para el condado de Santa Clara, California, excluyendo los píxeles nublados. En el siguiente ejemplo, se muestran varios conceptos: filtrado, asignación, reducción y el uso de una máscara de nubes:

Editor de código (JavaScript)

// 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/LC08/C02/T1_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.02, max: 0.4};
Map.addLayer(meanImage, vizParams, 'mean');

// Load a region in which to compute the mean and display it.
var counties = ee.FeatureCollection('TIGER/2018/Counties');
var santaClara = ee.Feature(counties.filter(ee.Filter.eq('NAME', 'Santa Clara')).first());
Map.addLayer(santaClara);

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

// Print mean NDVI for the region.
mean.get('nd_mean').evaluate(function(val){
  print('Santa Clara spring mean NDVI:', val);
});