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
ImageSourcedebe 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 unee.ImageCollectioncon.mosaic(). - No
mask_bands: No se admite el campomask_bandsde nivel superior. UsamissingDataen el manifiesto o asegúrate de que tu TIFF tenga un valor interno de sin datos. - No hay
data_typeen el conjunto de mosaicos: No especifiquesdata_typeen la seccióntilesets; se detecta automáticamente. - No hay
dimensionsen la fuente: No especifiquesdimensionsen elImageSource. - No
subdataset_prefix/subdataset_suffix. - No
min_tile_area_rationiskip_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.getpara leer los metadatos y la ubicación del bucket) - Visualizador de objetos de Storage (proporciona
storage.objects.getpara leer datos de píxeles)
Pasos para configurar en la consola de Google Cloud:
- Ve al navegador de Cloud Storage.
- Haz clic en el nombre del bucket.
- Selecciona la pestaña Permisos.
- Haz clic en OTORGAR ACCESO.
- Agrega las direcciones de correo electrónico de tus colaboradores (o un Grupo de Google,
o
allUserspara acceso público). - Asigna los roles Visualizador de buckets de almacenamiento y Visualizador de objetos de almacenamiento.
- 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": truecomo un campo de nivel superior junto con"imageManifest"en el cuerpo de la solicitudprojects.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 rmoee.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 vistaBASIC, 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 respuestas429 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 poree.data.startExternalImageIngestion(manifest, allow_overwrite=True)y asígnalo a tu lista de manifiestos. Pasarallow_overwrite=Trueincluso 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.