Using cache in ContextCapture API

Introduction

The goal of this tutorial is to leverage the caching mechanism of ContextCapture 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

Before creating jobs, it is important to understand how caching works in ContextCapture. 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 CalibrationCached ReconstructionCached Full
Calibration✔️✔️
Reconstruction✔️✔️✔️
Full✔️❌️✔️

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

ContextCapture 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 ContextCapture workspace reality data on Reality Data - reality data id is the workspace id, in {JOB_ID}/cache.

2. Create a job that will be cache

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

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

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 ContextCapture workspace reality data on Reality Data - 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 CCCS job to be cached",
  "workspaceId": "WORKSPACE_ID",
  "inputs": [
    {
      "id": "IMAGECOLLECTION_RD_ID",
      "description": "Drone ImageCollection"
    },
    {
      "id": "CCORIENTATIONS_RD_ID",
      "description": "Drone CCOrientations"
    }
  ],
  "settings": {
    "meshQuality": "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.

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

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 ContextCapture 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 CCCS 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"
    }
  }
}

Continue learning

Congratulations for completing the ContextCapture cache tutorial! You should now be able to create and use cached job for faster processing. To go further and use ContextCapture to its maximum potential, you can check the following tutorials.

More resources that you may like

Projects API

Project is necessary for using ContextCapture API. You can check its possibilities.

Reality Data API

Reality Data API is necessary for uploading inputs for ContextCapture, and downloading outputs.