Recursos do Earth Engine com base em GeoTiff do Cloud

Logotipo do Colab Executar no Google Colab Logotipo do GitHub Ver origem no GitHub

O Earth Engine oferece suporte a recursos com tecnologia Cloud Optimized GeoTIFFs (COGs). Uma vantagem dos recursos com tecnologia COG é que os campos espaciais e de metadados da imagem são indexados no momento da criação do recurso, tornando a imagem mais eficiente nas coleções. O desempenho dos recursos com tecnologia COG é comparável ao dos recursos ingeridos em casos de uso típicos.

Um único recurso pode ser apoiado por vários COGs (por exemplo, pode haver um COG por banda). No entanto, não é possível usar muitos blocos de COG para uma única banda.

Como alternativa, o Earth Engine pode carregar imagens diretamente de COGs no Google Cloud Storage (saiba mais). No entanto, uma imagem carregada por ee.Image.loadGeoTIFF e adicionada a uma coleção de imagens exigirá uma leitura do GeoTiff para operações de filtragem na coleção.

Para criar um recurso com tecnologia COG,

  1. Coloque os arquivos COG em um bucket do GCS (consulte Local para as regiões permitidas).
  2. Escreva um manifesto de upload de imagem
  3. Use o utilitário de linha de comando earthengine para enviar um comando de upload:
earthengine upload external_image --manifest my_manifest.json

Manifesto de imagem de amostra com um Tileset

O ImageManifest mais simples é aquele com um único Tileset. Se nenhuma banda for especificada, o recurso resultante vai conter todas as bandas do GeoTIFF com os nomes de banda codificados no GeoTIFF (nesse caso, "vis-red", "vis-green" e "vis-blue").

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo1',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': [
        'gs://ee-docs-demos/COG_demo.tif'] } ] }
    ],
    'properties': {
      'version': '1.1'
    },
    'startTime': '2016-01-01T00:00:00.000000000Z',
    'endTime': '2016-12-31T15:01:23.000000000Z',
  },
}

pprint(request)

Mais de um Tileset

É possível especificar um ImageManifest com mais de um Tileset, em que cada banda do recurso resultante é apoiada por uma das bandas de um Tileset usando os campos tilesetId e tilesetBandIndex. Isso é útil quando bandas diferentes têm resoluções ou tipos de dados diferentes. As bandas podem ser listadas em qualquer ordem de qualquer Tileset disponível. No exemplo a seguir:

  • "b4b3b2.tif" tem uma escala de 10 m, enquanto "b5b6b7" tem uma escala de 20 m.
  • A ordem das bandas do recurso resultante é mista dos COGs de entrada (por exemplo, a banda de saída 0 é do Tileset 0, enquanto a banda de saída 1 é do Tileset 1).
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo2',
    'uriPrefix': 'gs://ee-docs-demos/external_image_demo/',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['b4b3b2.tif'] } ] },
      { 'id': '1', 'sources': [ { 'uris': ['b5b6b7.tif'] } ] },
    ],
    'bands': [
      { 'id': 'red', 'tilesetId': '0', 'tilesetBandIndex': 0 },
      { 'id': 'rededge3', 'tilesetId': '1', 'tilesetBandIndex': 2 },
      { 'id': 'rededge2', 'tilesetId': '1', 'tilesetBandIndex': 1 },
      { 'id': 'green', 'tilesetId': '0', 'tilesetBandIndex': 1 },
      { 'id': 'blue', 'tilesetId': '1', 'tilesetBandIndex': 0 },
      { 'id': 'rededge1', 'tilesetId': '0', 'tilesetBandIndex': 2 },
    ],
  },
}

pprint(request)

Detalhes sobre recursos com tecnologia COG

Local

O local do bucket do Cloud Storage precisa ser um destes:

  • A multirregião dos EUA
  • Qualquer região birregional dos EUA que inclua US-CENTRAL1
  • A região US-CENTRAL1

Classe de armazenamento

A classe de armazenamento do bucket precisa ser "Standard Storage".

Permissões de compartilhamento

As ACLs dos recursos do Earth Engine com tecnologia COG e os dados subjacentes são gerenciados separadamente. Ao compartilhar recursos com tecnologia COG com colaboradores para leitura, é responsabilidade do proprietário garantir que o acesso de leitura seja concedido ao recurso do Earth Engine e aos arquivos COG subjacentes.

1. Conceder permissões de leitura do bucket do Google Cloud Storage

Para que os colaboradores leiam recursos com tecnologia COG, eles precisam ter acesso de leitura aos arquivos COG subjacentes no bucket do Google Cloud Storage. Sem essas permissões, o Earth Engine não poderá recuperar os dados para eles. Se os dados no Google Cloud Storage não estiverem visíveis para um usuário do Earth Engine, o Earth Engine vai retornar um erro do formulário "Falha ao carregar o GeoTIFF em gs://my-bucket/my-object#123456" (em que 123456 é a geração do objeto).

Especificamente, os colaboradores precisam ter as seguintes permissões:

  • storage.buckets.get no bucket (para recuperar metadados e local do bucket, permitindo que o Earth Engine resolva corretamente a origem do recurso).
  • storage.objects.get no bucket (para ler os dados reais do recurso com tecnologia COG).

Essas permissões são fornecidas pelas funções "Leitor de bucket legada do Storage" e "Leitor de objeto legada do Storage" respectivamente, entre outras.

