רכיבי Widget

יש מגוון ווידג'טים שאפשר להשתמש בהם כדי ליצור ממשקי משתמש. הווידג'טים האלה כוללים לחצנים, תיבות סימון, פסולים, תיבות טקסט ותפריטי בחירה. אפשר להדפיס או להוסיף לוח רק פעם אחת. בקטעים הבאים מוסבר על הפונקציונליות הבסיסית, המראה והתחושה של הווידג'טים. מידע נוסף על עיצוב הווידג'טים זמין בקטע 'סגנון'. בדוגמאות הבאות פשוט print() את הווידג'טים למסוף. פרטים על הוספת ווידג'טים לחלוניות מופיעים בדף 'חלוניות ופלטפורמות'.

ui.Label

תוויות הן פשוט אזורים שבהם מוצג טקסט. לדוגמה, הקוד הבא מדפיס תווית:

Code Editor‏ (JavaScript)

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

כך זה נראה:

כדי לפצל תוויות ארוכות, מוסיפים תו שורת חדש (\n) ומגדירים את הארגומנט של מאפיין הסגנון whiteSpace לערך 'pre':

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

ui.Button

לחצן הוא ווידג'ט אינטראקטיבי של ממשק משתמש שאפשר ללחוץ עליו. אפשר לציין פונקציה שתופעל (פונקציית ה-"callback") כשמשתמש לוחץ על הלחצן. (מידע נוסף על טיפול באירועים באמצעות פונקציות קריאה חוזרת זמין בדף 'אירועים'). בדוגמה הבאה, כשלוחצים על הלחצן, המרכז הנוכחי של המפה מודפס:

Code Editor‏ (JavaScript)

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

כך זה נראה:

ui.Checkbox

תיבת סימון היא ווידג'ט שמאפשר למשתמש לסמן (או לבטל את הסימון) של תיבה. כשמצב תיבת הסימון משתנה, פונקציות ה-callbacks שרשמות לווידג'ט מקבלות ערך בוליאני שמציין אם תיבת הסימון מסומנת עכשיו. לדוגמה:

Code Editor‏ (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);

תיבת הסימון המודפסת אמורה להיראות כך:

לתשומת ליבכם: סימון התיבה מפעיל שכבה שמוצגת במפה. בדומה לרכיבים אחרים בממשק המשתמש, אפשר לשנות את המפה של Code Editor באופן פרוגרמטי. מידע נוסף על האובייקט Map זמין בדף Panels and Layouts.

ui.Slider

פס הזזה הוא ווידג'ט שמאפשר למשתמש לשנות את פס ההזזה כדי לקבל מספר בטווח של פס ההזזה. מגדירים את הטווח באמצעות המבנה הגנרטיבי או על ידי הגדרת המאפיינים של פס ההזזה. בדוגמה הבאה נעשה שימוש בפס ההזזה כדי להגדיר את השקיפות של השכבה הראשונה במפה:

Code Editor‏ (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);

פס ההזזה אמור להיראות כך:

הערה: הערך של פס ההזזה מוצג משמאל לפס ההזזה.

ui.DateSlider

הווידג'ט DateSlider דומה לווידג'ט Slider, אבל הוא מטפל בתאריכים באופן מפורש. DateSlider שמוגדר לבחור יום מיוני 2018 נראה כך:

השדה DateSlider שימושי לסינון אוספים, כפי שמוצג בדוגמה הבאה, שבה נוצר נתון משולב שנתי על סמך הערך של DateRange שמוגדר ב-DateSlider:

