Anuncio: Todos los proyectos no comerciales registrados para usar Earth Engine antes del 15 de abril de 2025 deben verificar su elegibilidad no comercial para mantener el acceso a Earth Engine.

Se usó la API de Cloud Translation para traducir esta página.

Recursos de Earth Engine respaldados por GeoTIFF de Cloud

Ejecutar en Google Colab

Ver código fuente en GitHub

Earth Engine admite recursos respaldados por GeoTIFFs optimizados por la nube (COG). Una ventaja de los recursos respaldados por COG es que los campos espaciales y de metadatos de la imagen se indexarán en el momento de su creación, lo que mejorará el rendimiento de la imagen en las colecciones. El rendimiento de los recursos respaldados por COG es comparable al de los recursos transferidos en casos de uso típicos.

Ten en cuenta que un solo recurso puede tener la copia de seguridad de varios COG (por ejemplo, puede haber un COG por banda). Sin embargo, no se admite el uso de muchas tarjetas de COG para una sola banda.

(Como alternativa, Earth Engine puede cargar imágenes directamente desde los COG en Google Cloud Storage (obtén más información). Sin embargo, una imagen cargada a través de ee.Image.loadGeoTIFF y agregada a una colección de imágenes requerirá una lectura del GeoTiff para las operaciones de filtrado en la colección).

Para crear un recurso respaldado por COG, sigue estos pasos:

Coloca tus archivos COG en un bucket de GCS (consulta a continuación las regiones permitidas).
Escribe un manifiesto de carga de imágenes
Usa la utilidad de línea de comandos earthengine para enviar un comando de carga:

earthengine upload external_image --manifest my_manifest.json

Manifiesto de imagen de ejemplo con un `Tileset`

El ImageManifest más simple es uno con un solo Tileset. Si no se especifican bandas, el activo resultante contendrá todas las bandas del GeoTIFF con los nombres de las bandas codificados en el GeoTIFF (en este caso, "vis-red", "vis-green" y "vis-blue").

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo1',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['gs://ee-docs-demos/COG_demo.tif'] } ] }
    ],
    'properties': {
      'version': '1.1'
    },
    'startTime': '2016-01-01T00:00:00.000000000Z',
    'endTime': '2016-12-31T15:01:23.000000000Z',
  },
}

pprint(request)

Más de un `Tileset`

Es posible especificar un ImageManifest con más de un Tileset, en el que cada banda del activo resultante esté respaldada por una de las bandas de un Tileset con los campos tilesetId y tilesetBandIndex. Esto es útil en el caso de que diferentes bandas tengan diferentes resoluciones o tipos de datos. Las bandas se pueden enumerar en cualquier orden desde cualquier Tileset disponible. En el ejemplo que se muestra a continuación, se ilustra lo siguiente:

"b4b3b2.tif" tiene una escala de 10 m, mientras que "b5b6b7" tiene una escala de 20 m.
El orden de bandas del recurso resultante se mezcla a partir de los COG de entrada (p.ej., la banda de salida 0 es de Tileset 0, mientras que la banda de salida 1 es de Tileset 1).

request = {
  'imageManifest': {
    'name': f'projects/{ee_project}/assets/cogdemo2',
    'uriPrefix': 'gs://ee-docs-demos/external_image_demo/',
    'tilesets': [
      { 'id': '0', 'sources': [ { 'uris': ['b4b3b2.tif'] } ] },
      { 'id': '1', 'sources': [ { 'uris': ['b5b6b7.tif'] } ] },
    ],
    'bands': [
      { 'id': 'red', 'tilesetId': '0', 'tilesetBandIndex': 0 },
      { 'id': 'rededge3', 'tilesetId': '1', 'tilesetBandIndex': 2 },
      { 'id': 'rededge2', 'tilesetId': '1', 'tilesetBandIndex': 1 },
      { 'id': 'green', 'tilesetId': '0', 'tilesetBandIndex': 1 },
      { 'id': 'blue', 'tilesetId': '1', 'tilesetBandIndex': 0 },
      { 'id': 'rededge1', 'tilesetId': '0', 'tilesetBandIndex': 2 },
    ],
  },
}

