圖片資訊清單上傳

如果您需要更靈活的方式將圖片上傳至 Google Earth Engine (EE)，而非使用 程式碼編輯器 UI 或 「earthengine」指令列工具的 upload 指令，可以使用稱為「資訊清單」的 JSON 檔案描述圖片上傳作業，並使用指令列工具的 upload image --manifest 指令。

如需完整範例，請參閱這個 Colab 筆記本，其中示範如何使用資訊清單將圖塊圖片上傳為單一素材資源。

一次性設定

1. 資訊清單上傳功能僅適用於位於 Google Cloud Storage 中的檔案。如要開始使用 Google Cloud Storage，請建立 Google Cloud 專案 (如果您還沒有專案)。請注意，設定時必須指定用於結帳的信用卡。EE 目前不會向任何人收費，但將檔案轉移至 Google Cloud Storage 後再上傳至 EE 會產生少許費用。對於一般上傳資料大小 (數十或數百 GB)，費用會相當低。
2. 在專案中啟用 Cloud Storage API，並建立值區。
3. 安裝 Earth Engine Python 用戶端。其中包含 earthengine 指令列工具，我們會用來上傳資料。
4. 如要自動上傳，建議您使用與專案相關聯的 Google Cloud 服務帳戶。您不需要服務帳戶進行測試，但請在有空時開始熟悉如何使用服務帳戶。

如果將超大型來源檔案 (100 GB 以上) 拆分為多個區塊，上傳速度可能會變快。

資產 ID 和名稱

如果是 Cloud 專案擁有的資產，請使用以下命名慣例：projects/some-project-id/assets/some-asset-id。

瞭解舊專案和使用者擁有的資產的資產名稱

對於較舊的舊版專案，資訊清單中的資產名稱必須與 Earth Engine 其他位置顯示的資產 ID 略有不同。如要上傳資產 ID 開頭為 users/some_user 或 projects/some_project 的資產，資訊清單中的資產名稱必須在 ID 前方加上字串 projects/earthengine-legacy/assets/。舉例來說，EE 資產 ID users/username/my_geotiff 應使用名稱 projects/earthengine-legacy/assets/users/username/my_geotiff 上傳。

是的，這表示 projects/some_projects/some_asset 這類 ID 會轉換為名稱，其中 projects 會提及兩次：projects/earthengine-legacy/assets/projects/some_projects/some_asset。這會造成混淆，但為了符合 Google Cloud API 標準，這項操作是必要的。

使用資訊清單

下列程式碼區塊顯示基本資訊清單。它會從名為 gs://earthengine-test 的 Google Cloud Storage 值區上傳名為 small.tif 的檔案。

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://earthengine-test/small.tif"
          ]
        }
      ]
    }
  ]
}

如要使用它，請將它儲存為名為 manifest.json 的檔案，然後執行以下指令：

earthengine upload image --manifest /path/to/manifest.json

(檔案 gs://earthengine-test/small.tif 已存在且可公開讀取，可用於測試)。

圖塊集

為了提供足夠的彈性，解決常見的上傳問題，JSON 的資訊清單結構必須稍微複雜一些：如何描述所有可能的方式，將來自多個來源檔案的像素組合成單一資產。具體來說，您可以透過兩種獨立方式將檔案分組：

• 馬賽克。有時多個檔案代表多個圖塊 (例如，每個圖塊都是 1x1 度的正方形)。此類檔案必須拼接 (合併)至 EE 資產中的同一個頻帶。
• 分開錶帶。有時，多個檔案代表多個頻帶。此類檔案必須以 EE 素材資源中的頻帶形式堆疊在一起。

(兩種方法可能必須同時使用，但這種情況很少見)。

為了說明這些選項，資訊清單會引入「圖塊集」的概念。單一圖塊集會對應至單一 GDAL 來源。因此，單一圖塊集中的所有來源都必須具有相同的 GDAL 結構 (頻帶數量和類型、投影、轉換、缺少值)。由於 GDAL 來源可能有多個頻帶，因此一個圖塊集可能包含多個 EE 頻帶的資料。

對於馬賽克攝入，資訊清單會如下所示：

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/N30W22.tif"
          ]
        },
        {
          "uris": [
            "gs://bucket/N31W22.tif"
          ]
        }
      ]
    }
  ]
}

