## On this page

  

 

 # DynamicSceneGraphService

 Last update: 16.07.2025 

<a id="details" name="details"></a>## Detailed Description

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](namespace_a_n_s_y_s.xhtml "GLTFWriter API Documentation.") 2021 R1 distribution), first start EnSight with the following command line:

ensight.bat -grpc_server 12345



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

cpython.bat dynamic_scene_graph_example_client.py



 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](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.") ([SceneClientCommand::ClientCommandType::INIT](structensightservice_1_1_scene_client_command.xhtml#a0d35bc799b8649f6ca89ba7b81d85c9daf4d487da2248189a4581a1da2ef697a6 "Initial command to be sent. Can be sent repeatedly to reset session parameters or request a scene upd...")) message and EnSight will respond with a sequence of update messages. If the File-&gt;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:

import enspyqtgui_int

enspyqtgui_int.dynamic_scene_graph_command("dynamicscenegraph://localhost/client/update")



 This update will be seen by all current dynamic scene graph sessions that have the allow\_spontaneous flag set in their [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.") 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.

# <a class="anchor" id="entities"></a>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](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") message for each update message) or destroyed by [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") 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](structensightservice_1_1_delete_i_d.xhtml "Delete a list of entities.") command.

The currently defined entities are:

Entity Description Scene Top of the tree of entities. It may contain View and Variable entities. View Contains timestep and camera information for a tree of geometry. It may contain Group and Part entities. Group Child of a View or another Group. It may contain Part and Group entities. Includes a 4x4 matrix transform and arbitrary attributes. Part Child of a Group, parent to Geom entities. Defines a "mesh" and display attributes. Geom Child of a Part. Storage for the arrays that define a block of a geometry. Note: a single Geom will have connectivity defining either be LINES or TRIANGLES, not both. Includes: Coordinates, Connectivity, current variable data, edge flags Variable Defines variable display properties: Nodal, Elemental, ranges, interpolation, etc. Child of a Scene. 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.

## <a class="anchor" id="updateprocess"></a>The entity update gRPC message sequence

---

The update process is initiated by the client application unless a [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.") message has enabled spontaneous updates. A spontaneous update starts with step 2.

1. Client sends a [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.") ([SceneClientCommand::ClientCommandType::INIT](structensightservice_1_1_scene_client_command.xhtml#a0d35bc799b8649f6ca89ba7b81d85c9daf4d487da2248189a4581a1da2ef697a6 "Initial command to be sent. Can be sent repeatedly to reset session parameters or request a scene upd...")) message to the EnSight gRPC service of the type [SceneClientInit](structensightservice_1_1_scene_client_init.xhtml "Request by the client for an EnSight scene update."). This triggers the update sequence.
2. EnSight sends a [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") [UpdateSceneBegin](structensightservice_1_1_update_scene_begin.xhtml "Begin an update sequence.") ([SceneUpdateCommand::SceneUpdateCommandType::UPDATE\_SCENE\_BEGIN](structensightservice_1_1_scene_update_command.xhtml#a80ae6b52bf49715cfdc5392b614b32eaa1e55874750a5e9ffbf781850865d9db5 "Marks the beginning of a scene update.")) message to the client.
3. EnSight sends a series of [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") messages to the client. These messages can be of these types ([DeleteID](structensightservice_1_1_delete_i_d.xhtml "Delete a list of entities."), [UpdatePart](structensightservice_1_1_update_part.xhtml "Update a Part entity."), [UpdateGroup](structensightservice_1_1_update_group.xhtml "Update a Group entity."), [UpdateGeom](structensightservice_1_1_update_geom.xhtml "Update a Geom entity."), [UpdateVariable](structensightservice_1_1_update_variable.xhtml "Update a Variable entity."), [UpdateView](structensightservice_1_1_update_view.xhtml "Update a View entity.")). Note there should be no assumption about the order of these messages.
4. EnSight sends a final [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") [UpdateSceneEnd](structensightservice_1_1_update_scene_end.xhtml "End an update sequence.") ([SceneUpdateCommand::SceneUpdateCommandType::UPDATE\_SCENE\_END](structensightservice_1_1_scene_update_command.xhtml#a80ae6b52bf49715cfdc5392b614b32eaa376ded6d437b36e6d4723d10ebbce06d "Marks the completion of a scene update.")) message to the client, signifying the end of a scene graph update.

## <a class="anchor" id="entitydiagram"></a>Entity relationship diagram

---



## Function Documentation

<a id="ga52fdddcd2932b5fd9a19d0a740d24680" name="ga52fdddcd2932b5fd9a19d0a740d24680"></a>## [◆ ](#ga52fdddcd2932b5fd9a19d0a740d24680)GetAPIVersion()

 rpc ensightservice::DynamicSceneGraphService::GetAPIVersion  ( [VersionRequest](structensightservice_1_1_version_request.xhtml)  *versionrequest*) 

Get the server version of the dynamic scene graph stream.

Parameters versionrequestdummy argument Returns[VersionReply](structensightservice_1_1_version_reply.xhtml "The server API version.") the API version currently supported by the server Definition at line [140](dynamic__scene__graph_8proto_source.xhtml#l00140) of file [dynamic\_scene\_graph.proto](dynamic__scene__graph_8proto_source.xhtml).





<a id="ga013fc67ee73abc7c3d7ce82115972b67" name="ga013fc67ee73abc7c3d7ce82115972b67"></a>## [◆ ](#ga013fc67ee73abc7c3d7ce82115972b67)GetSceneStream()

 rpc ensightservice::DynamicSceneGraphService::GetSceneStream  ( stream  *SceneClientCommand*) 

Start a new dynamic scene graph stream.

This gRPC call opens a bi-directional stream between the client application and the EnSight gRPC server. The client application can make requests for updates to the current scene graph by sending [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.") messages. The EnSight server responds with a series of [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") messages.

Parameters [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.")A stream of [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml "Aggregate command sent by a dynamic scene graph client.") objects Returns[SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") A stream of [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml "Aggregate command sent by EnSight to a client.") messages from the EnSight client Definition at line [135](dynamic__scene__graph_8proto_source.xhtml#l00135) of file [dynamic\_scene\_graph.proto](dynamic__scene__graph_8proto_source.xhtml).





## <a id="func-members" name="func-members"></a>Functions

rpc [ensightservice::DynamicSceneGraphService::GetSceneStream](group___d_s_g.xhtml#ga013fc67ee73abc7c3d7ce82115972b67) (stream [SceneClientCommand](structensightservice_1_1_scene_client_command.xhtml)) returns(stream [SceneUpdateCommand](structensightservice_1_1_scene_update_command.xhtml)) rpc [ensightservice::DynamicSceneGraphService::GetAPIVersion](group___d_s_g.xhtml#ga52fdddcd2932b5fd9a19d0a740d24680) ([VersionRequest](structensightservice_1_1_version_request.xhtml) versionrequest) returns([VersionReply](structensightservice_1_1_version_reply.xhtml))