Earth Engine 程式碼編輯器

Earth Engine (EE) 程式碼編輯器 (網址：code.earthengine.google.com) 是以網路為基礎的 IDE，適用於 Earth Engine JavaScript API。程式碼編輯器功能旨在協助您快速輕鬆地開發複雜的地理空間工作流程。程式碼編輯器包含下列元素 (如圖 1 所示)：

  • JavaScript 程式碼編輯器
  • 將地理空間資料集視覺化的地圖顯示功能
  • API 參考文件 (「文件」分頁)
  • Git 型指令碼管理工具 (「指令碼」分頁)
  • 控制台輸出內容 (「控制台」分頁)
  • 工作管理員 (「工作」分頁)，可處理長時間執行的查詢
  • 互動式地圖查詢 (「檢查工具」分頁)
  • 資料封存或已儲存的指令碼搜尋功能
  • 幾何圖形繪製工具

程式碼編輯器的元件

圖 1. Earth Engine 程式碼編輯器元件圖，網址為 code.earthengine.google.com。

程式碼編輯器提供多種功能，協助您充分運用 Earth Engine API。在「指令碼」分頁中查看範例指令碼或儲存自己的指令碼。使用「檢查工具」分頁查詢地圖上的物件。使用 Google Visualization API 顯示及繪製數值結果圖表。按一下「取得連結」按鈕，即可與協作者和好友分享專屬指令碼網址。您在程式碼編輯器中開發的指令碼會傳送至 Google 進行處理，然後將產生的地圖圖塊和/或訊息傳回，以便顯示在「地圖」和/或「控制台」分頁中。如要執行程式碼編輯器，您只需要網路瀏覽器 (建議使用 Google Chrome，可獲得最佳體驗) 和網際網路連線。以下各節將詳細說明 Earth Engine 程式碼編輯器的元素。

JavaScript 編輯器

JavaScript 編輯器會：

  • 在輸入時格式化及醒目顯示程式碼
  • 為有問題的程式碼加上底線，提供修正建議和其他提示，協助您使用正確的語法
  • 自動完成成對的引號、方括號和圓括號
  • 提供 Earth Engine 函式的程式碼補全提示

程式碼編輯器上方有幾個按鈕，可執行及儲存指令碼、重設輸出對應和控制台，以及取得指令碼連結。按下「取得連結」按鈕後，瀏覽器的網址列會顯示專屬連結。這個連結代表按下按鈕時編輯器中的程式碼。

API 參考資料 (「文件」分頁)

程式碼編輯器的左側是「文件」分頁，其中包含完整的 JavaScript API 說明文件。您可以在「文件」分頁中搜尋及瀏覽說明文件。

指令碼管理工具 (「指令碼」分頁)

「Scripts」(指令碼) 分頁標籤位於程式碼編輯器的左側面板中，與 API 說明文件相鄰。指令碼管理工具會將私人、共用和範例指令碼儲存在 Google 託管的 Git 存放區。存放區會依存取層級排列，您的私人指令碼會儲存在「擁有者」資料夾 (users/username/default) 中您擁有的存放區。除非您與他人共用，否則只有您能存取「擁有者」資料夾中的存放區。「Writer」資料夾中的存放區，是擁有者授予您寫入權的存放區。您可以在「Writer」資料夾中新增指令碼、修改現有指令碼，或變更存放區的存取權 (您可能無法移除擁有者)。「讀者」資料夾中的存放區，是擁有者授予您讀取權的存放區。「範例」資料夾是由 Google 管理的特殊存放區，內含程式碼範例。「封存」資料夾包含您有權存取，但擁有者尚未從舊版指令碼管理工具遷移的舊版存放區。使用「指令碼」分頁頂端的篩選列，搜尋指令碼。

指令碼管理工具

圖 2. 指令碼管理工具。

