The dynamic scene graph gRPC service. More...

Detailed Description

The dynamic scene graph gRPC service.

The dynamic scene graph gRPC service provides a mechanism by which a client application can attach to a running EnSight session and read the current scene geometry. The API allows the client application to track the client scene graph state. It supports both complete and incremental updates. For incremental updates, the EnSight client tracks the remote scene graph state specific to each active scene stream.

The EnSight distribution includes a simple example client written in Python. The renderer in the example client is not complete (e.g. it does not support all of the texturing modes or two sided lighting), but it does demonstrate how a client should interpret the various messages that constitute a scene update operation. This example is located in the same directory (ensightXXX/site_preferences/extensions/grpc) as this .proto file and is named dynamic_scene_graph_example_client.py. To run the example client (Windows example, ANSYS 2021 R1 distribution), first start EnSight with the following command line:

Then in another shell window run the Python script using the EnSight Python interpreter:

Load some data into the EnSight session and then select "Update" from the example client GUI menus to initiate a scene refresh. By default, the example client will send a SceneClientCommand (SceneClientCommand::ClientCommandType::INIT) message and EnSight will respond with a sequence of update messages. If the File->Allow push updates option is enabled in the sample client, it will allow EnSight to push scene graph updates in asynchronous fashion. An EnSight initiated scene update can be started from the Python interpreter in the EnSight client using this code fragment:

This update will be seen by all current dynamic scene graph sessions that have the allow_spontaneous flag set in their SceneClientCommand INIT messages.

EnSight will export all of the geometry visible in the viewport 0 as the scene contents. Individual parts may have the metadata tag "ENS_DSG_HINTS" set to a string. If the string contains the substring "HIDE", that part will not be included in the export, even if it is visible in viewport 0.

Overview of the dynamic scene graph API entities

The gRPC API update commands define a collection of entities that describe the scene graph. These entities refer to each other using entity IDs. The IDs are a proxy for pointers. An individual entity can be updated (one SceneUpdateCommand message for each update message) or destroyed by SceneUpdateCommand messages. All addressable entities have a 64bit "id" associated with them. An "update" command is used to create an entity and to update its attributes.

An incremental update will only send updates for the entities that have changed since the previous update. If an entity no longer exists after this update, the entity ID will be sent in a DeleteID command.

The currently defined entities are:

The View, Group, Part, Geom and Variable entities all include a hash field. This string is unique to the contents of the update message. Thus, if two messages of the same type have the same hash, they can be considered to have identical contents.

The entity update gRPC message sequence

The update process is initiated by the client application unless a SceneClientCommand message has enabled spontaneous updates. A spontaneous update starts with step 2.

1. Client sends a SceneClientCommand (SceneClientCommand::ClientCommandType::INIT) message to the EnSight gRPC service of the type SceneClientInit. This triggers the update sequence.
2. EnSight sends a SceneUpdateCommand UpdateSceneBegin (SceneUpdateCommand::SceneUpdateCommandType::UPDATE_SCENE_BEGIN) message to the client.
3. EnSight sends a series of SceneUpdateCommand messages to the client. These messages can be of these types (DeleteID, UpdatePart, UpdateGroup, UpdateGeom, UpdateVariable, UpdateView). Note there should be no assumption about the order of these messages.
4. EnSight sends a final SceneUpdateCommand UpdateSceneEnd (SceneUpdateCommand::SceneUpdateCommandType::UPDATE_SCENE_END) message to the client, signifying the end of a scene graph update.

Entity relationship diagram

Function Documentation

◆ GetAPIVersion()

◆ GetSceneStream()