ウィジェット

UI の構築に使用できるウィジェットは、さまざまな種類があります。これらのウィジェットには、ボタン、チェックボックス、スライダー、テキストボックス、選択メニューなどがあります。ウィジェットは、1 回だけ印刷またはパネルに追加できます。以降のセクションでは、ウィジェットの基本的な機能、デザイン、操作性について説明します。ウィジェットのスタイル設定について詳しくは、スタイル セクションをご覧ください。次の例では、ウィジェットをコンソールに print() しています。パネルにウィジェットを追加する方法については、パネルとレイアウトのページをご覧ください。

ui.Label

ラベルは、テキストが表示される領域にすぎません。たとえば、次のコードはラベルを出力します。

コードエディタ(JavaScript)

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

その状況を図に表すと次のようになります。

ui_label.png

長いラベルを分割するには、改行文字(\n)を挿入し、whiteSpace スタイル プロパティの引数を 'pre' に設定します。

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

ui.Button

ボタンは、クリック可能なインタラクティブ UI ウィジェットです。ユーザーがボタンをクリックしたときに呼び出される関数(「コールバック」関数)を指定できます。(コールバック関数を使用したイベント処理の詳細については、イベントのページをご覧ください)。次の例では、ボタンがクリックされると、地図の現在の中心が出力されます。

コードエディタ(JavaScript)

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

その状況を図に表すと次のようになります。

ui_button.png

ui.Checkbox

チェックボックスは、ユーザーがボックスにチェックを入れる(またはチェックボックスをオフにする)ことができるウィジェットです。チェックボックスの状態が変化すると、ウィジェットに登録されたコールバックに、チェックボックスがオンになったかどうかを示すブール値が渡されます。次に例を示します。

コードエディタ(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);

印刷されたチェックボックスは次のようになります。

ui_checkbox.png

チェックボックスをオンにすると、地図上にレイヤが表示されます。他の UI コンポーネントと同様に、コードエディタの地図はプログラムで操作できます。Map オブジェクトの詳細については、パネルとレイアウトのページをご覧ください。

ui.Slider

スライダーは、ユーザーがスライダーを調整してスライダー範囲内の数値を取得できるようにするウィジェットです。コンストラクタを使用するか、スライダーのプロパティを設定して、範囲を構成します。次の例では、スライダーを使用して、地図の最初のレイヤの不透明度を設定しています。