按一下 按鈕，即可在「擁有者」資料夾中建立新的存放區，或在存放區中建立資料夾和檔案。你可以使用 圖示重新命名指令碼，並使用 圖示刪除指令碼。你可以拖曳指令碼，並整理到資料夾中 (圖 2)。如果將指令碼拖曳到其他存放區，系統會複製該指令碼。

所有指令碼和存放區都會保留完整版本記錄。按一下指令碼或存放區旁的 圖示，即可比較或還原至舊版。如要刪除存放區，請按一下 圖示。如要設定存放區的存取權，請按一下存放區名稱旁的 圖示。請注意，如果您分享存放區，共用對象必須點選設定對話方塊中顯示的連結，才能接受存放區。如要隱藏先前接受的存放區，請在指令碼管理工具中，按一下存放區名稱後方的 圖示。

您可以使用 Git 存取存放區，因此可以在程式碼編輯器以外的位置管理及編輯指令碼，或將指令碼與 GitHub 等外部系統同步處理。(如要進一步瞭解 Git，請參閱這篇教學文章)。按一下存放區名稱旁的 圖示，查看如何複製存放區的操作說明。請注意，如要瀏覽您有權存取的存放區，請前往 earthengine.googlesource.com。如要執行部分 Git 作業，您可能需要前往 earthengine.googlesource.com 頁面頂端的「產生密碼」連結，建立驗證憑證。

指令碼模組

建議您編寫可重複使用的模組化程式碼，這樣就能在指令碼之間共用，不必大量複製及貼上。為啟用模組化開發，Earth Engine 提供在指令碼之間共用程式碼的功能。舉例來說，假設您編寫的函式會執行一組實用的作業。新指令碼不必複製函式的程式碼，直接載入函式即可。如要讓其他指令碼使用函式或物件，請將其新增至名為 exports 的特殊物件。如要在其他指令碼中使用程式碼，請使用 require 函式載入其他指令碼的匯出內容。舉例來說，假設您在名為 FooModule.js 的檔案中定義下列模組，該檔案位於名為 Modules 的資料夾中：

程式碼編輯器 (JavaScript)

/**
 * The Foo module is a demonstration of script modules.
 * It contains a foo function that returns a greeting string.
 * It also contains a bar object representing the current date.
 * @module Modules/FooModule
 */

/**
 * Returns a greeting string.
 * @param {ee.String} arg The name to which the greeting should be addressed
 * @return {ee.String} The complete greeting.
 */
exports.foo = function(arg) {
  return 'Hello, ' + arg + '!  And a good day to you!';
};

/**
 * An ee.Date object containing the time at which the object was created.
 */
exports.bar = ee.Date(Date.now());

請注意，exports 關鍵字是以 exports.objectToExport 的形式使用。 您可以使用 require 函式，在其他指令碼中使用這個模組。例如：

程式碼編輯器 (JavaScript)

var Foo = require('users/username/default:Modules/FooModule.js');

print(Foo.doc);

print(Foo.foo('world'));

print('Time now:', Foo.bar);

require 函式預期會收到字串，說明模組位置的絕對路徑。具體來說，require() 的引數採用 'pathToRepository:pathToModuleScript' 形式。您只能從自己擁有和/或具有讀取權限的存放區載入模組。如要讓其他人使用您的模組，必須與要授予存取權的其他使用者共用存放區。您可能想記錄模組，協助他人瞭解如何使用；我們建議使用 JSDoc 樣式搭配 @module 標記。

您可以使用網址參數 ?scriptPath={repo}:{script} 分享存放區中檔案的參照，例如 https://code.earthengine.google.com/?scriptPath=users/username/utils:utils。造訪網址後，參照的檔案及其存放區會新增至「指令碼」分頁的「讀取者」或「寫入者」目錄，視您對共用存放區的權限層級而定。

資產管理工具 (「資產」分頁)

素材資源管理工具位於左側面板的「素材資源」分頁中。使用資產管理工具 (圖 3) 在 Earth Engine 中上傳及管理自己的圖片資產。詳情請參閱資產管理工具頁面。

