Verwerking en bewaking

Nadat invoerbestanden zijn geüpload, kan het platform verwerkte uitvoer genereren (gestandaardiseerde puntenwolken, mesh-HLOD’s, photospheres, enzovoort). Deze gids legt uit hoe u verwerkingsopties opsomt, verwerking start en de voortgang pollt totdat elke uitvoer een eindtoestand bereikt.

Er wordt van uitgegaan dat u een bundle met ten minste één voltooide uploadsessie hebt en de read:bundle- en write:bundle-scopes hebt.

---

Hoe het werkt

Verwerking is fire-and-forget: de API zet een verwerkingstaak in de wachtrij en retourneert onmiddellijk.

sequenceDiagram
  participant Client as Client
  participant RCAPI as RCAPI

  Client->>RCAPI: GET processing/options
  RCAPI-->>Client: options + metadata

  Client->>RCAPI: POST processing
  RCAPI-->>Client: accepted or typed error

  loop until all terminal
    Client->>RCAPI: GET bundle/processings
    RCAPI-->>Client: processing records (status, progress)
  end

Endpoints

Methode	Pad	Scope	Doel
GET	/v1/bundles/{bundleId}/processing/options	read:bundle	Mogelijke uitvoertypen en hun metadata opsommen
POST	/v1/bundles/{bundleId}/processing	write:bundle	Verwerking voor gevraagde uitvoer starten
GET	/v1/bundles/{bundleId}/processings	read:bundle	De verwerkingsrecords van de bundle opsommen om de voortgang te pollen
GET	/v1/site/{siteId}/bundles/{bundleId}	read:hierarchy	De bundle met zijn verwerkte uitvoercomponenten (ondertekende links) ophalen

Stap 1: verwerkingsopties opsommen

Ontdek vóór het starten welke uitvoer de bundle kan produceren en hoeveel elke kost.

GET {api_url}/v1/bundles/{bundleId}/processing/options?page=1&limit=20&sortBy=type&sortDir=ASC
Authorization: Bearer {access_token}

Queryparameters

Parameter	Type	Beschrijving
page	number	1-gebaseerde pagina-index (standaard 1)
limit	number	Paginagrootte (standaard 20, maximum 20)
sortBy	string	type of cost (standaard type)
sortDir	string	ASC of DESC (standaard ASC)

De response is een gepagineerde lijst ({ items, total }). Elke optie beschrijft één uitvoertype:

Veld	Betekenis
type	Uitvoercomponenttype dat u meegeeft bij het starten van de verwerking (bijv. StandardizedPointCloud, OgcPointCloudHlod)
hasProcessing	true wanneer er al een verwerking voor deze uitvoer is gestart
cost	Verwerkingskosten in bytes voor betaalde uitvoer; 0 voor free-tier-uitvoer

Voorbeeld:

{
  "items": [
    {
      "type": "StandardizedPointCloud",
      "hasProcessing": false,
      "cost": 734003200
    },
    {
      "type": "OgcPointCloudHlod",
      "hasProcessing": false,
      "cost": 734003200
    }
  ],
  "total": 2
}

Sla uitvoer over waar hasProcessing true is, tenzij u van plan bent opnieuw te verwerken.

Stap 2: verwerking starten

Geef de lijst met uitvoercomponenttypen die u door de pijplijn wilt laten produceren mee, plus een cost-veld dat de totale verwerkingskosten erkent. De server telt de cost-waarden uit stap 1 op voor elk type in requestedComponents en wijst het verzoek af wanneer uw erkenning niet overeenkomt.

Verwerking start asynchroon zodra de kosten zijn geaccepteerd.

POST {api_url}/v1/bundles/{bundleId}/processing
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "requestedComponents": [
    "StandardizedPointCloud",
    "OgcPointCloudHlod"
  ],
  "cost": 1468006400
}

In het bovenstaande voorbeeld is cost 734003200 + 734003200 uit de optielijst van stap 1.

Succesresponse

204 No Content: Verwerking is geaccepteerd en in de wachtrij geplaatst.

Foutresponse

Wanneer verwerking niet kan worden gestart, retourneert de API 409 Conflict met een getypeerde error:

error-waarde	Betekenis
ProcessingCostMismatch	De ingediende cost komt niet overeen met het berekende totaal voor de gevraagde uitvoer
InsufficientProcessingCapacity	De verwerkingslimiet van de organisatie zou worden overschreden
NoInputDataFoundForProcessing	Er zijn geen voltooide invoerbestanden beschikbaar op de bundle
FailedToLaunchProcessing	Pijplijnindiening is mislukt om een onverwachte reden

Voorbeeld:

{
  "error": "ProcessingCostMismatch"
}

Structurele validatie van de geüploade batch (verplichte typen, extensies, afhankelijkheden) wordt na het starten afgedwongen door de verwerkingspijplijn. Als uw uploadsessie is voltooid maar het requirements-contract heeft geschonden, kan de verwerking later mislukken, ook al is elk bestand succesvol geüpload en heeft de startaanroep 204 geretourneerd.

Stap 3: pollen voor voortgang

Poll na een succesvolle start de verwerkingsrecords van de bundle totdat elk een eindtoestand bereikt.

GET {api_url}/v1/bundles/{bundleId}/processings
Authorization: Bearer {access_token}

De response is een lijst ({ items, total }) met elk verwerkingsrecord voor de bundle. Er zijn geen queryparameters; alle records worden in één aanroep geretourneerd.

Elk item volgt één verwerkingstaak:

Veld	Betekenis
id	Identifier van het verwerkingsrecord
status	Pijplijnstatus (zie onderstaande tabel)
progress	Voltooiingspercentage (0–100) tijdens de activiteit
createdAt	Wanneer de taak is gemaakt
updatedAt	Wanneer de taak voor het laatst van toestand is veranderd
launchedById	Id van de gebruiker die de taak heeft gestart, of null
knownErrors	Gestructureerde fouten, elk met een errorCode en de betrokken errorFilepaths (null wanneer niet bestandsspecifiek)

Verwerkingsstatussen

Status	Eindtoestand?	Betekenis
Pending	nee	In de wachtrij, nog niet gestart
Processing	nee	Pijplijn draait
Restarted	nee	Taak is opnieuw gestart en draait weer
Ready	ja	Uitvoer succesvol geproduceerd
Failed	ja	Ongestructureerde pijplijnfout
FailedToLaunch	ja	Taak is nooit in de pijplijn terechtgekomen
KnownError	ja	Gestructureerde validatie- of formaatfout

Poll totdat elk record zich in een eindtoestand bevindt (Ready, Failed, FailedToLaunch of KnownError).

Voorbeeld van een response tijdens de uitvoering:

{
  "items": [
    {
      "id": "3f2b1c4d-8e7a-4b2c-9d1e-0a1b3c4d4e6f",
      "status": "Processing",
      "progress": 42,
      "createdAt": "2026-06-01T14:05:00Z",
      "updatedAt": "2026-06-01T14:12:00Z",
      "launchedById": "b1a2c3d4-5e6f-7a8b-9c0d-1e2f3a2b2c1d",
      "knownErrors": []
    },
    {
      "id": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b2c3d3e4f",
      "status": "Pending",
      "progress": 0,
      "createdAt": "2026-06-01T14:05:00Z",
      "updatedAt": "2026-06-01T14:05:00Z",
      "launchedById": "b1a2c3d4-5e6f-7a8b-9c0d-1e2f3a3b1c1d",
      "knownErrors": []
    }
  ],
  "total": 2
}

Voorbeeld met een bekende fout:

{
  "items": [
    {
      "id": "3f2b1c4d-8e7a-4b2c-9d1e-0a2b3c4d4e5f",
      "status": "KnownError",
      "progress": 100,
      "createdAt": "2026-06-01T14:05:00Z",
      "updatedAt": "2026-06-01T14:48:00Z",
      "launchedById": "b1a2c3d4-5e6f-7a8b-1c0d-2e6f3a4b5c6d",
      "knownErrors": [
        {
          "errorCode": "MissingTrajectory",
          "errorFilepaths": ["scan.las"]
        }
      ]
    }
  ],
  "total": 1
}

