GeoTIFFs optimizados para Cloud (COG) en Earth Engine

Google Earth Engine te permite trabajar con datos de ráster almacenados en tus propios buckets de Google Cloud Storage (GCS). Si usas GeoTIFF optimizados para la nube (COG), puedes acceder a tus datos y analizarlos directamente en Earth Engine sin transferirlos como un recurso de Earth Engine.

Este enfoque ofrece varios beneficios, en especial para administrar conjuntos de datos grandes o integrar Earth Engine en flujos de trabajo de Google Cloud más amplios o en herramientas y plataformas externas.

¿Por qué usar Cloud Storage y COG?

  • Flexibilidad e interoperabilidad: Mantén tus datos en buckets estándar de Cloud Storage, donde otras herramientas y servicios puedan acceder a ellos. Ya sea que subas los datos directamente o los exportes desde Earth Engine, Cloud Storage actúa como una fuente única de información para Earth Engine y los flujos de trabajo externos.
  • Controles de datos y salida: El almacenamiento de datos en Cloud Storage proporciona capacidades estándar de administración de almacén de objetos. Esto te permite descargar, migrar o compartir tus datos con funciones de Cloud Storage, como Pagos del solicitante o buckets públicos, y administrar el acceso con Cloud IAM estándar.
  • Escalamiento flexible: Evita los límites de almacenamiento de Earth Engine. Cloud Storage proporciona un escalamiento de almacenamiento de autoservicio prácticamente ilimitado a escala de petabytes.
  • Sin espera de transferencia: El registro de un COG se completa con rapidez, ya que Earth Engine solo lee los metadatos (como la proyección y las dimensiones) del encabezado del archivo para la indexación y la validación. Los datos de píxeles reales permanecen en Cloud Storage y se leen a pedido durante el procesamiento, lo que elimina la necesidad de una tarea de transferencia independiente.

Flujos de trabajo de COG en Earth Engine

Earth Engine admite flujos de trabajo bidireccionales con COG en Cloud Storage: puedes leer COG directamente desde Cloud Storage en Earth Engine y puedes escribir resultados de procesamiento de Earth Engine directamente en Cloud Storage como COG.

Lee COG desde Cloud Storage

Para incorporar COG alojados en Cloud Storage a Earth Engine, tienes dos opciones:

  1. Carga directa (ee.Image.loadGeoTIFF()): Carga una sola imagen directamente con su URI de Cloud Storage. Cada cálculo o solicitud de mosaico de mapa lee la versión actual del archivo, pero los mosaicos de mapa ya renderizados se almacenan en caché, por lo que, después de reemplazar un archivo, un mapa puede mostrar una combinación de mosaicos antiguos y nuevos; agrega #<generation> al URI para fijar una versión específica. Esta opción es ideal para pruebas rápidas, análisis ad hoc o datos temporales:

    JavaScript

    var image = ee.Image.loadGeoTIFF('gs://google-sample-bucket/my_image.tif');
    

    Python

    image = ee.Image.loadGeoTIFF('gs://google-sample-bucket/my_image.tif')
    

    Para ver ejemplos completos, consulta Imágenes de GeoTIFF optimizados para la nube.

  2. Recursos registrados: Registra uno o más COG como un recurso de Earth Engine con un manifiesto de carga (consulta la guía de registro de COG). Esta es la ruta recomendada para los flujos de trabajo de producción, en especial cuando se crean colecciones de imágenes.

Función Carga directa (loadGeoTIFF()) Recurso registrado (manifiesto)
Configuración Ninguno (solo un URI de Cloud Storage) Manifiesto (cliente de Python, CLI o REST)
Rendimiento Estándar (lee el encabezado cuando se lee) Optimizado (indexado en el momento de la creación)
Administración No se creó ningún recurso Se descuenta de la cuota de recuento de recursos, no del almacenamiento.
Caso práctico Prototipado, análisis ad hoc Flujos de trabajo de producción que necesitan lecturas rápidas

Escribe COG en Cloud Storage

Para guardar los resultados de los cálculos de Earth Engine como COG en tu bucket de Cloud Storage, usa la función de exportación por lotes Export.image.toCloudStorage() (consulta cómo exportar imágenes) y establece el parámetro cloudOptimized en true en formatOptions. Esto le indica a Earth Engine que compile la imagen y la escriba directamente en tu bucket de Cloud Storage como un COG que cumple con todos los requisitos.

