Registra recursos de GeoTIFF optimizado para la nube (COG)

Earth Engine admite recursos respaldados por GeoTIFF optimizados para la nube (COG) almacenados en Google Cloud Storage (GCS).

Cuando registras un recurso respaldado por COG, Earth Engine indexa los campos espaciales y de metadatos de la imagen en el momento de la creación. Esto hace que la imagen tenga un buen rendimiento cuando se usa en colecciones, con un rendimiento comparable al de los recursos transferidos estándar (consulta la descripción general de GeoTIFF optimizado para la nube [COG]).

En esta guía, se explica cómo preparar tus archivos, escribir el manifiesto, enviar la solicitud de registro, configurar los permisos y actualizar o borrar los recursos registrados.

Antes de comenzar

Antes de registrar un COG, debes configurar tus recursos de Cloud Storage de forma correcta.

Ubicación del bucket

Para que Earth Engine acceda a tu bucket de Cloud Storage, este debe estar ubicado en una de las siguientes regiones o multirregiones de centros de datos:

  • La multirregión us
  • Cualquier región birregional de EE.UU. que incluya us-central1
  • La región us-central1

Si tu bucket se coloca en cualquier otro centro de datos regional (como us-east4 o europe-west1), Earth Engine rechazará las solicitudes de registro y lectura. Consulta las ubicaciones de buckets de Cloud Storage compatibles.

Clase de almacenamiento y facturación

  • Te recomendamos que uses la clase de almacenamiento Standard. Standard Storage no tiene reglas de duración mínima de almacenamiento, lo que evita las penalizaciones de facturación por eliminación anticipada si actualizas o reemplazas archivos temporales.
  • Si bien los bucles de cómputo de Earth Engine no generan cargos adicionales por la recuperación de datos de Cloud Storage, el acceso a niveles de almacenamiento no Standard Storage desde herramientas externas (como el software de SIG de escritorio) genera tarifas de recuperación costosas.
  • Debes tener habilitada la facturación en tu proyecto de Google Cloud para usar Cloud Storage. Consulta la guía de inicio rápido de Cloud Storage para comenzar.

Prepara tus COG

Earth Engine lee los COG directamente desde Cloud Storage y recupera solo el encabezado y las tarjetas que necesita un cálculo, por lo que el diseño del archivo es importante. El archivo TIFF debe cumplir con los siguientes requisitos:

  • Mosaico, con dimensiones de mosaico cuadradas de potencia de 2, de 16 × 16 a 2048 × 2048 Recomendamos 512 × 512 para obtener el mejor rendimiento.
  • Se organizan de modo que todos los directorios de archivos de imagen (IFD) estén al principio.
  • Incluye descripciones generales de potencia de 2, si las hay. No se requieren resúmenes, pero se recomiendan para imágenes más grandes que una sola tarjeta.
  • Usa el intercalado BAND o PIXEL (consulta Archivos de banda única frente a archivos de varias bandas para conocer las ventajas y desventajas).

Para convertir una imagen, usa el controlador COG de GDAL, que produce el diseño requerido (mosaicos, descripciones generales y ubicación del encabezado) en un solo paso. Agrega OVERVIEW_RESAMPLING=NEAREST para los datos categóricos; el valor predeterminado es CUBIC. Para obtener recomendaciones de compresión, descripción general y diseño, consulta las prácticas recomendadas para preparar COG externos.

CLI de GDAL 3.11 o versiones posteriores

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ásica

Omite INTERLEAVE=BAND en las versiones de GDAL anteriores a la 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

Crea el manifiesto

Ya sea que registres un COG con la biblioteca cliente de Earth Engine para Python, la herramienta de línea de comandos de earthengine o la API de REST de Earth Engine, debes definir un manifiesto de carga de imágenes que especifique el destino del recurso, los URIs de Cloud Storage y los metadatos de banda opcionales. La API y la herramienta de línea de comandos se refieren a los recursos respaldados por COG como imágenes externas (ee.data.startExternalImageIngestion(), earthengine upload external_image y projects.image.importExternal).

Ejemplo: Un solo COG que respalda todas las bandas Si tu COG contiene todas las bandas (por ejemplo, RGB), el manifiesto requiere solo un conjunto de mosaicos:

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

Ejemplo: Varios COG (uno por banda) Si tienes archivos separados para diferentes bandas (por ejemplo, rojo, verde y azul en archivos 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 }
  ]
}

Restricciones del manifiesto

