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

Recursos de Earth Engine respaldados por GeoTIFF de Cloud

En este notebook, se muestra cómo crear recursos de Earth Engine respaldados por GeoTIFFs (COG) optimizados para la nube. 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 activo 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

Se debe poder acceder a los metadatos del bucket para que Earth Engine pueda determinar su ubicación. El usuario que realiza la llamada debe tener el permiso storage.buckets.get en el bucket. Ese permiso lo proporciona el rol "Lector de bucket de almacenamiento heredado", entre otros.

Para asignar este rol, sigue estos pasos: 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 todas las principales a las que se les debe otorgar acceso. 4. Asigna el rol "Storage Legacy Bucket Reader" (o crea un rol personalizado nuevo con solo el permiso storage.buckets.get y asígnale ese rol). 5. Guardar

Clase de almacenamiento

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

Permisos

Las ACL de los recursos de Earth Engine respaldados por COG y los datos subyacentes se administran por separado. Si se comparte un recurso respaldado por COG en Earth Engine, es responsabilidad del propietario asegurarse de que los datos de GCS se compartan con las mismas partes. Si los datos no son visibles, Earth Engine mostrará un error del tipo "No se pudo cargar el GeoTIFF en gs://my-bucket/my-object#123456" (123456 es la generación del objeto).

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 las documentaciones 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, 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 archivo 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 reducir aún más el tamaño del archivo de salida si especificas un predictor (-co PREDICTOR=2 para tipos de datos integrales y -co PREDICTOR=3 para tipos de datos de punto flotante).

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