Registrar recursos do GeoTIFF otimizado para nuvem (COG)

O Earth Engine é compatível com recursos que usam GeoTIFFs otimizados para nuvem (COGs, na sigla em inglês) armazenados no Google Cloud Storage (GCS).

Quando você registra um recurso com suporte a COG, o Earth Engine indexa os campos espaciais e de metadados da imagem no momento da criação. Isso faz com que a imagem tenha um bom desempenho quando usada em coleções, com desempenho comparável ao de recursos ingeridos padrão (consulte a visão geral do GeoTIFF otimizado para nuvem (COG)).

Este guia aborda como preparar os arquivos, escrever o manifesto, enviar a solicitação de registro, configurar permissões e atualizar ou excluir recursos registrados.

Antes de começar

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

Local do bucket

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

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

Se o bucket for colocado em qualquer outro data center regional (como us-east4 ou europe-west1), o Earth Engine vai rejeitar as solicitações de registro e leitura. Consulte os locais de bucket do Cloud Storage compatíveis.

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 de armazenamento, o que evita 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 cobranças extras de recuperação de dados do Cloud Storage, o acesso a níveis de armazenamento não padrão por ferramentas externas (como software GIS para computador) gera taxas de recuperação caras.
  • É preciso ativar o faturamento no projeto do Google Cloud para usar o Cloud Storage. Consulte o guia de início rápido do Cloud Storage para começar.

Preparar os COGs

O Earth Engine lê COGs diretamente do Cloud Storage, buscando apenas o cabeçalho e os blocos necessários para uma computação. Portanto, o layout do arquivo é importante. O TIFF precisa ser:

  • Em blocos, com dimensões quadradas de potência de 2, de 16x16 a 2048x2048. Recomendamos 512 x 512 para uma melhor performance.
  • Organizado de modo que todos os diretórios de arquivos de imagem (IFDs, na sigla em inglês) fiquem no início.
  • Inclua visões gerais de potência de 2, se houver. As visões gerais não são obrigatórias, mas são recomendadas para imagens maiores que um único bloco.
  • Use a intercalação BAND ou PIXEL (consulte arquivos de banda única versus multibanda para as compensações).

Para converter uma imagem, use o driver COG da GDAL, que produz o layout necessário (lado a lado, visões gerais e posicionamento do cabeçalho) em uma única etapa. Adicione OVERVIEW_RESAMPLING=NEAREST para dados categóricos. O padrão é CUBIC. Para recomendações de compactação, visão geral e layout, consulte Práticas recomendadas para preparar COGs externos.

CLI do GDAL 3.11+

gdal raster convert in.tif out.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co OVERVIEWS=IGNORE_EXISTING \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

CLI clássica

Omita INTERLEAVE=BAND em versões do GDAL anteriores à 3.11.

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

Criar o manifesto

Se você registrar um COG usando a biblioteca de cliente do Python do Earth Engine, a ferramenta de linha de comando earthengine ou a API REST do Earth Engine, será necessário definir um manifesto de upload de imagem especificando o destino do recurso, os URIs do Cloud Storage e os metadados de banda opcionais. A API e a ferramenta de linha de comando se referem aos recursos compatíveis com COG como imagens externas (ee.data.startExternalImageIngestion(), earthengine upload external_image, projects.image.importExternal).

Exemplo: um único COG que apoia todas as bandas Se o COG tiver todas as bandas (por exemplo, RGB), o manifesto vai exigir apenas um único 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 bandas diferentes (por exemplo, vermelho, verde e 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 }
  ]
}

Restrições do manifesto

Os manifestos de recursos com suporte do COG têm restrições que não se aplicam aos manifestos de ingestão padrão:

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

Enviar o pedido de registro

É possível enviar o manifesto para o Earth Engine usando a biblioteca de cliente do Python do Earth Engine, a ferramenta de linha de comando earthengine ou a API REST do Earth Engine. Escolha o método mais adequado ao seu fluxo de trabalho.

Biblioteca de cliente do Python

Em um script Python ou notebook do 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. Register the asset
result = ee.data.startExternalImageIngestion(manifest)
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 comando de upload earthengine:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Register the asset
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

API REST

Para fluxos de trabalho automatizados sem a biblioteca de cliente, envie uma solicitação POST autorizada 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 enviada, a solicitação de registro inicia uma operação leve de indexação de metadados. Como o registro do COG não copia dados de pixel, essa operação geralmente é concluída em segundos.

Configurar permissões

Ao contrário dos recursos padrão do Earth Engine, os dados de pixel de um COG permanecem no Cloud Storage. Ao compartilhar um recurso com suporte a COG com outras pessoas, você precisa conceder a elas acesso de leitura ao recurso do Earth Engine e aos arquivos do Cloud Storage.

Conceder permissões de bucket do Cloud Storage

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

Permissões necessárias:

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

É possível 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 os metadados e o 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 seus 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.

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.

Atualizar, substituir e excluir recursos com suporte do COG

Um recurso com suporte de COG é um ponteiro para uma versão específica de um arquivo no Cloud Storage, além de metadados (footprint, projeção, bandas e layout de visão geral) que o Earth Engine indexou quando você o registrou. O Earth Engine fixa a versão do arquivo para que esses metadados não fiquem fora de sincronia com os pixels, o que diferencia a atualização de recursos com suporte a COG da atualização de recursos padrão.

Gerações de objetos