Los manifiestos de los recursos respaldados por COG tienen restricciones que no se aplican a los manifiestos de transferencia estándar:

  • Bucket único: Todos los URI del manifiesto deben residir en el mismo bucket de Cloud Storage.
  • Un URI por fuente: Cada ImageSource debe contener exactamente un URI. No puedes unir varios archivos en una sola fuente de conjunto de mosaicos. Para crear un mosaico de varias escenas de COG, registra cada COG como un recurso y combínalas en un ee.ImageCollection con .mosaic().
  • No mask_bands: No se admite el campo mask_bands de nivel superior. Usa missingData en el manifiesto o asegúrate de que tu TIFF tenga un valor interno de sin datos.
  • No hay data_type en el conjunto de mosaicos: No especifiques data_type en la sección tilesets; se detecta automáticamente.
  • No hay dimensions en la fuente: No especifiques dimensions en el ImageSource.
  • No subdataset_prefix / subdataset_suffix.
  • No min_tile_area_ratio ni skip_metadata_read.

Envía la solicitud de registro

Puedes enviar tu manifiesto a Earth Engine con la biblioteca cliente de Python de Earth Engine, la herramienta de línea de comandos de earthengine o la API de REST de Earth Engine. Elige el método que mejor se adapte a tu flujo de trabajo.

Biblioteca cliente para Python

En una secuencia de comandos de Python o un notebook de Jupyter, usa la biblioteca cliente de Python de Earth Engine (ee.data) después de inicializar tu proyecto:

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']}")

Herramienta de línea de comandos

En la terminal, guarda el manifiesto en un archivo llamado manifest.json y ejecuta el comando de carga 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 de REST

Para los flujos de trabajo automatizados sin la biblioteca cliente, envía una solicitud POST autorizada directamente al endpoint de API de REST de Earth Engine projects.image.importExternal (se muestra aquí con 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))

Una vez enviada, la solicitud de registro inicia una operación de indexación de metadatos liviana. Debido a que el registro de COG no copia datos de píxeles, esta operación suele completarse en segundos.

Configura permisos

A diferencia de los recursos estándar de Earth Engine, los datos de píxeles de un COG permanecen en Cloud Storage. Cuando compartas un recurso respaldado por COG con otras personas, debes otorgarles acceso de lectura tanto al recurso de Earth Engine como a los archivos de Cloud Storage.

Otorga permisos del bucket de Cloud Storage

Los colaboradores necesitan permisos para leer los archivos de Cloud Storage.

Permisos necesarios:

  • storage.buckets.get (para recuperar los metadatos y la ubicación del bucket)
  • storage.objects.get (para leer los datos de píxeles)

Puedes otorgar estos permisos con los siguientes roles estándar de Cloud Storage:

  • Visualizador de buckets de almacenamiento (proporciona storage.buckets.get para leer los metadatos y la ubicación del bucket)
  • Visualizador de objetos de Storage (proporciona storage.objects.get para leer datos de píxeles)

Pasos para configurar en la consola de Google Cloud:

  1. Ve al navegador de Cloud Storage.
  2. Haz clic en el nombre del bucket.
  3. Selecciona la pestaña Permisos.
  4. Haz clic en OTORGAR ACCESO.
  5. Agrega las direcciones de correo electrónico de tus colaboradores (o un Grupo de Google, o allUsers para acceso público).
  6. Asigna los roles Visualizador de buckets de almacenamiento y Visualizador de objetos de almacenamiento.
  7. Haz clic en Guardar.

Comparte el recurso de Earth Engine

Comparte el recurso con el Administrador de recursos de Earth Engine o la CLI. Consulta la Guía de administración de recursos para obtener más detalles.

Actualiza, reemplaza y borra recursos respaldados por COG

Un recurso respaldado por COG es un puntero a una versión específica de un archivo en Cloud Storage, además de los metadatos (huella, proyección, bandas y diseño de descripción general) que Earth Engine indexó cuando lo registraste. Earth Engine fija la versión del archivo para que estos metadatos no se desincronicen con los píxeles, que es lo que hace que la actualización de los recursos respaldados por COG sea diferente de la actualización de los recursos estándar.

Generaciones de objetos

Cuando registras un COG, Earth Engine registra la generación del objeto de Cloud Storage (su número de versión) junto con el URI. Puedes ver la generación fijada en los metadatos del objeto; aparece como un sufijo #<generation> en el 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']

También puedes fijar una versión específica por tu cuenta incluyendo el sufijo #<generation> en el URI del manifiesto cuando registres (o vuelvas a registrar) el recurso. Sin ella, Earth Engine lee el objeto actual y fija la generación que encuentra. La fijación explícita es útil para revertir a una versión anterior que haya conservado un bucket con control de versiones de objetos.

