Using cache in Reality Modeling API

Tutorial result example

Introduction

The goal of this tutorial is to leverage the caching mechanism of Reality Modeling REST API in order to speed up your processing.

In this tutorial, we will create a job to be cached, then use this cache to export another format without reprocessing the complete data.

Info

Skill level:

Advanced

Duration:

15 minutes

Prerequisites

This tutorial assumes that you already have:

1. Cache re-usage and behavior

Cache re-usage

Before creating jobs, it is important to understand how caching works in Reality Modeling. When asked for, a cache will be created if the job is successful. If a job is failed or cancelled, no cache will be created.

A created cache can be used for later jobs in order to reuse it (new exports for example). This is the table of possible workflows:

Cached Calibration
Cached Reconstruction
Cached Full
Calibration
✔️
✔️
Reconstruction
✔️
✔️
✔️
Full
✔️
❌️
✔️

A new calibration job based on a cached reconstruction will failed for example.

Cache behavior

Reality Modeling considers that cache is the truth, and will use it as much as possible. For example, if you submit a full job with a Draft mesh quality to produce a 3MX, then use it as cache for a full job with Extra mesh quality to produce an OBJ, you will have a Draft OBJ result.

Caches are standalone snapshot of a job. They don't depend on each other. Note that for large projects, cache can be very large:

  • Cache upload will then slow marginally your job
  • Usage of Reality Data will increase

Cache can be cleaned: they are uploaded in the Reality Modeling workspace reality data on Reality Management - reality data id is the workspace id, in {JOB_ID}/cache.

2. Create a job that will be cache

In order to tell Reality Modeling we want to create a cache of the job, we just need to specify a setting in the job creation payload.

Request

A new job with cache is created by sending a HTTP POST message to https://api.bentley.com/contextcapture/jobs endpoint with the payload describing the job.

http
POST https://api.bentley.com/contextcapture/jobs HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Request Body

As you can see, we added in the settings a new section cacheSettings with the property createCache set to True.

At the end of the job, if it is successful, the cache will be automatically uploaded to Reality Modeling workspace reality data on Reality Management - reality data id is the workspace id, in {JOB_ID}/cache.

Note the JOB_ID created by this job. It will be useful later for using the cache.

json
{
"type": "Full",
"name": "My Reality Modeling job to be cached",
"workspaceId": "WORKSPACE_ID",
"inputs": [
  {
    "id": "IMAGECOLLECTION_RD_ID",
    "description": "Drone ImageCollection"
  },
  {
    "id": "CCORIENTATIONS_RD_ID",
    "description": "Drone CCOrientations"
  }
],
"settings": {
  "quality": "Extra",
  "processingEngines": 0,
  "outputs": [
    "OBJ"
  ],
  "cacheSettings":
  {
    "createCache": true
  }
}
}

3. Use a cached job

If you want to export your data to another format - 3SM for example, we can use the cached job to speed up the processing time.

Request

A new job with using cache is created by sending a HTTP POST message to https://api.bentley.com/contextcapture/jobs endpoint with the payload describing the job.

http
POST https://api.bentley.com/contextcapture/jobs HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Request Body

As you can see, we added in the settings a section cacheSettings with the property useCache set to JOB_ID_OF_CACHED_JOB. This tells Reality Modeling to download and use the cached job. That way, your job will be faster, since geometry was cached and only need to be converted to 3SM format.

It is possible to combine both properties in cacheSettings. For example you may want to use the cache of a Calibration job for a Full job, and have the result of this job cached for future exports.

json
{
"type":"Full",
"name":"My Reality Modeling job using cache",
"workspaceId":"WORKSPACE_ID",
"inputs":[
  {
    "id":"IMAGECOLLECTION_RD_ID",
    "description":"Drone ImageCollection"
  },
  {
    "id":"CCORIENTATIONS_RD_ID",
    "description":"Drone CCOrientations"
  }
],
"settings":{
  "meshQuality":"Extra",
  "processingEngines":0,
  "outputs":[
    "3SM"
  ],
  "cacheSettings":{
    "useCache":"JOB_ID_OF_CACHED_JOB"
  }
}
}