Reality Analysis
Download API definition:
This API is a Technical Preview and is available for testing purposes only. Do not use in production.
POST https://qa-api.bentley.com/realitydataanalysis/jobs

Create a new job based on its type and options

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with itwin-platform scope

Accept
Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Request body

Job Create

Name
Type
Required?
Description
type
Yes

Job type

name
String
Yes

Job name

iTwinId
String
Yes

ITwin Id

inputs
Yes

List of inputs of the job

outputs
Yes

List of output types of the job

costEstimationParameters
No

Optional cost estimation parameters to estimate the job cost before its processing.

Example

json
{
    "name": "My first objects2D job",
    "iTwinId": "510cd1a3-3703-4729-b08c-fecd9c87c3be",
    "type": "objects2D",
    "inputs": [{
            "type": "photos",
            "id": "e9803e0e-70ce-4ea6-b2ad-1c653cbf2f76"
        },
        {
            "type": "photoObjectDetector",
            "id": "111d3524-2bd3-46c4-9bf4-e0c650f5f8f2"
        }
    ],
    "outputs": ["objects2D"],
    "options": {
        "minPhotos": 2,
        "useTiePoints": true
    },
    "costEstimationParameters": {
        "gigaPixels": 2,
        "sceneWidth": 4.5,
        "sceneHeight": 3.0,
        "sceneLength": 1.7,
        "detectorScale": 1.2,
        "detectorCost": 1.4,
        "numberOfPhotos": 150
    }
}

Response 201 Created

Created

