Saltar al contenido principal

wiki-Documentacion

Ver en Git

Documentacion

title: Documentación​

Planet Ingest

ver. 11 enero 2024

  1. Cómo funciona planet
  2. APIs
  3. Cómo funciona la integración
  4. orders
  5. Subscriptions
  6. Procesamiento
  7. Addons
  8. Sistema
  9. Infraestructura
  10. Problemas conocidos

Cómo funciona planet​

https://developers.planet.com/docs/data/planetscope/

Las imagenes de Planet que usamos son las de PSScene. Dentro de este tipo hay distintos assets como por ejemplo la surface-reflectance, la capa de nubes, rgb, corregidas, etc.

Auravant descarga el product_bundle analytic_sr_udm2 que contiene los assets ortho_analytic_4b_sr (imagen de 4 bandas) y la máscara de datos ortho_udm2.

Estas imágenes pueden haber sido capturadas con disitntos sensores. El de última generación y que más disponibilidad tiene actualmente es el PSB.SD.

Hacia atrás en el tiempo no tiene la mejor disponibilidad.

Los disitntos tipos de sensores son muy distintos entre sí, por lo que usamos únicamente este.

Planet luego disponibilizó una herramienta de harmonización para hacer más comparables las imágenes de disitntos sensores pero no lo probamos.

APIs​

Las llamadas a las apis se realizan con una API KEY, que se obtiene desde la cuenta de planetlabs. La integración actualmente usa la KEY de bruno.marengo@auravant.com

La documentación en la web explica bien todos los puntos, pero en este documento se menciona lo básico.

Hay dos maneras de obtener imágenes: Subscriptions y Orders.

  • Mediante Orders se hace una búsqueda de imágenes y luego una consulta para solicitarlas. Planet las procesa de manera async y se hace polling hasta que las mismas estén listas.
  • Mediante Subscriptions se le indican filtros y Planet procesará día tras día todas las imágenes que coincidan con ese filtro. Se hace una consulta periódica para saber si la subscripción tiene nuevos resultados.

Planet guarda las imágenes procesadas en S3. Para eso se le indican en las solicitudes de procesamiento las credenciales y un bucket donde guardarlas.

Tanto las credenciales como el bucket tienen que tener bien seteados los permisos para que no puedan hacer otra cosa que no sea guardar objetos en ese único bucket.

Orders y Subscriptions guardan los resultados en estructuras distintas

Cómo funciona la integración​

Básicamente el alta de un lote HD se corresponde con una Subscription de planet para procesar las nueva imágenes. La única salvedad es que el histórico no se puede cargar fácilmente con una Subscription, por lo que en el alta de un lote se hace una Order de todas las imágenes pasadas.

La Subscription se registra en nuestra base de datos para el seguimiento.

Orders​

Primero se realiza una búsqueda de las imágenes filtrando por

  • fecha (de captura)
  • geometría (el filtro es de un intersect, por lo que puede haber imágenes parciales)
  • instrumento PSB.SD
  • que contenga los assets de ortho_analytic_4b_sr y ortho_udm2

Luego se crean Orders con los items obtenidos.

  • Se crea una Order por cada 500 items ya que es el máximo que se permite por orden.
  • Se solicita el product_bundle analytic_sr_udm2
  • Las Orders se solicitan de tipo partial ya que permitimos que falle alguna imagen del pedido.
  • Los archivos se guardarán bajo el prefijo orders/ en S3

En una orden se pueden solicitar pasos de post-procesamiento. En este caso se pide clip que es que corte la imagen a la forma del lote.

IMPORTANTE!: ESTE AREA ES EL QUE SE CONSUME DE LA CUOTA

Luego se hace polling cada 15 minutos hasta 15 veces hasta que esté lista.

La orden puede fallar (rara vez ha sucedido) o no estar lista luego de los 15 intentos.

la orden no se registra en la BD por lo que no se tiene tracking ante fallas

Una vez que la orden está lista, se procesa para el lote. Con la orden terminada se guarda un manifest.json con información sobre los items solicitados.