Ubicaciones admitidas de buckets de Cloud Storage

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, Earth Engine rechazará las solicitudes de registro y lectura. Earth Engine accede a los COG almacenados exclusivamente en buckets de Google Cloud Storage. No se admiten los proveedores externos de almacenamiento en la nube ni las URLs HTTP genéricas.

Especificaciones de exportación de COG de Earth Engine

Cuando se exportan resultados analíticos de Earth Engine con Export.image.toCloudStorage() con cloudOptimized: true en formatOptions, el exportador integrado de Earth Engine aplica automáticamente los siguientes estándares:

  • Estructura de archivos: Genera un BigTIFF (BIGTIFF=YES) con mosaicos internos (TILED=YES) y copia todas las descripciones generales al principio del archivo.
  • Resúmenes automáticos: Si las dimensiones del ráster de salida son de 512 x 512 píxeles o más, Earth Engine compila automáticamente cinco niveles de resúmenes de potencia de dos ([2, 4, 8, 16, 32]). Earth Engine selecciona de forma dinámica el método de remuestreo de resumen según el tipo de datos de píxeles de salida: remuestreo cúbico para imágenes de punto flotante y remuestreo de vecino más cercano para todas las demás imágenes discretas o de números enteros.
  • Compresión y división en mosaicos predeterminadas: Earth Engine exporta COG con división en mosaicos de bloques de píxeles de 256 x 256 y compresión LZW (COMPRESS=LZW). Las dimensiones de compresión y mosaico no se pueden personalizar en formatOptions.
  • Fragmentación automática: Si un ráster exportado es grande (supera los 4 GiB sin comprimir), Earth Engine divide automáticamente la exportación en varias tarjetas espaciales llamadas baseFilename-yMin-xMin (consulta Exportaciones de archivos grandes).
  • Anula los límites de fragmentación: Para exportar rásteres grandes (hasta un límite estricto de 16 GiB sin comprimir y 131,072 píxeles por borde) como un solo archivo sin fragmentación, especifica fileDimensions dentro de formatOptions. Cada dimensión debe ser un múltiplo entero positivo del tamaño de la tarjeta (256 de forma predeterminada, por ejemplo, [65536, 65536]). Debido a que fileDimensions establece la dimensión máxima del archivo en lugar del cuadro delimitador de salida, pasar un límite grande fuerza la exportación a un solo archivo sin requerir cálculos exactos de la cuadrícula. También puedes pasar skipEmptyFiles: true para evitar que se generen mosaicos de fondo vacíos.
  • Compensaciones de optimización: Cuando configures exportaciones grandes, evalúa la compensación entre el recuento de archivos y la velocidad de exportación. Especificar valores más pequeños para fileDimensions o shardSize produce más fragmentos de archivos, pero maximiza el procesamiento paralelo entre los trabajadores de backend, lo que genera tiempos de finalización de exportación más rápidos. Por el contrario, anular los límites para generar un solo archivo grande simplifica la administración de archivos y el uso compartido de datos, pero puede aumentar los tiempos de ejecución de la exportación debido al ensamblaje de un solo archivo y a los cuellos de botella de E/S. Las exportaciones de COG de un solo archivo muy grandes que se acercan al límite de 16 GiB sin comprimir (en especial, las imágenes que no se comprimen bien) también pueden superar la capacidad de almacenamiento temporal durante el ensamblaje de la descripción general y el COG. Si una exportación falla, considera fragmentar en archivos más pequeños o convertir una exportación de GeoTIFF estándar de forma externa.

Personaliza la creación de COG fuera de Earth Engine

Si bien exportar directamente con cloudOptimized: true es la forma más sencilla de generar COG listos para usar en la mayoría de los flujos de trabajo, también puedes exportar un GeoTIFF estándar (cloudOptimized: false, el valor predeterminado) y convertirlo en un COG por tu cuenta con herramientas externas como GDAL. Un flujo de trabajo de exportación y conversión de dos pasos puede ser útil cuando necesitas hacer lo siguiente:

  • Personaliza la compresión y el diseño: Adapta los tamaños de los bloques (como 512x512), los predictores, los métodos de remuestreo de descripción general o los códecs de compresión (como ZSTD) a tu conjunto de datos (consulta Prácticas recomendadas para preparar COG externos y Prepara tus COG).
  • Evita errores de capacidad en exportaciones masivas de un solo archivo: Omitir la generación de resúmenes y la reescritura del diseño de COG durante la exportación reduce la sobrecarga de memoria y almacenamiento temporal, lo que hace que las exportaciones de un solo archivo muy grandes tengan menos probabilidades de alcanzar los límites de capacidad.
  • Reduce el tiempo de ejecución de la exportación de Earth Engine: Descargar la compilación de la descripción general y el formato de COG en tu propio entorno de procesamiento acorta la fase de exportación de Earth Engine.