json
{
    "job": {
        "state": "unsubmitted",
        "outputs": [{
            "type": "objects2D"
        }],
        "inputs": [{
                "type": "photos",
                "id": "e9803e0e-70ce-4ea6-b2ad-1c653cbf2f76"
            },
            {
                "type": "photoObjectDetector",
                "id": "111d3524-2bd3-46c4-9bf4-e0c650f5f8f2"
            }
        ],
        "options": {
            "minPhotos": 2,
            "useTiePoints": true
        },
        "createdDateTime": "2021-11-04T14:13:27Z",
        "lastModifiedDateTime": "2021-11-04T14:13:27Z",
        "id": "6f51448f-6377-4330-9ab0-f13fe994b3f1",
        "email": "example@email.com",
        "dataCenter": "EastUs",
        "type": "objects2D",
        "name": "My first objects2D job",
        "iTwinId": "510cd1a3-3703-4729-b08c-fecd9c87c3be",
        "costEstimation": {
            "gigaPixels": 2,
            "sceneWidth": 4.5,
            "sceneHeight": 3.0,
            "sceneLength": 1.7,
            "detectorScale": 1.2,
            "detectorCost": 1.4,
            "numberOfPhotos": 150,
            "estimatedCost": 2.1
        }
    }
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json
{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

json
{
    "error": {
        "code": "InvalidRealityDataAnalysisRequest",
        "message": "Cannot create job.",
        "details": [{
            "code": "InvalidProperty",
            "message": "Required property 'iTwinId' is invalid.",
            "target": "iTwinId"
        }]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json
{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

Name
Description
retry-after

The number of requests exceeds the rate-limit for the client subscription.

Job type

Available job types among 'objects2D', 'segmentation2D', 'segmentation3D', 'segmentationOrthophoto' and 'changeDetection'.

Name
Type
Description
objects2D
String
segmentation2D
String
segmentation3D
String
segmentationOrthophoto
String
changeDetection
String

Job state

Possible state of a job among 'unsubmitted', 'active', 'success', 'failed' and 'cancelled'.

Name
Type
Description
unsubmitted
String
active
String
success
String
failed
String
cancelled
String

Input types

Input types available. Refer to 'Job types' page for per job type list.

Name
Type
Description
photos
String
photoObjectDetector
String
photoSegmentationDetector
String
orthophoto
String
orthophotoSegmentationDetector
String
pointClouds
String
objects2D
String
meshes
String
pointCloudSegmentationDetector
String
clipPolygon
String
segmentation3D
String
segmentation2D
String
pointClouds1
String
pointClouds2
String
meshes1
String
meshes2
String

Job Input

Input description for a job

Name
Type
Description
type

Input name

id
String

Reality Data id of the input

Output types

Output types available. Refer to 'Job types' page for per job type list.

Name
Type
Description
objects2D
String
segmentation2D
String
polygons2D
String
polygons3D
String
exportedPolygons2DSHP
String
exportedPolygons3DDGN
String
exportedPolygons3DCesium
String
lines2D
String
exportedLines2DSHP
String
exportedLines2DDGN
String
objects3D
String
exportedObjects3DDGN
String
exportedObjects3DCesium
String
exportedLocations3DSHP
String
segmentation3D
String
segmentedPointCloud
String
segmentedPhotos
String
exportedSegmentation3DPOD
String
exportedSegmentation3DLAS
String
exportedSegmentation3DLAZ
String
exportedSegmentation3DPLY
String
lines3D
String
exportedLines3DDGN
String
exportedLines3DCesium
String

Job Output

Output description for a job

Name
Type
Description
type

Output name

id
String, null

Reality Data id of the output

Objects2D Options

Options for Object2D job

Name
Type
Description
useTiePoints
Boolean

Improve detection using tie points in orientedPhotos (advanced)

minPhotos
Integer

Minimum number of 2D objects to generate a 3D object (default: 0)

maxDist
Number

Maximum distance between photos and 3D objects (default: 0)

exportSrs
String

SRS used by exports

Segmentation2D Options

Options for Segmentation2D job

Name
Type
Description
minPhotos
Integer

Minimum number of 2D objects to generate a 3D object (default: 0)

computeLineWidth
Boolean

Estimate 3D line width at each vertex

removeSmallComponents
Number

Remove 3D lines with total length smaller than this value

exportSrs
String

SRS used by exports

SegmentationOrthophoto Options

Options for SegmentationOrthophoto job

Segmentation3D Options

Options for Segmentation3D job

Name
Type
Description
computeLineWidth
Boolean

Estimate 3D line width at each vertex

removeSmallComponents
Number

Remove 3D lines with total length smaller than this value

exportSrs
String

SRS used by exports

saveConfidence
String

Save confidence in 3D segmentation

ChangeDetection Options

Options for a ChangeDetection job

Name
Type
Description
colorThresholdLow
Number

Low threshold to detect color changes (hysteresis detection). 0 to ignore color changes

colorThresholdHigh
Number

High threshold to detect color changes (hysteresis detection). 0 to ignore color changes

distThresholdLow
Number

Low threshold to detect spatial changes (hysteresis detection). 0 for automatic setting

distThresholdHigh
Number

High threshold to detect spatial changes (hysteresis detection). 0 for automatic setting

resolution
Number

Target point cloud resolution when starting from meshes

minPoints
Integer

Minimum number of points in a region to be considered as a change

exportSrs
String

SRS used by exports

Cost Estimation Parameters

Optional parameters for estimating job cost before its processing

Name
Type
Description
gigaPixels
Double, null

Number of giga pixels in inputs

numberOfPhotos
Int32, null

Number of photos in inputs

sceneWidth
Double, null

Width of the scene

sceneHeight
Double, null

Height of the scene

sceneLength
Double, null

Length of the scene

detectorScale
Double, null

Scale of the detector

detectorCost
Double, null

Cost of the detector

Job Create

Model for creating a new job

Name
Type
Description
type

Job type

name
String

Job name

iTwinId
String

ITwin Id

inputs

List of inputs of the job

outputs

List of output types of the job

costEstimationParameters

Optional cost estimation parameters to estimate the job cost before its processing.

Error and Warning messages

Model for error and warning messages

Name
Type
Description
code
String

Error or warning message code

title
String

Error or warning message title

message
String

Error or warning message

params
Array

Error or warning message parameters

Execution information

Execution details regarding a job

Name
Type
Description
exitCode
Integer, null

Exit code of the processing

submissionDateTime
Date-time, null

Submission date time of the job

startedDateTime
Date-time, null

Start date time of the job

endedDateTime
Date-time, null

End date time of the job

estimatedUnits
Double, null

Estimated cost of the executed job

errors

Errors, if any produced when processing the job

warnings

Warnings, if any produced when processing the job

Cost Estimation information

Cost estimate based on parameters before job processing

Name
Type
Description
gigaPixels
Double, null

Number of giga pixels in inputs

numberOfPhotos
Int32, null

Number of photos in inputs

sceneWidth
Double, null

Width of the scene

sceneHeight
Double, null

Height of the scene

sceneLength
Double, null

Length of the scene

detectorScale
Double, null

Scale of the detector

detectorCost
Double, null

Cost of the detector

estimatedCost
Double

Estimated Cost of the job using the CostEstimationParameters

Job

Job details

Name
Type
Description
id
String

Job id

email
String

User email address

state

Job state

type

Job type

name
String

Job name

iTwinId
String

ITwin Id

inputs

List of inputs of the job

outputs

List of outputs of the job

createdDateTime
Date-time

Created date-time of the job

lastModifiedDateTime
Date-time

Date-time of the latest modification of the job

executionInformation

Execution Information of the job

costEstimation

Cost estimation before job processing

dataCenter
String

Data center location of the job

Job response

Name
Type
Description
job

Complete job details

DetailedError

Contains error information and an array of more specific errors.

Name
Type
Description
code
String

One of a server-defined set of error codes.

message
String

A human-readable representation of the error.

target
String, null

The target of the error.

details

Optional array of more specific errors.

Detailed Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

Name
Type
Description
error

Error Detailed information.

Error

Contains error information.

Name
Type
Description
code
String

One of a server-defined set of error codes.

message
String

A human-readable representation of the error.

target
String, null

The target of the error.

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

Name
Type
Description
error

Error information.