pprint(request)

Detalles sobre los activos respaldados por COG

Ubicación

La ubicación del bucket de Cloud Storage debe ser una de las siguientes:

La multirregión de EE.UU.
Cualquier región doble de EE.UU. que incluya US-CENTRAL1
La región US-CENTRAL1

Clase de almacenamiento

La clase de almacenamiento del bucket debe ser "Standard Storage".

Permisos para compartir

Las ACL de los recursos de Earth Engine respaldados por COG y los datos subyacentes se administran por separado. Cuando compartes recursos respaldados por COG con colaboradores para su lectura, es responsabilidad del propietario garantizar que se otorgue acceso de lectura al recurso de Earth Engine y a los archivos COG subyacentes.

1. Otorga permisos de lectura al bucket de Google Cloud Storage

Para que los colaboradores lean los activos respaldados por COG, primero deben tener acceso de lectura a los archivos de COG subyacentes en el bucket de Google Cloud Storage. Sin estos permisos, Earth Engine no podrá recuperar los datos. Si un usuario de Earth Engine no puede ver los datos de Google Cloud Storage, Earth Engine mostrará un error del tipo "No se pudo cargar el GeoTIFF en gs://my-bucket/my-object#123456" (donde 123456 es la generación del objeto).

Específicamente, los colaboradores deben tener los siguientes permisos:

storage.buckets.get en el bucket (para recuperar los metadatos y la ubicación del bucket, lo que permite que Earth Engine resuelva correctamente la fuente del activo)
storage.objects.get en el bucket (para leer los datos reales del activo respaldado por COG).

Estos permisos son proporcionados por los roles "Storage Legacy Bucket Reader" y "Storage Legacy Object Reader", entre otros.

Para asignar estos roles a los colaboradores, sigue estos pasos:

Ve a la página de permisos del bucket: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
Haz clic en "OTORGAR ACCESO".
Agrega todos los principales (p.ej., usuarios, grupos, cuentas de servicio) a los que se les debe otorgar acceso de lectura.
Asigna los siguientes roles:
- “Storage Legacy Bucket Reader” (proporciona storage.buckets.get y otros permisos de lectura a nivel del bucket).
- “Lector de objetos heredados de almacenamiento” (proporciona storage.objects.get).
- (Como alternativa, puedes crear un rol personalizado nuevo con solo los permisos storage.buckets.get y storage.objects.get y asignarlo).
Guardar

2. Cómo compartir el recurso de Earth Engine para su lectura

Después de asegurarte de que tus colaboradores tengan los permisos necesarios en el bucket y los objetos de GCS subyacentes, también debes compartir el recurso de Earth Engine. Para obtener más información sobre cómo configurar los permisos de los activos de Earth Engine, consulta la guía de administración de activos de Earth Engine.

Generaciones

Cuando se crea un activo respaldado por COG, Earth Engine lee los metadatos de los TIFFs especificados en el manifiesto y crea una entrada en el almacén de activos. Cada URI asociado con esa entrada puede tener una generación. Consulta la documentación del control de versiones de objetos para obtener detalles sobre las generaciones. Si se especifica una generación, por ejemplo, gs://foo/bar#123, Earth Engine almacenará ese URI de forma literal. Si no se especifica una generación, Earth Engine almacenará ese URI con la generación del TIFF en el momento en que se llamó a ImportExternalImage.

Eso significa que, si se actualiza un TIFF que contiene un recurso externo en GCS (por lo tanto, se cambia su generación), Earth Engine mostrará un error que indica que no se pudo cargar el GeoTIFF en gs://my-bucket/my-object#123456 porque el objeto esperado ya no existe (a menos que el bucket habilite varias versiones de objetos). Esta política está diseñada para mantener los metadatos del activo sincronizados con los metadatos del objeto.

Configuración

En términos de cómo se debe configurar un COG, el TIFF DEBE cumplir con los siguientes requisitos:

Mosaico, en el que las dimensiones de la tarjeta son las siguientes:
- 256 x 256
- 512 x 512
- 1024x1024
- 2048x2048
Se organizan de modo que todos los IFD estén al principio.

Para obtener el mejor rendimiento, haz lo siguiente:

Usa dimensiones de tarjetas de 512 x 512 o superiores.
Incluye descripciones generales de la potencia de 2.

Según los casos de uso previstos, la opción de creación 'INTERLEAVE' puede afectar el rendimiento. Recomendamos usar la intercalación de BAND en todas las circunstancias.

Consulta esta página para obtener más detalles sobre una configuración optimizada.

El siguiente comando gdal_translate convertirá un ráster en un GeoTIFF optimizado para la nube, intercalado en bandas y comprimido con zstd, que tendrá un buen rendimiento en Earth Engine:

gdal_translate in.tif out.tif \
  -co COPY_SRC_OVERVIEWS=YES \
  -co TILED=YES \
  -co BLOCKXSIZE=512 \
  -co BLOCKYSIZE=512 \
  -co COMPRESS=ZSTD \
  -co ZSTD_LEVEL=22 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS

Es posible que se pueda reducir aún más el tamaño del archivo de salida si se especifica un predicador (-co PREDICTOR=2 para tipos de datos de números enteros y -co PREDICTOR=3 para tipos de datos de punto flotante).

Para los usuarios con GDAL >= 3.11, el controlador COG puede producir archivos sin tener que preocuparse por crear y preservar resúmenes.

gdal_translate in.tif out.tif \
  -of COG \
  -co OVERVIEWS=IGNORE_EXISTING \
  -co COMPRESS=ZSTD \
  -co LEVEL=22 \
  -co PREDICTOR=2 \
  -co INTERLEAVE=BAND \
  -co NUM_THREADS=ALL_CPUS \

Cómo crear recursos respaldados por GeoTIFF de Cloud con la API de REST

Nota: La API de REST contiene funciones nuevas y avanzadas que pueden no ser adecuadas para todos los usuarios. Si es la primera vez que usas Earth Engine, te recomendamos que comiences con la guía de JavaScript.

Para crear un recurso respaldado por COG con la API de REST, realiza una solicitud POST al extremo ImportExternalImage de Earth Engine. Como se muestra a continuación, esta solicitud debe estar autorizada para crear un recurso en tu carpeta de usuario.

Cómo iniciar una sesión autorizada

Para poder crear un recurso de Earth Engine en tu carpeta de usuario, debes poder autenticarte cuando realices la solicitud. Puedes usar credenciales del autenticador de Earth Engine para iniciar un AuthorizedSession. Luego, puedes usar AuthorizedSession para enviar solicitudes a Earth Engine.

import ee
import json
from pprint import pprint
from google.auth.transport.requests import AuthorizedSession

ee.Authenticate()  #  or !earthengine authenticate --auth_mode=gcloud

# Specify the cloud project you want associated with Earth Engine requests.
ee_project = 'your-project'

session = AuthorizedSession(
    ee.data.get_persistent_credentials().with_quota_project(ee_project)
)

Cuerpo de la solicitud

El cuerpo de la solicitud es una instancia de un ImageManifest. Aquí es donde se especifica la ruta de acceso al COG, junto con otras propiedades útiles.

Consulta esta guía para obtener detalles sobre cómo configurar un ImageManifest. Es posible definir uno o más Tileset con cada una de las cuales se respalda una o más bandas. Para ImportExternalImage, se admite un máximo de un ImageSource por Tileset.

Consulta este doc para obtener detalles sobre la exportación de COG.

Envía la solicitud

Realiza la solicitud POST al extremo projects.images.importExternal de Earth Engine.

url = f'https://earthengine.googleapis.com/v1alpha/projects/{ee_project}/image:importExternal'

response = session.post(
  url = url,
  data = json.dumps(request)
)

pprint(json.loads(response.content))

Recursos de Earth Engine respaldados por GeoTIFF de Cloud Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Manifiesto de imagen de ejemplo con un Tileset

Más de un Tileset