Widgets

Vous pouvez utiliser différents widgets pour créer vos UI. Ces widgets incluent des boutons, des cases à cocher, des curseurs, des zones de texte et des menus de sélection. Les widgets ne peuvent être imprimés ou ajoutés à un panneau qu'une seule fois. Les sections suivantes illustrent les fonctionnalités de base, l'apparence et l'ergonomie des widgets. Pour en savoir plus sur le style de vos widgets, consultez la section Style. Les exemples suivants print() simplement les widgets dans la console. Pour en savoir plus sur l'ajout de widgets aux panneaux, consultez la page Panneaux et mises en page.

ui.Label

Les libellés sont simplement des zones dans lesquelles du texte s'affiche. Par exemple, le code suivant imprime une étiquette:

var label = ui.Label('Cool label!');
print(label);

qui ressemble à ceci:

Séparez les libellés longs en insérant un nouveau caractère de ligne (\n) et en définissant l'argument de propriété de style whiteSpace sur 'pre':

print(ui.Label('Here is a:\nnew line', {whiteSpace: 'pre'}));

ui.Button

Un bouton est un widget d'interface utilisateur interactif sur lequel vous pouvez cliquer. Vous pouvez spécifier une fonction à appeler (la fonction "rappel") lorsqu'un utilisateur clique sur le bouton. (Pour en savoir plus sur la gestion des événements avec des fonctions de rappel, consultez la page sur les événements.) L'exemple suivant affiche le centre actuel de la carte lorsque l'utilisateur clique sur le bouton:

var button = ui.Button({
  label: 'Get Map Center',
  onClick: function() {
    print(Map.getCenter());
  }
});
print(button);

qui ressemble à ceci:

ui.Checkbox

Une case à cocher est un widget qui permet à l'utilisateur de cocher (ou de décocher) une case. Lorsque l'état de la case à cocher change, une valeur booléenne indiquant si la case est maintenant cochée est transmise aux rappels enregistrés sur le widget. Exemple :

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);

La case à cocher imprimée doit se présenter comme suit:

Notez que cocher cette case active un calque affiché sur la carte. Comme pour les autres composants d'interface utilisateur, la carte de l'éditeur de code peut être manipulée de manière programmatique. Pour en savoir plus sur l'objet Map, consultez la page "Panneaux et mises en page".

ui.Slider

Un curseur est un widget qui permet à un utilisateur d'ajuster un curseur pour obtenir un nombre compris dans la plage du curseur. Configurez la plage à l'aide du constructeur ou en définissant les propriétés du curseur. L'exemple suivant utilise le curseur pour définir l'opacité de la première couche sur la carte:

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);

Le curseur devrait se présenter comme suit:

Notez que la valeur du curseur s'affiche à droite de celui-ci.

ui.DateSlider

Le widget DateSlider est semblable au widget Slider, mais gère les dates explicitement. Voici à quoi ressemble un DateSlider configuré pour sélectionner un jour de juin 2018:

DateSlider est utile pour filtrer des collections, comme illustré dans l'exemple suivant, qui crée un composite annuel basé sur l'DateRange défini dans DateSlider:

// 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

Une zone de texte permet de collecter le texte saisi par l'utilisateur. Exemple :

var textbox = ui.Textbox({
  placeholder: 'Enter text here...',
  onChange: function(text) {
    print('So what you are saying is ' + text + '?');
  }
});
print(textbox);

La zone de texte devrait se présenter comme suit:

Notez que le rappel ne se déclenche que lorsque l'utilisateur a terminé de saisir du texte (et a appuyé sur Entrée) ou qu'il quitte la zone de texte.

ui.Select

Le widget de sélection représente un menu déroulant de choix parmi lesquels l'utilisateur peut en sélectionner un. L'exemple suivant illustre un menu déroulant permettant à un utilisateur de sélectionner un emplacement:

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);

Le widget de sélection devrait se présenter comme suit:

ui.Chart

Les graphiques du package ui.Chart se comportent de la même manière que les graphiques du package Chart. Plus précisément, un ui.Chart est une coque mince autour d'une instance de l'ChartWrapper de l'API Google Visualization. Pour en savoir plus sur la manipulation des objets ChartWrapper, consultez cette référence. Pour en savoir plus sur les fonctions d'assistance des graphiques dans Earth Engine, consultez la documentation sur les graphiques.

ui.Thumbnail

