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:
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.
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 enformatOptions. - 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
fileDimensionsdentro deformatOptions. 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 quefileDimensionsestablece 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 pasarskipEmptyFiles: truepara 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
fileDimensionsoshardSizeproduce 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 (comoZSTD) 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
Tileseten un manifiesto de recursos de COG hace referencia a un solo URI de Cloud Storage, por lo que los archivos individuales se registran como recursosee.Imageindependientes en unee.ImageCollectionen 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.Imagede varias bandas si se enumeran variostilesetsen 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 controladorCOGde 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=BANDes compatible con el controladorCOGa partir de GDAL 3.11 (y en todas las versiones de GDAL cuando se usa el controladorGTiff). No usesINTERLEAVE=TILE.
- Entrelazado de píxeles (
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) oNONE(sin comprimir).LZMA,WEBP,LERCyJXL(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 controladorCOGde GDAL) usan de forma predeterminada la compresiónLZWsin predictor, recomendamos la compresión Zstandard (ZSTD) (en GDAL,-co COMPRESS=ZSTD) con un nivel de compresión de16(o18–22cuando los tamaños de archivo más pequeños superan los tiempos de compresión más largos, con-co LEVEL=16para el controladorCOGo-co ZSTD_LEVEL=16para el controladorGTiff). CombinaZSTDcon un predictor (-co PREDICTOR=YESen el controladorCOG, o-co PREDICTOR=2para números enteros y-co PREDICTOR=3para números de punto flotante en el controladorGTiff). - 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
COGde GDAL) compilan y colocan descripciones generales al principio del archivo de forma predeterminada. Ten en cuenta que el controladorCOGde GDAL usa de forma predeterminada el remuestreo de descripción generalCUBIC, 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(oMODE) 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_NODATAdel archivo (establecida con-a_nodataen GDAL;NaNtambién se admite para datos de punto flotante) o un valormissingDataespecificado en el manifiesto de registro (que anulaGDAL_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,float32yfloat64(no se admitenuint64,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_CPUSpara 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
earthengineo 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
cloudOptimizedconfigurado comotrue(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.