Table of contents
Reality Conversion
Download API definition:
This API is a Technical Preview and is available for testing purposes only. Do not use in production.
PATCH https://dev-api.bentley.com/realityconversion/jobs/{id}

Patch can be used for changing the job state (to active or cancelled), options or changing cost estimation parameters.

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 parameters

Name
Required?
Description
id
Yes

Job Id.

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

JobStateModify (UpdateState)

Name
Type
Required?
Description
Job State
No

Set to 'active' to start processing the job, or 'cancelled' to cancel the running job.

Example

json
{
    "state": "active"
}

JobModify (UpdateOptions)

Name
Type
Required?
Description
options
No

List of optional parameters.

costEstimationParameters
No

Parameters to be used to estimate the cost of the job.

Example

json
{
    "options": {
        "processingEngines": 2,
        "merge": false
    },
    "costEstimationParameters": {
        "gigaPixels": 2.5,
        "megaPoints": 1.7
    }
}

Response 200 OK

Job was successfully updated.

json
{
    "job": {
        "id": "cc3d35cc-416a-4262-9714-b359da70b419",
        "name": "My first RCS job",
        "type": "Conversion",
        "state": "active",
        "createdDateTime": "2020-09-14T14:29:55Z",
        "lastModifiedDateTime": "2020-09-14T14:29:55Z",
        "iTwinId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "email": "example@email.com",
        "dataCenter": "East US",
        "inputs": [{
            "id": "58e0c0ca-f730-4e5b-808d-1c8cacacb4d4",
            "type": "LAS"
        }],
        "outputs": [{
            "id": "3ddee08c-01e8-44a5-8e56-3879109f6728",
            "type": "OPC"
        }],
        "options": {
            "processingEngines": 5,
            "merge": false
        },
        "costEstimation": {
            "estimatedCost": 3.5,
            "gigaPixels": 2.1,
            "megaPoints": 1.5
        }
    }
}

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 404 Not Found

Not Found

json
{
    "error": {
        "code": "JobNotFound",
        "message": "Requested job is not available."
    }
}

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": "InvalidRealityConversionRequest",
        "message": "Cannot modify job.",
        "details": [{
            "code": "InvalidChange",
            "message": "Cannot resubmit an already submitted job."
        }]
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json
{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

Name
Description
retry-after

Number of seconds to wait until client is allowed to make more requests.

Job Response

Name
Type
Description
job

Complete job details.

Job

Full representation of a job.

Name
Type
Description
id
String

Job unique id.

name
String

Job name.

type

Job type.

state

Job current state.

iTwinId
String

iTwin Id.

ownerId
String

owner Id.

createdDateTime
Date-time

Creation time of the job.

lastModifiedDateTime
Date-time

Last modification date of the job.

dataCenter
String

Datacenter location of the job.

email
String

User email address.

executionInformation

Execution information of the job.

costEstimation

Parameters to be used to estimate the cost of the job.

inputs

List of inputs of the job.

outputs

List of outputs of a job.

options

List of optional parameters.

Job Type

Possible values:

  • Conversion: Converts input data from one format to another.
  • ImportFeatures: Takes vector inputs and imports features into a feature class of Geospatial Features API. Use FDB as the output format for this type.
Name
Type
Description
Conversion
String
ImportFeatures
String

Job State

Job state.

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

Point Cloud Input Formats

List of available input formats for point cloud conversion.

Name
Type
Description
LAS
String
LAZ
String
PLY
String
E57
String
OPC
String
PointCloud
String
PNTS
String
Cesium3DTiles
String

Vector Input Formats

List of available input formats for vector conversion.

Name
Type
Description
ContextScene
String
GeoJSON
String
OVF
String
OVT
String
SHP
String

Tile Map Input Formats

Input types representing raster or tiled datasets for generating tile maps.

Name
Type
Description
Orthophoto
String
OrthophotoDSM
String
OMI
String
OVF
String
OVT
String

Job Input

Input description for a job.

Name
Type
Description
type

Input format for a job.

id
String

Reality data Id of the input.

Point Cloud Output Formats

List of available point cloud output formats.

  • OPC: Orbit Point Cloud
  • PNTS: OGC 3DTiles Point Cloud 1.0
  • GLB: OGC 3DTiles Point Cloud 1.1
  • GLBC: OGC 3DTiles Point Cloud 1.1 Compressed.
Name
Type
Description
OPC
String
PNTS
String
GLB
String
GLBC
String

Vector Output Formats

List of available vector output formats.

  • Use FDB as the output format when the job type is ImportFeatures.
Name
Type
Description
GeoJSON
String
FDB
String

Tile Map Output Formats

List of available tile map output formats.

Name
Type
Description
XYZTileMap
String

Job Output

Output description for a job.

Name
Type
Description
type

Output format for a job.

id
String, null

Reality data Id of the output.

Options

List of optional parameters.

Name
Type
Description
processingEngines
Integer

Number of engines to be used at most, between 0 and your engine limit. If set at 0, RCS will use your engine limit.

merge
Boolean

If true, then all the input files from multiple containers will be merged into one output file. Otherwise, creates one output per input file. Valid only for Conversion jobs.

inputSRS
String

EPSG code for the spatial reference system of input files (horizontal or horizontal+vertical).

outputSRS
String

EPSG code for the spatial reference system of output files (horizontal or horizontal+vertical).

sampleWorldStep
Double

Sampling step size in meters for traversing triangles in mesh geometry. Default is 0.125. Only valid for Cesium3DTiles input.

featureClassDisplayName
String

Name of the feature class to create in the Geospatial Features API. If omitted, uses the input reality data display name. Only valid for ImportFeatures jobs.

topLevel
Integer

Top level of the tile map to generate. Default is -1 (single tile for all input data). Only valid for TileMap output.

bottomLevel
Integer

Bottom level of the tile map to generate. Default is -1 (closest to native resolution). Only valid for TileMap output.

tileFormat
String

Tile format for the tile map. Supported values are 'JPG' (default) and 'PNG'. Only valid for TileMap output.

jpgQuality
Double

Quality of JPG tiles to generate (10–99). Default is 85. Only valid for TileMap output.

backgroundColor
String

Background color to use for tiles, in 'r.g.b' where r,g,b (red,green,blue) are values 0..255, default value is '255.255.255' (white). Only valid for TileMap output.

Execution Info

Execution information of the job.

Name
Type
Description
submissionDateTime
Date-time

Submission time of the job.

startedDateTime
Date-time, null

Start time of the job.

endedDateTime
Date-time, null

End time of the job.

estimatedUnits
Number, null

Estimated processing units cost.

Cost Estimation Parameters

Parameters to be used to estimate the cost of the job.

Name
Type
Description
gigaPixels
Number

Gigapixels to be processed.

megaPoints
Number

Megapoints to be processed.

Cost Estimation Information

Cost estimate based on parameters before job processing.

Name
Type
Description
gigaPixels
Double, null

Number of giga pixels in inputs.

megaPoints
Double, null

Number of mega points in inputs.

estimatedCost
Double

Estimated cost of the job using the CostEstimationParameters.

Job State

Set to 'active' to start processing the job, or 'cancelled' to cancel the running job.

Name
Type
Description
active
String
cancelled
String

Modify Job State

Request model for updating the state of a job. Use to start processing or cancel a running job.

Name
Type
Description
Job State

Set to 'active' to start processing the job, or 'cancelled' to cancel the running job.

Modify Job

PATCH model for updating job properties. All properties are optional; only provided fields will be updated.

Name
Type
Description
options

List of optional parameters.

costEstimationParameters

Parameters to be used to estimate the cost of the job.

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.

Was this page helpful?