Quando você registra um COG, o Earth Engine registra a geração do objeto do Cloud Storage (o número da versão) ao lado do URI. É possível ver a geração fixada nos metadados do recurso. Ela aparece como um sufixo #<generation> no URI:

Python

asset = ee.data.getAsset('projects/your-project-id/assets/my_cog_asset')
print(asset['tilesets'][0]['sources'][0]['uris'])
# ['gs://google-sample-bucket/my_optimized_image.tif#1750427474244728']

Também é possível fixar uma versão específica incluindo o sufixo #<generation> no URI do manifesto ao registrar (ou registrar novamente) o recurso. Sem ele, o Earth Engine lê o objeto atual e fixa qualquer geração que encontrar. A fixação explícita é útil para reverter para uma versão anterior que um bucket com controle de versão de objeto reteve.

Se você substituir o arquivo no Cloud Storage, ele vai receber uma nova geração. Se você excluí-lo, a geração fixada será removida. De qualquer forma, a leitura dos pixels do recurso falha, a menos que o controle de versões de objetos no bucket retenha a geração antiga. Nesse caso, o Earth Engine continua lendo os pixels antigos. As operações de metadados que usam o registro indexado (como ee.data.getAsset(), bandNames() e filtragem de coleções) continuam funcionando de qualquer maneira.

Atualizar um recurso depois de mudar o arquivo dele

Para apontar um recurso atual para uma nova versão do arquivo, registre-o novamente com o mesmo nome e a substituição ativada. O Earth Engine lê novamente o cabeçalho GeoTIFF, reindexa os metadados e fixa a nova geração em uma única chamada síncrona. As permissões atuais do recurso são preservadas, mas as propriedades, o período e os nomes das bandas vêm do novo manifesto. Portanto, inclua tudo o que você definiu anteriormente com ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Linha de comando: earthengine upload external_image --force --manifest manifest.json
  • API REST: inclua "overwrite": true como um campo de nível superior ao lado de "imageManifest" no corpo da solicitação projects.image.importExternal.

Não é necessário excluir o recurso primeiro, e fazer isso é contraproducente: um recurso independente perde as permissões, e uma imagem em uma coleção desaparece brevemente dela. Observe que ee.data.updateAsset() (projects.assets.patch) só pode mudar propriedades, período e nomes de bandas. Ele não pode mudar o arquivo para o qual um recurso aponta.

Ciclos de vida independentes

Os recursos do Earth Engine e os objetos do Cloud Storage são gerenciados separadamente:

  • A exclusão do recurso do Earth Engine (earthengine rm ou ee.data.deleteAsset()) remove apenas o registro do recurso. Os arquivos no Cloud Storage não são afetados.
  • Excluir o arquivo no Cloud Storage não remove o recurso. Ele ainda aparece nas listagens e na coleção (consulte gerações de objetos).

Trabalhar com coleções grandes

Não há exclusão em lote ou recursiva na API Earth Engine: cada recurso precisa ser excluído individualmente, e uma coleção precisa estar vazia antes de ser excluída. O earthengine rm -r lida com isso para você, mas emite as exclusões uma por uma. Portanto, uma coleção com dezenas de milhares de imagens pode levar horas para ser removida.

  • Para substituir as imagens de uma coleção, substitua em vez de excluir. Registre novamente cada imagem por nome com a substituição ativada (veja acima). Isso precisa de uma solicitação por imagem em vez de duas, mantém a coleção preenchida e evita excluir e recriar a coleção, que é onde as permissões dela estão. Exclua apenas as imagens que não estão no novo conjunto.
  • Para excluir muitos recursos, use um script para paralelizar o processo. Liste os recursos com ee.data.listAssets() (usando a visualização BASIC, que retorna apenas nomes e tipos, em vez de metadados completos para cada imagem) e exclua-os de um pequeno pool de linhas de execução. As solicitações de recursos compartilham limites de taxa em todo o projeto. Portanto, mantenha a simultaneidade modesta (cerca de 10 workers) e deixe que as novas tentativas integradas da biblioteca de cliente processem as respostas 429 Too Many Requests:

    Python

    import concurrent.futures
    import ee
    
    ee.Initialize(project='your-project-id')
    collection = 'projects/your-project-id/assets/my_collection'
    
    listing = ee.data.listAssets({'parent': collection, 'view': 'BASIC'})
    asset_ids = [a['name'] for a in listing['assets']]
    
    def delete(asset_id):
      try:
        ee.data.deleteAsset(asset_id)
      except ee.EEException as e:
        return f'{asset_id}: {e}'
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
      failures = [f for f in executor.map(delete, asset_ids) if f]
    
    if failures:
      print('\n'.join(failures))
    else:
      ee.data.deleteAsset(collection)
    

    A coleção só será excluída se todas as imagens forem excluídas. Portanto, uma falha parcial a deixa no lugar para uma nova execução.

    O mesmo padrão se aplica ao registro de várias imagens: substitua ee.data.deleteAsset(asset_id) no auxiliar por ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) e mapeie-o na lista de manifestos. Transmitir allow_overwrite=True mesmo na primeira execução torna o lote seguro para ser executado novamente após uma falha parcial, já que qualquer recurso que já tenha sido criado é substituído em vez de causar um erro.

Usar recursos registrados

Depois de registrado, um recurso com 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')

Para respostas a perguntas comuns sobre permissões, atualização de arquivos e gerenciamento de grandes coleções, consulte a seção COG das perguntas frequentes.