Reality Management API - Essentials - Tutorials

Introduction

This tutorial covers the essential topics for using the Reality Management API. You will learn the following:

How to create a reality data.
How to upload data files to your reality data.
How to query your created reality data.

You will also see how your reality data looks in an iTwin Viewer application.

Use sample data

This tutorial walks you through using the Reality Management API. We recommend using sample names and data while learning the API for this tutorial. The same instructions apply when using the Reality Management API for your production applications.

Before you begin

Ensure you meet the following requirements before starting the tutorial:

Be familiar with the concept of an iTwin. See the iTwin API Overview for more information.
Be familiar with the concept of Reality Data. See the Reality Management API Overview for more information.
(Optional) Be familiar with Azure Blob Storage. You can complete this tutorial regardless of your Azure knowledge level.
(Optional) An API client tool that allows you to execute HTTP calls. For ease of use, we have added executable code blocks enabling you to make sample requests within the tutorial. API client tools are helpful when testing your real-world applications.

Set up your tutorial environment

This section guides you through the pre-requisite steps for the tutorial so you can make sample API requests. It also provides sample data for you to use during the tutorial.

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 in the headers of the sample requests.

Application permissions

When using this API to authorize your own application, you need to define the scopes and permissions for your solution. See the Authorization overview for more information.

Create an iTwin

To use the Reality Management API, you must associate your reality data with an iTwin.

Click Create iTwin.

The ID of your iTwin is automatically populated in the requests that need it. Make sure 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.

Manually create an iTwin

An iTwin is required when using this API in your own applications. For more information on creating an iTwin, see the Create iTwin reference.

Get your data files

You must have reality data files on your computer to follow this tutorial. We have provided some sample files for you to use.

Click Download Data to download the sample reality data files.

There are a lot of data files. It may take a few minutes for them to download.
Please unzip the folder Scene.zip after the download completes.

There are a lot of data files. It may take a few minutes for them to unzip.

Generate your own files

Provide your own reality data files when using the Reality Management API in production applications. Please see the Reality Modeling API for more information.

Create a reality data

The Reality Management API enables you to create and manage reality models and data. A reality model is the real world environment visualized in a reality data viewer and is stored as data files. Reality data is a place to store your reality model and any information describing that reality model.

Send a request to the create reality data endpoint:

POST

https://qa-api.bentley.com/reality-management/reality-data/

The example request includes the following properties in its body:

iTwinId

The iTwin ID is a unique identifier associating your reality data with your iTwin. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.

displayName

Yes

The user friendly name of the reality data.

type

Yes

Indicates the format of your reality data files. Find the list of available types in the types table on the Reality Data Properties page. For the sample files provided, the type is Cesium3DTiles.

rootDocument

The path to the root document file. The root document file is a manifest containing extra information about the reality data and is used by the Visualization service to visualize your reality model. See the Root Document section on the Reality Data Properties page for more information. In our sample, the root document file is electrical_substation.json in the Scene folder making the rootDocument value Scene/electrical_substation.json.

More properties

This step contains the bare minimum properties required for this tutorial. Many more properties are available and detailed in the Create reality data reference.

Create reality data request example

The ID of your reality data is automatically populated in the following requests that need it.

Upload your reality model to the reality data's container

A reality data provides basic information about your reality model through its properties (such as what is the type/format of the files, where is the root document, etc). When you created your reality data, a container in the cloud was also created to serve as a home for your reality model.

This section details how to access and upload reality data files to that container.

Get your reality data's container

The Reality Management API exposes two endpoints you can use to access your reality data's container. One endpoint provides read access to the container. The other endpoint provides write access. However, both endpoints accept the same parameters. The container is hosted in Azure Blob Storage.

We want write access so you can upload the reality data files to the container. For more information on read access, please see the Retrieve read access to reality data container reference.

For write access, send the request to the write access endpoint.

GET

https://qa-api.bentley.com/reality-management/reality-data/{id}/writeaccess?iTwinId={iTwinId}

The endpoint accepts the following parameters:

Yes

The ID of your reality data. Reminder: The ID is pre-populated in this tutorial if you completed the Create reality data request example.

iTwinId

The ID of your iTwin. It affects the permissions for accessing the container as discussed in the Retrieve write access to reality data container reference. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.

Retrieve write access to reality data container request example

The href returned in the response is a SAS URI with write access to the Azure blob hosting your reality data's container.

Understanding the SAS URI

Understanding the SAS URI is not required to use it for the API or tutorial. You can learn more about Azure Storage SAS URI's from Microsoft's SAS token documentation.

Upload your files to the container

Microsoft has several workflows available for uploading data to an Azure blob. Exhaustively exploring these options is beyond this scope of this tutorial. However, we will point you to a couple of workflows that will allow you to upload the previously downloaded Scene folder with as little friction as possible.

Uploading the files via the command line

AzCopy is a command line tool that you can use to upload files to your storage account. This is our recommended way to upload your files for the tutorial.

To upload your reality data files, follow these steps:

Ensure you have clicked the Download Data button and unzipped the downloaded Scene folder.
Download AzCopy.
Run AzCopy via the command line. azcopy copy "{path_to_downloaded_Scene_folder}" "{SAS_URI_from_the_previous_response}" --recursive