Code Editor‏ (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

תיבת טקסט היא מקום לאיסוף טקסט שהמשתמשים מזינים. לדוגמה:

Code Editor‏ (JavaScript)

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

תיבת הטקסט אמורה להיראות כך:

הערה: קריאת החזרה (callback) מופעלת רק כשהמשתמש מסיים להזין טקסט (ולוחץ על return) או כשהמשתמש לוחץ מחוץ לתיבת הטקסט.

ui.Select

הווידג'ט של הבחירה מייצג תפריט נפתח של אפשרויות שממנו המשתמש יכול לבחור אחת. הדוגמה הבאה ממחישה תפריט נפתח שמאפשר למשתמש לבחור מיקום:

Code Editor‏ (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);

הווידג'ט שנבחר אמור להיראות כך:

ui.Chart

התרשימים בחבילה ui.Chart פועלים באופן דומה לתרשימים בחבילה Chart. באופן ספציפי, ui.Chart הוא מעטפת דקה מסביב למכונה של ChartWrapper של Google Visualization API. למידע נוסף על מניפולציה באובייקטים מסוג ChartWrapper, ראו מקור המידע הזה. למידע נוסף על פונקציות העזרה של התרשימים ב-Earth Engine, תוכלו לעיין במסמכי העזרה של התרשימים.

ui.Thumbnail

אפשר להשתמש בווידג'ט התמונות הממוזערות כדי להציג תצוגה מקדימה של אובייקטים מסוג ee.Image ו-ee.ImageCollection. אם תספקו לווידג'ט את הערך ee.Image, תוצג בו תמונה סטטית. אם תספקו לו את הערך ee.ImageCollection, תוצג בו אנימציה עם פריים אחד לכל תמונה בקלט. בדומה ל-ee.Image.getThumbURL() ול-ee.ImageCollection.getVideoThumbURL(), אפשר לציין פרמטרים כדי לקבוע את הפורמט והמידות של התמונה הממוזערת שייווצרו:

Code Editor‏ (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'}
}));

התמונה הממוזערת אמורה להיראות בערך כך:

ui.Map

ui.Map הוא ווידג'ט מפה. (למעשה, המפה של ברירת המחדל של Code Editor היא מופע של הכיתה הזו). כמו ווידג'טים אחרים, אפשר להדפיס מפה במסוף. אפשר לשנות את התוכן של המפה על ידי ניקוי, אחזור או הגדרה של שכבות נפרדות. בדוגמה הבאה מודפסת במסוף מפה שמציגה את הגבולות של המפה של Code Editor:

Code Editor‏ (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);

המפה המצורפת אמורה להיראות בערך כך:

בדוגמה הזו, המשתמש צריך ללחוץ על המפה הגדולה כדי שהמפה המשולבת תופיע במפה הקטנה.

אפשר גם לבצע פעולות על השכבות במפה באמצעות קריאה ל-layers() במופע המפה. הפונקציה layers() מחזירה ui.data.ActiveList, אובייקט שדומה למערך. כשמשנים את התצוגה, השכבות במפה משתנות גם הן. מידע נוסף זמין בקטע ui.Map.Layer.

ui.Map.Layer

שכבה היא לא ווידג'ט שניתן לשנות את הסגנון שלו, כמו ui.Button. זהו רק ייצוג נתונים של השכבה במפה. בדוגמה הבאה מוסבר איך מעדכנים מפה על ידי יצירת שכבה ועדכון המאפיינים של השכבה על סמך הקלט של המשתמש:

Code Editor‏ (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/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

אם אתם רוצים להציג (למשל באפליקציה) שכבה שהחישוב שלה יקר יחסית, כדאי לייצא את הנתונים לקטגוריה של Cloud Storage מטעמי ביצועים. שכבות סטטיות אלו, שמשמשות רק להצגת נתונים חזותית, יכולות לשפר את הרספונסיביות של האפליקציות והסקריפטים. לשם כך, אפשר ליצור שכבת תצוגה סטטית באמצעות Export.map.toCloudStorage(). כדי להשתמש בקבוצת משבצות שיוצאו בעבר באמצעות Export.map.toCloudStorage(), יוצרים ui.Map.Layer חדש מקטגוריה ומנתיב ספציפיים ב-Cloud Storage:

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

כשמריצים סקריפט שטעון שכבת Cloud Storage, עשויה להופיע הודעת האזהרה הבאה:

ui.Map.DrawingTools

יש קבוצה של כלי ציור גיאומטריה שנוספים כברירת מחדל ל-Map ב-Code Editor. אפשר לשנות את ההתנהגות של הכלים האלה בברירת המחדל Map באמצעות קריאה ל-Map.drawingTools(). לדוגמה, כדי להסתיר את כלי השרטוט:

Code Editor‏ (JavaScript)

Map.drawingTools().setShown(false);

כברירת מחדל, מפות חדשות לא כוללות כלים לציור, אבל אפשר להפעיל אותם על ידי קריאה ל-method‏ drawingTools() במפה:

Code Editor‏ (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]);

