Introduction
This tutorial will help you get started with Reality Analysis API v2. By the end of this tutorial, you should be able to prepare and run an Objects2D job to identify any objects within the provided image collection.
Before you begin
Ensure you meet the following requirements before starting the tutorial.
- Knowledge of the Reality Management API.
- Knowledge of the basics of iTwins API.
- Knowledge of Image Collection and Context Scene
- You should have an image collection to be processed.
Set up your tutorial environment
This section guides you through the prerequisites for the tutorial so you can make sample API requests.
Authorize your requests
This tutorial provides an access token enabling you to complete the tutorial without setting up your own authentication.
Click Authorize to generate the token. Your token is automatically populated for the remainder of this tutorial.
Create an iTwin
You must have an iTwin to proceed with this tutorial. If you already have an iTwin created, you may proceed with the job input preparation step.
You can create an iTwin by clicking the Create iTwin button below. The ID of your iTwin is automatically populated in the further requests that need it.
Make sure to save the iTwin ID. Click the Copy button to copy the ID and save it somewhere safe. When using the iTwin ID, make sure to remove the iTwin ID label from the pasted copy.
Prepare job inputs
For this tutorial, we will require:
- A reality data of type CCImageCollection. This will be an image collection which will contain the images to be analyzed.
- A reality data of type ContextScene. This will be a context scene file containing the references to the images to be analyzed. We will be using this reality data as an input for our Objects2D job.
1. Prepare Image Collection Reality Data
First, we have to create a reality data for the image collection which you have. Please execute the following request to create the reality data. Before executing the request, verify whether the iTwinId value is pre-populated in the request body. If it is missing, replace it with the appropriate iTwin ID created earlier in this tutorial.
Make sure to save the ID of the created reality data as we will be referencing it from the context scene file.
Once you have created the reality data, you need to upload the image collection there. Please follow the steps mentioned here to upload the images. Use the reality data ID and the iTwin ID obtained from the previous steps where required.
2. Prepare ContextScene Reality Data
Now, we need to create a reality data for a context scene which will have references for the images to be analyzed. The same can be created by executing the request below. Before executing the request, verify whether the iTwinId value is pre-populated in the request body. If it is missing, replace it with the appropriate iTwin ID created earlier in this tutorial.
The ID of the created context scene reality data will be automatically populated in the further requests that need it.
Once you have created the reality data, you need to upload a ContextScene.json file there. Please refer to the documentation here and prepare one. You need to add references to the images from the previously created image collection reality data.
We have provided a sample content for the ContextScene.json file below. The same can be used after updating the paths of images and the references according to your image collection reality data.
Once the ContextScene file is prepared, please upload it to the reality data created by following the steps mentioned here. Use the reality data ID and the iTwin ID obtained from the previous steps where required.
Create a job
A job can be created by sending a request to the following endpoint:
Create job request example
An Objects2D job can be created by executing the request below. Before executing the request, verify that ContextScene_Reality_Data_ID and iTwinId are pre-populated in the request body. If either value is missing, replace it with the appropriate Reality Data ID or iTwin ID created earlier in this tutorial.
We are using a Detector @bentley/bentley-traffic-signs-o2d from the Detector Library for this job. This detector identifies the traffic signs from the input photos. You can use any other detector from the detector library.
The API will respond with a 201 Created status code if the request is successful.
In response, the job state can be:
- Active : It means that the job has started processing.
- Queued : It means that there is a very high demand in your region. It will be active as soon as a resource is available for processing.
A reality data with an empty container will be created for the output and its ID will be available in the response. The job will upload the output Objects2D data to this container after successful completion.
The ID of your job is automatically populated in the further requests that need it.
Track job progress
The progress of a job can be obtained by sending a request to the following endpoint:
Track job progress request example
The API will respond with a 200 OK status code if the call is successful.
The response will give you the progress percentage of the job with its state.
Retrieve job details
The details of a job can be obtained by sending a request to the following endpoint:
Retrieve job details request example
The API will respond with a 200 OK status code if the call is successful.
What you've learned
Congratulations for completing the Reality Analysis API v2 - Essentials tutorial! You should now be able to create a job, track job progress and retrieve the job details.