Si reemplazas el archivo en Cloud Storage, se genera una nueva versión, y si lo borras, la versión fijada desaparece. En cualquier caso, la lectura de los píxeles del recurso falla, a menos que el control de versiones de objetos en el bucket conserve la generación anterior, en cuyo caso Earth Engine sigue leyendo los píxeles antiguos. Las operaciones de metadatos que usan el registro indexado (como ee.data.getAsset(), bandNames() y el filtrado de colecciones) siguen funcionando de cualquier manera.

Actualiza un recurso después de cambiar su archivo

Para dirigir un recurso existente a una versión nueva de su archivo, vuelve a registrarlo con el mismo nombre de recurso y la opción de reemplazo habilitada. Earth Engine vuelve a leer el encabezado de GeoTIFF, vuelve a indexar los metadatos y fija la nueva generación en una sola llamada síncrona. Se conservan los permisos existentes del recurso, pero sus propiedades, período y nombres de bandas provienen del manifiesto nuevo, por lo que se incluye todo lo que hayas configurado antes con ee.data.updateAsset().

  • Python: ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
  • Línea de comandos: earthengine upload external_image --force --manifest manifest.json
  • API de REST: Incluye "overwrite": true como un campo de nivel superior junto con "imageManifest" en el cuerpo de la solicitud projects.image.importExternal.

No es necesario que borres el recurso primero, y borrarlo es contraproducente: un recurso independiente pierde sus permisos, y una imagen de una colección desaparece brevemente de la colección. Ten en cuenta que ee.data.updateAsset() (projects.assets.patch) solo puede cambiar las propiedades, el período y los nombres de las bandas, pero no puede cambiar el archivo al que apunta un recurso.

Ciclos de vida independientes

Los recursos de Earth Engine y los objetos de Cloud Storage se administran por separado:

  • Borrar el recurso de Earth Engine (earthengine rm o ee.data.deleteAsset()) solo quita el registro del recurso. Tus archivos en Cloud Storage no se modifican.
  • Borrar el archivo en Cloud Storage no quita el recurso, ya que sigue apareciendo en las listas y en su colección (consulta generaciones de objetos).

Trabaja con colecciones grandes

No hay eliminación por lotes ni recursiva en la API de Earth Engine: cada recurso se debe borrar de forma individual, y una colección debe estar vacía antes de que se pueda borrar. earthengine rm -r se encarga de esto, pero emite las eliminaciones de a una, por lo que una colección con decenas de miles de imágenes puede tardar horas en quitarse.

  • Para reemplazar las imágenes de una colección, reemplázalas en lugar de borrarlas. Vuelve a registrar cada imagen por nombre con la opción de reemplazar habilitada (consulta más arriba). Esto requiere una solicitud por imagen en lugar de dos, mantiene la colección propagada en todo momento y evita borrar y volver a crear la colección, que es donde se encuentran sus permisos. Borra solo las imágenes que no estén en el conjunto nuevo.
  • Para borrar muchos recursos, paraleliza desde una secuencia de comandos. Enumera los activos con ee.data.listAssets() (con la vista BASIC, que solo devuelve nombres y tipos en lugar de metadatos completos para cada imagen) y bórralos de un grupo de subprocesos pequeño. Las solicitudes de recursos comparten límites de frecuencia en todo el proyecto, por lo que debes mantener la simultaneidad moderada (alrededor de 10 trabajadores) y permitir que los reintentos integrados de la biblioteca cliente controlen las respuestas 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)
    

    La colección se borra solo si se borraron todas las imágenes, por lo que un error parcial la deja en su lugar para que se vuelva a ejecutar.

    El mismo patrón se aplica para registrar muchas imágenes: reemplaza ee.data.deleteAsset(asset_id) en el ayudante por ee.data.startExternalImageIngestion(manifest, allow_overwrite=True) y asígnalo a tu lista de manifiestos. Pasar allow_overwrite=True incluso en la primera ejecución hace que el lote sea seguro para volver a ejecutarlo después de una falla parcial, ya que cualquier recurso que ya se haya creado se reemplaza en lugar de causar un error.

Usa recursos registrados

Una vez registrado, se accede a un recurso respaldado por COG en las secuencias de comandos de Earth Engine de la misma manera que a cualquier recurso de imagen transferido estándar:

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 obtener respuestas a preguntas frecuentes sobre permisos, actualización de archivos y administración de colecciones grandes, consulta la sección de COG de las Preguntas frecuentes.