Começar a usar o Earth Engine

Este guia de início rápido tem como objetivo ensinar a programar com a API JavaScript do Earth Engine. Para uma introdução ao JavaScript e exercícios mais aprofundados com a API Earth Engine, consulte os tutoriais. Para conferir o estilo de programação JavaScript recomendado, consulte o Guia de estilo do Google para JavaScript.

O Google Earth Engine permite que os usuários executem algoritmos em imagens e vetores georeferenciados armazenados na infraestrutura do Google. A API Google Earth Engine oferece uma biblioteca de funções que podem ser aplicadas aos dados para exibição e análise. O catálogo de dados públicos do Earth Engine contém uma grande quantidade de imagens e conjuntos de dados vetoriais disponíveis publicamente. Recursos particulares também podem ser criados nas pastas pessoais dos usuários.

Como usar estes documentos

A documentação do Earth Engine foi desenvolvida para pessoas que já conhecem a análise de dados geoespaciais. Os documentos são estruturados principalmente por tipo de dados. Por exemplo, a navegação à esquerda contém links para seções ou páginas sobre tipos de dados importantes, como Image, ImageCollection, Feature, FeatureCollection, Geometry, Reducer, Chart, Join e Array. Este guia descreve apenas o suficiente sobre esses tipos para você começar. Também há seções sobre aprendizado de máquina, algoritmos especializados ou específicos para sensores (por exemplo, algoritmos Landsat), apps voltados ao público, gerenciamento de dados (ativos) e detalhes importantes sobre o funcionamento interno do Earth Engine. Antes de mergulhar nisso, comece por aqui.

Editor de código

O editor de código é um ambiente interativo para desenvolver aplicativos do Earth Engine. O painel central fornece um editor de código JavaScript. Acima do editor, há botões para salvar o script atual, executá-lo e limpar o mapa. O botão Get Link gera um URL exclusivo para o script na barra de endereço. O mapa no painel de baixo contém as camadas adicionadas pelo script. Na parte de cima, há uma caixa de pesquisa para conjuntos de dados e lugares. O painel esquerdo contém exemplos de código, seus scripts salvos, uma referência de API pesquisável e um gerenciador de recursos para dados particulares. O painel à direita tem um inspetor para consultar o mapa, um console de saída e um gerenciador para tarefas de longa duração. O botão de ajuda help no canto superior direito contém links para este guia e outros recursos. Saiba mais no guia do Editor de código e no guia de ajuda.

Como abrir e executar o código no editor de código

As etapas abaixo demonstram como abrir o Earth Engine e executar um script personalizado que mostra uma imagem. Para ter os melhores resultados, instale a versão mais recente do Chrome, o navegador da Web do Google, disponível aqui.

1. Abra o editor de código do Earth Engine aqui: code.earthengine.google.com.
2. Navegue até a guia Scripts, localizada no canto esquerdo do editor de código. Lá, você vai encontrar uma coleção de scripts de exemplo que acessam, mostram e analisam dados do Earth Engine.
3. Em "Image Collection", selecione o exemplo "Composite filtrado". Um script vai aparecer no console central. Pressione o botão Run para executar o script. O exemplo de composição filtrada seleciona imagens do Landsat 7 que se cruzam ou estão dentro dos limites do Colorado e do Utah. Em seguida, ele mostra um composto de cores real das imagens selecionadas. Os exemplos apresentam métodos usados com frequência, como filter(), clip() e Map.addLayer().

Estruturas de dados do Earth Engine

As duas estruturas de dados geográficos mais importantes no Earth Engine são Image e Feature, que correspondem aos tipos de dados raster e vetor, respectivamente. As imagens são compostas por bandas e um dicionário de propriedades. Os recursos são compostos por um Geometry e um dicionário de propriedades. Uma pilha de imagens (por exemplo, uma série temporal de imagens) é processada por um ImageCollection. Uma coleção de recursos é processada por um FeatureCollection. Outras estruturas de dados fundamentais no Earth Engine incluem Dictionary, List, Array, Date, Number e String. Saiba mais sobre os tipos de dados básicos neste tutorial. É importante lembrar que esses são todos objetos do lado do servidor e não são manipulados da mesma forma que os objetos JavaScript do lado do cliente (saiba mais).

Algoritmos do Earth Engine

Há várias maneiras de executar operações na API:

• Chamar métodos anexados a objetos.
• Chamar algoritmos.
• Chamar funções específicas do editor de código.
• Definir novas funções.

A guia Documentos do Editor de código lista os métodos de cada classe de API. Por exemplo, a classe Image tem um método add():

var image3 = image1.add(image2);