Le widget de vignette permet de prévisualiser les objets ee.Image et ee.ImageCollection. Lorsqu'un ee.Image est fourni, le widget affiche une image statique. Lorsqu'un ee.ImageCollection est fourni, il affiche une animation avec un frame par image dans l'entrée. Comme pour ee.Image.getThumbURL() et ee.ImageCollection.getVideoThumbURL(), vous pouvez spécifier des paramètres pour contrôler le format et les dimensions de la vignette générée:

// 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'}
}));

La vignette devrait se présenter comme suit:

ui.Map

Un ui.Map est un widget de carte. (En fait, la carte de l'éditeur de code par défaut est une instance de cette classe.) Comme les autres widgets, vous pouvez imprimer une carte dans la console. Manipulez le contenu de la carte en effaçant, en obtenant ou en définissant des calques individuels. L'exemple suivant imprime une carte dans la console qui affiche les limites de la carte de l'éditeur de code:

// 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);

La carte intégrée devrait se présenter comme suit:

Dans cet exemple, l'utilisateur doit cliquer sur la grande carte pour que l'inset dessine dans la petite carte.

Vous pouvez également manipuler les calques sur la carte en appelant layers() sur l'instance de carte. layers() renvoie un ui.data.ActiveList, un objet semblable à un tableau. Lorsque vous modifiez ce paramètre, les calques de la carte changent également. Pour en savoir plus, consultez la section ui.Map.Layer.

ui.Map.Layer

Une couche n'est pas un widget stylable comme un ui.Button. Il ne s'agit que d'une représentation des données de la couche sur la carte. L'exemple suivant montre comment mettre à jour une carte en créant un calque et en mettant à jour ses propriétés en fonction de l'entrée utilisateur:

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/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

Si vous souhaitez afficher (par exemple dans une application) une couche relativement coûteuse à calculer, il peut être judicieux d'exporter vos données vers un bucket Cloud Storage pour des raisons de performances. Ces calques statiques, réservés à la visualisation, peuvent rendre vos applications et scripts plus réactifs. Vous pouvez créer une couche d'affichage statique à cette fin à l'aide de Export.map.toCloudStorage(). Pour utiliser un ensemble de tuiles précédemment exporté par Export.map.toCloudStorage(), créez un ui.Map.Layer à partir d'un bucket et d'un chemin Cloud Storage spécifiés:

Map.add(ui.Map.CloudStorageLayer({
  bucket: 'earthenginepartners-hansen',
  path: 'tiles/gfc_v1.4/loss_year',
  maxZoom: 12,
  suffix: '.png'
}));

Lorsque vous exécutez un script qui charge une couche Cloud Storage, le message d'avertissement suivant peut s'afficher:

ui.Map.DrawingTools

Un ensemble d'outils de dessin géométrique est ajouté par défaut à Map dans l'éditeur de code. Vous pouvez modifier le comportement de ces outils dans Map par défaut en appelant Map.drawingTools(). Par exemple, pour masquer les outils de dessin:

Map.drawingTools().setShown(false);

Les outils de dessin ne sont pas disponibles par défaut pour les cartes créées, mais vous pouvez les activer en appelant la méthode drawingTools() sur la carte:

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]);

Les calques de géométrie dessinés par les outils de dessin sont placés dans un ui.data.ActiveList auquel vous pouvez accéder en appelant Map.drawingTools().layers(). La liste des calques de géométrie répond aux événements comme les autres listes actives, par exemple la liste des calques sur le Map renvoyée par Map.layers(). L'exemple suivant montre comment définir la visibilité des calques de géométrie dessinés par les outils (qui sont affichés par défaut):

Map.drawingTools().layers().forEach(function(layer) {
  layer.setShown(false);
});

Pour ajouter un calque de manière programmatique aux outils de dessin, vous pouvez appeler la méthode addLayer sur les outils de dessin ou ajouter un calque directement à la liste des calques:

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);

L'état des outils de dessin est également conservé lorsque vous publiez une application. Si les outils de dessin sont affichés ou masqués, ils le seront également dans votre application. Les géométries de vos importations seront également conservées dans votre application.

ui.Map.GeometryLayer

Un GeometryLayer est un ensemble de géométries qui agit comme un seul Geometry, GeometryCollection ou FeatureCollection ajouté à la section "Importations" en haut de votre script et qui peut être référencé dans le code.

