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 l'application de styles à vos widgets, consultez la section "Style". Les exemples suivants se contentent d'afficher les widgets dans la console à l'aide de print(). Pour en savoir plus sur l'ajout de widgets aux panneaux, consultez la page Panneaux et mises en page.
ui.Label
Les étiquettes sont simplement des zones dans lesquelles du texte est affiché. Par exemple, le code suivant imprime une étiquette :
Éditeur de code (JavaScript)
var label = ui.Label('Cool label!'); print(label);
qui ressemble à ceci :
Divisez les libellés longs en insérant un caractère de nouvelle ligne (\n) et en définissant l'argument de la 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 l'utilisateur peut cliquer. Vous pouvez spécifier une fonction à appeler (la fonction de "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 Événements. L'exemple suivant affiche le centre actuel de la carte lorsque l'utilisateur clique sur le bouton :
Éditeur de code (JavaScript)
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 à un utilisateur de cocher (ou de décocher) une case. Lorsque l'état de la case à cocher change, les rappels enregistrés dans le widget reçoivent une valeur booléenne indiquant si la case est désormais cochée. Exemple :
Éditeur de code (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);
La case à cocher imprimée doit ressembler à ceci :
Notez que cocher la case active un calque affiché sur la carte. Comme pour les autres composants de l'interface utilisateur, la carte de l'éditeur de code peut être manipulée de manière programmatique. Pour en savoir plus sur l'objet Carte, 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 :
Éditeur de code (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);
Le curseur doit ressembler à ceci :
Notez que la valeur du curseur est affichée à droite de celui-ci.
ui.DateSlider
Le widget DateSlider est semblable au widget Slider, mais il gère explicitement les dates. Voici à quoi ressemble un DateSlider configuré pour sélectionner un jour de juin 2018 :
DateSlider est utile pour filtrer les collections, comme illustré dans l'exemple suivant, qui crée un composite annuel basé sur le DateRange défini dans DateSlider :
Éditeur de code (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
Une zone de texte est un endroit où collecter du texte saisi par l'utilisateur. Exemple :
Éditeur de code (JavaScript)
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 doit ressembler à ceci :
Notez que le rappel n'est déclenché que lorsque l'utilisateur a fini de saisir du texte (et a appuyé sur Entrée) ou qu'il clique en dehors de la zone de texte.
ui.Select
Le widget de sélection représente un menu déroulant d'options parmi lesquelles l'utilisateur peut en choisir une. L'exemple suivant illustre un menu déroulant permettant à un utilisateur de sélectionner un emplacement :
Éditeur de code (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);
Le widget de sélection doit ressembler à ceci :
ui.Chart
Les graphiques du package ui.Chart se comportent de la même manière que ceux du package Chart. Plus précisément, un ui.Chart est un wrapper léger autour d'une instance de ChartWrapper de l'API Google Visualization.
Pour en savoir plus sur la manipulation des objets ChartWrapper, consultez cette documentation de référence. Pour en savoir plus sur les fonctions d'assistance pour les graphiques dans Earth Engine, consultez la documentation sur les graphiques.
ui.Thumbnail
Le widget de vignette peut être utilisé pour 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 une image 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 miniature obtenue :
Éditeur de code (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'} }));
La miniature doit ressembler à ceci :
ui.Map
ui.Map est un widget de carte. (En fait, la carte par défaut de l'éditeur de code est une instance de cette classe). Comme pour 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 affiche une carte dans la console qui montre les limites de la carte de l'éditeur de code :
Éditeur de code (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);
La carte en incrustation devrait ressembler à ceci :
Dans cet exemple, l'utilisateur doit cliquer sur la grande carte pour que l'encart s'affiche 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 de type tableau. Lorsque vous le modifiez, les calques de la carte changent également. Pour en savoir plus, consultez la section ui.Map.Layer.
ui.Map.Layer
Un calque n'est pas un widget stylisable comme un ui.Button. Il s'agit simplement 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 des entrées utilisateur :
Éditeur de code (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
Si vous souhaitez afficher (par exemple dans une application) un calque relativement coûteux à 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 vos scripts plus réactifs. Pour ce faire, vous pouvez créer une couche d'affichage statique à 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 Cloud Storage et d'un chemin d'accès 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 à l'élément Map dans l'éditeur de code. Vous pouvez modifier le comportement de ces outils dans le Map par défaut en appelant Map.drawingTools(). Par exemple, pour masquer les outils de dessin :
Éditeur de code (JavaScript)
Map.drawingTools().setShown(false);
Les cartes nouvellement créées ne disposent pas d'outils de dessin par défaut, mais vous pouvez les activer en appelant la méthode drawingTools() sur la carte :
Éditeur de code (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]);
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 géométriques répond aux événements comme les autres listes actives, par exemple la liste des calques sur Map renvoyée par Map.layers(). L'exemple suivant montre comment définir la visibilité des calques géométriques dessinés par les outils (qui sont affichés par défaut) :
Éditeur de code (JavaScript)
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 :
Éditeur de code (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);
L'état des outils de dessin est également reporté lorsque vous publiez une application. Si les outils de dessin sont affichés ou masqués, ils seront également affichés ou masqués dans votre application. Les géométries de vos importations seront également reporté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 des importations en haut de votre script et pouvant ê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 que les modifications interactives apportées aux géométries déclenchent un événement. 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 de l'utilisateur.
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 ou efface une géométrie :
Éditeur de code (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); }
Notez que setLinked() permet d'activer ou de désactiver la connexion entre les outils de dessin géométrique et la section "Imports" de l'éditeur de code. Dans cet exemple, les outils de géométrie sont dissociés pour empêcher la création d'importations. toGeometry permet de convertir la couche en ee.Geometry. Si la couche importée 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 déplacement d'une géométrie de déclencher la fonction de rappel. Plus précisément, la fonction ne se déclenchera que 100 millisecondes après 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éométries géodésiques et planes). En convertissant 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, sa reconversion en Geometry générera une erreur. Pour éviter cela, convertissez-les en FeatureCollection ou supprimez des géométries jusqu'à ce qu'il n'y ait plus qu'un seul état géodésique dans la couche.
ui.Map.Linker
Comme un calque, un linker n'est pas un widget stylisable. Il s'agit d'un utilitaire en arrière-plan qui peut être utilisé pour synchroniser le mouvement de plusieurs instances ui.Map :
Éditeur de code (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
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 obtenir une transition par balayage entre les panneaux d'un ui.SplitPanel. L'exemple suivant utilise un ui.SplitPanel pour afficher les différences spectrales des cicatrices de brûlure :
Éditeur de code (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]);
Notez que le paramètre wipe est défini sur true dans le constructeur ui.SplitPanel pour permettre à l'utilisateur de faire glisser la poignée d'avant en arrière entre les deux visualisations.
Widgets de style
Le style d'un widget est contrôlé par le dictionnaire des propriétés de style du widget. 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 la définition des propriétés du dictionnaire de style met automatiquement à jour l'affichage du widget. 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 :
Éditeur de code (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);
Notez que dans cet exemple, le libellé est d'abord stylisé 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 au lieu de remplacer l'intégralité du dictionnaire de styles.
Pour en savoir plus sur les options de style des widgets, consultez la documentation de référence sur les feuilles de style en cascade (CSS) pour les styles listés dans la documentation style() de chaque widget. Notez que les styles autorisés pour les widgets Earth Engine diffèrent des styles CSS à plusieurs endroits, notamment fontSize et fontWeight pour font-style et font-weight, respectivement.
Le dictionnaire de 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.