Esse método adiciona as faixas de image2 às faixas de image1. A categoria ee.Algorithms contém uma lista de algoritmos com suporte para processamento especializado ou específico do domínio. Por exemplo, para criar camadas topográficas a partir de um modelo digital de elevação (DEM) de entrada:

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

As funções específicas do editor de código incluem os métodos Map e Export, que controlam como as camadas são adicionadas ao painel do mapa ou exportadas para o Google Drive, respectivamente. As funções também podem ser criadas em JavaScript usando

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

Conforme ilustrado na seção de mapeamento, as funções definidas pelo usuário são úteis para criar funcionalidades personalizadas ou modificar os elementos de uma coleção usando:

var collection2 = collection1.map(aFunction);

As seções a seguir ilustram esses conceitos para vários casos de uso simples.

'Hello world!' JavaScript

Imprimir informações no console é uma tarefa básica para receber informações sobre um objeto, mostrar o resultado numérico de uma computação, mostrar metadados do objeto ou ajudar na depuração. O exemplo clássico "Hello World!" no editor de código é:

print('Hello world!');

Copie essa linha para o editor de código e clique em Run. A saída é mostrada na guia Console, à direita do editor de código. Para um exemplo mais relevante de sensoriamento remoto, o comando a seguir imprime os metadados de uma imagem Landsat 8:

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

Inspecione cuidadosamente a saída no console para conferir os metadados disponíveis para as imagens do Landsat.

Adicionar dados ao mapa

Além de imprimir informações no console, adicionar dados ao Map é a maneira de visualizar dados geográficos. Use Map.addLayer() para fazer isso. No exemplo a seguir, uma Image é instanciada (como encontrar essas imagens será abordado mais adiante) usando ee.Image(), adicionada ao mapa com Map.addLayer() e o mapa é centralizado sobre a imagem:

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

O segundo parâmetro de Map.centerObject() é um nível de zoom, em que números maiores indicam uma escala maior (mais ampliado). Os parâmetros das funções Map são descritos em detalhes na referência da API acessível na guia Documentos. Se a aparência da imagem não for satisfatória, configure os parâmetros de exibição com um argumento adicional para Map.addLayer(). Por exemplo:

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

Os parâmetros de visualização são definidos por um literal de objeto, que inclui uma lista de bandas a serem exibidas, um valor de refletância mínimo e máximo e um valor de gama. Saiba mais sobre as bandas do Landsat. Saiba mais sobre a visualização de imagens neste link.

Use Map.addLayer() para adicionar elementos e coleções de elementos ao mapa. Por exemplo,

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

Como encontrar imagens, coleções de imagens e coleções de elementos

As imagens, coleções de imagens e coleções de elementos podem ser descobertas pesquisando o Catálogo de dados do Earth Engine. Por exemplo, digite "Landsat 8" no campo de pesquisa para ver os resultados em uma lista de conjuntos de dados raster. A lista completa dos conjuntos de dados do Earth Engine está disponível no Catálogo de dados do Earth Engine. Clique no nome do conjunto de dados para conferir uma breve descrição, informações sobre a disponibilidade temporal, o provedor de dados e o ID da coleção. Clique no botão Import para criar automaticamente uma seção Imports na parte de cima do script com uma variável para essa coleção.

Como alternativa, copie o ID da coleção e cole no código. Por exemplo, escolha o resultado de TOA de nível 1 da pesquisa "Landsat 8" e copie o ID da seguinte maneira:

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

Como essa é uma coleção de muitas imagens que abrangem a superfície terrestre, encontrar uma imagem individual na coleção exige filtragem para restringir a pesquisa. Como alternativa, a coleção de imagens pode ser reduzida a uma única imagem usando técnicas de composição e mosaico. Mais informações sobre filtragem e composição (consulte Redução) nas próximas seções.

As coleções de elementos também estão disponíveis no Data Catalog. A representação deles é menor do que a das coleções de imagens, mas você vai encontrar limites de áreas internacionais, de censo, de bacias hidrográficas e de áreas protegidas, entre outros. Saiba mais sobre como importar seus próprios conjuntos de dados vetoriais aqui.

Filtragem e classificação

Muitas vezes, é necessário filtrar uma coleção por espaço e/ou tempo para limitar o número de resultados. Por exemplo, considere a tarefa de classificar a coleção de cenas do Landsat 8 para encontrar uma cena sem nuvens em São Francisco. Primeiro, é necessário definir a região de interesse. Um ponto geralmente é útil para isso. Ative a guia Inspector no lado direito do editor de código e clique perto do centro da área de interesse. Copie as coordenadas da guia Inspector e crie um Point usando:

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

