Introducción a los Data Bundles

Un data bundle es el contenedor de una captura: archivos de entrada sin procesar (nubes de puntos, trayectorias, imágenes, etc.) más las salidas procesadas que la plataforma genera a partir de ellos. La API de RealityConnect expone el mismo ciclo de vida del bundle que usa la interfaz de Prevu3D, de modo que las integraciones pueden crear bundles, subir datos, iniciar el procesamiento, seguir el progreso y recuperar archivos de entrada sin necesidad de un navegador.

Este documento da por supuesto que has completado un flujo OAuth y dispones de un access_token, tu api_url regional y tu organization_id. Consulta las guías de flujo si no los tienes.

Todos los endpoints del flujo de trabajo de data bundles (/v1/bundles/..., /v1/organization/.../data-bundle-input-tree y /v1/nodes/.../bundle) están marcados como experimentales. Espera que el contrato evolucione hasta que pasen a ser estables. Consulta Endpoints experimentales.

Ámbitos requeridos

Ámbito	Se usa para
read:bundle	Obtener el árbol de entradas del dispositivo, listar sesiones de subida, listar opciones de procesamiento, listar registros de procesamiento, listar URLs de descarga de archivos de entrada
write:bundle	Crear un bundle, abrir y finalizar sesiones de subida, iniciar el procesamiento

También necesitas acceso al contenido y permisos de nodo sobre el nodo padre donde se crea el bundle, y sobre el propio bundle para los pasos posteriores.

Flujo integral

flowchart LR
  A["1. Get input tree"] --> B["2. Create bundle"]
  B --> C["3. Upload input files"]
  C --> D["4. List processing options"]
  D --> E["5. Start processing"]
  E --> F["6. Poll processing records"]

Cada paso numerado se corresponde con una guía dedicada:

Paso	Guía	Resumen
1–2	Crear un Data Bundle	Obtener el árbol de entradas del dispositivo, elegir un dbuPath de hoja, crear el bundle bajo un nodo padre
3	Subir datos a un Data Bundle	Abrir una sesión de subida, subir cada archivo a S3 mediante multiparte, finalizar
4–6	Procesamiento y seguimiento	Listar las salidas disponibles, iniciar el procesamiento, sondear hasta que cada trabajo alcance un estado terminal

Descargar archivos de entrada es opcional: úsalo solo cuando necesites recuperar de nuevo los archivos de entrada subidos del bundle.

Modelo de validación

Las reglas estructurales (tipos de archivo obligatorios, extensiones permitidas, dependencias entre tipos, multiplicidad) se describen en el array requirements que se devuelve al abrir una sesión de subida. Es responsabilidad del usuario seguir esa estructura antes de subir y antes de iniciar el procesamiento.

La API de subida registra cada archivo bajo el type que proporcionas y completa la sesión únicamente por recuento. La validación profunda del contenido (si un .las es una captura de dispositivo genuina, si un JSON de metadatos referencia correctamente su imagen) ocurre después de iniciar un procesamiento, no en el momento de la subida. Un archivo con el nombre correcto pero mal formado se sube sin error y falla más tarde durante el procesamiento.

Los fallos de procesamiento causados por una estructura de subida incorrecta (falta de tipos obligatorios, dependencias rotas, extensiones incorrectas, etc.) no serán reembolsados.