Há uma variedade de widgets que você pode usar para criar suas interfaces. Esses widgets incluem
botões, caixas de seleção, controles deslizantes, caixas de texto e menus de seleção. Os widgets só podem ser
impressos ou adicionados a um painel uma vez. As seções a seguir ilustram a funcionalidade,
a aparência e o comportamento básicos dos widgets. Consulte a
seção "Estilo" para mais informações sobre como estilizar
seus widgets. Os exemplos a seguir simplesmente mostram os widgets no console usando print(). Para saber como adicionar widgets a painéis, consulte a página
Painéis e layouts.
ui.Label
Os rótulos são simplesmente áreas em que o texto é exibido. Por exemplo, o código a seguir imprime um rótulo:
Editor de código (JavaScript)
var label = ui.Label('Cool label!'); print(label);
O resultado será parecido com este:
Divida rótulos longos inserindo um caractere de nova linha (\n)
e definindo o argumento da propriedade de estilo whiteSpace como
'pre':
print(ui.Label('Here is a:\nnew line', {whiteSpace: 'pre'}));
ui.Button
Um botão é um widget de interface interativo que pode ser clicado. Você pode especificar uma função a ser chamada (a função de "callback") quando um usuário clicar no botão. Para mais informações sobre o processamento de eventos com funções de callback, consulte a página Eventos. O exemplo a seguir mostra o centro atual do mapa quando o botão é clicado:
Editor de código (JavaScript)
var button = ui.Button({ label: 'Get Map Center', onClick: function() { print(Map.getCenter()); } }); print(button);
O resultado será parecido com este:
ui.Checkbox
Uma caixa de seleção é um widget que permite ao usuário marcar (ou desmarcar) uma caixa. Quando o estado da caixa de seleção muda, os callbacks registrados no widget recebem um valor booleano que indica se a caixa de seleção está marcada. Exemplo:
Editor de código (JavaScript)
var checkbox = ui.Checkbox('Show SRTM layer', true); checkbox.onChange(function(checked) { // Shows or hides the first map layer based on the checkbox's value. Map.layers().get(0).setShown(checked); }); Map.addLayer(ee.Image('CGIAR/SRTM90_V4')); print(checkbox);
A caixa de seleção impressa será semelhante a:
Ao marcar a caixa, você ativa uma camada mostrada no mapa. Assim como outros componentes da interface, o mapa do Editor de Código pode ser manipulado de forma programática. Saiba mais sobre o objeto Map na página "Painéis e layouts".
ui.Slider
Um controle deslizante é um widget que permite ao usuário ajustar um controle deslizante para receber um número dentro do intervalo do controle deslizante. Configure o intervalo usando o construtor ou definindo as propriedades do controle deslizante. O exemplo a seguir usa o controle deslizante para definir a opacidade da primeira camada no mapa:
Editor de código (JavaScript)
var slider = ui.Slider(); slider.setValue(0.9); // Set a default value. slider.onChange(function(value) { Map.layers().get(0).setOpacity(value); }); Map.addLayer(ee.Image(255), {palette: 'blue'}); print(slider);
O controle deslizante vai ficar assim:
O valor do controle deslizante é mostrado à direita dele.
ui.DateSlider
O widget DateSlider é como o widget Slider, mas processa
datas explicitamente. Um DateSlider configurado para selecionar um dia de junho de 2018 é semelhante a:
O DateSlider é útil para filtrar coleções, como mostrado no
exemplo a seguir, que cria um composto anual com base no DateRange
definido no DateSlider:
Editor de código (JavaScript)
// Use a DateSlider to create annual composites of this collection. var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1'); // Use the start of the collection and now to bound the slider. var start = ee.Image(collection.first()).date().get('year').format(); var now = Date.now(); var end = ee.Date(now).format(); // Run this function on a change of the dateSlider. var showMosaic = function(range) { var mosaic = ee.Algorithms.Landsat.simpleComposite({ collection: collection.filterDate(range.start(), range.end()) }); // Asynchronously compute the name of the composite. Display it. range.start().get('year').evaluate(function(name) { var visParams = {bands: ['B4', 'B3', 'B2'], max: 100}; var layer = ui.Map.Layer(mosaic, visParams, name + ' composite'); Map.layers().set(0, layer); }); }; // Asynchronously compute the date range and show the slider. var dateRange = ee.DateRange(start, end).evaluate(function(range) { var dateSlider = ui.DateSlider({ start: range['dates'][0], end: range['dates'][1], value: null, period: 365, onChange: showMosaic, style: {width: '180px'} }); Map.add(dateSlider.setValue(now)); }); // Initialize the map location at southern Africa. Map.setCenter(23.861, -27.144, 6);
ui.Textbox
Uma caixa de texto é um local para coletar texto inserido pelo usuário. Exemplo:
Editor de código (JavaScript)
var textbox = ui.Textbox({ placeholder: 'Enter text here...', onChange: function(text) { print('So what you are saying is ' + text + '?'); } }); print(textbox);
A caixa de texto vai ficar assim:
O callback só é acionado quando o usuário termina de inserir o texto (e pressiona return) ou clica fora da caixa de texto.
ui.Select
O widget de seleção representa um menu suspenso de opções em que o usuário pode escolher uma. O exemplo a seguir ilustra um menu suspenso que permite ao usuário selecionar um local:
Editor de código (JavaScript)
var places = { MTV: [-122.0849, 37.3887], PEK: [116.4056, 39.9097], ZRH: [8.536, 47.376] }; var select = ui.Select({ items: Object.keys(places), onChange: function(key) { Map.setCenter(places[key][0], places[key][1]); } }); // Set a place holder. select.setPlaceholder('Choose a location...'); print(select);
O widget de seleção será parecido com este:
ui.Chart
Os gráficos no pacote ui.Chart se comportam de maneira semelhante aos gráficos no pacote Chart. Especificamente, um ui.Chart é um shell fino
em torno de uma instância do ChartWrapper da API Google Visualization.
Para mais informações sobre como manipular objetos ChartWrapper, consulte
esta
referência. Para mais informações sobre as funções auxiliares de gráfico no Earth Engine, consulte
a documentação sobre gráficos.
ui.Thumbnail
O widget de miniatura pode ser usado para visualizar objetos ee.Image e
ee.ImageCollection. Quando um ee.Image é fornecido, o widget
mostra uma imagem estática. Quando um ee.ImageCollection é fornecido, ele mostra uma
animação com um frame por imagem na entrada. Assim como em ee.Image.getThumbURL() e
ee.ImageCollection.getVideoThumbURL(), é possível especificar parâmetros para controlar o
formato e as dimensões da miniatura resultante:
Editor de código (JavaScript)
// Create a box around an area in the Brazilian Amazon. var box = ee.Geometry.Polygon([[ [-62.9564, 2.5596], [-62.9550, 2.4313], [-62.8294, 2.4327], [-62.8294, 2.5596] ]]); // Visualize the image in RGB. var image = ee.Image('LANDSAT/LE07/C02/T1_L2/LE07_233058_20011113') .select(['SR_B[1-3]']) // blue, green, red reflectance .multiply(0.0000275).add(-0.2) // apply scaling factors .visualize({ bands: ['SR_B3', 'SR_B2', 'SR_B1'], min: 0, max: 0.12, gamma: 1.3 }); // Print a thumbnail to the console. print(ui.Thumbnail({ image: image, params: {dimensions: '256x256', region: box, format: 'png'}, style: {height: '300px', width: '300px'} }));
A miniatura será parecida com esta:
ui.Map
Um ui.Map é um widget de mapa. Na verdade, o mapa padrão do editor de código é uma instância dessa classe. Como outros widgets, é possível imprimir
um mapa no console. Manipule o conteúdo do mapa limpando, recebendo ou definindo camadas individuais. O exemplo a seguir mostra um mapa no console que mostra os limites
do mapa do editor de código:
Editor de código (JavaScript)
// Make a little map. var map = ui.Map(); // Make the little map display an inset of the big map. var createInset = function() { var bounds = ee.Geometry.Rectangle(Map.getBounds()); map.centerObject(bounds); map.clear(); map.addLayer(bounds); }; // Run it once to initialize. createInset(); // Get a new inset map whenever you click on the big map. Map.onClick(createInset); // Display the inset map in the console. print(map);
O mapa de inserção vai ficar assim:
Neste exemplo, o usuário precisa clicar no mapa grande para que o mapa menor seja desenhado.
Também é possível manipular camadas no mapa chamando layers() na instância do mapa. O layers() retorna um ui.data.ActiveList, um objeto semelhante a uma matriz. Quando ele é alterado, as camadas no mapa também mudam. Saiba mais
na seção ui.Map.Layer.
ui.Map.Layer
Uma camada não é um widget que pode ser estilizado, como um ui.Button. É apenas uma representação de dados da camada no mapa. O exemplo a seguir demonstra como atualizar um mapa criando uma camada e atualizando as propriedades dela com base na entrada do usuário:
Editor de código (JavaScript)
var consoleMap = ui.Map({ lon: -2.0174, lat: 48.6474, zoom: 13 }); // Create a Layer from this Sentinel-2 image var image = ee.Image('COPERNICUS/S2_HARMONIZED/20150821T111616_20160314T094808_T30UWU'); var visParams = {bands: ['B4', 'B3', 'B2'], max: 2048, gamma: 1}; var layer = ui.Map.Layer(image, visParams); // Update the map by updating the layers list. var layers = consoleMap.layers(); layers.add(layer); // Make a textbox to accept a gamma value. // Update the layer when the gamma value is entered. var gammaBox = ui.Textbox({ value: 1, onChange: function(value) { // visParams is NOT an ActiveDictionary, so set it again. visParams.gamma = value; layer.setVisParams(visParams); } }); print(ui.Label('Enter a gamma value:')); print(gammaBox); print(consoleMap);
ui.Map.CloudStorageLayer
Se você quiser exibir (por exemplo, em um app) uma camada relativamente cara para computação,
talvez seja melhor exportar os dados para um bucket do Cloud Storage
por motivos de desempenho. Essas camadas estáticas, somente para visualização, podem tornar seus apps
e scripts mais responsivos. Para isso, crie uma camada de exibição estática usando
Export.map.toCloudStorage().
Para usar um conjunto de blocos exportado anteriormente por
Export.map.toCloudStorage(),
construa um novo ui.Map.Layer com base em um bucket do Cloud Storage e caminho especificados:
Map.add(ui.Map.CloudStorageLayer({ bucket: 'earthenginepartners-hansen', path: 'tiles/gfc_v1.4/loss_year', maxZoom: 12, suffix: '.png' }));
Ao executar um script que carrega uma camada do Cloud Storage, talvez você veja a mensagem de aviso:
ui.Map.DrawingTools
Há um conjunto de ferramentas de desenho de geometria que é adicionado por padrão ao Map
no Editor de Código. É possível mudar o comportamento dessas ferramentas no Map padrão
chamando Map.drawingTools(). Por exemplo, para ocultar as ferramentas de desenho:
Editor de código (JavaScript)
Map.drawingTools().setShown(false);
Os mapas recém-criados não recebem ferramentas de desenho por padrão, mas podem ser ativados chamando o método drawingTools() no mapa:
Editor de código (JavaScript)
var map = ui.Map(); // Prints true since drawingTools() adds drawing tools to the map. print(map.drawingTools().getShown()); // Replace the default Map with the newly created map. ui.root.widgets().reset([map]);
As camadas de geometria desenhadas pelas ferramentas de desenho são colocadas em um
ui.data.ActiveList que pode ser acessado chamando
Map.drawingTools().layers(). A lista de camadas de geometria responde a eventos
como outras listas ativas, por exemplo, a lista de camadas no Map retornada por
Map.layers(). O exemplo a seguir mostra como definir a visibilidade das camadas de geometria desenhadas pelas ferramentas (que são mostradas por padrão):
Editor de código (JavaScript)
Map.drawingTools().layers().forEach(function(layer) { layer.setShown(false); });
Para adicionar uma camada de forma programática às ferramentas de desenho, chame o método addLayer nas ferramentas de desenho ou adicione uma camada diretamente à lista de camadas:
Editor de código (JavaScript)
var geometries = [ee.Geometry.Point([0,0]), ee.Geometry.Rectangle([[0,0], [1,1]])]; Map.drawingTools().addLayer(geometries, 'my_geometry1', 'red'); var layer = ui.Map.GeometryLayer(geometries, 'my_geometry2', 'blue'); Map.drawingTools().layers().add(layer);
O estado das ferramentas de desenho também é transferido quando você publica um app. Se as ferramentas de desenho estiverem mostradas ou ocultas, elas também serão mostradas ou ocultas no app. As geometrias nas suas importações também serão transferidas para o app.
ui.Map.GeometryLayer
Um GeometryLayer é uma coleção de geometrias que atua como um único
Geometry, GeometryCollection ou FeatureCollection
que é adicionado à seção de importações na parte de cima do script e pode ser referenciado no
código.
Os GeometryLayers desenhados pelas ferramentas de desenho têm um comportamento padrão que pode ser substituído por novas funções de callback. Por exemplo, suponha que você queira que as mudanças interativas nas geometrias acionem um evento. Para implementar um comportamento específico, defina os métodos onEdit(), onErase() ou onDraw() nas ferramentas para responder às ações do usuário.
O exemplo a seguir mostra como acionar um cálculo e atualizar um rótulo com o resultado dele quando o usuário adiciona/edita/apaga uma geometria:
Editor de código (JavaScript)
// Load elevation data. var srtm = ee.Image('NASA/NASADEM_HGT/001').select('elevation'); Map.addLayer(srtm, {min: 0, max: 5000}, 'SRTM'); // Make a label to display mean elevation at drawn points. var label = new ui.Label('Draw points to calculate mean elevation'); var inspector = new ui.Panel([label]); Map.add(inspector); // Don't make imports that correspond to the drawn points. Map.drawingTools().setLinked(false); // Limit the draw modes to points. Map.drawingTools().setDrawModes(['point']); // Add an empty layer to hold the drawn points. Map.drawingTools().addLayer([]); // Set the geometry type to be point. Map.drawingTools().setShape('point'); // Enter drawing mode. Map.drawingTools().draw(); // This function gets called when the geometry layer changes. // Use debounce to call the function at most every 100 milliseconds. var getAverageElevation = ui.util.debounce(function() { var points = Map.drawingTools().layers().get(0).toGeometry(); var elevation = srtm.reduceRegion({ reducer: ee.Reducer.mean(), geometry: points, scale: 30 }).get('elevation'); // Asynchronously evaluate the mean elevation. elevation.evaluate(showElevation); }, 100); // Set the callback function on changes of the geometry layer. Map.drawingTools().onEdit(getAverageElevation); Map.drawingTools().onDraw(getAverageElevation); Map.drawingTools().onErase(getAverageElevation); // Set the label to the result of the mean reduction. function showElevation(elevation) { inspector.clear(); var elevationLabel = ui.Label('Mean elevation: ' + elevation); inspector.add(elevationLabel); }
Observe que setLinked() é usado para alternar a conexão entre as
ferramentas de desenho de geometria e a seção Importações
do Editor de Código. Neste exemplo, as ferramentas de geometria estão desvinculadas para
evitar que as importações sejam criadas. toGeometry é usado para converter a
camada em um ee.Geometry. Se a camada importada representar um Feature
ou FeatureCollection, será possível recuperar o objeto do EE usando
getEeObject(). Observe também o uso de ui.util.debounce para evitar que cada movimento de uma geometria acione a função de callback. Especificamente,
a função não será acionada até que 100 milissegundos tenham se passado desde o último evento. Isso
ajuda a garantir que a função seja executada somente quando o usuário concluir a ação de edição.
Uma camada de geometria nas importações é associada a um Geometry ou GeometryCollection, portanto, só pode conter geometrias com o mesmo estado geodésico, porque o formato GeoJSON permite apenas um único estado geodésico para a coleção de geometrias (consulte a página Geometrias geodésicas x planas para mais informações). Converter a camada de geometria em um
FeatureCollection pressionando o ícone de engrenagem ao lado do nome da camada
permite adicionar geometrias geodésicas e planas à mesma camada. No entanto, convertê-lo de volta para um Geometry produzirá um erro. Para evitar isso, converta
para um FeatureCollection ou exclua geometrias até que haja apenas um estado geodésico
na camada.
ui.Map.Linker
Assim como uma camada, um vinculador não é um widget que pode ser estilizado. Ele é um utilitário de bastidores que
pode ser usado para sincronizar o movimento de várias instâncias de ui.Map:
Editor de código (JavaScript)
// Add two maps to the screen. var left = ui.Map(); var right = ui.Map(); ui.root.clear(); ui.root.add(left); ui.root.add(right); // Link the "change-bounds" event for the maps. // When the user drags one map, the other will be moved in sync. ui.Map.Linker([left, right], 'change-bounds');
ui.SplitPanel
Uma ui.SplitPanel é útil para comparar coisas lado a lado. A vantagem
de um ui.SplitPanel em relação a dois painéis comuns é que uma alça pode ser usada para
fazer uma transição de limpeza entre os painéis em um ui.SplitPanel. O
exemplo a seguir usa um ui.SplitPanel para mostrar as diferenças espectrais
de cicatrizes de queimaduras:
Editor de código (JavaScript)
// Load an image of the Santa Rosa, California 2017 fires. var image = ee.Image('LANDSAT/LC08/C02/T1_TOA/LC08_045033_20171011'); // Add a color-SWIR composite to the default Map. Map.setCenter(-122.6624, 38.5011, 12); Map.addLayer(image, {bands: ['B7', 'B5', 'B3'], max: 0.3}, 'color-SWIR'); // Make another map and add a color-NIR composite to it. var linkedMap = ui.Map(); linkedMap.addLayer(image, {bands: ['B5', 'B4', 'B3'], max: 0.3}, 'color-NIR'); // Add a thermal image to the map. linkedMap.addLayer(image, { bands: ['B11'], min: 290, max: 305, palette: ['gray', 'white', 'yellow', 'red'] }, 'Thermal'); // Link the default Map to the other map. var linker = ui.Map.Linker([ui.root.widgets().get(0), linkedMap]); // Make an inset map and add it to the linked map. var inset = ui.Map(); inset.style().set({position: 'bottom-right', width: '300px', height: '250px'}); inset.setControlVisibility({all: false, mapTypeControl: true}); linkedMap.add(inset); // Register a function to the linked map to update the inset map. linkedMap.onChangeBounds(function() { var bounds = ee.Geometry.Rectangle(Map.getBounds()); inset.centerObject(bounds); inset.layers().set(0, bounds); }); // Create a SplitPanel which holds the linked maps side-by-side. var splitPanel = ui.SplitPanel({ firstPanel: linker.get(0), secondPanel: linker.get(1), orientation: 'horizontal', wipe: true, style: {stretch: 'both'} }); // Set the SplitPanel as the only thing in root. ui.root.widgets().reset([splitPanel]);
O parâmetro wipe é definido como true
no construtor ui.SplitPanel para permitir que o usuário deslize a alça
para frente e para trás entre as duas visualizações.
Widgets de estilo
O estilo de um widget é controlado pelo dicionário de propriedades de estilo do widget. Você
pode acessar o dicionário chamando style() no widget. O
objeto retornado por style() é uma instância de
ui.data.ActiveDictionary. Isso significa que a definição de propriedades do dicionário de estilo atualiza automaticamente a forma como o widget é exibido. As chaves permitidas
para o dicionário de estilo de cada widget são detalhadas nos documentos de referência do widget para a
chamada style().
Os estilos do widget podem ser definidos com o construtor, chamando
style().set() ou chamando style() com um argumento de
dicionário. Exemplo:
Editor de código (JavaScript)
var redLabel = ui.Label('Big, Red Label'); redLabel.style().set('color', 'red'); redLabel.style().set('fontWeight', 'bold'); redLabel.style().set({ fontSize: '32px', padding: '10px' }); print(redLabel);
Neste exemplo, o rótulo é estilizado primeiro chamando
style().set() com argumentos de chave e valor e, em seguida, chamando
style().set() com um argumento de dicionário. A segunda chamada não
substitui a primeira. Ela adiciona e substitui propriedades de estilo individuais em vez de
substituir todo o dicionário de estilo.
Para mais informações sobre as opções de estilo para widgets, consulte esta
referência de Cascading Style Sheet
(CSS) para os estilos listados na documentação do style() para cada
widget. Os estilos permitidos para widgets do Earth Engine são diferentes dos estilos CSS
em vários lugares, principalmente fontSize e fontWeight para
font-style e font-weight, respectivamente.
O dicionário de estilos também contém chaves que controlam a posição do widget. Consulte a página Painéis e layouts para mais informações sobre como usar propriedades posicionais.