HxGN 3D Graphics Data Service Web API - Integration - Ver. 3.7.0.3 - Administration & Configuration - Hexagon

HxGN VDS Install and Setup

Language
English
Product
Integration
Search by Category
Administration & Configuration
VDS Version
3.13

The HxGN 3D Graphics Data Service (3D GDS) Web API serves as an integration layer between viewers such as the Graphics View Control and the 3D Graphic Data Service component in VDS. The Web API enables the following actions initiated by the viewer:

  • Request a list of aspect IDs that are available for a plant.

  • Create graphic queries based on advanced queries.

  • Request myVR tree and batch data for graphic queries.

  • Request monikers for selected items in the viewer to allow property queries against another data store.

  • Request render IDs for known monikers.

The 3D GDS Web API exposes its functionality as OData services. The 3D GDS Web API looks at the settings provided in the WebAPISettings.json file in %PROGRAMDATA%\HxGN 3D Graphic Data Service\Settings. These settings include configuration for security, messaging service, telemetry, and so forth.

The settings in this configuration file that are described below can be modified using the VDS Configuration Utility. We recommend that you do not manually edit this configuration file. However, if you choose to edit the file, make a backup of it before you begin.

Settings

Issuer

Access token's issuer address. Do not change if deployed behind the Visualization Edge Gateway.

ServiceId

Service's unique identifier or resource identifier or audience identifier from authorization server. Do not change if deployed behind the Visualization Edge Gateway.

AllowedOrigins

List of origins allowed access to the resource.

AllowCredentials

Indicates whether the resource supports user credentials in the request. Typically True for a secured environment.

Hostname

Specifies the host name of the server on which the RabbitMQ broker software is installed.

Virtualhost

Specifies the virtual host name of the server on which the RabbitMQ broker software is installed. This name is case-sensitive and must match exactly what was entered in RabbitMQ. The virtual host name must also be unique for each server.

Username

Specifies the username used to connect to the RabbitMQ broker software to publish events.

Password

Specifies the password used to connect to the RabbitMQ broker software to publish events.

Port

Specifies the port used to connect to the RabbitMQ broker software. The default value is 5672, which is the default installation port for RabbitMQ.

DisableSmartTelemetry

Turns on and off Hexagon smart telemetry.

DisableTelemetry

Turns on and off Azure Application Insights.

InstrumentationKey

Identifies the Azure resource to associate your Application Insights telemetry data.

Query Examples

The following requests are supported for all viewers.

Retrieve Available Aspects for a Specific Plant

This endpoint is used to retrieve information about a specific plant.

HTTP Request: GET https://{{BaseURL}}/GDS/V1/Plants('{{PlantName}}')?$select=Aspects

HTTP Response: JSON { "@odata.context":"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Plants/$entity", "Aspects": [ ] }

Retrieve URLs for Aspects of a Specific Query

This endpoint is used to request the list of URLs to be given to mMap for different aspects of a query.

HTTP Request: GET
https://{{BaseURL}}:/vds/3d/gds/v1/Plants('{{PlantName}}')?$select=Aspects

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/URLs

HTTP Response: JSON { "@odata.context": "https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Collection(Com.Ingr.GDS.V1.AspectURL)", "value": [ { "Aspect": 0, "URL": "https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect=0,Device=0)" }, { "Aspect": 4, "URL": "https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect=4,Device=0)" }, { "Aspect": 5, "URL": "https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect=5,Device=0)" }, ... }

Prepare workspace for display

This POST action used to prepare workspace for display by taking workspace location. This action creates workspace within the graphic data service and prepares workspace for display.

This endpoint supports asynchronous requests as specified by the OData Specification. If a Prefer: async-response header is included in the request, the response is 200 if a workspace is ready to display, or 202 if a workspace display preparation is in progress. If the response is 200 it also returns the tag, size and batches in the display tree. The intended use for asynchronous requests is to allow clients to provide responsive feedback during long-running display tree generation processes.

HTTP Request: POST
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/PrepareForDisplay

Request Body: JSON { "BaseUri": "{{AppsBaseUri}}", "ResourceUri": "{{AppsWorkingSetRelativeUri}}" }

HTTP Response : JSON { "@odata.context":
"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Com.Ingr.GDS.V1.myVRTreeData", "Aspect": "{{AspectId}}", "ETag": "{{ETag}}", "Size": "{{TreeSize}}", "Timemark": "{{Timemark}}", "Status": "{{QueryStatus}}", "BatchIds": [ ], "Range": { "Low": [{{xLow}},{{yLow}}, {{zLow}}], "High":[{{xHigh}},{{yHigh}}, {{zHigh}}] } } }

Retrieve a myVR k-DOP Tree of Batches Status

This endpoint is used to request the status for a k-DOP tree of batches. If the tree is out of date or has not yet been generated, the GDS will regenerate the tree. myVR represents the rendering engine name.