שכבות הגיאומטריה שמצוירות באמצעות כלי הציור מועברות ל-ui.data.ActiveList, שאליו אפשר לגשת באמצעות קריאה ל-Map.drawingTools().layers(). רשימת שכבות הגיאומטריה מגיבה לאירועים כמו רשימות פעילות אחרות, למשל רשימת השכבות ב-Map שמוחזרת על ידי Map.layers(). בדוגמה הבאה מוסבר איך להגדיר את ההצגה של שכבות הגיאומטריה שמצוירות על ידי הכלים (שמוצגות כברירת מחדל):

Code Editor‏ (JavaScript)

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

כדי להוסיף שכבה באופן פרוגרמטי לכלים לציור, אפשר להפעיל את השיטה addLayer בכלי לציור או להוסיף שכבה ישירות לרשימת השכבות:

Code Editor‏ (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);

המצב של כלי הציור נשמר גם כשמפרסמים אפליקציה. אם כלי הציור מוצגים או מוסתרים, הם יוצגו או ייסתרו גם באפליקציה. גם הגיאומטריות של הפריטים שיובאו יועברו לאפליקציה.

ui.Map.GeometryLayer

GeometryLayer הוא אוסף של גיאומטריות שפועלות כ-Geometry, ‏ GeometryCollection או FeatureCollection יחיד, שמתווסף לקטע הייבוא בחלק העליון של הסקריפט וניתן להפנות אליו בקוד.

ל-GeometryLayers שכלי הציור מציירים יש התנהגות ברירת מחדל שאפשר לשנות על ידי מתן פונקציות קריאה חוזרת חדשות. לדוגמה, נניח שאתם רוצים שהשינויים האינטראקטיביים בגיאומטריות יגרמו להפעלת אירוע. כדי להטמיע התנהגות מסוימת, אפשר להגדיר את השיטות onEdit(),‏ onErase() או onDraw() בכלים כדי להגיב לפעולות של המשתמשים. בדוגמה הבאה מוסבר איך מפעילים חישוב ומעדכנים תווית בתוצאת החישוב כשהמשתמש מוסיף, עורך או מחק גיאומטריה:

Code Editor‏ (JavaScript)

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

הערה: המקש setLinked() משמש להפעלה או להשבתה של החיבור בין הכלים לציור גיאומטריה לבין הקטע ייבוא של עורך הקוד. בדוגמה הזו, הכלים של הגיאומטריה לא מקושרים כדי למנוע יצירה של ייבוא. toGeometry משמש להמרת השכבה ל-ee.Geometry. אם השכבה המיובאת מייצגת Feature או FeatureCollection, אפשר לאחזר את אובייקט ה-EE הבסיסי באמצעות getEeObject(). שימו לב גם לשימוש ב-ui.util.debounce כדי למנוע מכל תנועה של גיאומטריה להפעיל את פונקציית ה-callback. באופן ספציפי, הפונקציה לא תופעל עד שיחלפו 100 אלפיות השנייה מהאירוע האחרון. כך תוכלו לוודא שהפונקציה תפעל רק אחרי שהמשתמש ישלים את פעולת העריכה.

