Como registrar recursos GeoTIFF otimizados para nuvem (COG)

O Earth Engine oferece suporte a recursos com o suporte de GeoTIFFs otimizados para nuvem (COGs, na sigla em inglês) armazenados no Google Cloud Storage (GCS).

Ao registrar um recurso com o suporte de COG, o Earth Engine indexa os campos espaciais e de metadados da imagem no momento da criação. Isso torna a imagem eficiente quando usada em coleções, com desempenho comparável aos recursos ingeridos padrão (consulte a visão geral do GeoTIFF otimizado para nuvem (COG)).

Pré-requisitos e configuração do Cloud Storage

Antes de registrar um COG, configure corretamente os recursos do Google Cloud Storage.

1. Local do bucket (requisito estrito)

Para que o Earth Engine acesse seu bucket do Cloud Storage, ele precisa estar localizado em uma das seguintes regiões ou multirregiões do data center:

  • A multirregião us
  • Qualquer birregional dos EUA que inclua us-central1
  • A região us-central1

Se o bucket estiver em qualquer outro data center regional (como us-east4 ou europe-west1), o Earth Engine vai rejeitar solicitações de registro e leitura.

2. Classe de armazenamento e faturamento

  • Recomendamos o uso da classe de armazenamento Standard. O Standard Storage não tem regras de duração mínima, evitando penalidades de faturamento por exclusão antecipada se você atualizar ou substituir arquivos temporários.
  • Embora os loops de computação do Earth Engine não gerem sobretaxas de recuperação de dados do Cloud Storage, o acesso a níveis de armazenamento não Standard Storage de ferramentas externas (como software SIG para computador) gera taxas de recuperação caras.
  • É necessário ativar o faturamento no projeto do Google Cloud para usar o GCS. Consulte o Guia de início rápido do Google Cloud Storage para começar.

Etapa 1: preparar os COGs

Os arquivos TIFF precisam ser otimizados para a nuvem. O TIFF precisa ser:

  • Em blocos, com dimensões de bloco de 256 x 256, 512 x 512, 1024 x 1024 ou 2048 x 2048. Recomendamos 512 x 512 ou mais para melhor desempenho.
  • Organizado para que todos os diretórios de arquivos de imagem (IFDs) estejam no início.
  • Inclua visões gerais de potência de 2.
  • Use o intercalamento BAND.

Você pode usar o GDAL para converter suas imagens.

Como usar o driver GDAL COG (GDAL >= 3.1 recomendado) :

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Como usar o driver GTiff padrão :

Primeiro, gere visões gerais internas de potência de 2 (usando gdal raster overview add ou gdaladdo), depois copie a imagem e as visões gerais em um layout de COG em blocos:

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Etapa 2: criar o manifesto

Se você registrar um COG usando a biblioteca de cliente Python do Earth Engine, a ferramenta de linha de comando earthengine ou a API REST do Earth Engine, defina um manifesto de upload de imagem especificando o destino do recurso, os URIs do Google Cloud Storage e os metadados de banda opcionais.

Exemplo: COG único com suporte a todas as bandas Se o COG contiver todas as bandas (por exemplo, RGB), o manifesto exigirá apenas um conjunto de blocos:

{
  "name": "projects/my-project/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

Exemplo: vários COGs (um por banda) Se você tiver arquivos separados para diferentes bandas (por exemplo, vermelho, verde, azul em arquivos separados):

{
  "name": "projects/my-project/assets/my_multi_band_cog",
  "tilesets": [
    {
      "id": "red_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_red.tif" ] } ]
    },
    {
      "id": "green_tileset",
      "sources": [ { "uris": [ "gs://google-sample-bucket/band_green.tif" ] } ]
    }
  ],
  "bands": [
    { "id": "R", "tilesetId": "red_tileset", "tilesetBandIndex": 0 },
    { "id": "G", "tilesetId": "green_tileset", "tilesetBandIndex": 0 }
  ]
}

Etapa 3: enviar a solicitação de registro

Você pode enviar o manifesto ao Earth Engine usando a biblioteca de cliente Python do Earth Engine, a ferramenta de linha de comando earthengine ou a API REST do Earth Engine. Escolha o método que melhor se adapta ao seu fluxo de trabalho.

Biblioteca de cliente do Python

Em um script Python ou notebook Jupyter, use a biblioteca de cliente Python do Earth Engine (ee.data) depois de inicializar o projeto:

import ee

# 1. Authenticate and initialize
ee.Authenticate()
ee.Initialize(project='your-project-id')

# 2. Define the manifest as a Python dictionary
manifest = {
  "name": "projects/your-project-id/assets/my_cog_asset",
  "tilesets": [
    {
      "id": "default_tileset",
      "sources": [
        {
          "uris": [
            "gs://google-sample-bucket/my_optimized_image.tif"
          ]
        }
      ]
    }
  ]
}

# 3. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