El manifest describe todos los archivos procesados y su ubicación en S3. Se agrupan los archivos que correspondan a un mismo item, creándose una capa por cada uno. Esa capa se crea con la metadata correspondiente al archivo de metadata del item.

Subscriptions​

La Subscription se crea con fecha de inicio futura. La fecha de finalización también puede ser nula para indicar que no termina.

Se definen para la Subscription los mismos filtros que para las órdenes. La diferencia es que no se usan bundles sino se piden los assets individuales ortho_analytic_4b_sr y ortho_udm2

Una vez creada, se guarda el subscription_id para luego hacer seguimiento de los resultados.

Los resultados que vayan apareciendo se guardarán en S3

La Subscription estará en estado running mientras esté activa y luego podrá pasar a failed (nunca ha pasado), cancelled o completed.

Por cada Subscription se debe consultar un endpoint para obtener los últimos resultados. Si bien podría verificar S3, Planet aconseja consultar en endpoint para saber si efectivamente se terminó de subir. En cada consulta se filtran por fecha para no traer todos cada vez. Cada resultado es un item nuevo con sus archivos.

Cada nuevo resultado se almacena en la BD. Además se crea una capa por cada uno y se vinculan ambos registros. Esa capa se crea con la metadata correspondiente al archivo de metadata del resultado.

Shapes​

Se solicita la forma del lote junto con un buffer para evitar "agujeros" en los bordes en reproyecciones. Para eso se transforma el shape 4326 de la BD a su correspondiente UTM (metros) y aplica un buffer de 5.5 metros, que termina siendo aprox 2 pixels.

Planet no permite alta de Orders ni Subscriptions de shapes:

  1. con mas de 500 puntos
  2. con superficie menor a 1 ha.

Por eso, la integración:

  1. simplifica la forma buffereada, asegurándose que ningun borde se reduzca más alla de la forma original.
  2. intenta "salvar" los lotes con superficie < 1ha aplicando recursivamente un buffer de 1m hasta 50 veces. Si luego de esos 50 buffers el lote aún no supera la ha, levanta error.

Procesamiento​

Tanto de orders como de Subscriptions, el resultado es el mismo: una lista de items, cada uno con sus outputs (imagen, mascara y metadata), asociadas a una capa (layer_id).

El procesamiento luego es simple:

Una vez procesada, se mueven los outputs al bucket de capas de planet, desapareciendo del bucket de resultados de planet.

Para cada item procesado, a partir del layer_id se actualizan los resultados de la capa en la base de datos.

Addons​

El alta de Planet se maneja con cuota de hectareas. La cuota se asigna mediante addons a un usuario o espacio, que luego sponsorea las altas deduciéndose de su cuota el area correspondiente de cada lote.

Al momento de dar un alta, se debe indicar un sponsor y se verifica la cuota disponible sumandose todas las cuotas y restandose todos los consumos de ese sponsor.

Al registrarse el alta, se registra el addon de consumo sponsoreado con el dueño del lote como el usuario asignado. La cantidad de addon consumida es la del area del lote.

Tener en cuenta que por el buffer, el area solicitada a planet es mayor, pero el area que se le cuenta al cliente es la del lote

Además, el lote no puede tener más de una subscripción en curso.

Sistema​

El sistema se basa en una API, un Celery Worker y un Celery Beat.

La API expone unos endpoints internos para el alta de lotes, validaciones y para disparar la ejecución de ciertas tareas.

En la API del alta se hacen las validaciones de quota y se crea la subscripción. Luego se dispara la tarea async de creación de la Order del histórico.

El worker ejecuta las tareas:

  • history_fetcher: crea la orden y dispara la tarea de polling
  • poll_order: verifica el estado de la orden, si está lista la procesa y sino se dispara a si misma en 15 minutos
  • subscription_status_updater: busca todas (o una) Subscription y consulta su estado en Planet para actualizarlo en la BD
  • results_fetcher: busca todas las Subscriptions de la BD y consulta los últimos resultados disponibles en Planet. En caso de haber nuevos, crea las capas y dispara las tareas de procesamiento
  • process_and_store_image: recibe datos del lote, capa y los outputs de un item y procesa la imagen
  • results_updater: Recibe el resultado de ejecución de una o varias process_and_store_image y actualiza las capas en la BD