שכבת גיאומטריה בייבוא משויכת ל-Geometry או ל-GeometryCollection, כך שהיא יכולה להכיל רק גיאומטריות עם אותו מצב גיאודטי, כי פורמט GeoJSON מאפשר רק מצב גיאודטי אחד לאוסף של גיאומטריות (למידע נוסף, ראו Geodesic vs. Planar Geometries). כדי להמיר את שכבת הגיאומטריה ל-FeatureCollection, לוחצים על סמל גלגל השיניים לצד שם השכבה. כך תוכלו להוסיף גיאומטריה גיאודזית וגיאומטריה מישורית לאותה שכבה. עם זאת, המרה חזרה ל-Geometry תגרום לשגיאה. כדי למנוע זאת, צריך להמיר את הגיאומטריות ל-FeatureCollection או למחוק אותן עד שיישאר רק מצב גיאודטי אחד בשכבה.

ui.Map.Linker

כמו שכבה, קישור הוא לא ווידג'ט שניתן לשנות את הסגנון שלו. זוהי תוכנית שירות ברקע שאפשר להשתמש בה כדי לסנכרן את התנועה של כמה מכונות ui.Map:

Code Editor‏ (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

ui.SplitPanel שימושי להשוואה בין דברים זה לצד זה. היתרון של ui.SplitPanel על פני שתי חלוניות רגילות הוא שאפשר להשתמש בידית כדי ליצור מעבר מחיקה בין החלונות ב-ui.SplitPanel. בדוגמה הבאה נעשה שימוש ב-ui.SplitPanel כדי להציג את ההבדלים הספקטרליים בין צלקות כוויות:

Code Editor‏ (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]);

הערה: הפרמטר wipe מוגדר ל-true ב-constructor של ui.SplitPanel כדי לאפשר למשתמש להחליק את הידית הלוך ושוב בין שתי התצוגות החזותיות.

עיצוב ווידג'טים

הסגנון של הווידג'ט נקבע על ידי מילון מאפייני הסגנון של הווידג'ט. כדי לגשת למילון, צריך להפעיל את הפונקציה style() בווידג'ט. האובייקט שמוחזר על ידי style() הוא מופע של ui.data.ActiveDictionary. כלומר, הגדרת המאפיינים של מילון הסגנונות מעדכנת באופן אוטומטי את האופן שבו הווידג'ט מוצג. המפתחות המותרים לכל מילון סגנונות של ווידג'ט מפורטים במסמכי העזרה של הווידג'ט לגבי הקריאה style().

אפשר להגדיר את הסגנונות של הווידג'ט באמצעות ה-constructor, על ידי קריאה ל-style().set() או על ידי קריאה ל-style() עם ארגומנט של מילון. לדוגמה:

Code Editor‏ (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);

שימו לב שבדוגמה הזו, קובעים את הסגנון של התווית קודם על ידי קריאה ל-style().set() עם ארגומנטים של מפתח וערכו, ואז על ידי קריאה ל-style().set() עם ארגומנט של מילון. הקריאה השנייה לא מבטלת את הראשונה, אלא מוסיפה ומחליפת מאפייני סגנון ספציפיים במקום להחליף את כל מילון הסגנונות.

למידע נוסף על אפשרויות העיצוב של ווידג'טים, אפשר לעיין בחומר העזר בנושא גיליונות סגנונות מדורגים (CSS) כדי למצוא את הסגנונות שמפורטים במסמכי העזרה של style() לכל ווידג'ט. חשוב לזכור שהסגנונות שמותר להשתמש בהם בווידג'טים של Earth Engine שונים מסגנונות CSS בכמה מקומות, במיוחד fontSize ו-fontWeight במקום font-style ו-font-weight, בהתאמה.

במילון הסגנונות יש גם מפתחות ששולטים במיקום של הווידג'ט. למידע נוסף על שימוש במאפייני מיקום, ראו הדף 'חלוניות ותצוגות'.