Ferramenta de linha de comando

No terminal, salve o manifesto em um arquivo chamado manifest.json e execute o earthengine upload comando:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

API REST (Python)

Para fluxos de trabalho automatizados sem a biblioteca de cliente, envie uma solicitação autorizada POST diretamente para o endpoint de API REST do Earth Engine projects.image.importExternal (demonstrado aqui usando Python):

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

# 1. Authenticate and start an authorized HTTP session
ee.Authenticate()
ee_project = 'your-project-id'
session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

# 2. Define the REST request body wrapping the manifest
request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/my_cog_asset',
    'tilesets': [
      {
        'id': 'default_tileset',
        'sources': [
          {
            'uris': [
              'gs://google-sample-bucket/my_optimized_image.tif'
            ]
          }
        ]
      }
    ]
  }
}

# 3. Send the POST request
url = (
    'https://earthengine.googleapis.com/v1alpha/'
    f'projects/{ee_project}/image:importExternal'
)
response = session.post(url=url, data=json.dumps(request))
pprint(json.loads(response.content))

Depois de enviado, o pedido de registro inicia uma operação de indexação de metadados leve. Como o registro de COG não copia dados de pixel, essa operação normalmente é concluída em segundos.

Restrições de manifesto para recursos de COG

Ao criar um manifesto para recursos com o suporte de COG, observe estas restrições estritas (que são diferentes dos manifestos de ingestão padrão):

  • Bucket único:todos os URIs no manifesto precisam estar no mesmo bucket do GCS.
  • Um URI por origem:cada ImageSource precisa conter exatamente um URI. Não é possível mesclar vários arquivos em uma única origem de conjunto de blocos. Para mesclar várias cenas de COG, registre cada COG como um recurso e combine-os em uma ee.ImageCollection usando .mosaic().
  • Sem mask_bands: mask_bands de nível superior não é compatível. Use missingData no manifesto ou verifique se o TIFF tem um valor nodata interno.
  • Sem data_type no conjunto de blocos:não especifique data_type na seção tilesets . Ele é detectado automaticamente.
  • Sem dimensions na origem: não especifique dimensions no ImageSource.
  • Sem subdataset_prefix / subdataset_suffix.
  • Sem min_tile_area_ratio ou skip_metadata_read.

Etapa 4: configurar permissões (essencial para compartilhamento)

Ao contrário dos recursos padrão do Earth Engine, os dados de pixel de um COG permanecem no GCS. Ao compartilhar um recurso com o suporte de COG com outras pessoas, é necessário conceder acesso de leitura ao recurso do Earth Engine e aos arquivos do GCS.

1. Conceder permissões de bucket do GCS

Os colaboradores precisam de permissões para ler os arquivos do GCS.

Permissões necessárias:

  • storage.buckets.get (para recuperar metadados e local do bucket)
  • storage.objects.get (para ler os dados de pixel)

Você pode conceder essas permissões usando os seguintes papéis padrão do Cloud Storage:

  • Leitor de buckets do Storage (fornece storage.buckets.get para ler metadados e local do bucket)
  • Leitor de objetos do Storage (fornece storage.objects.get para ler dados de pixel)

Etapas para configurar no console do Google Cloud :

  1. Acesse o navegador do Cloud Storage.
  2. Clique no nome do bucket.
  3. Selecione a guia Permissões.
  4. Clique em PERMITIR ACESSO.
  5. Adicione os endereços de e-mail dos colaboradores (ou um grupo do Google ou allUsers para acesso público).
  6. Atribua os papéis Leitor de buckets do Storage e Leitor de objetos do Storage.
  7. Clique em Salvar.

2. Compartilhar o recurso do Earth Engine

Compartilhe o recurso usando o gerenciador de recursos do Earth Engine ou a CLI. Consulte o Guia de gerenciamento de recursos para mais detalhes.

Como gerenciar gerações de objetos

Ao registrar um COG, o Earth Engine armazena a geração (versão) específica do objeto do GCS. Se você atualizar o arquivo no GCS, a geração dele vai mudar.

  • Por padrão, o Earth Engine não vai carregar o recurso e retornará um erro: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
  • Isso foi projetado para evitar que os metadados (como projeção ou área de cobertura) fiquem dessincronizados com os pixels subjacentes.

  • Prática recomendada:se você precisar atualizar os dados de imagem subjacentes, registre-os como um novo recurso ou execute novamente o comando de upload com a flag --force em vez de substituir arquivos no local:

    earthengine --project your-project-id upload external_image --force --manifest manifest.json

Como usar recursos registrados

Depois de registrado, um recurso com o suporte de COG é acessado em scripts do Earth Engine como qualquer recurso de imagem ingerido padrão:

JavaScript

var image = ee.Image('projects/your-project-id/assets/my_cog_asset');

Python

image = ee.Image('projects/your-project-id/assets/my_cog_asset')