This endpoint supports asynchronous requests as specified by the OData Specification. If a Prefer: async-response header is included in the request, the response is 200 if a tree is immediately available, or 202 if a tree generation is in progress. If the response is 200, it also returns the tag and batch IDs in the tree. Asynchronous requests allow clients to provide responsive feedback during long-running tree generation processes.

HTTP Request: GET https://{{BaseURL}}/GDS/V1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/Tree

HTTP Response : JSON { "@odata.context": "https://{{BaseURL}}/GDS/V1/$metadata#Com.Ingr.GDS.V1.myVRTree", "Aspect": "{{AspectId}}", "ETag": "{{ETag}}", "Size": "{{TreeSize}}", "Timemark": "{{Timemark}}", "Status": "{{QueryStatus}}", "BatchIds": [ ] }

Retrieve a myVR k-DOP Tree of Batches Stream

This endpoint is used to request a stream containing the k-DOP tree of batches for a specific query. A request to retrieve the tree status must be called successfully before this endpoint is used.

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/Tree/$value

HTTP Response: is a binary stream.

Retrieve a myVR Batch RenderIds, Monikers, and Ranges

This endpoint is used to request render IDs, monikers, and ranges for a given batch. A request to retrieve the tree status must be called successfully before this endpoint is used.

The OData query option (?$expand=RenderIds) is applied as shown in the example below to include render IDs in the response.

HTTP Request: GET
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/Batches(Id={{BatchId}})?$expand=RenderIds

HTTP Response : JSON { "@odata.context": "https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/Batches(RenderIds())/$entity", "BatchId": "{{BatchId}}", "Aspect": "{{AspectId}}", "Device": "{{DeviceId}}", "RenderIds": [ { "Id": "{{RenderId}}", "Moniker": "{{Moniker}}", "Range": { "Low": [{{xLow}},{{yLow}}, {{zLow}}], "High":[{{xHigh}},{{yHigh}}, {{zHigh}}] } } ] }

Retrieve a myVR Batch Stream

This endpoint requests a stream containing the specific batch for a query. A request to retrieve the tree status must be called successfully before this endpoint is used.

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/Batches(Id={{BatchId}})/$value

HTTP Response: is a binary stream.

Retrieve a Render Id in a Plant

This endpoint is used to request the moniker and range for a given render ID.

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/RenderIds({{RenderId}})

HTTP Response: JSON { "Id": "{{RenderId}}", "Moniker": "{{Moniker}}", "Range": { "Low": [{{xLow}},{{yLow}}, {{zLow}}], "High":[{{xHigh}},{{yHigh}}, {{zHigh}}] } }

Retrieve Multiple Render IDs in a Plant

This endpoint requests the monikers and ranges for a given set of render IDs. The endpoint is implemented as an action and the body of the request must contain the list of render IDs.

OData query options (?$select=Id,Moniker) are applied as shown in the example below to retrieve only the ID and Moniker properties of the render ID.

HTTP Request: POST
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Com.Ingr.GDS.V1.LookupRenderIds/?$select=Id,Moniker

Request Body: JSON { "Lookup": { "RenderIds": [ ] } }

HTTP Response: JSON { "value": [ { "Id": "{{RenderId}}", "Moniker": "{{Moniker}}" } ] }

Retrieve a Moniker in a Plant

This endpoint requests the render ID and range for a given moniker.

HTTP Request: GET
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Monikers('{{Moniker}}')

HTTP Response: JSON { "Id": "{{RenderId}}", "Moniker": "{{Moniker}}", "Range": { "Low": [{{xLow}},{{yLow}}, {{zLow}}], "High":[{{xHigh}},{{yHigh}}, {{zHigh}}] } }

Retrieve Multiple Monikers in a Plant

This endpoint is used to request the render ids and ranges for a given set of monikers. The endpoint is implemented as an action and the body of the request should contain the list of monikers.

OData query options (?$select=Id,Moniker) are applied as shown in the example below to retrieve only the ID and Moniker properties.

HTTP Request: POST https:
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Com.Ingr.GDS.V1.LookupMonikers/?$select=Id,Moniker

Request Body: JSON { "Lookup": { "Monikers": [ ] } }

HTTP Response: JSON { "value": [ { "Id": "{{RenderId}}", "Moniker": "{{Moniker}}" } ] }

Perform a Fence Locate on a Query

This endpoint requests all render IDs and ranges for graphic objects that fall within a specified fence. A flag is also sent to indicate if graphic objects that are partially within the fence are to be included.

The fence is specified as an array of doubles. This should be evenly divisible by 3, and must include values for at least two points.

HTTP Request: POST
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')/myVR(Aspect={{AspectId}},Device={{DeviceId}})/FenceLocate

Request Body: JSON { "Fence": [{array of doubles representing points in the fence}], "Overlapping": true }