Prácticas recomendadas para preparar COG externos

Los COG generados por herramientas geoespaciales comunes (como GDAL, Rasterio, QGIS, ArcGIS o el paquete terra de R) suelen funcionar en Earth Engine, siempre que usen un esquema de compresión y un tipo de datos de píxeles compatibles. Los siguientes lineamientos pueden ayudarte a organizar los archivos y ajustar la configuración de compresión y diseño para optimizar el almacenamiento y el rendimiento.

Dimensiones internas de los mosaicos

Genera siempre rásteres con mosaicos internos. Earth Engine requiere mosaicos cuadrados con dimensiones que sean potencias de dos, de entre 16 × 16 y 2,048 × 2,048 píxeles. Los exportadores de COG dedicados (como el controlador COG de GDAL con -of COG) dividen automáticamente las imágenes en bloques de 512 x 512 píxeles (-co BLOCKSIZE=512), mientras que los exportadores de GeoTIFF estándar (-of GTiff) requieren una división explícita (-co TILED=YES) y, a menudo, se establecen de forma predeterminada en bloques de 256 x 256. Las tarjetas que son demasiado pequeñas requieren muchas lecturas independientes de Cloud Storage para cubrir un área, mientras que las tarjetas que son demasiado grandes obligan a Earth Engine a descargar y descomprimir más datos de los que necesita una solicitud. Las tarjetas de 512 × 512 logran un buen equilibrio entre ambos.

Cómo elegir las dimensiones de los archivos

Cuando decidas si almacenar un conjunto de datos como un solo COG o dividirlo en varios archivos, equilibra la cantidad de archivos con el tamaño de cada uno:

  • Evita miles de archivos pequeños: Leer una región que abarca cientos de archivos pequeños requiere solicitudes de Cloud Storage y lecturas de encabezados independientes para cada archivo, lo que aumenta la latencia.
  • Evita un solo archivo masivo: Almacenar un conjunto de datos continental o global en un archivo gigante puede limitar la capacidad de procesamiento de lectura paralela cuando muchos trabajadores leen del mismo objeto a la vez. También hay un límite estricto: Earth Engine lee, como máximo, los primeros 10,000,000 de bytes (10 MB) de un archivo cuando lo carga o lo registra, y todo lo que necesita (todos los IFD, incluidas las tablas de desplazamiento de mosaicos y de recuento de bytes, que aumentan con la cantidad de mosaicos y, para los archivos intercalados por bandas, la cantidad de bandas) debe estar dentro de ese rango. No se cargará una imagen con cientos de miles de mosaicos o un GeoTIFF de más de 10 MB cuyos IFD estén al final del archivo en lugar de al principio. Para mantenerte por debajo del límite, usa mosaicos más grandes (hasta 2048 x 2048) o divide la imagen en varios COG registrados como un ee.ImageCollection.
  • Tamaño de archivo recomendado: Cuando dividas un conjunto de datos grande en varios archivos, intenta que los archivos individuales tengan entre 2,000 x 2,000 y 5,000 x 5,000 píxeles (entre 20 MB y 500 MB comprimidos). Ten en cuenta que cada Tileset en un manifiesto de recursos de COG hace referencia a un solo URI de Cloud Storage, por lo que los archivos individuales se registran como recursos ee.Image independientes en un ee.ImageCollection en lugar de un mosaico dentro de un solo recurso de COG.