對於個別頻帶，資訊清單會如下所示 (您也需要新增 bands 區段，如以下所述)：

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "bands": ...,
  "tilesets": [
    {
      "id": "tileset_for_band1",
      "sources": [
        {
          "uris": [
            "gs://bucket/band1.tif"
          ]
        }
      ]
    },
    {
      "id": "tileset_for_band2",
      "sources": [
        {
          "uris": [
            "gs://bucket/band2.tif"
          ]
        }
      ]
    }
  ]
}

請注意，在個別頻帶的情況下，我們必須為每個圖塊集提供不同的圖塊集 ID，以便清楚區分。圖塊集 ID 可以是任意字串，這些字串不會保留在上傳的素材資源中。圖塊集 ID 僅用於擷取作業，用於區分堆疊的圖塊集。

錶帶

第二個重要的概念，是將來源檔案與 EE 素材資源頻帶配對。這項操作會使用資訊清單的 bands 部分。

您可以省略 bands 部分，在這種情況下，系統會先從第一個圖塊集的檔案建立區塊，然後再從下一個圖塊集建立，依此類推。根據預設，頻帶會命名為「b1」、「b2」等。如要覆寫預設頻帶名稱，請在結尾加入「bands」區段，如下所示：

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/rgb.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "R",
      "tilesetBandIndex": 0
    },
    {
      "id": "G",
      "tilesetBandIndex": 1
    },
    {
      "id": "B",
      "tilesetBandIndex": 2
    }
  ]
}

EE 頻帶數量必須與所有圖塊集的頻帶總數相同。

如果您不想從檔案擷取所有頻帶，可以使用 tilesetBandIndex 欄位來指出應擷取哪些 GDAL 頻帶。第一個帶的圖塊集 BandIndex 為 0。

範例：

假設來源檔案有四個頻帶：「tmin」、「tmin_error」、「tmax」、「tmax_error」。我們只想擷取「tmin」和「tmax」。相關的資訊清單部分如下所示：

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "temperature",
      "sources": [
        {
          "uris": [
            "gs://bucket/temperature.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "tmin",
      "tilesetBandIndex": 0,
      "tilesetId": "temperature"
    },
    {
      "id": "tmax",
      "tilesetBandIndex": 2,
      "tilesetId": "temperature"
    }
  ]
}

遮罩頻帶

頻帶遮罩是由資訊清單的 maskBands 元件控制。系統支援三種可能的遮罩設定 (但遮罩頻帶一律視為特定檔案中的最後一個頻帶)。

1. 為所有資料帶設定相同檔案的遮罩。
2. 為來自所有其他檔案的所有資料帶遮罩。
3. 遮蓋部分資料頻帶。

1. 最常見的情況是單一 GeoTIFF，其最後一個頻帶用於其他頻帶的遮罩。這項功能僅適用於 Byte 類型的 GeoTIFF。請使用下列資訊清單：

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "data_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/data_file.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "data_band",
      "tilesetId": "data_tileset"
    },
    {
      "id": "qa_band",
      "tilesetId": "data_tileset"
    }
  ],
  "maskBands": [
    {
      "tilesetId": "data_tileset"
    }
  ]
}

2. 如要將遮罩 GeoTIFF 用作另一個 GeoTIFF 中所有頻帶的遮罩，請使用下列資訊清單：

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "data_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/data_file.tif"
          ]
        }
      ]
    },
    {
      "id": "mask_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/mask_file.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "data_band",
      "tilesetId": "data_tileset"
    },
    {
      "id": "qa_band",
      "tilesetId": "data_tileset"
    }
  ],
  "maskBands": [
    {
      "tilesetId": "mask_tileset"
    }
  ]
}