Crie datas de início e término:

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

Filtre a coleção do Landsat 8 usando o ponto e as datas, depois classifique usando uma propriedade de metadados (descoberta durante a inspeção dos metadados da cena do Landsat 8):

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

Essa coleção pode ser impressa e inspecionada com segurança. Se a coleção tiver muitas imagens, a impressão será muito lenta, terá um tempo limite ou retornará um erro. As imagens na coleção são um List armazenado na propriedade "features" do ImageCollection. O ID de qualquer imagem na coleção pode ser copiado para o construtor Image, como acima. Como alternativa, receba a primeira imagem (cobertura de nuvens mais baixa):

var first = filteredCollection.first();

Acesse a funcionalidade completa de filtragem do Earth Engine usando filter() com um ee.Filter como argumento. Os métodos filterBounds() e filterDate() usados acima são atalhos. Por exemplo, o código a seguir cria um Filter, o usa para filtrar um FeatureCollection e mostra o resultado:

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

Banda matemática

Realize operações matemáticas em imagens usando métodos Image. Isso pode incluir recombinações de bandas (índices espectrais), diferenciação de imagens ou operações matemáticas, como multiplicação por uma constante. Por exemplo, calcule a diferença entre imagens do Índice de Vegetação por Diferença Normalizada (NDVI, na sigla em inglês) com 20 anos de diferença:

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

Observe o uso de um function definido pelo usuário neste exemplo. Mais informações sobre funções na próxima seção.

Mapeamento (o que fazer em vez de um loop for)

Use map() para iterar itens em uma coleção. Os loops FOR não são a maneira certa de fazer isso no Earth Engine e devem ser evitados. A função map() pode ser aplicada a um ImageCollection, um FeatureCollection ou um List e aceita um function como argumento. O argumento da função é um elemento da coleção em que ela é mapeada. Isso é útil para modificar cada elemento da coleção da mesma forma, por exemplo, adicionar. Por exemplo, o código a seguir adiciona uma banda NDVI a cada imagem em um ImageCollection:

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

Outra tarefa comum é adicionar uma nova propriedade (ou "atributo" ou "campo") a elementos em um FeatureCollection. No exemplo abaixo, a nova propriedade é uma computação que envolve dois atributos:

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

Observe que o cast para ee.Number é necessário para que o valor da propriedade seja reconhecido como um número para usar o método add()). O tipo da coleção pode ser alterado por map(). Exemplo:

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

Observe a propriedade adicionada (foo) para cada elemento criado a partir do centroide da imagem. Na linha final, o elenco torna a coleção resultante reconhecível como um FeatureCollection.

Reduzindo

A redução é a maneira de agregar dados ao longo do tempo, do espaço, das bandas, das matrizes e de outras estruturas de dados no Earth Engine. Existem vários métodos para essa finalidade na API. Por exemplo, para fazer uma composição de um ImageCollection, use reduce() para reduzir as imagens na coleção a uma imagem. Um exemplo simples é criar a média composta das cinco cenas menos nubladas na coleção Landsat 8 definida anteriormente:

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

A redução também é a maneira de conseguir estatísticas de uma imagem nas regiões definidas por um Feature ou FeatureCollection. Suponha que a tarefa seja calcular os valores médios de pixels em uma área de interesse. Use reduceRegion() para esse fim. Exemplo:

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

Saiba mais sobre redutores na documentação sobre redutores.

Mascaramento

Cada pixel em um ee.Image tem um valor e uma máscara que varia de 0 (sem dados) a 1. Os pixels mascarados (em que mask==0) são tratados como sem dados. Os pixels com 0 < máscara ≤ 1 têm um valor, mas ele é ponderado pela máscara para cálculos numéricos.

É possível tornar os pixels transparentes ou excluí-los da análise usando máscaras. Os pixels são mascarados quando o valor da máscara é zero. Continuando o exemplo de diferenciação de imagens, use uma máscara para mostrar áreas de NDVI aumentadas e diminuídas no intervalo de diferença:

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

Neste exemplo, a máscara da diferença de NDVI é atualizada pela máscara de terra com updateMask(). Isso define a máscara dos pixels de diferença de NDVI como a máscara de terra sempre que a máscara de diferença de NDVI for diferente de zero.

O mascaramento também é útil para excluir dados da análise. Considere o exemplo reduceRegion() da seção Redução. Suponha que a tarefa seja calcular um NDVI médio sazonal para o condado de Santa Clara, CA, excluindo pixels nublados. O exemplo a seguir demonstra vários conceitos: filtragem, mapeamento, redução e uso de uma máscara de nuvem:

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