コードエディタ(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_slider.png

スライダーの値はスライダーの右側に表示されます。

ui.DateSlider

DateSlider ウィジェットは Slider ウィジェットに似ていますが、日付を明示的に処理します。2018 年 6 月から 1 日を選択するように構成された DateSlider は次のようになります。

DateSlider.png

DateSlider は、コレクションのフィルタリングに役立ちます。次の例では、DateSlider で設定された DateRange に基づいて年次コンポジットを作成しています。

コードエディタ(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

テキスト ボックスは、ユーザーが入力したテキストを収集する場所です。次に例を示します。

コードエディタ(JavaScript)

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

テキスト ボックスは次のようになります。

ui_textbox.png

コールバックは、ユーザーがテキストの入力を完了して return キーを押したとき、またはテキスト ボックスの外をクリックしたときにのみ呼び出されます。

ui.Select

選択ウィジェットは、ユーザーが 1 つを選択できる選択肢のプルダウン メニューを表します。次の例は、ユーザーが場所を選択できるようにするプルダウン メニューを示しています。

コードエディタ(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_select.png

ui.Chart

ui.Chart パッケージのグラフは、Chart パッケージのグラフと同様に動作します。具体的には、ui.Chart は Google Visualization API の ChartWrapper のインスタンスを囲む薄いシェルです。ChartWrapper オブジェクトの操作について詳しくは、こちらのリファレンスをご覧ください。Earth Engine のグラフ ヘルパー関数の詳細については、グラフのドキュメントをご覧ください。

ui.Thumbnail

サムネイル ウィジェットを使用すると、ee.Image オブジェクトと ee.ImageCollection オブジェクトをプレビューできます。ee.Image を指定すると、ウィジェットに静止画像が表示されます。ee.ImageCollection を指定すると、入力内の画像ごとに 1 フレームのアニメーションが表示されます。ee.Image.getThumbURL() や ee.ImageCollection.getVideoThumbURL() と同様に、パラメータを指定して、生成されるサムネイルの形式とサイズを制御できます。

コードエディタ(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_thumbnail.png

ui.Map

ui.Map はマップ ウィジェットです。(実際、デフォルトのコードエディタの Map は、このクラスのインスタンスです)。他のウィジェットと同様に、地図をコンソールに出力できます。個々のレイヤをクリア、取得、設定して、地図のコンテンツを操作します。次の例では、コードエディタの Map の境界を示す地図をコンソールに出力します。

コードエディタ(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);

インセット マップは次のようになります。

ui_map.png

この例では、ユーザーが大きな地図をクリックすると、小さな地図にインセットが描画されます。

地図インスタンスで layers() を呼び出して、地図上のレイヤを操作することもできます。layers() は、配列のようなオブジェクトである ui.data.ActiveList を返します。変更すると、地図上のレイヤも変更されます。詳しくは、ui.Map.Layer セクションをご覧ください。

ui.Map.Layer

レイヤは、ui.Button のようなスタイル設定可能なウィジェットではありません。これは、地図上のレイヤのデータ表現にすぎません。次の例は、レイヤを作成し、ユーザー入力に基づいてレイヤのプロパティを更新することで、地図を更新する方法を示しています。

コードエディタ(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

計算コストが比較的高いレイヤを(アプリなどで)表示する場合は、パフォーマンス上の理由から、データを Cloud Storage バケットにエクスポートすることをおすすめします。これらの静的な可視化専用レイヤを使用すると、アプリやスクリプトの応答性を高めることができます。この目的のために、Export.map.toCloudStorage() を使用して静的な表示レイヤを作成できます。以前に Export.map.toCloudStorage() によってエクスポートされたタイルセットを使用するには、指定された Cloud Storage バケットとパスから新しい ui.Map.Layer を作成します。

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 には、デフォルトで一連のジオメトリ描画ツールが追加されています。Map.drawingTools() を呼び出すことで、デフォルトの Map でこれらのツールの動作を変更できます。たとえば、描画ツールを非表示にするには、次のようにします。

コードエディタ(JavaScript)

Map.drawingTools().setShown(false);

新しく作成された地図には、デフォルトでは描画ツールは表示されませんが、地図で drawingTools() メソッドを呼び出すことで有効にできます。

コードエディタ(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.layers() によって返される Map のレイヤリストなど)と同様に、イベントに応答します。次の例は、ツールによって描画されるジオメトリ レイヤ(デフォルトで表示される)の表示 / 非表示を設定する方法を示しています。

コードエディタ(JavaScript)

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

描画ツールにプログラムでレイヤを追加するには、描画ツールで addLayer メソッドを呼び出すか、レイヤリストに直接レイヤを追加します。

コードエディタ(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 として機能するジオメトリのコレクションです。スクリプトの上部にあるインポート セクションに追加され、コード内で参照できます。

描画ツールによって描画される GeometryLayer にはデフォルトの動作がありますが、新しいコールバック関数を指定することで、この動作をオーバーライドできます。たとえば、ジオメトリのインタラクティブな変更によってイベントをトリガーするとします。特定の動作を実装するには、ユーザー アクションに応答するために、ツールの onEdit()、onErase()、onDraw() メソッドを設定します。次の例は、ユーザーがジオメトリを追加、編集、消去したときに、計算をトリガーして計算結果でラベルを更新する方法を示しています。

コードエディタ(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);
}

setLinked() は、ジオメトリ描画ツールとコードエディタの [Imports] セクションの接続を切り替えるために使用されます。この例では、インポートが作成されないように、ジオメトリ ツールがリンク解除されています。toGeometry は、レイヤを ee.Geometry に変換するために使用されます。インポートされたレイヤが Feature または FeatureCollection を表している場合は、getEeObject() を使用して基盤となる EE オブジェクトを取得できます。また、ジオメトリの各移動でコールバック関数がトリガーされないように、ui.util.debounce が使用されていることにも注意してください。具体的には、最後のイベントから 100 ミリ秒が経過するまで関数は呼び出されません。これにより、ユーザーが編集アクションを完了した場合にのみ関数が実行されるようになります。

インポートのジオメトリ レイヤは Geometry または GeometryCollection に関連付けられているため、同じ測地状態のジオメトリのみを含めることができます。これは、GeoJSON 形式ではジオメトリのコレクションに対して 1 つの測地状態のみが許可されるためです(詳細については、測地ジオメトリと平面ジオメトリのページをご覧ください)。レイヤ名の横にある歯車アイコンを押して、ジオメトリ レイヤを FeatureCollection に変換すると、同じレイヤに測地線ジオメトリと平面ジオメトリを追加できます。ただし、Geometry に戻すとエラーが発生します。これを回避するには、FeatureCollection に変換するか、レイヤに測地線状態が 1 つだけになるまでジオメトリを削除します。

ui.Map.Linker

レイヤと同様に、リンカーはスタイル設定可能なウィジェットではありません。これは、複数の ui.Map インスタンスの動きを同期するために使用できる、バックグラウンドのユーティリティです。

コードエディタ(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 の利点は、2 つの通常のパネルとは異なり、ハンドルを使用して ui.SplitPanel 内のパネル間でワイプ遷移を実現できることです。次の例では、ui.SplitPanel を使用して、火傷痕のスペクトルの違いを表示しています。

コードエディタ(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]);

ユーザーが 2 つのビジュアリゼーション間でハンドルを前後にスワイプできるように、ui.SplitPanel コンストラクタで wipe パラメータが true に設定されていることに注意してください。

ウィジェットのスタイルを設定する

ウィジェットのスタイルは、ウィジェットのスタイル プロパティの辞書によって制御されます。辞書にアクセスするには、ウィジェットで style() を呼び出します。style() によって返されるオブジェクトは ui.data.ActiveDictionary のインスタンスです。つまり、スタイル ディクショナリのプロパティを設定すると、ウィジェットの表示方法が自動的に更新されます。各ウィジェットのスタイル ディクショナリで使用できるキーの詳細については、style() 呼び出しに関するウィジェットのリファレンス ドキュメントをご覧ください。

ウィジェットのスタイルは、コンストラクタで設定するか、style().set() を呼び出すか、辞書引数を指定して style() を呼び出すことで設定できます。次に例を示します。

コードエディタ(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() を呼び出すことで行われています。2 回目の呼び出しは 1 回目の呼び出しをオーバーライドしません。スタイル ディクショナリ全体を置き換えるのではなく、個別のスタイル プロパティを追加して置き換えます。

ウィジェットのスタイル設定オプションの詳細については、各ウィジェットの style() ドキュメントに記載されているスタイルのカスケーディング スタイル シート(CSS)リファレンスをご覧ください。Earth Engine ウィジェットで使用できるスタイルは、いくつかの点で CSS スタイルとは異なります。特に、font-style と font-weight の fontSize と fontWeight が異なります。

スタイル ディクショナリには、ウィジェットの位置を制御するキーも含まれています。位置プロパティの使用方法について詳しくは、パネルとレイアウトのページをご覧ください。