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
ImageSourceprecisa 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 umee.ImageCollectionusando.mosaic(). - Não
mask_bands: o campomask_bandsde nível superior não é compatível. UsemissingDatano manifesto ou verifique se o TIFF tem um valor nodata interno. - Nenhum
data_typeno conjunto de blocos: não especifiquedata_typena seçãotilesets. Ele é detectado automaticamente. - Nenhum
dimensionsna origem: não especifiquedimensionsnoImageSource. - Não
subdataset_prefix/subdataset_suffix. - Não
min_tile_area_ratioouskip_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.getpara ler os metadados e o local do bucket) - Leitor de objetos do Storage (fornece
storage.objects.getpara ler dados de pixel)
Etapas para configurar no console do Google Cloud:
- Acesse o Navegador do Cloud Storage.
- Clique no nome do bucket.
- Selecione a guia Permissões.
- Clique em PERMITIR ACESSO.
- Adicione os endereços de e-mail dos seus colaboradores (ou um Grupo do Google
ou
allUserspara acesso público). - Atribua os papéis Leitor de buckets do Storage e Leitor de objetos do Storage.
- 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": truecomo um campo de nível superior ao lado de"imageManifest"no corpo da solicitaçãoprojects.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 rmouee.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çãoBASIC, 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 respostas429 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 poree.data.startExternalImageIngestion(manifest, allow_overwrite=True)e mapeie-o na lista de manifestos. Transmitirallow_overwrite=Truemesmo 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.