Les GeometryLayer dessinés par les outils de dessin ont un comportement par défaut que vous pouvez remplacer en fournissant de nouvelles fonctions de rappel. Par exemple, supposons que vous souhaitiez déclencher un événement en cas de modification interactive des géométries. Pour implémenter un comportement particulier, vous pouvez définir les méthodes onEdit(), onErase() ou onDraw() sur les outils afin de répondre aux actions des utilisateurs. L'exemple suivant montre comment déclencher un calcul et mettre à jour un libellé avec le résultat du calcul lorsque l'utilisateur ajoute/modifie/efface une géométrie:

// Load elevation data.
var srtm = ee.Image('USGS/SRTMGL1_003');
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);
}

Notez que setLinked() permet d'activer ou de désactiver la connexion entre les outils de dessin géométrique et la section Importations de l'éditeur de code. Dans cet exemple, les outils de géométrie sont dissociés pour éviter la création d'importations. toGeometry permet de convertir le calque en ee.Geometry. Si le calque importé représente un Feature ou un FeatureCollection, vous pouvez récupérer l'objet EE sous-jacent à l'aide de getEeObject(). Notez également l'utilisation de ui.util.debounce pour empêcher chaque mouvement d'une géométrie de déclencher la fonction de rappel. Plus précisément, la fonction ne se déclenchera pas tant que 100 millisecondes ne se seront pas écoulées depuis le dernier événement. Cela permet de s'assurer que la fonction ne s'exécute que lorsque l'utilisateur a terminé l'action de modification.

Un calque de géométrie dans les importations est associé à un Geometry ou à un GeometryCollection. Il ne peut donc contenir que des géométries ayant le même état géodésique, car le format GeoJSON n'autorise qu'un seul état géodésique pour la collection de géométries (pour en savoir plus, consultez la page Géodésique par rapport aux géométries planes). Si vous convertissez le calque de géométrie en FeatureCollection en appuyant sur l'icône en forme de roue dentée à côté du nom du calque, vous pourrez ajouter des géométries géodésiques et planes au même calque. Toutefois, la conversion en Geometry génère une erreur. Pour éviter cela, convertissez-les en FeatureCollection ou supprimez les géométries jusqu'à ce qu'il n'y ait qu'un seul état géodésique dans le calque.

ui.Map.Linker

Comme une couche, un linker n'est pas un widget stylable. Il s'agit d'un utilitaire en coulisse qui peut être utilisé pour synchroniser le mouvement de plusieurs instances ui.Map:

// 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

Un ui.SplitPanel est utile pour comparer des éléments côte à côte. L'avantage d'un ui.SplitPanel par rapport à deux panneaux ordinaires est qu'une poignée peut être utilisée pour effectuer une transition d'effacement entre les panneaux dans un ui.SplitPanel. L'exemple suivant utilise un ui.SplitPanel pour afficher les différences spectrales des cicatrices de brûlure:

// 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]);

Notez que le paramètre wipe est défini sur true dans le constructeur ui.SplitPanel afin de permettre à l'utilisateur de faire glisser le curseur entre les deux visualisations.

Attribuer un style aux widgets

Le style d'un widget est contrôlé par le dictionnaire de ses propriétés de style. Vous pouvez accéder au dictionnaire en appelant style() sur le widget. L'objet renvoyé par style() est une instance de ui.data.ActiveDictionary. Cela signifie que le paramétrage des propriétés du dictionnaire de styles met automatiquement à jour la façon dont le widget s'affiche. Les clés autorisées pour le dictionnaire de style de chaque widget sont détaillées dans la documentation de référence du widget pour l'appel style().

Les styles du widget peuvent être définis avec le constructeur, en appelant style().set() ou en appelant style() avec un argument de dictionnaire. Exemple :

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);

Notez que dans cet exemple, le style de l'étiquette est d'abord défini en appelant style().set() avec des arguments de clé et de valeur, puis en appelant style().set() avec un argument de dictionnaire. Le deuxième appel ne remplace pas le premier. Il ajoute et remplace des propriétés de style individuelles plutôt que de remplacer l'ensemble du dictionnaire de styles.

Pour en savoir plus sur les options de style pour les widgets, consultez cette documentation de référence sur les feuilles de style en cascade (CSS) pour les styles listés dans la documentation style() pour chaque widget. Notez que les styles autorisés pour les widgets Earth Engine diffèrent des styles CSS à plusieurs endroits, en particulier fontSize et fontWeight pour font-style et font-weight, respectivement.

Le dictionnaire des styles contient également des clés qui contrôlent la position du widget. Pour en savoir plus sur l'utilisation des propriétés de position, consultez la page Panneaux et mises en page.