Al dispararse las tareas de procesamiento de imágenes, se utiliza un Celery Chord. Esto es un listado de tareas (process_and_store_image) que se pueden ejecutar en cualquier orden y que una vez que se ejecutaron todas, se llama a una función de callback (results_updater) pasandole el resultado de todas ellas.

Se limita la cantidad de imagenes a procesar a LAYERS_PER_CHORD para acotar el daño en caso de algun error de conexión. Además permite manejar la cantidad de consultas que se hacen a la BD (Cuando menos capas por CHORD, más consultas se harán)

Celery Beat dispara las tareas:

  • results_fetcher: 4 veces por día
  • subscription_status_updater: 2 veces por día

Problemas conocidos​

La baja de addons.​

Cuando se quiere dar de baja una addon de cuota de Planet, se piensa poner fecha fin en la BD al item de cuota para que le deje de contar al usuario como una compra. El problema es que las subscrpciones en Planet siguen corriendo. Para estos casos, hay una función cancel_subscription para cancelar las Subscriptions.

Aún así, notar que todos los consumos del addon quedan con la fecha original de la cuota.

Por otro lado, dar de baja sólo un consumo implica el mismo problema y la necesidad de cancelar la Subscription en Planet.

En un momento se quizo automatizar esto pero los casos posibles son muchos y se debe definir bien para poder hacerlo bien.

Baja de suscripciones en planet​

Otra manera de dar de baja es utilizando el script features/extras/set_subscriptions_end_date.py. Este busca los addons en la BD con la función list_addons, y setea una fecha de end_date FUTURA tanto en la BD como en Planet.

La idea es modificar la query de la función list_addons para buscar las suscripciones que se desee (por ejemplo buscar por workspace_id en vez de user_id, o buscar una puntual) para luego pasarlo a las otras funciones que actualizan las fechas.

Polígonos por campaña​

Esta integración busca la última forma del lote que se activa para solicitar a Planet. Una vez que se solicita, Planet busca y corta las imagenes en función de esa forma.

Si cambia la forma de un lote con HD activada, la forma que quedó solicitada a Planet va a ser distinta:

  • Si la nueva forma de la BD está contenida por la forma solicitada, no hay problema. Planet procesa una imagen más grande
  • Si la nueva forma de la BD NO está contenida por la forma solicitada, la función de procesamiento se encontrará con que la imagen no llega a cubrir la totalidad del lote y la marcará como imagen parcial.

En ese último caso, el lote dejará de tener imágenes nuevas.

La solución ahí es utilizar la funcion refresh_subscription que busca la nueva forma de la BD y actualiza la Subscription.

Alternativamente (y probablemente mejor) se podría guardar el id de la forma que se solicita a Planet y utilizar siempre esa al procesar la imagen. El usuario verá imágenes incompletas en caso de haber agrandado el lote.

Actualización de forma e índices NDVI​

Al cambiar la forma del lote, cuando se procesen las imágenes se va a calcular el NDVI y guardar en la BD para la nueva forma, mientras que los valores que ya están corresponden a la forma anterior.

Reprocesamiento​

En caso de querer reprocesar ya sea porque falló algo y le faltan imágenes, o porque hay que reprocesar un lote que cambió de forma o porque se quieren imagenes nuevas, se debe utilizar Orders.

Si se desea enviar una nueva order, con la función history_fetcher(field_id, start_date, end_date, key_id=None) que se utiliza en el alta de lote, simplemente se especifican las fechas y disparando esa tarea en Celery se procesa todo el rango de fechas.

Cuando el histórico no se termina de cargar, es muy probable que el polling de ordenes haya fallado. En este caso se puede re-disparar el polling de todas las órdenes de un lote mediante la función trigger_order_polling del archivo features/extras/reprocess_orders.py.

TODO: Dado que Orders es la manera predeterminada para pedir imagenes, amerita diseñar un modelo de datos que guarde las Orders que se generan y le haga seguimiento.