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.
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.
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.
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.
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:
The example request includes the following properties in its body:
type
is Cesium3DTiles
.electrical_substation.json
in the Scene
folder making the rootDocument
value Scene/electrical_substation.json
.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.
The endpoint accepts the following parameters:
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.
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.
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.
The example request includes the following parameters:
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.
The example request accepts the following parameters:
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.
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.
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.
- Choose a
- 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.