Archivos de banda única frente a archivos multibanda

  • Un archivo por banda: Es útil para imágenes multiespectrales o hiperespectrales cuando los flujos de trabajo suelen leer solo un subconjunto de bandas (por ejemplo, calcular el NDVI a partir de bandas rojas y del infrarrojo cercano). Los COG de una sola banda independientes se pueden combinar en un solo recurso ee.Image de varias bandas si se enumeran varios tilesets en el manifiesto de registro. También se requieren archivos separados cuando las bandas tienen diferentes resoluciones de píxeles (como las bandas de 10 m, 20 m y 60 m de Sentinel-2), ya que un solo archivo COG solo puede tener un tamaño de píxel en todas sus bandas.
  • Archivos de varias bandas (intercalación de píxeles frente a intercalación de bandas): Earth Engine admite COG de varias bandas intercaladas por píxeles (INTERLEAVE=PIXEL, el valor predeterminado en el controlador COG de GDAL) y por bandas (INTERLEAVE=BAND):
    • Entrelazado de píxeles (INTERLEAVE=PIXEL): Almacena todas las bandas de una mosaico espacial juntas en un solo bloque comprimido. Esto es ideal para conjuntos de datos con algunas bandas que casi siempre se leen juntas (como las imágenes RGB), ya que una sola solicitud de rango recupera todas las bandas. Sin embargo, si una consulta lee solo una banda de un archivo intercalado por píxeles, Earth Engine aún debe recuperar y descomprimir todas las bandas de esa tarjeta.
    • Entrelazado de bandas (INTERLEAVE=BAND): Almacena las tarjetas de cada banda en bloques comprimidos separados para que Earth Engine pueda recuperar y descomprimir solo las bandas solicitadas. En GDAL, -co INTERLEAVE=BAND es compatible con el controlador COG a partir de GDAL 3.11 (y en todas las versiones de GDAL cuando se usa el controlador GTiff). No uses INTERLEAVE=TILE.

Opciones de compresión, descripciones generales y creación

  • Compresión: Earth Engine admite COG comprimidos con ZSTD, DEFLATE (ZLIB), LZW, PACKBITS, JPEG (para datos de 8 bits) o NONE (sin comprimir). LZMA, WEBP, LERC y JXL (JPEG-XL) no son compatibles con los recursos respaldados por COG. Para usar archivos con compresión de archivos con estos códecs en Earth Engine, ingrésalos como recursos estándar en su lugar. Si bien muchos exportadores de COG (como el controlador COG de GDAL) usan de forma predeterminada la compresión LZW sin predictor, recomendamos la compresión Zstandard (ZSTD) (en GDAL, -co COMPRESS=ZSTD) con un nivel de compresión de 16 (o 18–22 cuando los tamaños de archivo más pequeños superan los tiempos de compresión más largos, con -co LEVEL=16 para el controlador COG o -co ZSTD_LEVEL=16 para el controlador GTiff). Combina ZSTD con un predictor (-co PREDICTOR=YES en el controlador COG, o -co PREDICTOR=2 para números enteros y -co PREDICTOR=3 para números de punto flotante en el controlador GTiff).
  • Ubicación y nuevo muestreo de las vistas generales: Asegúrate de que todos los directorios de archivos de imagen (IFD) y las vistas generales de potencia de dos se encuentren al principio del archivo TIFF para que Earth Engine y los visores de mapas web puedan leer las vistas generales en una sola solicitud de rango. Los exportadores de COG dedicados (como el controlador COG de GDAL) compilan y colocan descripciones generales al principio del archivo de forma predeterminada. Ten en cuenta que el controlador COG de GDAL usa de forma predeterminada el remuestreo de descripción general CUBIC, a menos que la imagen tenga una tabla de colores. Para los datos categóricos o discretos (como las clasificaciones de cobertura del suelo o las máscaras de bits de QA), pasa -co OVERVIEW_RESAMPLING=NEAREST (o MODE) para que las descripciones generales alejadas no interpolen valores de clase no válidos.
  • Sin datos y máscaras: Earth Engine enmascara automáticamente los píxeles que coinciden con la etiqueta GDAL_NODATA del archivo (establecida con -a_nodata en GDAL; NaN también se admite para datos de punto flotante) o un valor missingData especificado en el manifiesto de registro (que anula GDAL_NODATA). Earth Engine también admite máscaras de transparencia TIFF internas de 1 bit que tienen descripciones generales de máscaras de resolución reducida que coinciden. Las bandas alfa adicionales estándar (ExtraSamples) se leen como bandas de imágenes normales, en lugar de máscaras automáticas.
  • Tipos de datos de píxeles admitidos: Earth Engine admite COG uint8, int8, uint16, int16, uint32, int32, int64, float32 y float64 (no se admiten uint64, float16, números complejos ni tipos de números enteros de menos de un byte).
  • BigTIFF y subprocesos múltiples: Siempre pasa -co BIGTIFF=YES. La detección de BigTIFF predeterminada de GDAL estima el tamaño del archivo antes de la compresión y puede elegir TIFF clásico para un archivo que termina superando su límite de 4 GB, lo que produce un resultado dañado. El espacio de encabezado adicional que usa BigTIFF es insignificante. También pasa -co NUM_THREADS=ALL_CPUS para paralelizar la compresión en todos los núcleos de CPU disponibles.