3. 如要將 GeoTIFF 用於其他檔案中特定頻帶的遮罩，請使用下列資訊清單 (與先前情況的差異在於 maskBands 中的 bandIds 欄位已設好)：

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "id": "data_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/data_file.tif"
          ]
        }
      ]
    },
    {
      "id": "mask_tileset",
      "sources": [
        {
          "uris": [
            "gs://bucket/mask_file.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "data_band",
      "tilesetId": "data_tileset"
    },
    {
      "id": "qa_band",
      "tilesetId": "data_tileset"
    }
  ],
  "maskBands": [
    {
      "tilesetId": "mask_tileset",
      "bandIds": ["data_band"]
    }
  ]
}

在上一範例中，我們使用 data_tileset 圖塊集的兩個頻帶，但只將遮罩套用至其中一個頻帶 (data_band)，如同唯一提供的 maskBands 清單物件的 bandIds 欄位所指定。

請注意，只有 maskBands 中提到的圖塊集最後一區會用做遮罩區。

金字塔式推銷政策

當 Earth Engine 在擷取期間建構圖像金字塔時，必須不斷將 2x2 像素格狀圖縮減為單一像素，並以某種方式轉換像素值。根據預設，系統會計算平均像素值，在大多數情況下，當影像帶代表大致連續的資料時，這麼做是正確的做法。不過，有兩種情況會導致依賴預設值產生不正確的結果，在這種情況下，您必須設定頻帶定義中的 pyramidingPolicy 欄位 (如果未設定，系統會預設為「MEAN」)。

若要分類光柵圖像 (例如土地覆蓋率分類)，最合理的像素金字塔方法是採用四個值中的大多數來產生下一個值。這項操作會使用「MODE」層疊政策：

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/landcover.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "landcover",
      "pyramidingPolicy": "MODE"
    }
  ]
}

如果「平均值」和「模式」都不適用於影像格式帶 (例如位元封裝的像素)，則應使用「取樣」金字塔處理政策。「SAMPLE」一律會採用每個 2x2 格線左上方像素的值。以下範例會將「MEAN」金字塔化政策指派給代表連續變數 (「NDVI」) 的頻帶，並將「SAMPLE」指派給資料的「QA」頻帶。

{
  "name": "projects/earthengine-legacy/assets/users/username/some_folder/some_id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/ndvi.tif"
          ]
        }
      ]
    }
  ],
  "bands": [
    {
      "id": "NDVI",
      "tilesetBandIndex": 0,
      "pyramidingPolicy": "MEAN"
    },
    {
      "id": "QA",
      "tilesetBandIndex": 1,
      "pyramidingPolicy": "SAMPLE"
    }
  ]
}

開始與結束時間

所有素材資源都應指定開始和結束時間，以便提供更多資料背景資訊，尤其是如果這些素材資源已納入集合。這些欄位並非必要欄位，但我們強烈建議您盡可能使用這些欄位。

開始和結束時間通常是指觀察時間，而非產生來源檔案的時間。

為了簡化操作，系統會將結束時間視為不包含在內的邊界。舉例來說，如果素材資源的放送時間正好是一天，請將開始和結束時間設為兩個相連日子的午夜 (例如 1980-01-31T00:00:00 和 1980-02-01T00:00:00)。如果素材資源沒有持續時間，請將結束時間設為與開始時間相同。在資訊清單中以 ISO 8601 字串表示時間。建議您假設結束時間不包含在內 (例如每日素材資源的隔天午夜)，以簡化日期值。

範例：

{
  "name": "projects/some-project-id/assets/some-asset-id",
  "tilesets": [
    {
      "sources": [
        {
          "uris": [
            "gs://bucket/img_20190612.tif"
          ]
        }
      ]
    }
  ],
  "startTime": "1980-01-31T00:00:00Z",
  "endTime": "1980-02-01T00:00:00Z"
}

資訊清單結構參考資料

下列 JSON 結構包含所有可能的圖片上傳資訊清單欄位。如要查看欄位定義，請參閱下方的「 資訊清單欄位定義」一節。

{
  "name": <string>,
  "tilesets": [
    {
      "dataType": <string>,
      "id": <string>,
      "crs": <string>,
      "sources": [
        {
          "uris": [
            <string>
          ],
          "affineTransform": {
            "scaleX": <double>,
            "shearX": <double>,
            "translateX": <double>,
            "shearY": <double>,
            "scaleY": <double>,
            "translateY": <double>
          }
        }
      ]
    }
  ],
  "bands": [
    {
      "id": <string>,
      "tilesetId": <string>,
      "tilesetBandIndex": <int32>,
      "missingData": {
        "values": [<double>]
      },
      "pyramindingPolicy": <string>
    }
  ],
  "maskBands": [
    {
      "tilesetId": <string>,
      "bandIds": [
        <string>
      ]
    }
  ],
  "footprint": {
    "points": [
      {
        "x": <double>,
        "y": <double>
      }
    ],
    "bandId": <string>
  },
  "missingData": {
     "values": [<double>]
  },
  "pyramidingPolicy": <string>,
  "uriPrefix": <string>,
  "startTime": {
    "seconds": <integer>
  },
  "endTime": {
    "seconds": <integer>
  },
  "properties": {
    <unspecified>
  }
}

