Processing Service

Component Diagram

The Processing Service turns the raw capture of a finished session (RGB keyframes + depth + telemetry) into a textured mesh and a Cesium 3D tileset. It writes them back to object storage and registers them in PostgreSQL (see Data Model & Storage).

flowchart LR
    ING["«component»<br/>Ingestion Service"]
    Q[("«component»<br/>Job Queue")]
    DB[("«component»<br/>PostgreSQL")]
    S3[("«component»<br/>Object Storage")]
    API["«component»<br/>API Gateway"]

    subgraph PS["«component» Processing Service"]
        direction TB
        JC["«component»<br/>Job Consumer<br/>pull · heartbeat · retry"]
        ORC["«component»<br/>Pipeline Orchestrator<br/>runs stages in order,<br/>updates job status"]

        subgraph STG["Pipeline Stages (IStage)"]
            direction TB
            PREP["«component»<br/>Capture Preparation<br/>verify manifest + sha256,<br/>select keyframes"]
            SFM["«component»<br/>SfM Stage — COLMAP<br/>feature_extractor → sequential_matcher<br/>→ mapper → image_undistorter"]
            MVS["«component»<br/>MVS Stage — OpenMVS<br/>InterfaceCOLMAP → DensifyPointCloud<br/>→ ReconstructMesh → RefineMesh → TextureMesh"]
            EXP["«component»<br/>Export Stage<br/>mesh → mesh.glb,<br/>render preview.webp"]
            TIL["«component»<br/>Tiling Stage<br/>mesh.glb → tileset.json + tiles/*.glb"]
            PREP --> SFM --> MVS --> EXP --> TIL
        end

        SA["«component»<br/>Storage Adapter<br/>S3 download / upload"]
        MR["«component»<br/>Metadata Repository<br/>sessions · meshes · storage_objects"]
        WS[("«artifact»<br/>Local scratch workspace<br/>/work/{session_id}")]

        JC --> ORC
        ORC --> STG
        STG --> WS
        ORC --> SA
        ORC --> MR
    end

    ING -- "IJobPublisher<br/>enqueue(session_id)" --> Q
    Q -- "IJobSource<br/>next() / ack() / fail()" --> JC
    SA -- "IObjectStore<br/>S3 API (HTTPS)" --> S3
    MR -- "IMetadataRepo<br/>SQL (TLS)" --> DB
    ORC -- "INotifier<br/>session READY / FAILED" --> API

Loading

Components

Component	Responsibility	Interfaces
Job Consumer	Takes one job at a time from the queue. Sends a heartbeat while the job runs. Retries failed jobs up to 3 times, then gives up	Uses IJobSource
Pipeline Orchestrator	Runs the stages in order, times each stage, updates the job status and sessions.status, and cleans the scratch workspace	Uses IStage, IObjectStore, IMetadataRepo, INotifier
Capture Preparation	Downloads the capture set using manifest.json, checks each file's checksum and drops blurry or duplicate frames	Implements IStage
SfM Stage (COLMAP)	Estimates camera positions and a sparse point cloud, then produces undistorted images for OpenMVS	Implements IStage
MVS Stage (OpenMVS)	Builds the dense point cloud, the mesh and the texture	Implements IStage
Export Stage	Converts the textured mesh to mesh.glb (TransformScene) and renders a preview image	Implements IStage
Tiling Stage	Splits mesh.glb into a 3D Tiles 1.1 tileset with levels of detail (e.g. 3d-tiles-tools / py3dtiles)	Implements IStage
Storage Adapter	Reads from and writes to the S3 buckets and adds the object metadata headers	Provides IObjectStore
Metadata Repository	Writes storage_objects rows, inserts the meshes row and updates sessions.status, all in one transaction	Provides IMetadataRepo

Pipeline stages and outputs

#	Stage	Tool / commands	Input	Output	Written to
1	Capture preparation	Python	capture/manifest.json, rgb/*.jpg, depth/*.png	Checked frame list	Scratch
2	Sparse reconstruction (SfM)	COLMAP feature_extractor, sequential_matcher, mapper, image_undistorter	Keyframes	sparse/ (cameras, images, points3D), undistorted images	roamview-work/…/work/sparse/
3	Dense reconstruction	OpenMVS InterfaceCOLMAP, DensifyPointCloud	COLMAP dense folder	scene.mvs, scene_dense.ply	roamview-work/…/work/dense/
4	Meshing + texturing	OpenMVS ReconstructMesh, RefineMesh, TextureMesh	scene_dense.mvs	Textured mesh (.ply + texture)	Scratch
5	Export	OpenMVS TransformScene + preview render	Textured mesh	mesh.glb, preview.webp	roamview-assets/…/meshes/{mesh_id}/v{n}/
6	Tiling	3D Tiles tool	mesh.glb	tiles/tileset.json, tiles/{level}/*.glb	roamview-assets/…/meshes/{mesh_id}/v{n}/tiles/
7	Register	Metadata Repository	Object keys + sizes	meshes row (object_storage_key, tileset_key, preview_key), storage_objects rows, sessions.status = READY	PostgreSQL