En los siguientes ejemplos, se convierte un GeoTIFF en un COG optimizado con la CLI unificada de gdal raster convert (disponible en GDAL 3.11 y versiones posteriores) o gdal_translate. Omite INTERLEAVE=BAND en las versiones de GDAL anteriores a la 3.11 y agrega OVERVIEW_RESAMPLING=NEAREST para los datos categóricos:

# Using the GDAL 3.11+ unified CLI
gdal raster convert src.tif dst.tif \
  -f COG \
  --co BIGTIFF=YES \
  --co BLOCKSIZE=512 \
  --co INTERLEAVE=BAND \
  --co COMPRESS=ZSTD \
  --co LEVEL=16 \
  --co PREDICTOR=YES \
  --co NUM_THREADS=ALL_CPUS

# Using gdal_translate (all GDAL versions)
gdal_translate src.tif dst.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co PREDICTOR=YES \
  -co NUM_THREADS=ALL_CPUS

Consideraciones de costos y clases de almacenamiento

Cuando se analizan los recursos de COG registrados, las lecturas de Earth Engine no generan cargos por operaciones de lectura de Cloud Storage ni por recuperación de datos en tu proyecto de Google Cloud.

Cloud Storage te factura principalmente por el almacenamiento de datos en reposo mensual estándar (GB/mes) y por cualquier tarifa de transferencia de datos de clientes externos o de salida de red (según la ubicación del bucket y la configuración de red del cliente).

Recomendaciones de clases de almacenamiento

  • Almacenamiento estándar (recomendado): El almacenamiento estándar es más adecuado para los flujos de trabajo activos de Earth Engine. Como no tiene reglas de duración mínima de almacenamiento, puedes reemplazar, actualizar o borrar libremente los COG temporales sin incurrir en penalizaciones por eliminación temprana. Además, si tú o tus colaboradores acceden al bucket con software de SIG de escritorio, secuencias de comandos de GDAL o notebooks de aprendizaje automático fuera de Earth Engine, Standard Storage no genera tarifas de recuperación de datos.
  • Almacenamiento Nearline, Coldline y Archive Storage: Todas las clases de Cloud Storage proporcionan el mismo acceso y la misma capacidad de procesamiento de baja latencia que el almacenamiento Standard Storage, por lo que no hay penalización en el rendimiento de lectura cuando se usan niveles de almacenamiento más fríos en Earth Engine. Si bien las lecturas de Earth Engine desde estos niveles tampoco generan tarifas de recuperación de datos, Cloud Storage aplica duraciones mínimas de almacenamiento estrictas (30 días para Nearline, 90 días para Coldline y 365 días para Archive). Si modificas o borras archivos antes de que se cumpla su duración mínima, se aplicarán cargos adicionales por eliminación anticipada. Además, acceder a objetos fríos desde cualquier herramienta de cliente externa genera cargos adicionales costosos por recuperación de datos.

Para obtener información detallada sobre los precios y las políticas de duración mínima, consulta la Guía de precios de Google Cloud Storage.

Flujo de trabajo de alto nivel

Los flujos de trabajo típicos para usar COG en Earth Engine implican los siguientes pasos:

Para importar datos externos, haz lo siguiente:

  • Optimiza: Convierte tus archivos de trama al formato COG con herramientas externas (como GDAL, secuencias de comandos de estaciones de trabajo locales o canalizaciones de procesamiento en la nube).
  • Sube: Sube los COG a un bucket de Cloud Storage en una ubicación compatible.
  • Permisos: Asegúrate de que tú y los colaboradores del proyecto tengan acceso de lectura de Cloud Storage a los archivos (consulta Permisos de COG).
  • Registra: Usa la biblioteca cliente de Python, la herramienta de línea de comandos de earthengine o la API de REST para registrar los COG como recursos de Earth Engine (consulta Registro de COG).

Para exportar resultados:

  • Exporta: Ejecuta una exportación por lotes de Earth Engine a Cloud Storage con cloudOptimized configurado como true (consulta cómo exportar imágenes).
  • Registrar (opcional): Vuelve a registrar el COG exportado en Earth Engine como un recurso nuevo para realizar más análisis (consulta Registro de COG).

¿Todo listo para comenzar? Sigue la guía de registro de COG detallada para registrar tu primer recurso. Para obtener respuestas a preguntas frecuentes, consulta la sección de COG de las Preguntas frecuentes.