Objetos do Earth Engine

Agora que você já tem experiência com JavaScript, aprenda a colocar objetos e primitivos JavaScript em contêineres do Earth Engine para enviar ao servidor e processar no Google.

Strings

Por exemplo, defina uma string e coloque-a no contêiner ee.String() para ser enviada ao Earth Engine:

Editor de código (JavaScript)

// Define a string, then put it into an EE container.
var aString = 'To the cloud!';
var eeString = ee.String(aString);
print('Where to?', eeString);

Pense em ee.Thing como um contêiner para algo que existe no servidor. Neste exemplo, a string é definida primeiro e depois colocada no contêiner. Você também pode definir o contêiner e o conteúdo dele de uma só vez. Exemplo:

Editor de código (JavaScript)

// Define a string that exists on the server.
var serverString = ee.String('This is on the server.');
print('String on the server:', serverString);

Embora o primeiro argumento de print() seja apenas uma string no cliente, o segundo argumento é enviado ao servidor para ser avaliado e, em seguida, enviado de volta.

Números

Use ee.Number() para criar objetos de número no servidor. Por exemplo, use o método Math.E do JavaScript para criar um valor constante no servidor:

Editor de código (JavaScript)

// Define a number that exists on the server.
var serverNumber = ee.Number(Math.E);
print('e=', serverNumber);

Os métodos ee.String() e ee.Number() são construtores. Um construtor recebe o argumento (e possivelmente outros parâmetros), coloca em um contêiner e retorna o contêiner e o conteúdo dele como um objeto do Earth Engine que pode ser manipulado no código. Qualquer construtor que comece com ee retorna um objeto do Earth Engine.

Métodos em objetos do Earth Engine

Depois de criar um objeto do Earth Engine, você precisa usar os métodos dele para processar. Neste exemplo, não é possível usar o Math.log() do JavaScript para processar esse objeto do Earth Engine. É necessário usar o método equivalente definido para um ee.Number:

Editor de código (JavaScript)

// Use a built-in function to perform an operation on the number.
var logE = serverNumber.log();
print('log(e)=', logE);

Neste exemplo, log() é um método para um objeto ee.Number. Use a guia Documentos no lado esquerdo do editor de código para conferir uma lista de todos os métodos de cada tipo de objeto do Earth Engine, por exemplo, ee.Number > log(). Os métodos de objetos do Earth Engine retornam outros objetos do Earth Engine.

Listas

Para transformar uma lista JavaScript em um objeto ee.List no servidor, coloque um literal JavaScript em um contêiner, como com números e strings. O Earth Engine também oferece métodos convenientes do lado do servidor para criar sequências de números. Por exemplo:

Editor de código (JavaScript)

// Make a sequence the hard way.
var eeList = ee.List([1, 2, 3, 4, 5]);
// Make a sequence the easy way!
var sequence = ee.List.sequence(1, 5);
print('Sequence:', sequence);

Como os objetos ee.List só existem no servidor, use as funções fornecidas pelo Earth Engine para interagir com eles. Por exemplo, para extrair algo da lista, use o método get() do objeto ee.List:

Editor de código (JavaScript)

// Use a method on an ee.List to extract a value.
var value = sequence.get(2);
print('Value at index 2:', value);

Transmitir para TV

Às vezes, o Earth Engine não sabe o tipo de um objeto retornado de um método. Você, como programador, sabe que a variável value no exemplo anterior é um objeto numérico. Mas se você tentar usar o método add() de um ee.Number, vai receber um erro como:

value.add não é uma função

Isso é comum com a função get(), que pode retornar todos os tipos de objetos do Earth Engine. Para corrigir isso, use o construtor ee.Number para converter o resultado:

Editor de código (JavaScript)

// Cast the return value of get() to a number.
print('No error:', ee.Number(value).add(3));

Dicionários

É possível construir um Dictionary do Earth Engine com um objeto JavaScript, assim como strings, números e listas. No momento da construção, é possível usar a funcionalidade do JavaScript para inicializar o objeto do Earth Engine. Nesse caso, um ee.Dictionary é construído diretamente de um objeto literal JavaScript:

Editor de código (JavaScript)

// Make a Dictionary on the server.
var dictionary = ee.Dictionary({
  e: Math.E,
  pi: Math.PI,
  phi: (1 + Math.sqrt(5)) / 2
});

// Get some values from the dictionary.
print('Euler:', dictionary.get('e'));
print('Pi:', dictionary.get('pi'));
print('Golden ratio:', dictionary.get('phi'));

// Get all the keys:
print('Keys: ', dictionary.keys());

Neste exemplo, observe que, depois de ter um ee.Dictionary, você precisa usar métodos no ee.Dictionary para receber valores (ao contrário do dicionário JavaScript na lição anterior). Especificamente, get(key) retorna o valor associado a key. Como o tipo de objeto retornado por get() pode ser qualquer coisa, se você for fazer algo com o objeto além de imprimir, transmita-o para o tipo certo. O método keys() também retorna um ee.List.

Datas

Os objetos de data são a maneira como o Earth Engine representa o tempo. Como nos exemplos anteriores, é importante distinguir entre um objeto JavaScript Date e um objeto ee.Date do Earth Engine. Crie um ee.Date de uma string, de um Date JavaScript ou usando métodos estáticos fornecidos pela classe ee.Date. Consulte a seção "Data" na guia Documentos para mais detalhes. Este exemplo ilustra a construção de datas de strings ou uma data JavaScript que representa milissegundos desde a meia-noite de 1º de janeiro de 1970:

Editor de código (JavaScript)

// Define a date in Earth Engine.
var date = ee.Date('2015-12-31');
print('Date:', date);

// Get the current time using the JavaScript Date.now() method.
var now = Date.now();
print('Milliseconds since January 1, 1970', now);

// Initialize an ee.Date object.
var eeNow = ee.Date(now);
print('Now:', eeNow);

As datas são úteis para filtrar coleções, principalmente como argumentos para o método filterDate(). Consulte esta seção da página "Começar" para mais informações sobre como classificar coleções.

Digressão: transmissão de parâmetros por nome

Os argumentos para métodos do Earth Engine podem ser transmitidos em ordem. Por exemplo, para criar um ee.Date de ano, mês e dia, transmita os parâmetros do método estático fromYMD() na ordem ano, mês e dia:

Editor de código (JavaScript)

var aDate = ee.Date.fromYMD(2017, 1, 13);
print('aDate:', aDate);

Como alternativa, é possível transmitir os parâmetros por nome, em qualquer ordem. Embora possa ser mais código, ele pode melhorar a legibilidade e a reutilização. Para transmitir parâmetros por nome, transmita um objeto JavaScript em que as chaves do objeto são os nomes dos parâmetros do método e os valores são os argumentos do método. Exemplo:

Editor de código (JavaScript)

var theDate = ee.Date.fromYMD({
  day: 13,
  month: 1,
  year: 2017
});
print('theDate:', theDate);

Os nomes das propriedades do objeto (as chaves) correspondem aos nomes especificados na documentação do ee.Date.fromYMD(). Além disso, o objeto transmitido como argumento pode ser salvo em uma variável para reutilização, como ilustrado no exemplo de objeto JavaScript.

Agora você já tem uma introdução suficiente ao JavaScript para começar a usar o Earth Engine. Consulte a página Cliente x servidor para uma explicação mais detalhada sobre objetos JavaScript x Earth Engine.

Na próxima seção, saiba mais sobre os conceitos de programação funcional para usar de maneira eficaz loops for, condições if/else e iterações no Earth Engine.