Objetos do Earth Engine

Agora que você já conhece o JavaScript, aprenda a colocar objetos JavaScript e primitivos 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. Também é possível 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 para 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 JavaScript Math.E 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), o coloca em um contêiner e retorna o contêiner e o conteúdo 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 do Earth Engine para processá-lo. Neste exemplo, não é possível usar o Math.log() do JavaScript para processar esse objeto do Earth Engine. É preciso 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 Docs no lado esquerdo do editor de código para ver uma lista de todos os métodos para 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 acontece com números e strings. O Earth Engine também oferece métodos de conveniência 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 existem apenas 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 por 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:

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 fazer a conversão do 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 criar um Dictionary do Earth Engine com base em um objeto JavaScript, 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 mostrá-lo, será necessário convertê-lo para o tipo certo. Observe também que o método keys() 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 com base em uma string, em um Date do 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 do 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, especificamente 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 os métodos do Earth Engine podem ser transmitidos em ordem. Por exemplo, para criar um ee.Date de ano, mês e dia, é possível transmitir parâmetros do método estático fromYMD() na ordem ano, mês, 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, conforme 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 loops for, condições if/else e iterações no Earth Engine de maneira eficaz.