Este guia de iniciação é uma maneira rápida de começar a programar com a API JavaScript do Earth Engine. Para uma introdução ao JavaScript e exercícios mais detalhados com a API Earth Engine, consulte os tutoriais. Para ver o estilo de programação JavaScript recomendado, consulte o Guia de estilo de JavaScript do Google.
O Google Earth Engine permite que os usuários executem algoritmos em imagens e vetores georreferenciados armazenados na infraestrutura do Google. A API Google Earth Engine fornece uma biblioteca de funções que podem ser aplicadas aos dados para exibição e análise. O Data Catalog público do Earth Engine contém uma grande quantidade de imagens e conjuntos de dados vetoriais disponíveis publicamente. Os recursos particulares também podem ser criados nas pastas pessoais dos usuários.
Como usar estes documentos
A documentação do Earth Engine foi criada para pessoas que já conhecem a análise de dados
geoespaciais. A documentação é estruturada principalmente por tipo de dados. Por exemplo, a
navegação do lado esquerdo 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. Há também seções para
machine learning, algoritmos especializados ou específicos de sensores
(por exemplo, algoritmos do Landsat),
apps voltados ao público, gerenciamento de dados (recursos)
e detalhes importantes sobre o funcionamento interno do Earth Engine.
Antes de começar, confira estas informações.
O editor de código
O Editor de Código é um ambiente interativo para desenvolver aplicativos do Earth Engine (Figura 1). O painel central oferece 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 Gerar link cria um URL exclusivo para o script na barra de endereço. O mapa no painel inferior 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 da API pesquisável e um gerenciador de recursos para dados particulares. O painel direito tem um inspetor para consultar o mapa, um Console de produção e um gerenciador para tarefas de longa duração. O botão de ajuda no canto superior direito contém links para este guia e outros recursos de ajuda. Saiba mais no guia do Editor de código e no guia de ajuda.
Abrir e executar código no Editor de Código
As etapas abaixo mostram 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.
- Abra o editor de código do Earth Engine aqui: code.earthengine.google.com.
- Navegue até a guia Scripts, localizada na extrema esquerda 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.
- Em "Image Collection", selecione o exemplo "Filtered Composite". Um script vai aparecer no console central. Pressione o botão Executar 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 de Utah. Em seguida, ele exibe uma composição de cores verdadeiras das imagens selecionadas. Os exemplos apresentam métodos usados com frequência, como
filter(),clip()eMap.addLayer().
Estruturas de dados do Earth Engine
As duas estruturas de dados geográficos mais fundamentais no Earth Engine são
Image e
Feature, que correspondem aos tipos de dados rasterizados e vetoriais,
respectivamente. As imagens são compostas por bandas e um dicionário de propriedades.
Os elementos 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 todos esses são objetos do lado do servidor e não são manipulados da mesma
maneira 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.
- Algoritmos de chamada.
- 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():
Editor de código (JavaScript)
var image3 = image1.add(image2);
Esse método adiciona as bandas de image2 às bandas de image1.
A categoria ee.Algorithms contém uma lista de algoritmos atualmente compatíveis
para processamento especializado ou específico de domínio. Por exemplo, para criar
camadas topográficas com base em um modelo digital de elevação (DEM, na sigla em inglês) de entrada:
Editor de código (JavaScript)
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
Editor de código (JavaScript)
var myFunction = function(args) { // do something return something; };
Como ilustrado na seção Map, as funções definidas pelo usuário são úteis para criar funcionalidades personalizadas ou modificar os elementos de uma coleção usando:
Editor de código (JavaScript)
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, exibir o resultado numérico de um cálculo, exibir metadados de objetos ou ajudar na depuração. O exemplo icônico "Hello World!" no Editor de Código é:
Editor de código (JavaScript)
print('Hello world!');
Copie essa linha para o editor de código do Editor de Código e clique em Executar. Observe que a saída é exibida na guia Console, à direita do Editor de código. Para um exemplo mais relevante de sensoriamento remoto, o código a seguir mostra os metadados de uma imagem do Landsat 8:
Editor de código (JavaScript)
print(ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_044034_20140318'));
Inspecione cuidadosamente a saída no console para ver os metadados disponíveis para as imagens do Landsat.
Adicionar dados ao mapa
Além de exibir 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, um Image é instanciado (como encontrar essas imagens é abordado mais adiante) usando ee.Image(), adicionado ao mapa com Map.addLayer() e o mapa é centralizado sobre a imagem:
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);
O segundo parâmetro de Map.centerObject() é um nível de zoom, em que números maiores indicam uma escala maior (mais zoom). 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:
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');
Observe que os parâmetros de visualização são definidos por um objeto literal, que inclui uma lista de bandas para exibição, um valor de refletância mínimo e máximo e um valor gama. Saiba mais sobre as bandas do Landsat neste link. Saiba mais sobre a visualização de imagens aqui.
Use Map.addLayer() para adicionar elementos e coleções de elementos ao mapa. Por
exemplo,
Editor de código (JavaScript)
var counties = ee.FeatureCollection('TIGER/2018/Counties'); Map.addLayer(counties, {}, 'counties');
Encontrar imagens, coleções de imagens e coleções de elementos
Imagens, coleções de imagens e coleções de elementos são detectáveis pesquisando o Data Catalog do Earth Engine. Por exemplo, inserir "Landsat 8" no campo de pesquisa resulta em uma lista de conjuntos de dados rasterizados. A lista completa de conjuntos de dados do Earth Engine está no Catálogo de dados do Earth Engine. Clique no nome do conjunto de dados para ver uma breve descrição, informações sobre a disponibilidade temporal, o provedor de dados e o ID da coleção. Clique no botão Importar para criar automaticamente uma seção Importações na parte de cima do script com uma variável para essa coleção.
Como alternativa, copie o ID da coleção e cole-o no código. Por exemplo, escolha o resultado TOA de nível 1 da pesquisa "Landsat 8" e copie o ID da seguinte maneira:
Editor de código (JavaScript)
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_TOA');
Como essa é uma coleção de muitas imagens que abrangem a superfície terrestre, para encontrar uma imagem individual na coleção, é necessário filtrar 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. Saiba mais sobre filtragem e composição (consulte Reduce) nas próximas seções.
As coleções de atributos também estão disponíveis no Data Catalog. A representação deles é menor do que as coleções de imagens, mas você vai encontrar limites internacionais, de censo, de bacias hidrográficas e de áreas protegidas, para citar alguns. Saiba como importar seus próprios conjuntos de dados vetoriais aqui.
Filtrar e ordenar
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 de São Francisco. Primeiro, é necessário definir a
região de interesse. Um ponto costuma ser ú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:
Editor de código (JavaScript)
var point = ee.Geometry.Point(-122.262, 37.8719);
Crie as datas de início e término:
Editor de código (JavaScript)
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 e, em seguida, ordene usando uma propriedade de metadados (descoberta durante a inspeção dos metadados da cena do 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);
Essa coleção pode ser impressa e inspecionada com segurança. Se a coleção tiver muitas imagens, a impressão será muito lenta, expirará ou retornará um erro. Observe que
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, pegue a primeira
imagem (menor cobertura de nuvens):
Editor de código (JavaScript)
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, usa-o para filtrar um FeatureCollection e
mostra o 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');
Cálculo de bandas
Realizar 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 as imagens do Índice de Vegetação por Diferença Normalizada (NDVI) com 20 anos de diferença:
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);
Observe o uso de um function definido pelo usuário neste exemplo. Mais informações sobre
funções na próxima seção.
Map (o que fazer em vez de um loop for)
Use map() para iterar os itens de uma coleção. Os loops for NÃO são a
maneira certa de fazer isso no Earth Engine e precisam 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 todos os elementos da coleção da mesma maneira, por exemplo, adicionando. Por exemplo, o código a seguir adiciona uma banda NDVI a cada
imagem em um 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);
Outra tarefa comum é adicionar uma nova propriedade (ou "atributo" ou "campo") a elementos em um
FeatureCollection. No exemplo a seguir, a nova propriedade é um
cálculo que envolve dois atributos:
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);
Observe a conversão para ee.Number necessária 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:
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);
Observe a propriedade adicionada (foo) para cada elemento criado com base no centroide
da imagem. Na linha final, a transmissão faz com que a coleção resultante seja reconhecida como um
FeatureCollection.
Reduzir
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 o
composto mediano das cinco cenas menos nubladas na coleção do 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());
A redução também é a maneira de receber 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 pixel em uma área de interesse. Use reduceRegion() para
essa finalidade. Exemplo:
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 });
Saiba mais sobre os redutores no documento sobre redutores.
Máscara
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 exibir áreas de NDVI aumentado e diminuído 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, observe que a máscara da diferença do NDVI é atualizada pela máscara de terra
com updateMask(). Isso define a máscara dos pixels de diferença do NDVI como a
máscara de terra sempre que a máscara de diferença do NDVI for diferente de zero.
O mascaramento também é útil para excluir dados da análise. Considere o
exemplo reduceRegion() da seção
Reduzir. 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 o uso de uma máscara de nuvem:
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); });