De verwerkingslijst bevat niet het uitvoer-type per record. Om voltooide uitvoer terug te koppelen aan hun componenttypen en ondertekende links, haalt u de componenten van de bundle op (zie Verwerkte uitvoer ophalen).

Pollrichtlijnen

• Interval: 1-5 minuten is een redelijke standaard. Verwerking kan meerdere minuten tot enkele uren duren, afhankelijk van de invoergrootte.
• Rate limits: de bundle-endpoints delen een rate-limit-bucket met meerdere andere endpoints. Vermijd pollen onder de minuut.

Verwerkte uitvoer ophalen

Zodra een verwerkingsrecord Ready bereikt, haalt u de bundle op om de uitvoercomponenten en hun ondertekende downloadlinks te verkrijgen. Bundledetails bevinden zich op het hiërarchie-endpoint:

GET {api_url}/v1/site/{siteId}/bundles/{bundleId}
Authorization: Bearer {access_token}

Dit endpoint vereist de read:hierarchy-scope en retourneert de bundle met zijn components-array:

Veld	Betekenis
id	Bundle-id
name	Bundlenaam
components	Eén vermelding per beschikbare component (invoer en verwerkte uitvoer)

Elke component bevat:

Veld	Betekenis
id	Component-id
type	Componenttype, bijv. StandardizedPointCloud, OgcPointCloudHlod
version	Componentversie
signedLink	Ondertekende URL om de component te downloaden; geen auth-header vereist
roots	Toegangspuntpaden binnen de component, indien van toepassing

Voorbeeld:

{
  "id": "a6f75b3c-f261-4b27-9a2a-9a6cc4178a13",
  "name": "ZF capture 2026-06-01",
  "components": [
    {
      "id": "5d6e7f8a-9b0c-1d2e-3f4a-1b3c7d4e8f0a",
      "type": "StandardizedPointCloud",
      "version": "1",
      "signedLink": "https://cdn…/components/…?X-Amz-…"
    }
  ]
}

Een RealityPlan-project stelt dezelfde bundle beschikbaar via GET /v1/reality-plan/{projectId}/bundles/{bundleId} (scope read:twin).

Volledig voorbeeld

import time
import requests

API_URL = "https://<your-regional-api-url>"
TOKEN = "<access_token>"
BUNDLE_ID = "<bundleId>"

headers = {"Authorization": f"Bearer {TOKEN}"}
base = f"{API_URL}/v1/bundles/{BUNDLE_ID}"

# 1. Discover outputs.
options = requests.get(
    f"{base}/processing/options",
    headers=headers,
    params={"page": 1, "limit": 20},
).json()

options_by_type = {item["type"]: item for item in options["items"]}
to_process = [
    item["type"]
    for item in options["items"]
    if not item["hasProcessing"]
]
total_cost = sum(options_by_type[t]["cost"] for t in to_process)
print(f"Launching: {to_process} (cost: {total_cost})")

# 2. Start processing.
response = requests.post(
    f"{base}/processing",
    headers=headers,
    json={"requestedComponents": to_process, "cost": total_cost},
)

if response.status_code == 409:
    raise RuntimeError(
        f"Processing failed to start: {response.json().get('error')}"
    )
response.raise_for_status()  # expect 204

# 3. Poll until every job is terminal.
TERMINAL = {"Ready", "Failed", "FailedToLaunch", "KnownError"}
POLL_SECONDS = 15
TIMEOUT_SECONDS = 3600
deadline = time.time() + TIMEOUT_SECONDS

while time.time() < deadline:
    listing = requests.get(
        f"{base}/processings",
        headers=headers,
    ).json()

    processings = listing.get("items", [])
    for p in processings:
        print(f"  {p['id']}: {p['status']} ({p['progress']}%)")

    if processings and all(p["status"] in TERMINAL for p in processings):
        break

    time.sleep(POLL_SECONDS)
else:
    raise TimeoutError("Processing did not finish within the timeout")

Volgende stap

Om de ruwe invoerbestanden op te halen die zijn geüpload (voor archivering, herverwerking of audit), zie Invoerbestanden downloaden.