Reality Data Properties

This page describes the reality data properties in detail. All the properties appear in the list below. Some properties have an additional section below the table that explains the property further.

Reality data must use the required properties listed below.

• displayName
• type

Authoring

The Authoring property value is not controlled by the Reality Management API, it is left to be managed by the application. The value also does not change the behavior of the API. The purpose of this property is to show if new model data is being uploaded to the reality data. This is particularly useful when a reality data is shared or possibly managed by multiple users. It is up to the creator of the application to implement behavior within the application that uses the Authoring property value.

Classification and Types

Classification

While Classification defines the nature of the reality data, it is related to the Type property.

The following values are currently supported:

• Terrain: Data is a representation of the terrain.
• Imagery: Data is vertical, satellite or orthophoto imagery.
• Pinned: Any non-geographic data that may be pinned to a location on Earth.
• Model: Most common classification. Data is a modelisation of the a real world object or feature.
• Undefined: For non-reality data used as input for reality data creation.

Types

The reality management API supports many different types of reality data. Refer to the table below to see which types are explicitly supported by the API. You can also define your own type if you do not see the one you need in the table.

The Display Type column lists the common name of the various types of reality data.

The Type column lists the strings used by the API. Pass one of these strings when setting the type property through the API. The type indicates the format of the reality data files. The type property is a free string. You can define your own types if needed. However, some specific type keywords are reserved. The type values listed in the table are reserved keywords.

Usually, the type clearly imposes the classification. Point Clouds, Web Ready Scalable Meshs, and Reality Modeling 3MX are necessarily Model data since they are modelisations of the real world. Determine which classification value to use based on your type of reality data by referring to the Classification column. Some types can have different possible classifications. For example, the TIF format supports the storage of Terrain data when the pixel is elevation data or Imagery for satellite data. Likewise, a JPG file can represent an orthophoto (Imagery) or be an oblique picture of a feature (a neighborhood, people, etc.) and can be classified as Pinned data. Similarly, a PDF document could be a written document (Pinned) or a Map (Model).

At this time, not all reality data types can be visualized in the iTwin Viewer. Any types in the table that have a Yes in their iTwin.js Ready column can be visualized. Some types can be converted to a format that can be visualized by the iTwin Viewer. See the Reality Conversion API for more information.

* This is not a type explicitly supported by the API. Instead, it is a “catch-all” meant to show that more file types can be used. The Type property values included in this row are just examples and are not reserved keywords.

** Varies is not a valid classification value. This term is used to show that the classification value depends on the content contained in the reality data.

Root Document

The rootDocument property represents the path to the root document file. The root document is a manifest containing a variety of information about the reality data. For example, you can use the root document to navigate through the other reality data files and display them at various levels of detail. You can think of the rootDocument property as metadata that your application can use to consume the reality data.

The rootDocument property is required to visualize your reality data in an iTwin Viewer. The iTwin Viewer uses the root document file to parse how it should render your reality data. For example, the root document often contains information required to geolocate your reality data. Not all reality data types can be visualized in the Viewer at this time. However, including the rootDocument property can still help your client app navigate through the reality data files even if they cannot be visualized.

If the root document file is at the root of your reality data folder structure, then the property’s value is {root_document_file_name}, where the value of {root_document_file_name} depends on your reality data type. If your reality data file is nested inside sub-folders, then the property’s value is {path_to_root_document}/{root_document_file_name}, with {path_to_root_document} depending on your file structure.

Recognizing which file is the root document requires some level of familiarity with the reality data type you are working with. For the reality data types that can be visualized in the iTwin Viewer, we provide a hint for identifying the root document in the table below.

DataCenterLocation

DataCenterLocation represents a data center location. The Reality Management API supports many different data location geographically located at different places. Usually, the data center location is the same as the iTwin in which the reality data is created.

Data center locations used by Reality Management API are :

• East US
• North Europe
• Southeast Asia
• Japan East
• UK South
• Australia East
• Canada Central
• Central India

Acquisition

The Acquisition object contains the ISO-8601 compliant start time and end time (UTC) of data acquisition, as well as the Acquirer. The Acquirer is a text indicating by whom or what instance or process has acquired the data. See example below:

"acquisition": {
          "startDateTime": "2021-05-12T20:03:12Z",
          "endDateTime": "2021-05-15T05:07:18Z",
          "acquirer": "Data Acquisition Inc."
      },

Extent

The Extent contains the rectangular area on the Earth which encloses the reality data. Defined by the most southwestern point and the most northeastern point. The latitude and longitude types are double. See example below:

"extent": {
              "southWest": {
                  "latitude": 50.1171,
                  "longitude": -122.9543
              },
              "northEast": {
                  "latitude": 50.1172,
                  "longitude": -122.9543
              }
          },

Size

After the model data is uploaded successfully to the reality data, whether due to the creation or a modification of the reality data, the Size property is then scheduled to be recalculated. This process can take a few minutes, so the Size value might not be accurate immediately after the upload is complete. For large model uploads, meaning a few gigabytes or more, this process can take longer.