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 guia do Editor de código e no guia de ajuda.
no canto superior direito contém links para este guia e outros recursos. Saiba mais noComo 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.
- Abra o editor de código do Earth Engine aqui: code.earthengine.google.com.
- 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.
- 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()
eMap.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()
:
Editor de código (JavaScript)
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:
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; };
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:
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, 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 é:
Editor de código (JavaScript)
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:
Editor de código (JavaScript)
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:
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 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:
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');
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,
Editor de código (JavaScript)
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:
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, 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:
Editor de código (JavaScript)
var point = ee.Geometry.Point(-122.262, 37.8719);
Crie 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, depois classifique 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, 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):
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
, o usa 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');
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:
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.
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
:
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 abaixo, a nova propriedade é uma
computação 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 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:
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 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:
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 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:
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 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:
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); });