Recursos de Earth Engine respaldados por GeoTIFF de Cloud

Logotipo de Colab Ejecutar en Google Colab Logotipo de GitHub Ver el código fuente en GitHub

Earth Engine admite recursos respaldados por GeoTIFF optimizados para la nube (COGs). 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 la creación del recurso, lo que hará que la imagen tenga un mejor rendimiento en las colecciones. El rendimiento de los recursos respaldados por COG es comparable al de los recursos incorporados en casos de uso típicos.

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

(Como alternativa, Earth Engine puede cargar imágenes directamente desde COGs 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, haz lo siguiente:

  1. Coloca tus archivos COG en un bucket de GCS (consulta Ubicación para ver las regiones permitidas).
  2. Escribe un manifiesto de carga de imágenes
  3. 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 muestra con un Tileset

El ImageManifest más simple es aquel que tiene un solo Tileset. Si no se especifican bandas, el recurso 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 recurso 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 las diferentes bandas tengan diferentes resoluciones o tipos de datos. Las bandas se pueden enumerar en cualquier orden desde cualquier Tileset disponible. En el siguiente ejemplo:

  • "b4b3b2.tif" tiene una escala de 10 m, mientras que "b5b6b7" tiene una escala de 20 m.
  • El orden de las bandas del recurso resultante se mezcla de los COGs 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 recursos 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 birregional 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 se comparten recursos respaldados por COG con colaboradores para su lectura, es responsabilidad del propietario asegurarse de que se otorgue acceso de lectura tanto al recurso de Earth Engine como a los archivos COG subyacentes.

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

Para que los colaboradores lean los recursos respaldados por COG, primero deben tener acceso de lectura a los archivos COG subyacentes en el bucket de Google Cloud Storage. Sin estos permisos, Earth Engine no podrá recuperar los datos por ellos. Si los datos de Google Cloud Storage no son visibles para un usuario de Earth Engine, Earth Engine mostrará un error con el formato "Failed to load the GeoTIFF at gs://my-bucket/my-object#123456" (en el que 123456 es la generación del objeto).

En particular, 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 recurso).
  • storage.objects.get en el bucket (para leer los datos reales del recurso respaldado por COG).

Estos permisos se proporcionan a través de las funciones "Storage Legacy Bucket Reader" y "Storage Legacy Object Reader" respectivamente, entre otras.

Para asignar estas funciones a los colaboradores, haz lo siguiente:

  1. Ve a la página de permisos del bucket: https://console.cloud.google.com/storage/browser/{MY-BUCKET};tab=permissions
  2. Haz clic en "OTORGAR ACCESO"
  3. Agrega todos los principales (p.ej., usuarios, grupos, cuentas de servicio) a los que se debe otorgar acceso de lectura.
  4. Asigna las siguientes funciones:
    • "Storage Legacy Bucket Reader" (proporciona storage.buckets.get y otros permisos de lectura a nivel del bucket).
    • "Storage Legacy Object Reader" (proporciona storage.objects.get).
    • (Como alternativa, puedes crear una nueva función personalizada solo con los permisos storage.buckets.get y storage.objects.get, y asignarla).
  5. Guardar

2. Comparte 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 recursos de Earth Engine, consulta la guía de administración de recursos de Earth Engine.

Generaciones

Cuando se crea un recurso respaldado por COG, Earth Engine lee los metadatos de los TIFFs especificados en el manifiesto y crea una entrada de almacén de recursos. Cada URI asociado con esa entrada puede tener una generación. Consulta los documentos de 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 algún TIFF que comprende un recurso externo en GCS (y, por lo tanto, cambia su generación), Earth Engine mostrará un error "Failed to load the GeoTIFF at 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 recurso sincronizados con los metadatos del objeto.

Configuración

En cuanto a la forma en que se debe configurar un COG, el TIFF DEBE ser lo siguiente:

  • En mosaicos, en los que las dimensiones de los mosaicos son las siguientes:

    • 256x256
    • 512x512
    • 1024x1024
    • 2048x2048

  • Organizado de modo que todos los IFD estén al principio.

Para obtener el mejor rendimiento, haz lo siguiente:

  • Usa dimensiones de mosaicos de 512x512 o superiores.
  • Incluye resúmenes de potencias de 2.

Según los casos de uso previstos, la "INTERLEAVE" opción de creación 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 por banda 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 reducir aún más el tamaño del archivo de salida si se especifica un predictor (-co PREDICTOR=2 para tipos de datos 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 conservar 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 \

Crea recursos respaldados por Cloud GeoTiff 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 eres nuevo en 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.

Inicia una sesión autorizada

Para poder crear un recurso de Earth Engine en tu carpeta de usuario, debes poder autenticarte como tú mismo cuando realices la solicitud. Puedes usar credenciales del autenticador de Earth Engine para iniciar una AuthorizedSession. Luego, puedes usar la 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í 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, cada uno de los cuales respalda una o más bandas. Para ImportExternalImage, se admite como máximo un ImageSource por Tileset.

Consulta este documento para obtener detalles sobre la exportación de COGs.

Envía la solicitud

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

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))