HTTP Response: JSON { "value": [ { "Id": "{{RenderId}}", "Moniker": "{{Moniker}}", "Range": { "Low": [{{xLow}},{{yLow}}, {{zLow}}], "High":[{{xHigh}},{{yHigh}}, {{zHigh}}] } } ] }

POST Query

Create a query that is scoped by a data source outside of the 3D GDS. The 3D GDS issues an HTTP GET request against the URI specified in the Scope value and parse the response as JSON.

HTTP Request: POST
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries

Request body: JSON { "Name" : "{{QueryName}}", "Scope" : "{{ScopeURL}}" }

HTTP Response: When successfully created, 201 (Created) with full query properties as created on the 3D GDS.

Memory Usage

Can be used to report on the amount of memory that the 3D GDS service is using.

HTTP Request: GET
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/MemoryUsage

HTTP Response: JSON { "@odata.context":
"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Com.Ingr.GDS.V1.MemoryUsage", "Plant": "{{PlantName}}", "MaterialCache": { "Cache": 999, "Count": 999, "Overhead": 999 }, "Process": { "NonPagedPool": 999, "PagedPool": 999, "PageFile": 999, "WorkingSet": 999 }, "QueryCache": { "Queries": [ { "Name": "{{QueryName}}", "Session": 999, "Tree": 999 }, { "Name": "{{QueryName}}", "Session": 999, "Tree": 999 } ] }, "WorldCache": { "GraphicCnt": 999, "RenderIdCnt": 999, "Rendered": 999 } }

GDS Web API compress the response using the standards defined by the HTTP 1.1 specification. Compression is automatically supported by some clients, and can be manually added by others. To use GDS compression, include one of the following HTTP header in a request:

  • Accept-Encoding: gzip,

  • Accept-Encoding: deflate,

  • Accept-Encoding: br

  • Accept-Encoding: gzip, deflate, br

The response includes one of the following for header:

  • Content-Encoding: gzip

  • Content-Encoding: deflate

  • Content-Encoding: br

The GDS Web API compresses the response using br with the fastest compression level when there are multiple formats specified in the request header.

Diagnostics

As with all Web APIs derived from the Smart API SDK, all four diagnostic endpoints are supported.

Echo

Tests network latency by emulating the ping protocol. This endpoint reads and sends back the content of the request message body with an HTTP 200 status code.

HTTP Request: POST https://{{BaseURL}}/vds/3d/gds/v1/diagnostic/echo

Upload

Can be used to test upload speed. This endpoint reads the content of the request message body and responds back with an HTTP 204 status code and empty body.

HTTP Request: POST https://{{BaseURL}}/vds/3d/gds/v1/diagnostic/upload

Download

Tests download speed. This endpoint accepts the request and responds back with an HTTP 200 status code and a random set of bytes in the message body. The response size is controlled by the contentBytes query parameter. If the parameter is missing, the service responds with 65536 bytes (64 KB) content.

HTTP Request:
GET https://{{BaseURL}}/vds/3d/gds/v1/diagnostic/download?contentBytes={{ByteSize}}

Status

Checks the overall health status. This endpoint responds with an HTTP 200 status code and an OK string in the message body if the API is functional. The API responds with an HTTP 500 status code and an UNHEALTHY string in the message body if the API is not functional. Any other response such as no response because of a timeout also indicates a not healthy state.

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/diagnostic/status

Test Query Examples

The following requests are for an internal test application and should not be relied upon for use. They can be removed or modified without notice.

Retrieve List of Plants

This endpoint is used in the generation of the list of plants that are available for viewing.

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/Plants

HTTP Response: JSON { "@odata.context":"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Plants", "value": [ { "Name": "{{PlantName}}", "Site": "{{SiteName}}" } ] }

Retrieve a Specific Plant

This endpoint is used to retrieve information about a specific plant.

HTTP Request: GET https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')

HTTP Response: JSON { "@odata.context":"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Plants/$entity", "Name": "{{PlantName}}", "Site": "{{SiteName}}", "Aspects": [ ] }

Retrieve List of Queries

This endpoint is used in the generation of the list of queries for a plant that are available for viewing.

HTTP Request: GET
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries

HTTP Response: JSON { "@odata.context":
"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Plants('{{PlantName}}')/Queries", "value": [ { "Name": "{{QueryName}}", "Scope": "{{QueryScope}}", "Graphics": "{{GraphicCount}}", "Timemark": "{{QueryTimemark}}", } ] }

Retrieve a Specific Query

This endpoint is used to request information about a specific query.

HTTP Request: GET
https://{{BaseURL}}/vds/3d/gds/v1/Plants('{{PlantName}}')/Queries('{{QueryName}}')

HTTP Response: JSON { "@odata.context":
"https://{{BaseURL}}/vds/3d/gds/v1/$metadata#Plants('{{PlantName}}')/Queries/$entity", "Name": "{{QueryName}}", "Scope": "{{QueryScope}}", "Graphics": "{{GraphicCount}}", "Timemark": "{{QueryTimemark}}", }