Table of contents
Reality Management
Download API definition:

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
Property
Type
Required?
Read-only?
Description
id
string(guid)
Generated
Read-only
Guid Identifier of the reality data. This identifier is assigned by the service at the creation of the reality data. It is also unique.
displayName
string
Required
Modifiable
The name of the reality data. This property may not contain any control sequence such as a URL or code.
dataset
string
Optional
Modifiable
This field can be used to define a loose grouping of reality data. This property may not contain any control sequence such as a URL or code.
group
string
Optional
Modifiable
This field can also be used to define a second level of grouping.This property may not contain any control sequence such as a URL or code.
description
string
Optional
Modifiable
A textual description of the reality data. This property may not contain any control sequence such as a URL or code.
tags
array
Optional
Modifiable
Textual identifiers to identify reality data.
dataCenterLocation
string
Generated
Read-only
Identifies the Azure Data Center used. For details about Data Center refer to the DataCenterLocation section below.
rootDocument
string
Optional
Modifiable
Used to indicate the root document of the reality data. The root document can be in a subfolder and is then specified. e.g. "Tile_Root.json" or "Folder1/SubFolder1/File.json" are valid values. The service reserves the right to validate the existence of the indicated file. See the Root Document section below for more details.
size
integer
Generated
Read-only
The size of the reality data in Kilobytes. This size can be temporarily not up to date after a change, see Authoring and Size section below.
authoring
boolean
Optional
Modifiable
A boolean value that indicates if data is being created or uploaded. See Authoring section for details.
classification
string
Optional
Modifiable
Specific value constrained field that indicates the nature of the reality data. See Classification and Type section for details.
type
string
Required
Modifiable
A key indicating the format of the data. See Type section below about registered types and more details.
acquisition
object
Optional
Modifiable
Provides information regarding the acquisition, such as dates and acquirer used. See Acquisition section below.
extent
object
Optional
Modifiable
contains the rectangular area on the Earth which encloses the reality data. See Extent section below.
modifiedDateTime
string(date)
Generated
Read-only
Read-Only. ISO-8601 compliant time (UTC) of last modification of the reality data. e.g. "2017-05-10T13:43:03Z"
lastAccessedDateTime
string(date)
Generated
Read-only
Read-Only. ISO-8601 compliant time (UTC) of last access of the reality data. e.g. "2017-05-10T13:43:03Z"
createdDateTime
string(date)
Generated
Read-only
Read-Only. ISO-8601 compliant time (UTC) of the creation of the reality data. e.g. "2017-05-10T13:43:03Z"
ownerId
string(guid)
Generated
Modifiable
Identifier of the owner of the reality data. If permissions are sufficient, changing ownership is possible.

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.

Display Type
Type
Classification
iTwin.js Ready
Cesium 3D Tiles
Cesium3DTiles
Model
Yes
Cesium 3D Point Cloud
PNTS
Model
Yes
Web Ready Orbit Point Cloud
OPC
Model
Yes
Web Ready 3D Scalable Mesh
RealityMesh3DTiles
Model
Yes
Web Ready Terrain Scalable Mesh
Terrain3DTiles
Model
Yes
Reality Modeling 3MX
3MX
Model
3D Scalable Mesh
3SM
Model
Reality Modeling Cloud Project
CCCloudProject
Undefined
Reality Modeling Image Collection
CCImageCollection
Undefined
Reality Modeling Orientations
CCOrientations
Undefined
Reality Modeling Inputs
ContextCaptureInputs
Undefined
Context Detector
ContextDetector
Undefined
Context Scene
ContextScene
Undefined
Collada
DAE
Model
Bentley DGN
DGN
Model
Digital Surface Model
DSM
Model
Autodesk FBX
FBX
Model
Graphics Language Binary
GLB
Model
Graphics Language Transmission Format
GLTF
Model
Google Earth KML
KML
Model
LAS Point Cloud
LAS
Model
LAZ Point Cloud
LAZ
Model
LOD Tree
LOD
Model
OpenCities Planner LodTree
LodTree
Model
Wavefront OBJ
OBJ
Model
Multiresolution Image
OMI
Imagery
Mapping Resource
OMR
Undefined
Imagery
Orthophoto
Imagery
Orthophoto and DSM
OrthophotoDSM
Imagery
OpenSceneGraph Binary
OSGB
Model
Vector File
OVF
Undefined
Tiled Vector File
OVT
Undefined
Polygon File Format
PLY
Undefined
Pointools POD
PointCloud
Model
Smart3D Capture
S3C
Model
Reality Modeling Scan Collection
ScanCollection
Undefined
ESRI Shapefile
SHP
Undefined
Scene Layer Package (SPLK)
SLPK
Model
SpaceEyes3D Builder
SpaceEyes3D
Model
Stereo Lithography
STL
Model
Terrain Scalable Mesh
TSM
Model
Unstructured Data
Unstructured
Undefined
Other File Formats*
TIF/JPG/PDF/etc.*
Varies**

* 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.

Type
Root Document
Cesium 3D Tiles
The file with the .json extension in the root folder.
Cesium 3D Point Cloud
The file with the .json extension in the root folder.
Web Ready Orbit Point Cloud
The file with the .opc extension in the root folder.
Web Ready 3D Scalable Mesh
The file with the .json extension in the root folder. Often named n0.json_.
Web Ready Terrain Scalable Mesh
The file with the .json extension in the root folder.

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.