資產管理員

圖 3. 資產管理工具。

您可以透過編碼網址分享程式碼編輯器指令碼。以下各節說明產生指令碼網址的各種方式、可用選項，以及管理指令碼網址的方法。

程式碼編輯器頂端的「取得連結」按鈕 (圖 4) 提供介面，可生成指令碼網址及設定指令碼行為選項。請注意以下快照和已儲存指令碼網址之間的差異。

歡迎參閱

圖 4. 「取得連結」按鈕。

如要分享編輯器中的程式碼，請點選程式碼編輯器頂端的「取得連結」按鈕，系統就會建立編碼的快照網址。如果有人使用 Earth Engine 帳戶造訪該網址，瀏覽器會前往程式碼編輯器，並複製建立連結時的環境，包括程式碼、匯入項目、地圖圖層和地圖位置。按一下「取得連結」按鈕後，系統會自動將指令碼連結複製到剪貼簿。此外，系統會顯示對話方塊，提供控制共用指令碼執行的選項，以及複製和造訪產生連結的按鈕。控制選項包括禁止指令碼自動執行，以及在使用者開啟共用連結時隱藏程式碼窗格。可拖曳的對話方塊可透過「Esc」鍵或點按頁面其他位置關閉。

儲存的指令碼可選擇分享連結，連結一律會載入最新儲存版本，且只有您和其他目前有權存取指令碼存放區的使用者可以存取。如要使用這項功能，請從「指令碼管理工具」分頁載入已儲存的指令碼，然後按一下「取得連結」按鈕右側的下拉式箭頭，並選取「複製指令碼路徑」。系統會顯示對話方塊，內含可共用的指令碼網址。請注意，指令碼網址也已在瀏覽器的網址列中設定。如要瞭解如何與他人共用存放區，請參閱「指令碼管理工具」一節。

「取得連結」按鈕右側的下拉式按鈕提供「管理連結」選項。按一下這個選項後，系統會載入新的瀏覽器分頁，並顯示介面，方便您回想、移除及下載先前產生的指令碼連結。選取指令碼並按下下載按鈕後，系統會將壓縮資料夾 (「code_editor_links.zip」) 下載到您的系統，其中包含每個所選指令碼的 .txt 檔案表示法。

ui.url 模組可透過 get 和 set 方法，以程式輔助方式操控指令碼網址的片段 ID。也就是說，程式碼編輯器指令碼和 Earth Engine 應用程式可以讀取網頁網址中的值並儲存。請注意下列兩個網址的結尾，第一個網址將 debug 變數設為 false，第二個則設為 true；請造訪這兩個連結，並注意第一個連結中，控制台的偵錯核取方塊未勾選，第二個連結則已勾選，這會改變每個指令碼的行為。

https://code.earthengine.google.com/5695887aad76979388a723a85339fbf2#debug=false;

https://code.earthengine.google.com/5695887aad76979388a723a85339fbf2#debug=true;

這項功能可用於設定地圖縮放和中心點，以及其他您可能想在傳送連結給特定使用者或群組時自訂的行為。

搜尋工具

如要尋找可在指令碼中使用的資料集，請使用資料封存檔的搜尋工具。搜尋工具是程式碼編輯器頂端的文字方塊，顯示「搜尋地點和資料集...」在搜尋列中輸入資料產品、感應器或其他關鍵字的名稱，然後按一下 按鈕，即可查看相符地點、點陣和表格資料集的清單。按一下任何點陣或表格結果，即可查看封存資料集中該資料集的說明。如要將資料集直接匯入指令碼，請按一下「import」連結或資料集說明中的 按鈕。

匯入

將資料集匯入指令碼後，系統會將結果整理在指令碼頂端的匯入區段中，匯入內容前會隱藏該區段。建立一些匯入作業後，畫面應該會與圖 5 類似。如要將匯入項目複製到其他指令碼，或將匯入項目轉換為 JavaScript，請按一下「匯入」標題旁的 圖示，然後將產生的程式碼複製到指令碼中。你可以使用 圖示刪除匯入內容。