Microsoft has an example in the Use a SAS token section of their Get started with AzCopy page. Be sure to at least read the Run AzCopy link. It points out restrictions on where you can run AzCopy.

Uploading the files graphically

Microsoft has a desktop application called Azure Storage Explorer that you can download to have a graphical experience of dragging and dropping your reality data files into your blob container.

To upload your reality data files using Azure Storage Explorer, follow these steps:

Ensure you have clicked the Download Data button and unzipped the downloaded Scene folder.
Download the application by going to Microsoft's Azure Storage Explorer website and selecting your operating system.
Once you have the application downloaded and open, you can follow Microsoft's instructions in the Attach to an individual resource and Shared access signature (SAS) URL sections of their Get started with Storage Explorer page. The resource you want to connect to should be "Blob container" (or something similarly named).
After following Microsoft's instructions and connecting, drag and drop the Scene folder into the container.

Programmatic options

The above two options are easiest for uploading your reality model quickly. However, if you are attempting to programmatically upload a reality model in your application, we recommend using Microsoft's Azure Blob Storage client libraries. Microsoft has Azure Blob Storage client libraries for .NET, Java, Python, JavaScript, C++, and Go. If you are using a language that does not have a client library, check out the raw Azure Blob Storage REST API.

Query your created reality data

The Reality Management API exposes two endpoints you can use to query your reality data.

Query reality data associated with an iTwin

This endpoint returns the first 100 reality data associated with the iTwin specified in the request. It only returns reality data that you have access to, relative to your organization's access rights.

To query all reality data associated with your iTwin, send a request to the get iTwin's reality data endpoint.

GET

https://qa-api.bentley.com/reality-management/reality-data/?iTwinId={iTwinId}

The example request includes the following parameters:

iTwinId

The ID of your iTwin. If you do not provide your iTwin ID, then the request instead returns the first 100 reality data that you have access to across all iTwins. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.

More properties

This step contains the bare minimum parameters required for this tutorial. More parameters are available and detailed in the documentation for the Get iTwin's reality data endpoint.

Get iTwin's reality data request example

At this point, only the reality data you created during this tutorial should be listed.

Query a specific reality data

This endpoint takes a reality data ID and returns that specific reality data.

To query a specific reality data, send a request to the get reality data metadata endpoint.

GET

https://qa-api.bentley.com/reality-management/reality-data/{id}?iTwinId={iTwinId}

The example request accepts the following parameters:

Yes

The ID of your reality data. Reminder: The ID is pre-populated in this tutorial if you completed the Create reality data request example.

iTwinId

The ID of your iTwin. It affects the permissions for querying the reality data as discussed in the Get reality data metadata reference. Reminder: The ID is pre-populated in this tutorial if you clicked the Create an iTwin button during setup.

Get reality data metadata request example

Visualize your newly uploaded reality data

After creating a reality data and uploading your reality model to its container, you can now visualize your reality data in an iTwin Viewer.

Click View Reality Data to see the reality model you created in a Viewer.

Viewer Errors

The reality data viewer will attempt to display helpful error messages if it detects a potential mistake. To resolve some of the errors, please check the following:

Ensure that you have completed all steps of the tutorial before clicking the View Reality Data button.
Verify that the rootDocument path specified during the Create a reality data step is still valid based on the structure of the files you uploaded during the Upload your reality model to the reality data's container step.

The official Reality Data sample provides an example on attaching and visualizing reality data in an iTwin Viewer. Check out that sample, our iTwin.js documentation, the @itwin/reality-data-client package, and the reality-capture web application for how to visualize your reality data in your own application.

Reality Data Location

If you are building your own iTwin Viewer application, it is helpful to know the location of your reality data. The sample reality data has the following coordinates (with longitude and latitude in degrees and height in meters):

Longitude: 4.668735091306921&deg
Latitude: 45.265122669456325&deg
Height: 456.72571760937933 meters

What you've learned

In this tutorial, you should have learned:

How to Create a reality data:
- Choose a displayName.
- Choose the type from types table.
- Include the rootDocument path.
- Execute the Create reality data request.
How to Upload your reality model to the reality data's container to the reality data's container:
- Supply your reality data's ID and your iTwin's ID for the Retrieve write access to reality data container request.
- Upload your reality data files using the command line, a graphical application, or programmatically.
How to Query your created reality data for your reality data(s)
- Query all reality data associated with your iTwin by providing your iTwin's ID to the Get iTwin's reality data endpoint.
- Query a specific reality data by providing that reality data's ID and your iTwin's ID to the Get reality data metadata endpoint.

This tutorial provided the background knowledge required for you to:

Learn how to Visualize your newly uploaded reality data in an iTwin Viewer by checking out the official Reality Data sample.

More resources that you may like

Reality Management API

The reference documentation for the reality management API. Allows you to manage your reality data and is covered in this tutorial.

Reality Modeling API

The reference documentation for the reality modeling API. Allows you to turn images and point clouds into reality meshes, orthophotos and others.

Reality Analysis API

The reference documentation for the reality analysis API. Allows you to run AI/ML on photos, maps, meshes or point clouds.