Introduction
This tutorial will help you get started with Reality Modeling API v2. You will learn the following:
- Create a job
- Track job progress
- Retrieve job details
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.
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 input data creation step.
You can create an iTwin by clicking the Create iTwin button below. The ID of your iTwin is automatically populated in the 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.
Create a reality data for the job input
An input reality data of an image collection is required for this tutorial. The same can be created by executing the request below. The created reality data's ID is automatically populated in the further requests that need it.
Upload data to reality data container
Once you have created the reality data, you need to upload an image collection to its container. Please follow the steps mentioned here. Use the reality data ID and the iTwin ID obtained from the above steps where required.
Create a job
A job can be created by sending a request to the following endpoint:
Create job request example
We will be creating a FillImageProperties job to transform a collection of images into a scene with known metadata, such as GPS information. For more information on the request payload, please go through the job creation documentation here.
Before executing the request, verify that ImageCollection_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.
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 scene and its ID will be available in the response. The job will upload the output scene 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 Modeling API v2 - Essentials tutorial! You should now be able to create a job, track job progress and retrieve the job details.