Earth Engine presenta niveles de cuotas no comerciales para proteger los recursos de procesamiento compartidos y garantizar un rendimiento confiable para todos. Los proyectos no comerciales usan el nivel de la comunidad de forma predeterminada, aunque puedes cambiar el nivel de un proyecto en cualquier momento.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Registra recursos de GeoTIFF optimizado para la nube (COG)

Earth Engine admite recursos respaldados por GeoTIFF optimizados para la nube (COGs) 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 estándar transferidos (consulta la descripción general de GeoTIFF optimizado para la nube [COG]).

Requisitos previos y configuración de Cloud Storage

Antes de registrar un COG, debes configurar correctamente tus recursos de Google Cloud Storage.

1. Ubicación del bucket (requisito estricto)

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

La multirregión us
Cualquier 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.

2. 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 sanciones 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 recargos por recuperación de datos de Cloud Storage, el acceso a niveles de almacenamiento que no son Standard Storage desde herramientas externas (como el software GIS de escritorio) genera costosas tarifas de recuperación.
Debes tener habilitada la facturación en tu proyecto de Google Cloud para usar GCS. Consulta la guía de inicio rápido de Google Cloud Storage para comenzar.

Paso 1: Prepara tus COGs

Tus archivos TIFF deben estar optimizados para la nube. El TIFF debe ser lo siguiente:

En mosaico, con dimensiones de mosaico de 256 x 256, 512 x 512, 1024 x 1024 o 2048 x 2048. Recomendamos 512 x 512 o más para obtener el mejor rendimiento.
Organizado de modo que todos los directorios de archivos de imagen (IFDs) estén al principio.
Incluye resúmenes de potencia de 2.
Usa el intercalado BAND.

Puedes usar GDAL para convertir tus imágenes.

Usa el controlador GDAL COG (se recomienda GDAL >= 3.1):

gdal_translate in.tif out.tif \
  -of COG \
  -co BIGTIFF=YES \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=16 \
  -co BLOCKSIZE=512 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Usa el controlador GTiff estándar:

Primero, genera resúmenes internos de potencia de 2 (con gdal raster overview add o gdaladdo), luego copia la imagen y los resúmenes en un diseño de COG en mosaico:

gdaladdo -r nearest in.tif 2 4 8 16 32  # or -r cubic for continuous/float data

gdal_translate in.tif out.tif \
  -co BIGTIFF=YES \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=16 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \
  -co PREDICTOR=2  # 2 for integers, 3 for floating point

Paso 2: Construye el manifiesto

Ya sea que registres un COG con la biblioteca cliente de Python de Earth Engine, la herramienta de línea de comandos 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 Google Cloud Storage y los metadatos de banda opcionales.

Ejemplo: Un solo COG que respalda todas las bandas Si tu COG contiene todas las bandas (p.ej., RGB), el manifiesto solo requiere 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 COGs (uno por banda) Si tienes archivos separados para diferentes bandas (p.ej., 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 }
  ]
}

Paso 3: 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 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 cuaderno 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. Start the ingestion task (allow_overwrite=True corresponds to --force)
result = ee.data.startExternalImageIngestion(manifest, allow_overwrite=True)
print(f"Asset registered: {result['name']}")

Herramienta de línea de comandos

En tu terminal, guarda el manifiesto en un archivo llamado manifest.json y ejecuta el earthengine upload command:

# 1. Verify your environment is authenticated
earthengine authenticate

# 2. Submit the external image upload task
earthengine --project your-project-id \
  upload external_image \
  --manifest manifest.json

API de REST (Python)

Para los flujos de trabajo automatizados sin la biblioteca cliente, envía una solicitud autorizada POST directamente al extremo de la API de REST de Earth Engine projects.image.importExternal (que 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 ligera. Debido a que el registro de COG no copia datos de píxeles, esta operación suele completarse en segundos.

Registro síncrono: Debido a que el registro de COG es una llamada a la API síncrona y rápida en lugar de un trabajo de procesamiento por lotes asíncrono, no crea una tarea en segundo plano en la pestaña Tareas del Editor de código ni en el administrador de tareas por lotes. La llamada a la API se bloquea hasta que se completan la validación de metadatos y la indexación, después de lo cual el recurso está disponible de inmediato en la pestaña Recursos del Editor de código o con ee.data.getAsset().

Restricciones de manifiesto para recursos COG

Cuando crees un manifiesto para recursos respaldados por COG, ten en cuenta estas restricciones estrictas (que difieren de los manifiestos de transferencia estándar):

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

Paso 4: Configura los permisos (fundamental para compartir)

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

1. Otorga permisos de bucket de GCS

Los colaboradores necesitan permisos para leer los archivos de GCS.

Permisos necesarios:

storage.buckets.get (para recuperar metadatos y 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 Storage (proporciona storage.buckets.get para leer metadatos y 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:

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 allUsers para el acceso público).
Asigna los roles Visualizador de buckets de Storage y Visualizador de objetos de Storage.
Haz clic en Guardar.

2. 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.

Administra las generaciones de objetos

Cuando registras un COG, Earth Engine almacena la generación específica (versión) del objeto GCS. Si actualizas el archivo en GCS, su generación cambia.

De forma predeterminada, Earth Engine no podrá cargar el recurso y mostrará un error: Failed to load the GeoTIFF at gs://google-sample-bucket/my-object#old-generation.
Esto está diseñado para evitar que los metadatos (como la proyección o la huella) se desincronice con los píxeles subyacentes.
Práctica recomendada: Si necesitas actualizar los datos de imagen subyacentes, regístralos como un recurso nuevo o vuelve a ejecutar el comando de carga con la marca --force en lugar de reemplazar los archivos en su lugar:
```
earthengine --project your-project-id upload external_image --force --manifest manifest.json
```

Usa recursos registrados

Una vez registrado, se accede a un recurso respaldado por COG en las secuencias de comandos de Earth Engine como 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')

Registra recursos de GeoTIFF optimizado para la nube (COG) Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.