程式碼編輯器的匯入部分

圖 5. 程式碼編輯器頂端的匯入部分。

地圖

API 中的地圖物件是指程式碼編輯器中顯示的地圖。舉例來說，Map.getBounds() 會傳回程式碼編輯器中顯示的地理區域。如要查看這項顯示的其他自訂項目，請檢查 API 中的 Map 函式。

圖層管理工具

使用地圖右上角的圖層管理工具，調整地圖上新增圖層的顯示方式。具體來說，您可以切換圖層的顯示狀態，或使用滑桿調整透明度。按一下 圖示，即可調整個別圖層的視覺化參數。顯示的視覺化工具 (圖 6) 可讓您以互動方式設定圖層顯示參數。按一下工具右側的按鈕 (預設會對提供的最小值和最大值範圍執行「自訂」延展)，即可將顯示畫面線性延展至顯示視窗中影像值的百分位數或標準差。系統會根據目前縮放等級的地圖視窗中所有像素計算統計資料。使用滑桿調整 Gamma 和/或透明度。按一下「調色盤」單選按鈕，然後新增顏色 ()、移除顏色 () 或手動輸入以半形逗號分隔的十六進位字串清單 ()，指定自訂調色盤。按一下「套用」，將視覺化參數套用至目前顯示畫面。按一下「匯入」，將視覺化參數物件載入為指令碼匯入區段中的新變數。

圖層視覺化工具。

圖 6. 圖層視覺化工具。

「檢查工具」分頁

工作管理員旁邊的「檢查工具」分頁可供您以互動方式查詢地圖。啟用「檢查器」分頁後，游標會變成十字線，點選地圖時，游標下方會顯示位置和圖層值。舉例來說，圖 7 顯示在「檢查器」分頁中點選地圖的結果。游標位置和縮放等級會連同像素值和地圖上的物件清單一起顯示。物件清單是互動式清單。如要查看更多資訊，請展開「檢查器」分頁中的物件。

「檢查工具」分頁

圖 7. 「檢查器」分頁會顯示游標位置的相關資訊，以及游標下方的圖層值。

控制台分頁

print()指令碼中的文字、物件或圖表等項目時，結果會顯示在控制台中。控制台具有互動功能，因此你可以展開列印物件，進一步瞭解相關詳細資料。

「工作」分頁

Earth Engine 工作是作業，執行時間遠長於標準 API 要求逾時時間。這些長時間執行的工作是唯一能在 Earth Engine 和鄰近系統 (Google Cloud Storage、Google 雲端硬碟等) 中建立永久構件的機制，可分為 Import 和 Export 兩類。

匯入工作可用於上傳圖片或上傳表格，將各種檔案類型 (.csv、.tif 等) 的資料匯入 Earth Engine。匯出工作可用於執行 EE 計算系統的結果並寫入結果 (請參閱資料匯出指南)。

如果是匯出作業，每次在程式碼編輯器中呼叫 Export 函式，都會在「工作」分頁的「未提交的工作」部分填入項目。如要將匯出工作提交至伺服器，請按一下工作旁邊的「執行」按鈕。系統會顯示設定對話方塊，讓您為工作指定各種參數。如果在建立工作時已完整指定工作 (也就是說，對 Export 的呼叫包含所有必要參數)，請按住 ctrl 或 ⌘，然後按一下「執行」，即可提交工作，不必顯示對話方塊。

如果是匯入作業，檔案會先在本機上傳，再將工作提交至伺服器。上傳階段的匯入工作會在「未提交的工作」部分顯示進度，並在檔案上傳完成後自動提交至伺服器。

未提交的工作只會顯示在建立該工作的頁面上，關閉頁面後就會遺失。將工作提交至伺服器後，按一下 UI 中的工作列，即可取得工作狀態的其他資訊和選項，包括要求取消的選項。

