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}}", }