Para atribuir essas funções aos colaboradores:

  1. Acesse a página de permissão do bucket: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Clique em "CONCEDER ACESSO"
  3. Adicione todos os principais (por exemplo, usuários, grupos, contas de serviço) que devem receber acesso de leitura.
  4. Atribua as seguintes funções:
    • "Leitor de bucket legada do Storage" (fornece storage.buckets.get e outras permissões de leitura no nível do bucket).
    • "Leitor de objeto legada do Storage" (fornece storage.objects.get).
    • Como alternativa, você pode criar uma nova função personalizada com apenas as permissões storage.buckets.get e storage.objects.get e atribuir essa função.
  5. Salvar

2. Compartilhar o recurso do Earth Engine para leitura

Depois de garantir que seus colaboradores tenham as permissões necessárias no bucket e nos objetos do GCS, você também precisará compartilhar o recurso do Earth Engine. Para mais informações sobre como definir permissões de recursos do Earth Engine, consulte o guia de gerenciamento de recursos do Earth Engine.

Gerações

Quando um recurso com tecnologia COG é criado, o Earth Engine lê os metadados dos TIFFs especificados no manifesto e cria uma entrada de repositório de recursos. Cada URI associado a essa entrada pode ter uma geração. Consulte os documentos de controle de versão de objetos para mais detalhes sobre gerações. Se uma geração for especificada, por exemplo, gs://foo/bar#123, o Earth Engine vai armazenar esse URI literalmente. Se uma geração não for especificada, o Earth Engine vai armazenar esse URI com a geração do TIFF no momento em que ImportExternalImage foi chamado.

Isso significa que, se qualquer TIFF que compreenda um recurso externo no GCS for atualizado (mudando a geração), o Earth Engine vai retornar um erro "Falha ao carregar o GeoTIFF em gs://my-bucket/my-object#123456" porque o objeto esperado não existe mais (a menos que o bucket permita várias versões de objetos). Essa política foi projetada para manter os metadados do recurso sincronizados com os metadados do objeto.

Configuração

Em termos de como um COG deve ser configurado, o TIFF PRECISA ser:

  • Em blocos, em que as dimensões do bloco são:

    • 256x256
    • 512x512
    • 1024x1024
    • 2.048 x 2.048

  • Organizado para que todos os IFDs estejam no início.

Para melhor desempenho:

  • Use dimensões de bloco de 512 x 512 ou maiores.
  • Inclua visões gerais de potência de 2.

Dependendo dos casos de uso pretendidos, a "INTERLEAVE" opção de criação pode afetar o desempenho. Recomendamos o uso de intercalação de banda em todas as circunstâncias.

Consulte esta página para mais detalhes sobre uma configuração otimizada.

O comando gdal_translate a seguir vai converter um raster em um GeoTIFF otimizado para nuvem, intercalado por banda e compactado por zstd, que terá um bom desempenho no Earth Engine:

gdal_translate in.tif out.tif \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=22 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS

É possível reduzir ainda mais o tamanho do arquivo de saída especificando um preditor (-co PREDICTOR=2 para tipos de dados inteiros e -co PREDICTOR=3 para tipos de dados de ponto flutuante).

Para usuários com GDAL >= 3.11, o driver COG pode produzir arquivos sem precisar se preocupar em criar e preservar visões gerais.

gdal_translate in.tif out.tif \
  -of COG \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=22 \
  -co PREDICTOR=2 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \

Como criar recursos com tecnologia Cloud GeoTiff usando a API REST

Observação:a API REST contém recursos novos e avançados que podem não ser adequados para todos os usuários. Se você é iniciante no Earth Engine, recomendamos começar com o guia do JavaScript.

Para criar um recurso com tecnologia COG usando a API REST, faça uma solicitação POST para o endpoint ImportExternalImage do Earth Engine. Como mostrado abaixo, essa solicitação precisa ser autorizada para criar um recurso na pasta do usuário.

Iniciar uma sessão autorizada

Para criar um recurso do Earth Engine na pasta do usuário, você precisa se autenticar ao fazer a solicitação. É possível usar credenciais do autenticador do Earth Engine para iniciar uma AuthorizedSession. Em seguida, use a AuthorizedSession para enviar solicitações ao Earth Engine.

import ee
import json
from pprint import pprint
from google.auth.transport.requests import AuthorizedSession

ee.Authenticate()  #  or !earthengine authenticate --auth_mode=gcloud

# Specify the cloud project you want associated with Earth Engine requests.
ee_project = 'your-project'

session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

Corpo da solicitação

O corpo da solicitação é uma instância de um ImageManifest. É aqui que o caminho para o COG é especificado, juntamente com outras propriedades úteis.

Consulte este guia para detalhes sobre como configurar um ImageManifest. É possível definir um ou mais Tileset, com cada um deles apoiando uma ou mais bandas. Para ImportExternalImage, no máximo um ImageSource é compatível por Tileset.

Consulte este documento para detalhes sobre como exportar COGs.

Enviar a solicitação

Faça a solicitação POST para o endpoint projects.images.importExternal do Earth Engine.

url = f'https://earthengine.googleapis.com/v1alpha/projects/{ee_project}/image:importExternal'

response = session.post(
  url = url,
  data = json.dumps(request)
)

pprint(json.loads(response.content))