如要在全頁檢視畫面中查看及取消多項工作 (包括行動用戶端)，請使用 Cloud Console 中的「工作」頁面。

Profiler

分析器會顯示特定演算法和其他運算部分所耗用的資源 (CPU 時間、記憶體) 相關資訊。這有助於診斷指令碼執行緩慢或因記憶體限制而失敗的原因。如要使用分析器，請點按「執行」按鈕下拉式選單中的「使用分析器執行」選項。如要使用快速鍵，請按住 Alt 鍵 (Mac 上的 Option 鍵)，然後按一下「執行」，或按下 Ctrl+Alt+Enter 鍵。程式碼編輯器右側會啟用「分析器」分頁。指令碼執行時，「剖析器」分頁會顯示指令碼的資源用量表。按一下「執行」按鈕 (不進行分析)，「分析器」分頁就會消失，分析器也會停用。

如要瞭解剖析器輸出的詳細資訊，請參閱運算總覽頁面。

AI 助理 (「問問」分頁)

程式碼編輯器內建以 Gemini 為基礎的 AI 助理，可協助您編寫、偵錯及瞭解指令碼。助理位於右側面板的「Ask」分頁中。

如要瞭解如何設定及使用這項助理，請參閱「Earth Engine 程式碼編輯器中的 AI 助理」指南。

幾何工具

您也可以在畫面上繪製幾何圖形，然後匯入腳本。如要建立幾何圖形，請使用地圖顯示畫面左上角的幾何圖形繪製工具 (圖 8)。如要繪製點，請使用地標圖示 ；如要繪製線條，請使用線條圖示 ；如要繪製多邊形，請使用多邊形圖示 ；如要繪製矩形，請使用矩形圖示 。(請注意，矩形是平面幾何圖形，因此無法放置在具有測地線幾何圖形 (例如線和多邊形) 的圖層上)。

使用任何繪圖工具時，系統會自動建立新的幾何圖層，並將該圖層的匯入項目新增至「匯入」部分。如要將幾何圖形新增至新圖層，請將滑鼠懸停在地圖顯示畫面中的「Geometry Imports」(幾何圖形匯入) 上，然後按一下「+new layer」(+新圖層) 連結。您也可以在「幾何圖形匯入」專區切換幾何圖形的顯示設定。請注意，繪製的幾何圖形預設為測地線，但矩形除外，矩形僅為平面。使用 Geometry 建構函式將其轉換為平面幾何圖形。如要進一步瞭解 Earth Engine 中的幾何圖形，請參閱幾何圖形頁面。

圖 8. 幾何圖形繪製工具位於地圖顯示畫面左上角。

如要設定幾何圖形匯入指令碼的方式，請按一下地圖上「幾何圖形匯入」部分或程式碼編輯器「匯入」部分中圖層旁的 圖示。幾何圖層設定工具會顯示在對話方塊中，如圖 9 所示。請注意，您可以將繪製的形狀匯入為幾何圖形、特徵或特徵集合。您也可以透過幾何圖形匯入設定變更圖層的顯示顏色、為圖層新增屬性 (如果匯入為 Feature 或 FeatureCollection)，或重新命名圖層。

幾何設定工具

圖 9.幾何設定工具。

最後，如要防止編輯圖層中的幾何圖形，可以按下圖層旁邊的 圖示鎖定圖層。這樣一來，您就無法在圖層上新增、刪除或編輯任何幾何圖形。如要再次解鎖圖層，請按下 圖示。

該怎麼辦？

按一下程式碼編輯器右上方的 按鈕，即可查看本開發人員指南、其他說明論壇、程式碼編輯器導覽，以及有助於編碼、執行程式碼和在地圖上顯示資料的鍵盤快速鍵清單。按一下 按鈕，即可回報錯誤、要求新功能、建議資料集，或在不需要回覆時傳送其他意見回饋。