資訊清單欄位定義

名稱

string

要建立的素材資源名稱。name 的格式為「projects/*/assets/**」(例如「projects/earthengine-legacy/assets/users/USER/ASSET」)。

圖塊集

list

定義圖塊集屬性的字典清單。詳情請參閱下列 tilesets 字典元素欄位。

tilesets[i].dataType

string

指定資料的數值資料類型。預設值是 GDAL 回報的類型，在這種情況下，您不需要定義。

資料類型	值
未指定	「DATA_TYPE_UNSPECIFIED」
8 位元帶正負號整數	「INT8」
8 位元無符號整數	「UINT8」
16 位元帶正負號整數	「INT16」
16 位元無符號整數	「UINT16」
32 位元帶正負號整數	「INT32」
32 位元不帶正負號整數	「UINT32」
32 位元浮點	「FLOAT32」
64 位元浮點	「FLOAT64」

tilesets[i].id

string

圖塊集的 ID。在資產資訊清單中指定的圖塊集之間不得重複。這個 ID 會在處理步驟中捨棄，只用於將圖塊集連結至頻帶。空字串是有效的 ID。

tilesets[i].crs

string

像素格線的座標參考系統，請盡可能指定為標準代碼 (例如 EPSG 代碼)，否則請使用 WKT 格式。

tilesets[i].sources

list

字典清單，定義圖片檔案及其附檔的屬性。詳情請參閱下列 sources 字典元素欄位。

tilesets[i].sources[j].uris

list

要攝入的資料 URI 清單。僅支援 Google Cloud Storage URI。每個 URI 都必須採用以下格式：gs://bucket-id/object-id。主要物件應為清單的第一個元素，而附屬物件則列在後面。如果已設定，每個 URI 前面都會加上 ImageManifest.uriPrefix。

tilesets[i].sources[j].affineTransform

dictionary

選用的仿射變換。只有在 uris (包括任何附屬檔案) 的資料不足以放置像素時，才需要指定。以字典的形式提供，其中包含下列索引鍵：「scaleX」、「shearX」、「translateX」、「shearY」、「scaleY」、「translateY」。詳情請參閱 這份參考資料。

鍵和值的範例：

{
  "scaleX": 0.1,
  "shearX": 0.0,
  "translateX": -180.0,
  "shearY": 0.0,
  "scaleY": -0.1,
  "translateY": 90.0
}

頻帶

list

字典清單，定義來自圖塊集的單一頻帶的屬性。請注意，資源素材的頻帶順序與 bands 的順序相同。詳情請參閱下列 bands 字典元素欄位。

bands[i].id

string

頻帶的 ID (名稱)。

bands[i].tilesetId

string

與頻帶相對應的圖塊集 ID。

bands[i].tilesetBandIndex

int32

與該區塊相對應的圖塊集，從零開始的區塊索引。

bands[i].missingData.values

list

代表該頻帶中沒有資料的值清單 (double 型別)。

bands[i].pyramidingPolicy

string

金字塔式推銷政策。詳情請參閱 這個連結。選項包括：

• 「MEAN」(預設)
• 「MODE」
• 「SAMPLE」

maskBands

list

字典清單，定義來自圖塊集的單一遮罩帶的屬性。最多可提供 1 個遮罩頻帶。詳情請參閱下列 maskBands 字典元素欄位。

maskBands[i].tilesetId

string

與遮罩區塊相對應的圖塊集 ID。圖塊集的最後一個帶一律會用做遮罩帶。

maskBands[i].bandIds

list of strings

遮罩頻帶套用的頻帶 ID 清單。如果留空，系統會將遮罩頻帶套用至素材資源中的所有頻帶。每個頻帶只能有一個對應的遮罩頻帶。

足跡

dictionary

字典，定義圖片中所有有效像素的足跡屬性。如果為空白，則預設足跡為整個圖片。詳情請參閱下列 footprint 字典元素欄位。

footprint.points

list

點清單，定義圖片中所有有效像素的足跡。點是由字典定義，其中「x」和「y」鍵的值為浮點值。點清單用於描述環狀區域，該區域會形成簡單多邊形的外部，且必須包含圖片所有有效像素的中心。這必須是線性環：最後一個點必須與第一個點相同。座標會以 bandId 指定的頻帶投影。

注意：請使用非整數座標 (例如每個像素的中心)，因為如果像素 (1x1 矩形) 與足跡相交，footprint 會視為包含該像素。為避免誤選相鄰像素，請勿使用整數值座標，因為這些是像素之間的邊界。沿著像素中心繪製足跡可避免納入非預期的像素，因為當所需像素與地圖邊界 (例如反經線或極點) 相鄰時，可能會導致錯誤。

舉例來說，如果是含有四個有效像素的 2x2 圖片，以下是其中一個可能的環形：

[
  {
    "x": 0.5,
    "y": 0.5
  },
  {
    "x": 0.5,
    "y": 1.5
  },
  {
    "x": 1.5,
    "y": 1.5
  },
  {
    "x": 1.5,
    "y": 0.5
  },
  {
    "x": 0.5,
    "y": 0.5
  }
]

footprint.bandId

string

頻帶 ID，其 CRS 定義了足跡的座標。如果留空，系統會使用第一個頻帶。

missingData.values

list

值清單 (雙精度型別)，代表影像所有頻帶中沒有資料。適用於所有未指定專屬 missingData 的頻帶。

pyramidingPolicy

string

金字塔式推銷政策。如未指定，系統會預設套用「MEAN」政策。套用至所有未指定專屬頻帶的頻帶。 詳情請參閱 這個連結。選項包括：

• 「MEAN」(預設)
• 「MODE」
• 「SAMPLE」

uriPrefix

string

在資訊清單中定義的所有 uris 前方加上選用前置字串。

startTime

integer

與資產相關聯的時間戳記 (如果有的話)。這通常會對應至拍攝衛星影像的時間。如果素材資源對應的時間間隔為一個月或一年的平均值，這個時間戳記就會對應到該時間間隔的開始時間。以 Epoch (1970-01-01) 起算的秒數和 (選用) 奈秒數表示。假設位於世界標準時間時區。

endTime

integer

如果資產對應的時間間隔為一個月或一年的平均值，則這個時間戳記會對應到該時間間隔的結束時間 (不含)。以 Epoch (1970-01-01) 起算的秒數和 (選用) 奈秒數表示。假設位於世界標準時間時區。

資源

dictionary

任意鍵/值組合的平面字典。鍵必須是字串，值可以是數字或字串。系統目前不支援使用者上傳的資產的清單值。

限制

JSON 資訊清單大小

JSON 資訊清單檔案大小上限為 10 MB。如果您要上傳的檔案很多，請考慮如何減少描述資料集所需的字元數量。舉例來說，您可以使用 uriPrefix 欄位，避免需要為 uris 清單中的每個 URI 提供 Google Cloud 值區路徑。如果需要進一步縮減大小，請嘗試縮短檔案名稱。

圖片檔案格式

每個圖片檔案都必須是 TIFF 圖片。如果資訊清單中未指定 CRS，則檔案必須是內嵌 CRS 的 GeoTIFF。

TIFF 檔案可使用 DEFLATE、JPEG-XL/JXL、LERC、LERC_DEFLATE、LERC_ZSTD、LZMA、LZW、WEBP 或 ZSTD 壓縮。

針對上傳大型檔案，我們提供以下最佳做法建議：

• 最佳選擇：ZSTD 可提供速度和壓縮率的良好平衡。
• 避免使用：雖然 LZMA 可提供良好的壓縮效果，但速度可能會非常慢。
• 未壓縮的檔案：檔案較大，上傳時間也較長。
• 有損壓縮 (例如 JPEG)：可能會變更像素值。使用無損壓縮功能 (例如 DEFLATE、LZMA、LZW、ZSTD)，除非您瞭解這些壓縮演算法對資料的潛在影響。